Allow annotations using basic types in the stdlib?
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
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
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.stinner@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.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
I agree with Steve. There is *cognitive* overhead to type annotations. I find that they make Python code harder to read and understand. So I object to them in the documentation and docstrings as well. (Note: while I agree that the notation is compact for the simple types, the fact that it would appear for some signatures and not for others is a show stopper from my point of view...consistency is important to reducing the cognitive overhead of reading the docs.) I'm dealing with the spread of annotations on my current project, having to ask programmers on the team to delete annotations that they've "helpfully" added that to my mind serve no purpose on a project of the size we're developing, where we aren't using static analysis for anything. Maybe I'm being a curmudgeon standing in the way of progress, but I'm pretty sure there are a number of people in my camp :) On Mon, 06 Nov 2017 16:22:23 +0000, Steve Holden <steve@holdenweb.com> wrote:
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.stinner@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.
On Mon, Nov 6, 2017, 10:27 R. David Murray, <rdmurray@bitdance.com> wrote:
I agree with Steve. There is *cognitive* overhead to type annotations. I find that they make Python code harder to read and understand. So I object to them in the documentation and docstrings as well. (Note: while I agree that the notation is compact for the simple types, the fact that it would appear for some signatures and not for others is a show stopper from my point of view...consistency is important to reducing the cognitive overhead of reading the docs.)
I'm dealing with the spread of annotations on my current project, having to ask programmers on the team to delete annotations that they've "helpfully" added that to my mind serve no purpose on a project of the size we're developing, where we aren't using static analysis for anything.
I think this is the key point in your situation if the project is private.
Maybe I'm being a curmudgeon standing in the way of progress, but I'm pretty sure there are a number of people in my camp :)
The key thing here is there are people like me who are using your analyzers (and you are as well indirectly since the CLA bot is fully type hinted 😁). I think the key question is whether we expect typeshed to keep up with richer annotations using typing or are basic ones in the stdlib going ot leave less of a gap in support in the long-term? To be honest, I suspect most Python code in the stdlib would require protocols to be accurate (C code is another matter), but return type hints could be reasonably accurate. -Brett
On Mon, 06 Nov 2017 16:22:23 +0000, Steve Holden <steve@holdenweb.com> wrote:
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.stinner@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.
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/brett%40python.org
On 11/06/2017 01:25 PM, R. David Murray wrote:
Maybe I'm being a curmudgeon standing in the way of progress, but I'm pretty sure there are a number of people in my camp :)
I'm definitely there: anything which optimizes machine-readabilty over readability for the Mark 1 eyeball is a lose. Tres. -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com
On Nov 6, 2017, at 08:02, Victor Stinner <victor.stinner@gmail.com> wrote:
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:
I’m still -1 on adding annotations to the stdlib, despite their increasing use out in the wild, for the reasons that Steve and David have pointed out. (Let’s let Eric be the one that breaks the mold with data classes. Then we can blame him!) -Barry
On 11/6/2017 1:40 PM, Barry Warsaw wrote:
On Nov 6, 2017, at 08:02, Victor Stinner <victor.stinner@gmail.com> wrote:
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:
I’m still -1 on adding annotations to the stdlib, despite their increasing use out in the wild, for the reasons that Steve and David have pointed out. (Let’s let Eric be the one that breaks the mold with data classes. Then we can blame him!)
Thanks for volunteering me! Note that dataclasses completely ignores the annotations (they could all be None, for all I care), except for the one specific case of ClassVar. And that's still up for discussion, see https://github.com/ericvsmith/dataclasses/issues/61. Eric.
participants (7)
-
Barry Warsaw -
Brett Cannon -
Eric V. Smith -
R. David Murray -
Steve Holden -
Tres Seaver -
Victor Stinner