classification
Title: Document that typing.SupportsXXX protocols are runtime checkable
Type: Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, docs@python, gvanrossum, levkivskyi, ramalho
Priority: normal Keywords:

Created on 2020-06-14 19:43 by ramalho, last changed 2020-08-03 00:11 by gvanrossum. This issue is now closed.

Messages (8)
msg371513 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-06-14 19:43
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
msg371703 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-06-17 00:23
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.
msg373623 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-07-14 01:43
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.
msg374646 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2020-07-31 17:03
>  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?
msg374647 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-31 17:09
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>
> _______________________________________
>
msg374675 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-08-02 01:05
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.
msg374702 - (view) Author: Luciano Ramalho (ramalho) * Date: 2020-08-02 23:11
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.
msg374703 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-08-03 00:11
Thanks, I was looking for this.
History
Date User Action Args
2020-08-03 00:11:34gvanrossumsetstatus: open -> closed
resolution: fixed
messages: + msg374703

stage: resolved
2020-08-02 23:11:53ramalhosetmessages: + msg374702
2020-08-02 01:05:04ramalhosetmessages: + msg374675
2020-07-31 17:09:09gvanrossumsetmessages: + msg374647
2020-07-31 17:03:00Mariattasetnosy: + Mariatta
messages: + msg374646
2020-07-14 01:43:36ramalhosetmessages: + msg373623
2020-06-17 00:23:11gvanrossumsetmessages: + msg371703
2020-06-15 01:18:10xtreaksetnosy: + gvanrossum, levkivskyi
2020-06-14 19:43:07ramalhocreate