PEP 484 type annotations for Requests

[ygingras]

I am considering adding type annotations to Requests to help my team do static analysis of code that depends on it. Would a pull request containing type annotations be merge back?

More info on type annotations:

• PEP 484: https://www.python.org/dev/peps/pep-0484/
• mypy, the type-checker of choice these days: http://mypy-lang.org/

Given the need to support Python 2.x, the preferred format for annotations would be as Type Comments, but I would be open to do .pyi stubs if that makes it easier for everyone.

[Lukasa]

Thanks for suggesting this!

No, Requests has no interest in maintaining type annotations in-tree. This has been our policy since PEP 484 was originally discussed on python-dev. PEP 484's type annotations are a poor fit for Requests due to the substantial complexity and flexibility in our API, and so writing a set that are sufficiently complete to be useful without being misleading is a tricky thing to do.

I should note that the typeshed has partial type stubs for Requests: you may find it helpful to extend theirs rather than start from scratch.

[JordanP]

type annotations are a poor fit for Requests due to the substantial complexity and flexibility in our API

On the contrary, I find Requests source code clear and relatively straightforward. And having used the typing module, it is also flexible.

It would be great for the Python community if we could try annotating Requests, and give feedback about typing + mypy to the people in charge. I mean, if no one is trying, how can we expect these projects to succeed and meet the demand ?

I am really getting used to having method signatures annotated, it helps me a lot when I do code reviews. And the IDE autocompletion is just awesome.

But yeah, improving the stubs in typeshed would be a nice start, if upstream is not ready yet.

[Lukasa]

On the contrary, I find Requests source code clear and relatively straightforward. And having used the typing module, it is also flexible.

The clarity of the source code is not the issue here: the issue here is the flexibility of inputs to the API.

I noted this originally in mailing list posts when PEP 484 was discussed, and as far as I am aware nothing has changed since.

It would be great for the Python community if we could try annotating Requests, and give feedback about typing + mypy to the people in charge. I mean, if no one is trying, how can we expect these projects to succeed and meet the demand ?

Third parties like yourself are entirely free to do whatever you like. You are welcome to attempt to annotate the source and to provide the appropriate feedback upstream.

However, the Requests project and maintainers are not researchers on behalf of PEP 484. It is not incumbent upon us to make PEP 484 a success. Adding type hints to the Requests repository makes us responsible for keeping them up-to-date, which is not something any of us feel like is worth doing at this time.

However, I highly recommend you read through the link above where I originally explained my concerns with adding type hints to the Requests API. Until those concerns are addressed, and until we can validate the correctness of type hints in our CI, I'm going to be opposed to adding first-party support for them.

[sigmavirus24]

Further there are already some flawed and unofficial hints in https://github.com/python/typeshed. We won't endorse those, but they already exist, so there's less work for you to do.

Also, in the spirit of being explicit, I wholeheartedly agree with @Lukasa.

[ygingras]

Fair enough, Cory and Ian. I will start by adding to typeshed and see where that leads us. Cheers!

[kylebebak]

@Lukasa
Thanks for the mailing list post. I've been fooling around with mypy for a bit and you articulate my main doubt about this PEP's usefulness, namely that the most Pythonic code is the most difficult to annotate. Sufficiently Pythonic code is currently impossible to annotate.

It sort of follows that for this PEP to be successful the definition of "Pythonic" would have to change. It's hard to see members of the community working to make that happen.