[Python-Dev] typeshed for 3rd party packages

[Guido van Rossum]

On Wed, Apr 22, 2015 at 9:26 AM, Ian Cordasco <graffatcolmingov at 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 $MyPackage
> link to the docs in typeshed to avoid users filing bugs on $MyPackage'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.

-- 
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20150422/a539c6f9/attachment.html>