Document that typing.SupportsXXX protocols are runtime checkable

[ramalho]

BPO	40978
Nosy	@gvanrossum, @ilevkivskyi, @Mariatta, @ramalho

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-08-03.00:11:34.946>
created_at = <Date 2020-06-14.19:43:07.805>
labels = ['3.8', '3.9', '3.10', 'docs']
title = 'Document that typing.SupportsXXX protocols are runtime checkable'
updated_at = <Date 2020-08-03.00:11:34.945>
user = 'https://github.com/ramalho'

bugs.python.org fields:

activity = <Date 2020-08-03.00:11:34.945>
actor = 'gvanrossum'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-08-03.00:11:34.946>
closer = 'gvanrossum'
components = ['Documentation']
creation = <Date 2020-06-14.19:43:07.805>
creator = 'ramalho'
dependencies = []
files = []
hgrepos = []
issue_num = 40978
keywords = []
message_count = 8.0
messages = ['371513', '371703', '373623', '374646', '374647', '374675', '374702', '374703']
nosy_count = 5.0
nosy_names = ['gvanrossum', 'docs@python', 'levkivskyi', 'Mariatta', 'ramalho']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue40978'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[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

[gvanrossum]

And here I had hoped that this was a Pull Request. :-)

Note that the docs also still state that these are ABCs -- in fact they are Protocols.

I'm not sure why the same info should be repeated for the @runtime_checkable decorator though.

[ramalho]

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-sig@python.org/message/CSM3ZCWNRBO4RGGTSM664DD37JYOUVCO/
[2] https://mail.python.org/archives/list/typing-sig@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.

[Mariatta]

because their runtime results are inconsistent with how Mypy handles them, producing both false positives and false negatives.

@guido or @ivan, do you have further thoughts or additional context to share about the above point?

[gvanrossum]

I agree with Luciano's conclusion and have nothing to add other than to
encourage him to submit a PR for the docs. (I know he already submitted a
PR to refactor the docs. Honestly I lost track of that one. Luciano, if you
need my review for that one, please ping me.)

On Fri, Jul 31, 2020 at 10:04 AM Mariatta <report@bugs.python.org> wrote:

Mariatta <mariatta@python.org> added the comment:

> because their runtime results are inconsistent with how Mypy handles
them, producing both false positives and false negatives.

@guido or @ivan, do you have further thoughts or additional context to
share about the above point?

----------
nosy: +Mariatta

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue40978\>

---