<div dir="ltr"><div class="gmail_default" style="font-size:small">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</div></div><div class="gmail_extra"><br clear="all"><div><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr">Steve Holden<br></div></div></div>
<br><div class="gmail_quote">On Mon, Nov 6, 2017 at 4:07 PM, Victor Stinner <span dir="ltr"><<a href="mailto:victor.stinner@gmail.com" target="_blank">victor.stinner@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Related to annotations, are you ok to annotate basic types in the<br>
*documentation* and/or *docstrings* of the standard library?<br>
<br>
For example, I chose to document the return type of time.time() (int)<br>
and time.time_ns() (float). It's short and I like how it's formatted.<br>
See the current rendered documentation:<br>
<br>
<a href="https://docs.python.org/dev/library/time.html#time.time" rel="noreferrer" target="_blank">https://docs.python.org/dev/<wbr>library/time.html#time.time</a><br>
<br>
"Annotations" in the documentation and docstrings have no impact on<br>
Python runtime performance. Annotations in docstrings makes them a few<br>
characters longer and so impact the memory footprint, but I consider<br>
that the overhead is negligible, especially when using python3 -OO.<br>
<span class="HOEnZb"><font color="#888888"><br>
Victor<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
2017-11-06 17:02 GMT+01:00 Victor Stinner <<a href="mailto:victor.stinner@gmail.com">victor.stinner@gmail.com</a>>:<br>
> Hi,<br>
><br>
> While discussions on the typing module are still hot, what do you<br>
> think of allowing annotations in the standard libraries, but limited<br>
> to a few basic types:<br>
><br>
> * None<br>
> * bool, int, float, complex<br>
> * bytes, bytearray<br>
> * str<br>
><br>
> I'm not sure about container types like tuple, list, dict, set,<br>
> frozenset. If we allow them, some developers may want to describe the<br>
> container content, like List[int] or Dict[int, str].<br>
><br>
> My intent is to enhance the builtin documentation of functions of the<br>
> standard library including functions implemented in C. For example,<br>
> it's well known that id(obj) returns an integer. So I expect a<br>
> signature like:<br>
><br>
>   id(obj) -> int<br>
><br>
><br>
> Context: Tal Einat proposed a change to convert the select module to<br>
> Argument Clinic:<br>
><br>
>    <a href="https://bugs.python.org/issue31938" rel="noreferrer" target="_blank">https://bugs.python.org/<wbr>issue31938</a><br>
>    <a href="https://github.com/python/cpython/pull/4265" rel="noreferrer" target="_blank">https://github.com/python/<wbr>cpython/pull/4265</a><br>
><br>
> The docstring currently documents the return like:<br>
> ---<br>
> haypo@selma$ pydoc3 select.epoll.fileno|cat<br>
> Help on method_descriptor in select.epoll:<br>
><br>
> select.epoll.fileno = fileno(...)<br>
>     fileno() -> int<br>
><br>
>     Return the epoll control file descriptor.<br>
> ---<br>
><br>
> I'm talking about "-> int", nice way to document that the function<br>
> returns an integer.<br>
><br>
> Problem: even if Argument Clinic supports "return converters" like<br>
> "int", it doesn't generate a docstring with the return type. So I<br>
> created the issue:<br>
><br>
> "Support return annotation in signature for Argument Clinic"<br>
> <a href="https://bugs.python.org/issue31939" rel="noreferrer" target="_blank">https://bugs.python.org/<wbr>issue31939</a><br>
><br>
> But now I am confused between docstrings, Argument Clinic, "return<br>
> converters", "signature" and "annotations"...<br>
><br>
> R. David Murray reminded me the current policy:<br>
><br>
> "the python standard library will not include type annotations, that<br>
> those are provided by typeshed."<br>
><br>
> While we are discussing removing (or not) typing from the stdlib (!),<br>
> I propose to allow annotations in the stdlib, *but* only limited to<br>
> the most basic types.<br>
><br>
> Such annotations *shouldn't* have a significant impact on performances<br>
> (startup time) or memory footprint.<br>
><br>
> The expected drawback is that users can be surprised that some<br>
> functions get annotations, while others don't. For example,<br>
> os.fspath() requires a complex annotation which needs the typing<br>
> module and is currently done in typeshed, whereas id(obj) can get its<br>
> return type documented ("-> int").<br>
><br>
> What do you think?<br>
><br>
> Victor<br>
______________________________<wbr>_________________<br>
Python-Dev mailing list<br>
<a href="mailto:Python-Dev@python.org">Python-Dev@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/python-dev" rel="noreferrer" target="_blank">https://mail.python.org/<wbr>mailman/listinfo/python-dev</a><br>
Unsubscribe: <a href="https://mail.python.org/mailman/options/python-dev/steve%40holdenweb.com" rel="noreferrer" target="_blank">https://mail.python.org/<wbr>mailman/options/python-dev/<wbr>steve%40holdenweb.com</a><br>
</div></div></blockquote></div><br></div>