[Python-ideas] Conventions for Python code documentation

[Guido van Rossum]

On Tue, Jan 20, 2015 at 6:57 PM, Terry Reedy <tjreedy at udel.edu> wrote:
>
> My particular interest here is adding type information to the signature
> information already displayed in Idle calltips.  It would be nice if the
> typing module (eventually) had a function to do that. It could be used by
> help(function) also.  The point is to help people write correct calls in
> the first place, by providing easily accessed information, rather than wait
> for a checker or the runtime to find the error.
>

That is  indeed part of the plan. In first approximation, the repr() of an
annotation (if it is one of the classes defined in typing.py, such as
Union, Callable, or classes derived from Generic[...]) will be usable to
describe the type. E.g. the repr() of Tuple[int, str] is exactly
'Tuple[int, str]'. (This works today in my prototype at
https://github.com/ambv/typehinting/tree/master/prototyping .)

There are some issues around forward references (not yet implemented) which
mean that you probably have to use a simple helper function defined in
typing.py to get the annotation, but it should be pretty smooth sailing.

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