Add type hints

[Robert Craigie]

Would be really nice to have type hints for this project.

I don't know if you want to target Python 2 or python < 3.5 but in that case you can use type comments.

[Shivaram Lingamneni]

3.6 is the lowest supported version, so that's not a concern.

I looked into this briefly before. I got the sense that because of the heavy use of kwargs, it wouldn't add much value in the absence of PEP 612, which requires Python 3.10. Maybe I misunderstood the nature of the problem?

Is the goal to ensure internal consistency within mureq, or to enable mureq's clients to verify the types of the arguments they're passing?

[Robert Craigie]

Is the goal to ensure internal consistency within mureq, or to enable mureq's clients to verify the types of the arguments they're passing?

The goal for me is to make it easy to use mureq with strict mode in pyright which will report errors if a function is not annotated. It matters less that the API is correctly typed and more that there are type annotations in the first place.

With pyright you can also type kwargs but no other type checker supports this yet AFAIK. This is what typed kwargs looks like in pyright:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from typing_extensions import TypedDict, Unpack

    class RequestKwargs(TypedDict, total=False):
        timeout: int


def get(url: str, **kwargs: 'Unpack[RequestKwargs]') -> 'Response':
    ...


get('foo')  # valid
get('foo', bar='baz')  # invalid
get('foo', timeout=1)  # valid

It should be noted that I've added the type definitions within a TYPE_CHECKING declaration as these features rely on typing_extensions which is not included in the stdlib and therefore incompatible with mureq.

[Shivaram Lingamneni]

Could this be solved using pyright's ignore directive?

[Robert Craigie]

Yes you can ignore the errors either by disabling the diagnostic rule or on an individual case by case basis but I would rather not do either of these if possible.

In my opinion type hints are better than no type hints even if the signatures themselves do not provide much value. For example:

def get(url: str, **kwargs: object) -> 'Response':
    """get performs an HTTP GET request."""
    return request('GET', url=url, **kwargs)