Feature Request: type annotations #650
Comments
|
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 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. |
Now we explicitly ignore specific imports instead of a blanket ignore on all missing types. Upgraded databases and pytest to get their latest versions which include types, for the rest we're ignoring them explicitly. see #485 - arrow doesn't have types but we can replace it with std library calls - requests_async deprecated in favor of httpx, so we'd need to upgrade to get types. The API of httpx is a little different as well. - structlog doesn't have types currently hynek/structlog#165 - rure No stubs yet davidblewett/rure-python#23 - pytest_mock types recently added to the typeshed so we'll need to wait for the next release of mypy. pytest-dev/pytest-mock#152 - markdown_html_finder Wrapper around some Rust code. Needs stubs to be added. chdsbd/markdown-html-finder#5 - asyncio_redis We're our own fork of it, but adding types would be rather manual. Granted we aren't using that much of the API surface. https://github.com/chdsbd/asyncio-redis - zstandard No stubs yet, so we're ignoring for the time being indygreg/python-zstandard#120 - inflection Types, but I think they're misconfigured, once they're fixed we can unignore. jpvanhal/inflection#49 - django Need to setup django-stubs for this to work since django doesn't have any static types. https://github.com/TypedDjango/django-stubs - dj_database_url Doesn't have any static types yet jazzband/dj-database-url#135 - responses No types yet getsentry/responses#339 - stripe Plan for types, but they don't exist currently stripe/stripe-python#650
Now we explicitly ignore specific imports instead of a blanket ignore on all missing types. Upgraded databases and pytest to get their latest versions which include types, for the rest we're ignoring them explicitly. see #485 - arrow doesn't have types but we can replace it with std library calls - requests_async deprecated in favor of httpx, so we'd need to upgrade to get types. The API of httpx is a little different as well. - structlog doesn't have types currently hynek/structlog#165 - rure No stubs yet davidblewett/rure-python#23 - pytest_mock types recently added to the typeshed so we'll need to wait for the next release of mypy. pytest-dev/pytest-mock#152 - markdown_html_finder Wrapper around some Rust code. Needs stubs to be added. chdsbd/markdown-html-finder#5 - asyncio_redis We're using our own fork of it, but adding types would be rather manual. Granted we aren't using that much of the API surface. https://github.com/chdsbd/asyncio-redis - zstandard No stubs yet, so we're ignoring for the time being indygreg/python-zstandard#120 - inflection Types, but I think they're misconfigured, once they're fixed we can unignore. jpvanhal/inflection#49 - django Need to setup django-stubs for this to work since django doesn't have any static types. https://github.com/TypedDjango/django-stubs - dj_database_url Doesn't have any static types yet jazzband/dj-database-url#135 - responses No types yet getsentry/responses#339 - stripe Plan for types, but they don't exist currently stripe/stripe-python#650
|
Having a separate |
Added basic type stubs for some of the smaller libraries the bot and web_api use. Libraries with missing types that remain: - structlog, waiting on the release of its typed api - requests_async, need to convert to httpx which has types - asyncio_redis, maybe write stubs, or use a different client - django, stubs exist, last time we tried it, there were a number of false positives - stripe, no types currently, could probably write some minimal stubs rel: stripe/stripe-python#650
Added basic type stubs for some of the smaller libraries the bot and web_api use. We put the types in the `typings` folder which we configure in the Mypy, but is also the [default path that pyright looks at](https://github.com/microsoft/pyright/blob/b9e61e9f2ae6179284fed8e7b534e5dcb46c8f8b/docs/configuration.md) so pylance should just work. Libraries with missing types that remain: - structlog, waiting on the release of its typed api - requests_async, need to convert to httpx which has types - asyncio_redis, maybe write stubs, or use a different client - django, stubs exist, last time we tried it, there were a number of false positives - stripe, no types currently, could probably write some minimal stubs rel: stripe/stripe-python#650 rel: indygreg/python-zstandard#120 rel: davidblewett/rure-python#23 rel: jazzband/dj-database-url#135
|
@nihaals have you seen the |
I can think of a few: Typeshed uses 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. |
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 |
|
There seems to have been recent activity in this front, python/typeshed#8696, #871 |
|
Sorry, I am new to python annotations. How would I use the types in typeshed to annotate my code? |
You just need to import stripe. Typeshed is only used by your type checker and doesn't need to be imported. |
|
Separate stubs are an option. You don't even need to create a separate 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 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 & #1074 |
|
We have been gradually adding type annotations and finally activated them, shipping 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 |
I think adding type annotations to this library would be helpful for mypy users.
The text was updated successfully, but these errors were encountered: