(original) (raw)
On Wed, Apr 22, 2015 at 9:26 AM, Ian Cordasco <graffatcolmingov@gmail.com> wrote:
As the other maintainer of requests, I think having hints \*might\* help some developers, but looking at what Cory generated (which looks to be valid), I'm wondering about something else with Type Hints.I've heard several people say "Just create an aliased type for the hint so it's shorter!" but doesn't that mean we then have to document that alias for our users? I mean if the IDE suggests that the developer use XYZ for this parameter and there's no explanation for XYZ actually is (in the IDE), doesn't this just add a lot more maintenance to adding hints? Maintainers now have to:- Keep the stubs up-to-date- Document the stubs (and if the stubs are in typeshed, does MyPackagelinktothedocsintypeshedtoavoidusersfilingbugsonMyPackage link to the docs in typeshed to avoid users filing bugs on MyPackagelinktothedocsintypeshedtoavoidusersfilingbugsonMyPackage's issue tracker?)- Version the stubs (assuming they're maintained in a third-party location, e.g., typeshed)Don't get me wrong. I really like the idea of moving towards Type Hints. I'm not even particularly against adding type hints for Requests to typeshed. I'm just hesitant that it will be easy to make them entirely accurate.
To be useful for the users of a package, type aliases need to be exported by the package, which means that the package itself grows a dependency on typing.py. You could probably make that a conditional dependency, e.g.
try:
from typing import Union, Tuple, AnyStr, Optional
HeaderTuple = Union\[Tuple\[AnyStr, AnyStr\], Tuple\[AnyStr, AnyStr, Optional\[AnyStr\]\]\]
# etc.
except ImportError:
pass # Don't define type aliases
and use a stub file for the actual signatures. User code that itself has a hard dependency on typing could import and use the type aliases unconditionally; user code with a conditional dependency on typing should stick to stubs (or similar import hacks).
If you use type hints this way you should probably maintain the stubs as part of your package (as .pyi files living alongside the .py files) so that you don't have to deal with typeshed being out of date.
There are many other possible workflows; we haven't discovered the best one(s) yet. It's a work in progress.