PEP 484: Mark as Final

[JelleZijlstra]

PEP 484 is still marked as "Provisional", but as @Fidget-Spinner pointed out in python/typing#805, it shouldn't be any more. python/cpython#16204 removed talk about typing's provisional status from the module docs, and enhancements to typing have been in the form of new PEPs for the last few release cycles.

Going to mark this as a draft so Guido can have a chance to comment once he's back.

[Fidget-Spinner]

Thanks for the fix Jelle!

PS. I recently stopped @ people inside my commits (or the first message in a PR), see this to learn more: https://mail.python.org/archives/list/[email protected]/thread/OCVQ6IYOVTVYW7ADDNOHKR7JDRBYLM3T/. I think it shouldn't matter as long as you squash-merge with a separate commit message though.

[JelleZijlstra]

I believe that was a GitHub bug that has since been fixed. Still I'll make sure to remove your name in case the bug reappears :)

[Fidget-Spinner]

I believe that was a GitHub bug that has since been fixed. Still I'll make sure to remove your name in case the bug reappears :)

Thanks :)!

[gvanrossum]

Sounds like a plan. We won’t be able to get away with minor changes here any more (check the file’s history, there have quite a few...).

[Fidget-Spinner]

Sounds like a plan. We won’t be able to get away with minor changes here any more (check the file’s history, there have quite a few...).

Hmm now that you mentioned it, I realized that I'm not 100% sure of the potential ramifications of this. I'll ping the other PEP authors to see if they'd like to add anything.

@JukkaL and @ambv

[JelleZijlstra]

I guess one reason PEP 484 is a bit special is that for a lot of things it's the only specification. For example, PEP 450 added the statistics module, but later when things were added to that module it was just done through bugs.python.org issues, and there was no need to update the PEP. But for PEP 484 we can't do that because there's no other document (like the module documentation for statistics) that serves as a specification for what all type checkers should do. The typing documentation doesn't really serve this use case, because it focuses (rightly) just on things that are actually in the module, not on how typing should work in general. So if we decide that something small needs changing, we just update the PEP.

A better solution is going to be to write a new guide to Python typing in the CPython documentation. This guide would serve both as an informal specification for type checkers and as a guide for users. This is something that came up a few other times recently. We've been pointing people at the mypy docs, but at this point mypy is just one of several type checkers. I'd be interested in putting together such a document if people agree that it would be useful.

[Fidget-Spinner]

Thanks, you raised some really good points. I think another problem is that PEP 484 covers both type checkers and the typing module. While the typing module stuff is definitely Final, the type checker stuff is still up for change (inconsistencies between different type checkers is another thing i see on typing-sig/gitter somewhat frequently). TBH, this PEP feels closer to an Informational PEP rather than a Standards Track (your point about lack of docs is probably a contributing factor too).

A better solution is going to be to write a new guide to Python typing in the CPython documentation.

Personally, I think a quick band-aid for now is to link the mypy docs' getting started guide or cheatsheet. The typing docs is getting very long. If we add in an informal specification, it might compete with asyncio (which feels very strange if you compare the runtime complexities). So it's probably going to need some strategizing (maybe it shouldn't even be in CPython's docs, but rather live in a separate repo? eg. in python/typing?). If we really do go ahead with this, I'd be interested to help out too.

[JelleZijlstra]

The typing docs is getting very long

I'd suggest a separate document from the documentation for the typing module. The typing docs would get a reference to this new guide and otherwise just be a reference for the runtime components of the module. The new document could go into the HOWTO section (https://docs.python.org/3.10/howto/index.html).

[srittau]

A better solution is going to be to write a new guide to Python typing in the CPython documentation. This guide would serve both as an informal specification for type checkers and as a guide for users. This is something that came up a few other times recently. We've been pointing people at the mypy docs, but at this point mypy is just one of several type checkers. I'd be interested in putting together such a document if people agree that it would be useful.

This would be very much appreciated. Please let me know if you need any help, e.g. writing certain sections or reviewing the document.

[gvanrossum]

Hm... This is a difficult area -- the various type checkers very much rely on peps for coordinating functionality, and the user docs don't feel like the right place. We probably need to have a discussion in some other place than the peps repo, so I'm closing this for now.