[issue40978] Document that typing.SupportsXXX protocols are runtime checkable
New submission from ramalho <luciano@ramalho.org>: 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 <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
Change by Karthikeyan Singaravelan <tir.karthi@gmail.com>: ---------- nosy: +gvanrossum, levkivskyi _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
Guido van Rossum <guido@python.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
ramalho <luciano@ramalho.org> 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-issue...) and started two threads about them in the typing-sig mailing list: [1] https://mail.python.org/archives/list/typing-sig@python.org/message/CSM3ZCWN... [2] https://mail.python.org/archives/list/typing-sig@python.org/message/FSV6WSFG... 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 <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
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> _______________________________________
Guido van Rossum <guido@python.org> added the comment: 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> _______________________________________
---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
Luciano Ramalho <luciano@ramalho.org> 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 <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
Luciano Ramalho <luciano@ramalho.org> 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 <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
Guido van Rossum <guido@python.org> added the comment: Thanks, I was looking for this. ---------- resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40978> _______________________________________
participants (5)
-
Guido van Rossum -
Karthikeyan Singaravelan
-
Luciano Ramalho
-
Mariatta
-
ramalho