While I appreciate the value of annotations I think that *any* addition of them to the stdlib would complicate an important learning resource unnecessarily. S
Steve Holden On Mon, Nov 6, 2017 at 4:07 PM, Victor Stinner <victor.stin...@gmail.com> wrote: > 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.stin...@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 >
_______________________________________________ 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/archive%40mail-archive.com