(original) (raw)

Related to annotations, are you ok to annotate basic types in the
\*documentation\* and/or \*docstrings\* of the standard library?

For example, I chose to document the return type of time.time() (int)
and time.time\_ns() (float). It's short and I like how it's formatted.
See the current rendered documentation:

https://docs.python.org/dev/library/time.html#time.time

"Annotations" in the documentation and docstrings have no impact on
Python runtime performance. Annotations in docstrings makes them a few
characters longer and so impact the memory footprint, but I consider
that the overhead is negligible, especially when using python3 -OO.

Victor

2017-11-06 17:02 GMT+01:00 Victor Stinner <victor.stinner@gmail.com>:
\> Hi,
\>
\> While discussions on the typing module are still hot, what do you
\> think of allowing annotations in the standard libraries, but limited
\> to a few basic types:
\>
\> \* None
\> \* bool, int, float, complex
\> \* bytes, bytearray
\> \* str
\>
\> I'm not sure about container types like tuple, list, dict, set,
\> frozenset. If we allow them, some developers may want to describe the
\> container content, like List\[int\] or Dict\[int, str\].
\>
\> My intent is to enhance the builtin documentation of functions of the
\> standard library including functions implemented in C. For example,
\> it's well known that id(obj) returns an integer. So I expect a
\> signature like:
\>
\> id(obj) -> int
\>
\>
\> Context: Tal Einat proposed a change to convert the select module to
\> Argument Clinic:
\>
\> https://bugs.python.org/issue31938
\> https://github.com/python/cpython/pull/4265
\>
\> The docstring currently documents the return like:
\> ---
\> haypo@selma$ pydoc3 select.epoll.fileno|cat
\> Help on method\_descriptor in select.epoll:
\>
\> select.epoll.fileno = fileno(...)
\> fileno() -> int
\>
\> Return the epoll control file descriptor.
\> ---
\>
\> I'm talking about "-> int", nice way to document that the function
\> returns an integer.
\>
\> Problem: even if Argument Clinic supports "return converters" like
\> "int", it doesn't generate a docstring with the return type. So I
\> created the issue:
\>
\> "Support return annotation in signature for Argument Clinic"
\> https://bugs.python.org/issue31939
\>
\> But now I am confused between docstrings, Argument Clinic, "return
\> converters", "signature" and "annotations"...
\>
\> R. David Murray reminded me the current policy:
\>
\> "the python standard library will not include type annotations, that
\> those are provided by typeshed."
\>
\> While we are discussing removing (or not) typing from the stdlib (!),
\> I propose to allow annotations in the stdlib, \*but\* only limited to
\> the most basic types.
\>
\> Such annotations \*shouldn't\* have a significant impact on performances
\> (startup time) or memory footprint.
\>
\> The expected drawback is that users can be surprised that some
\> functions get annotations, while others don't. For example,
\> os.fspath() requires a complex annotation which needs the typing
\> module and is currently done in typeshed, whereas id(obj) can get its
\> return type documented ("-> int").
\>
\> What do you think?
\>
\> Victor
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: https://mail.python.org/mailman/options/python-dev/steve%40holdenweb.com