[issue40978] Document that typing.SupportsXXX protocols are runtime checkable
New submission from ramalho : The typing module documentation (https://docs.python.org/3/library/typing.html#typing.SupportsInt) does not mention that the protocols listed below are all decorated with `@runtime_checkable`. This should mentioned in the entry for each protocol and also in the entry for `@runtime_checkable` * SupportsAbs * SupportsBytes * SupportsComplex * SupportsFloat * SupportsIndex * SupportsInt * SupportsRound -- assignee: docs@python components: Documentation messages: 371513 nosy: docs@python, ramalho priority: normal severity: normal status: open title: Document that typing.SupportsXXX protocols are runtime checkable versions: Python 3.10, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue40978> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40979] typing module docs: keep text, add subsections
New submission from ramalho : The typing module documentation page has a very long section "Classes, functions, and decorators" (https://docs.python.org/3/library/typing.html#classes-functions-and-decorators) that should be split in subsections. The ordering of the entries seems haphazard: it's not alphabetical. Its grouped according to invisible categories. The categories appear as comments in the source code of typing.py: the `__all__` global lists the API split into categories (see below). We should add these categories to the page as subsections of "Classes, functions, and decorators" - Super-special typing primitives. - ABCs (from collections.abc). - Structural checks, a.k.a. protocols. - Concrete collection types. -- assignee: docs@python components: Documentation messages: 371514 nosy: docs@python, ramalho priority: normal severity: normal status: open title: typing module docs: keep text, add subsections versions: Python 3.10, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue40979> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40979] typing module docs: keep text, add subsections
ramalho added the comment: Thanks, I am happy to submit a PR. Before I do, I'd like to discuss the subsection titles, starting from the arrangement in typing.__all__: # Special typing constructs (source comment is: "Super-special typing primitives") Any Callable ClassVar Final ForwardRef Generic Literal Optional Protocol Tuple Type TypeVar Union In this section I propose we add: - NamedTuple and TypedDict: source comments say "Not really a type" (for both), and I believe it's confusing to list them along the other collections. Tuple is already in the "Special constructs" category, so NamedTuple should follow in there. TypedDict is very different from the other collections, it's purely a type hinting construct with no runtime counterpart so it's pretty special IMHO. - AnyStr: should be listed right after TypeVar, NoReturn, NewType - Text, TYPE_CHECKING: I am not sure about those, but if they are removed from the "One-off things" all that remains are functions and decorators, which looks good. # ABCs (from collections.abc) [Keep this title] AbstractSet ByteString Container ContextManager Hashable ItemsView Iterable Iterator KeysView Mapping MappingView MutableMapping MutableSequence MutableSet Sequence Sized ValuesView Awaitable AsyncIterator AsyncIterable Coroutine Collection AsyncGenerator AsyncContextManager # Concrete collection types [keep this title] ChainMap Counter Deque Dict DefaultDict List OrderedDict Set FrozenSet - Generator should go with "ABCs" - NamedTuple TypedDict should go with "Special typing constructs" # Protocols (source comment is "Structural checks, a.k.a. protocols.") Reversible SupportsAbs SupportsBytes SupportsComplex SupportsFloat SupportsIndex SupportsInt SupportsRound # Functions and decorators (source comment is "One-off things.") cast final get_args get_origin get_type_hints no_type_check no_type_check_decorator overload runtime_checkable - AnyStr NewType NoReturn: these should go with "Special typing constructs" - Text TYPE_CHECKING: either go with "Special typing constructs" or a constants section, which could include AnyStr as well There are also the IO and re types which could have their own subsections. Looking forward for feeback on this. Thanks! -- ___ Python tracker <https://bugs.python.org/issue40979> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40979] typing module docs: keep text, add subsections
ramalho added the comment: Sorry, there was an editing mistake above. Where I wrote: - AnyStr: should be listed right after TypeVar, NoReturn, NewType I meant to write: - AnyStr: should be listed right after TypeVar - NoReturn, NewType: both belong with "Special Constructs" as well - Text, TYPE_CHECKING: I am not sure about those ... -- ___ Python tracker <https://bugs.python.org/issue40979> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40978] Document that typing.SupportsXXX protocols are runtime checkable
ramalho added the comment: After experimenting with theses protocols, I believe the user community is better served by leaving undocumented the fact that they are runtime checkable, because their runtime results are inconsistent with how Mypy handles them, producing both false positives and false negatives. I've documented the problems (https://github.com/fluentpython/abc-protocol-labs/blob/master/protocol-issues.rst) and started two threads about them in the typing-sig mailing list: [1] https://mail.python.org/archives/list/typing-...@python.org/message/CSM3ZCWNRBO4RGGTSM664DD37JYOUVCO/ [2] https://mail.python.org/archives/list/typing-...@python.org/message/FSV6WSFGWD4QZO6ECY3JADF7M2PW5FKK/ Thread [1] got a useful partial response from Guido. Open questions remain. Thread [2] got no response at all. I will gladly reengage in those threads or in this issue if there is interest. As it stands, I believe the use of the @runtime_checkable feature on several of these protocols is unreliable and should not be promoted. -- ___ Python tracker <https://bugs.python.org/issue40978> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40979] typing module docs: keep text, add subsections
ramalho added the comment: This is my proposal for sections to replace the existing "Classes, functions, and decorators" section. The names are sorted within each section. # Special typing primitives Any Callable ClassVar ForwardRef Generic Literal NamedTuple NewType NoReturn Optional Type TypedDict TypeVar Union # Generic ABCs AbstractSet AsyncContextManager AsyncGenerator AsyncIterable AsyncIterator Awaitable ByteString Collection Container ContextManager Coroutine Generator Hashable io.IO io.BytesIO io.TextIO ItemsView Iterable Iterator KeysView Mapping MappingView MutableMapping MutableSequence MutableSet re.Pattern re.Match Sequence Sized ValuesView # Generic Concrete Collections ChainMap Counter DefaultDict Deque Dict FrozenSet List OrderedDict Set Tuple # Structural checks, a.k.a. protocols. Reversible SupportsAbs SupportsBytes SupportsComplex SupportsFloat SupportsInt SupportsRound # Functions and decorators cast final get_args get_origin get_type_hints no_type_check no_type_check_decorator overload runtime_checkable type_check_only # Aliases and constants AnyStr Text TYPE_CHECKING -- ___ Python tracker <https://bugs.python.org/issue40979> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue13005] operator module docs include repeat
New submission from Luciano Ramalho : The operator module documentation for versions 3.2 and 3.3 includes the repeat function in a table "9.3.1. Mapping Operators to Functions" [1], but fails to mention that the repeat function is deprecated and mul should be used instead, as described in the 2.7 version of the operator module docs [2]. The main entry for the repeat function was removed in the 3.2 and 3.3 docs, only the mention in the table remains [1]. [1] http://docs.python.org/py3k/library/operator#mapping-operators-to-functions [2] http://docs.python.org/library/operator#operator.__repeat__ -- assignee: docs@python components: Documentation messages: 144251 nosy: docs@python, luciano priority: normal severity: normal status: open title: operator module docs include repeat versions: Python 3.2, Python 3.3 ___ Python tracker <http://bugs.python.org/issue13005> ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1293741] doctest runner cannot handle non-ascii characters
Luciano Ramalho added the comment: I have confirmed everything that akaihola reports in Python 2.4, 2.5 and 2.6, but the problem is not limited to non-matching test output. It also happens with doctests with zero failures when the module is run with the -v command-line switch, or testmod is called with verbose=True. The attached file shows a work-around: handle the UnicodeEncodeError thrown by testmod, and display the "object" attribute of the exception to see exactly where the problem is. -- nosy: +luciano title: doctest runner cannot handle non-ascii characters -> doctest runner cannot handle non-ascii characters versions: +Python 2.5, Python 2.6 Added file: http://bugs.python.org/file12684/issue1293741.py ___ Python tracker <http://bugs.python.org/issue1293741> ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue45090] Add pairwise to What's New in Python 3.10; mark it as new in itertools docs
New submission from Luciano Ramalho : Thanks for adding `itertools.pairwise()`! Let's make it easier to find by mentioning it in "What's New in Python 3.10" and also marking it as "New in Python 3.10" in the `itertools` module documentation. -- assignee: docs@python components: Documentation messages: 400966 nosy: docs@python, ramalho priority: normal severity: normal status: open title: Add pairwise to What's New in Python 3.10; mark it as new in itertools docs versions: Python 3.10 ___ Python tracker <https://bugs.python.org/issue45090> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue42781] functools.cached_property docs should explain that it is non-overriding
New submission from Luciano Ramalho : functools.cached_property is a great addition to the standard library, thanks! However, the docs do not say that @cached_property produces a non-overriding descriptor, in contrast with @property. If a user replaces a @property with a @cached_property, her code may or may not break depending on the existence of an instance attribute with the same name as the decorated method. This is surprising and may affect correctness, so it deserves even more attention than the possible performance loss already mentioned in the docs, related to the shared-dict optimization. In the future, perhaps we can add an argument to @cached_property to optionally make it produce overriding descriptors. -- assignee: docs@python components: Documentation messages: 384019 nosy: docs@python, ramalho priority: normal severity: normal status: open title: functools.cached_property docs should explain that it is non-overriding versions: Python 3.10, Python 3.8, Python 3.9 ___ Python tracker <https://bugs.python.org/issue42781> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue42781] functools.cached_property docs should explain that it is non-overriding
Luciano Ramalho added the comment: > FYI, the usual term is "data descriptor" instead of "overriding descriptor". Yes, the Python docs are consistent in always using "data descriptor", but I've adopted "overriding descriptor" from Martelli's Python in a Nutshell--in Fluent Python I also put a note saying that "data descriptor" is used in the docs. I think "overriding descriptor" is more descriptive. In particular, I find "non-data descriptor" quite puzzling. But this issue is not about changing the jargon. > Normally the docs for things like property() and cached_property() > don't mention the term descriptor at all. From the user point of > view, that is an implementation detail. I'd agree, if I wasn't personally bitten by the issue I reported. I was refactoring an existing class which had hand-made caches in a couple of methods decorated with @property. When I discovered @cached_property, I tried to simplify my code by using it, and it broke my code in one place, but not in the other. Leonardo Rochael had experience with cached_property and told me about the difference. I suggest a warning noting the different behavior regarding existing instance attributes. The warning doesn't need to assume the user knows what is a descriptor, but it should in my opinion point to your excellent Descriptor HowTo Guide for more information. > I would suggest a small amendment, and say "cached as a normal attribute with > the same name". The choice of attribute isn't arbitrary, it is exactly the > same as the cached property. That's good too. >> In the future, perhaps we can add an argument to @cached_property >> to optionally make it produce overriding descriptors. > That doesn't make any sense to me. It would defeat the entire mechanism for > cached_property(). My idea would be to add a dummy __set__ method if the overriding option was True (default would be False). The method could raise an exception. But its presence would make @cached_property behave more like @property in the most common use case of @property: as an overriding descriptor emulating a read-only attribute. >> If a user replaces a @property with a @cached_property, her >> code may or may not break depending on the existence of an >> instance attribute with the same name as the decorated method. > We've never had a report of an issue like this and I don't expect to see over. You just did ;-). I filed this issue after spending hours trying to figure out what the problem was in my code on my second attempt at using @cached_property. I expected @cached_property would work as a drop-in replacement for @property when emulating a read-only attribute, and it did not. > One other possible addition is to note that the attribute is writeable: Yes, the code snippet you suggested is a good way of saying "this produces a non-overriding descriptor". However we want to say it, I think it is important to contrast the behavior of @cached_property v. @property regarding the presence of attributes with the same name. Cheers and a happy 2021 with two doses of vaccine for you and your loved ones, Raymond! -- ___ Python tracker <https://bugs.python.org/issue42781> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue43378] Pattern Matching section in tutorial refers to | as
Change by Luciano Ramalho : -- nosy: ramalho priority: normal severity: normal status: open title: Pattern Matching section in tutorial refers to | as ___ Python tracker <https://bugs.python.org/issue43378> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue43378] Pattern Matching section in tutorial refers to | as or
New submission from Luciano Ramalho : Section 4.6. "match Statements" of the Python 3.10 tutorial says: """ You can combine several literals in a single pattern using | (“or”): """ For someone just learning Python, this may suggest that | is always "or", when in fact it is a bitwise operator (that may be overloaded), but inside a match clause has this special meaning without any overloading. I believe this exception should be made explicit in section 4.6, otherwise it may lead readers of the tutorial to a misconception. -- assignee: -> docs@python components: +Documentation nosy: +docs@python title: Pattern Matching section in tutorial refers to | as -> Pattern Matching section in tutorial refers to | as or type: -> enhancement versions: +Python 3.10 ___ Python tracker <https://bugs.python.org/issue43378> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40979] typing module docs: keep text, add subsections
Luciano Ramalho added the comment: Reviewers, besides adding section titles and reordering the entries, I made only these changes to the text: - entry for IO, TextIO, BinaryIO: added sentence "These types are in the ``typing.io`` namespace." - entry for Pattern, Match: added sentence "These types are in the ``typing.re`` namespace." - entry for TypedDict: removed the words "equivalent to" from the sentence "At runtime it is a plain dict." -- ___ Python tracker <https://bugs.python.org/issue40979> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40978] Document that typing.SupportsXXX protocols are runtime checkable
Luciano Ramalho added the comment: I have added a note about the protocols decorated with `@runtime_checkable` to the `Procools` section of the reorganized `typing.rst` in https://bugs.python.org/issue40979. I also expanded the note about the caveats of `@runtime_checkable` in its entry in `Functions and decorators` section, giving `SupportsFloat` as an example issue. -- ___ Python tracker <https://bugs.python.org/issue40978> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40979] typing module docs: keep text, add subsections
Luciano Ramalho added the comment: I have incorporated Guido's suggestions and added additional subsections to make it easier to navigate the page. I also added notes that fix the issue https://bugs.python.org/issue40978 — "Document that typing.SupportsXXX protocols are runtime checkable" -- ___ Python tracker <https://bugs.python.org/issue40979> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue40978] Document that typing.SupportsXXX protocols are runtime checkable
Luciano Ramalho added the comment: The merged PR that fixed https://bugs.python.org/issue40979 also fixes this issue. It is now documented that these protocols are runtime checkable, with caveats. -- ___ Python tracker <https://bugs.python.org/issue40978> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
