Feature Request: type annotations

[chdsbd]

I think adding type annotations to this library would be helpful for mypy users.

[ob-stripe]

Hi @chdsbd, thanks for the feature request and sorry for delayed reply.

While I agree it would be awesome to have type annotations in the library, we still need to support Python 2.7 for the time being despite it having reached EOL at the beginning of the year, as a large portion of our user base has yet to upgrade.

Additionally, in its current form the stripe-python library does not know the exact shape of API requests and responses -- it accepts arbitrary maps both ways. So even if we had type annotations, many of them would look like t.Dict[str, t.Any] which is better than nothing but not extremely useful.

In order to offer exact types like we do in our typed language libraries (stripe-java, stripe-dotnet, etc.) and in TypeScript, we would need to pin the library to a specific API version. It's something we're considering, but it would be a huge change from the current state so we don't plan on making this change soon.

Note that we're also considering shipping a separate, Python 3.6+ only version of stripe-python with full support for types and async methods. We haven't made a lot of progress towards this recently, but it's still on our roadmap.

[nihaals]

Having a separate stripe-stubs package could also be helpful so it wouldn't break old versions (although definitely all for dropping <3.6, could help add more modern features like async)

[dalanmiller]

@nihaals have you seen the *-stubs pattern used elsewhere?

[nihaals]

have you seen the *-stubs pattern used elsewhere?

I can think of a few:

• discord.py-stubs
• django-stubs
• djangorestframework-stubs

Typeshed uses types-*. I rarely need to install separate stub packages so I'm not sure what the most popular convention is. awesome-python-typing includes a list of some "awesome" stub packages which might be a useful resource.

I believe typeshed aims to be something similar to TypeScript's DefinitelyTyped, which, for TS, is definitely the most popular and really the best place to put types if they're not included in the library, so typeshed might be best. A bonus of this is some type checkers already include/use typeshed, so users won't even need to install the stubs package themselves.

[andersk]

While I agree it would be awesome to have type annotations in the library, we still need to support Python 2.7 for the time being despite it having reached EOL at the beginning of the year, as a large portion of our user base has yet to upgrade.

There is a Python 2–compatible annotation syntax.

https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code https://mypy.readthedocs.io/en/stable/python2.html

[tony]

types-stripe: https://pypi.org/project/types-stripe/ (https://github.com/python/typeshed/tree/master/stubs/stripe)

There seems to have been recent activity in this front, https://github.com/python/typeshed/pull/8696, https://github.com/stripe/stripe-python/issues/871

[ekeric13]

Sorry, I am new to python annotations. How would I use the types in typeshed to annotate my code? I get Import "types_stripe" could not be resolved when I install it and import it

[bosmobosmo]

Sorry, I am new to python annotations. How would I use the types in typeshed to annotate my code? I get Import "types_stripe" could not be resolved when I install it and import it

You just need to import stripe. Typeshed is only used by your type checker and doesn't need to be imported.

[Avasam]

Separate stubs are an option. You don't even need to create a separate stripe-stubs package (which could be shipped as part of the stripe distribution), you can just include your type-stubs files (.pyi) along the runtime ones (.py).

Stub files have the advantage of being (mostly) version agnostic (there's some edge cases), but can fall out of sync with the original code. Case in point: typeshed is still on stripe 3.5 because no maintainer or contributor care to spend the time on these stubs.

Inline type annotations on the other hand, are restricted by the lowest supported python version. Luckily, most features have been backported thanks to typing_extensions or by using the typing module. Type-checking-only code can also be hidden behind a typing.TYPE_CHECKING check. The validity of your syntax, annotations and imports can also statically be checked thanks to static type-checkers like mypy, pyright, pytype, pyre, etc. (typeshed validates for mypy, pyright and pytype)

Type comments are a thing for Python 2 code, but they can get really unwieldy. Thankfully support for Python 2 has been dropped since version 6.0.0.

Edit: Just saw all the typing-related PRs, so it seems this is well on its way! https://github.com/stripe/stripe-python/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Aclosed+type & https://github.com/stripe/stripe-python/pull/1074

[richardm-stripe]

We have been gradually adding type annotations and finally activated them, shipping py.typed last week in https://github.com/stripe/stripe-python/releases/tag/v7.1.0.

Your feedback is welcome, please upgrade your stripe-python and give the types a spin!

The approach we've taken was to try and annotate the interface for stripe-python as it already exists, which mean using relatively new type features like **params: Unpack[ParamsTypedDict] instead of introducing new parameter classes. This means that the best experience comes from type checkers like pyright that seem to be a little bit further along in their support for Unpack than mypy is, so be aware of that.