Think through a strategy for documenting Mypy and the type system

[gnprice]

We have two main bodies of documentation right now:

• PEP 484 serves to some extent as reference documentation on the type system. The PEP format isn't directly oriented to this purpose, as it also has the history of the proposal, the rejected alternatives, etc. It's also to some extent a historical document and has a high barrier to making changes, which impedes incrementally improving it as documentation. At present PEP 484 also leaves a lot of details unspecified, because we're reluctant to standardize details that we haven't gotten enough experience with in real usage to be confident how they should work.
• The Mypy documentation is aimed at being user documentation for the type system, as well as on the use of the mypy type-checker tool. It describes the system in more narrative fashion aimed at someone writing type annotations, and it describes details that aren't specified in the PEP. This is much like how for most Python language features, developers generally refer to the Python Language Reference rather than a corresponding PEP.

We've arrived at this setup through a particular historical path, and there are some things that aren't great about it. As we continue to improve the documentation, we should work out what set of bodies of documentation we'd like to have, and how to move toward that.

Here's one setup that I think would improve some things:

• PEP 484, in much the same role as today.
• User-facing documentation of the PEP 484 type system and annotation syntax. Perhaps under a title like "Python Type Hints Reference", to follow the title of PEP 484 "Type Hints".
• Documentation of the use of the mypy tool itself. This would focus on the CLI and the workflow specific to the type-checker, plus any Mypy-specific details that are too involved to put into a "Mypy only" box in the Type Hints Reference. (The latter might then have a box that mostly just links to the relevant section of this document.) Perhaps the "Mypy Usage Reference"? A quick-start or tutorial section might have some small annotation examples in order to be self-contained for its purpose, but the bulk of the work of documenting how to write annotations would be left to the Type Hints Reference, which this would just link to.

A good first draft of the Python Type Hints Reference and Mypy Usage Reference might come from just taking the existing Mypy documentation and pulling it apart into two documents. Most of it would land in the Type Hints Reference, I think, and the Mypy Usage Reference would be relatively short.

The big value of making this distinction, though, comes if we can make the Python Type Hints Reference function as shared documentation across all the tools that implement PEP 484, including PyCharm and pytype, with the same kind of shared status as the PEP itself -- playing a role complementary to the PEP by addressing annotation-writers rather than implementors, having a more narrative style with more examples, and being readily editable with a low-friction pull-request workflow to continuously improve as exposition.

In particular:

• To the extent that the various tools that implement PEP 484 agree on details, this allows us all to share the effort of documenting them well, and allows our users (especially users of multiple tools!) to go to a common place to read about them.
• To the extent those agreed-on details aren't specified in the PEP, we should consider making them explicit there in any case. Or when the implementations happen to agree but we aren't yet confident of standardizing that for some reason, it'd be good to be explicit that that's the case where we do document those details.
• To the extent the implementations disagree, this is likely to cause grief to users who use multiple tools (e.g., Need a standard for searching stub files typing#184), and we should be discussing those details to find agreement (as we are in that thread) and putting that in the PEP.
• To the extent that the implementations disagree and we can't work out the differences, or haven't yet, users will benefit from explicitly documenting the disagreements. In a Type Hints Reference we might do this with boxes labeled "Mypy only:" and so on, like how the Library Reference documents differences between Python versions.

[gvanrossum]

Thanks! This sounds like a great plan. Eventually I expect that we'll have to have several separate docs on the type hints: formal reference docs describing the type system exactly and formally, and (somewhat) informal user docs that take users through the various parts of the type system, discussing warts and patterns for common situations.

Also, I think that we soon will have to come up with a way to add features to typing.py that are (at least initially) exclusive to mypy, so that mypy can develop somewhat faster than the PEP approval process.

Note that feedback and suggested improvements to the PEP (whether they're purely editorial or might require a formal discussion on python-{ideas,dev}) should start off as issues on the https://github.com/python/typing/ tracker.

[gnprice]

Yeah, that division may also make sense. I think of splitting documentation mainly in terms of who the audience is: people implementing the type system for Mypy, PyCharm, pytype, and other tools need one form of documentation, people who have gotten started writing type hints and are now doing so need another form, and people who are just getting started need a third form.

I think the core Python documentation, in the Language Reference and Library Reference, are a very successful model for the "user who's already gotten started" category, which is also generally the highest-volume category: there are many more users than implementors, and a user spends much more time already past the introductory stage than in it. The style is pretty formal and specific, but readable, and doesn't always nail things 100% down. So my hope is that a Type Hints Reference would be in the same style and similarly effective for that role.

The Language Reference and parts of the Library Reference also serve the "implementor" category to some degree, but that use case isn't stressed hard for Python because CPython is so well-established and dominant that in practice its accidental behavior is almost as important for other implementations' compatibility as any documented behavior. For type hints we'll need a more consciously formal and 100% exact document, even at the expense of readability. I think we might evolve PEP 484 into that document; if that doesn't make sense in the PEP format, I definitely agree we should find a way to have it somewhere.

For core Python, my experience has been that a lot of the role of "informal user docs" is actually served well by the Language Reference and the Library Reference, so I'd hope for a Type Hints Reference in a similar style to accomplish that as well. The main exception is for users just getting started. The Python Tutorial and a number of resources on the web serve that for core Python; we'll definitely want something for type hints as well. Because that tends to benefit from hands-on examples, I wonder if it might do best in the context of a particular tool, like as a Mypy tutorial.

[gvanrossum]

All very reasonable. PEP 484 was originally meant to be the formal 100%
exact spec, but falls short because I ran out of time and the focus of the
discussion was more on inclusion/exclusion of specific features than on
nailing down the included features -- everybody understood what they meant,
or we collectively didn't realize there were ambiguities (e.g. the recent
unresolved discussion about subclasses overriding methods in violation of
Liskov). But I would like the PEP to become the formal spec again.
Editorial suggestions are welcome at python/typing !

On Wed, Mar 2, 2016 at 11:54 AM, Greg Price [email protected]
wrote:

Yeah, that division may also make sense. I think of splitting
documentation mainly in terms of who the audience is: people implementing
the type system for Mypy, PyCharm, pytype, and other tools need one form of
documentation, people who have gotten started writing type hints and are
now doing so need another form, and people who are just getting started
need a third form.

I think the core Python documentation, in the Language Reference and
Library Reference, are a very successful model for the "user who's already
gotten started" category, which is also generally the highest-volume
category: there are many more users than implementors, and a user spends
much more time already past the introductory stage than in it. The style is
pretty formal and specific, but readable, and doesn't always nail things
100% down. So my hope is that a Type Hints Reference would be in the same
style and similarly effective for that role.

The Language Reference and parts of the Library Reference also serve the
"implementor" category to some degree, but that use case isn't stressed
hard for Python because CPython is so well-established and dominant that in
practice its accidental behavior is almost as important for other
implementations' compatibility as any documented behavior. For type hints
we'll need a more consciously formal and 100% exact document, even at the
expense of readability. I think we might evolve PEP 484 into that document;
if that doesn't make sense in the PEP format, I definitely agree we should
find a way to have it somewhere.

For core Python, my experience has been that a lot of the role of
"informal user docs" is actually served well by the Language Reference and
the Library Reference, so I'd hope for a Type Hints Reference in a similar
style to accomplish that as well. The main exception is for users just
getting started. The Python Tutorial and a number of resources on the web
serve that for core Python; we'll definitely want something for type hints
as well. Because that tends to benefit from hands-on examples, I wonder if
it might do best in the context of a particular tool, like as a Mypy
tutorial.

—
Reply to this email directly or view it on GitHub
#1262 (comment).

--Guido van Rossum (python.org/~guido)

[emmatyping]

I think this can be closed. We now have good docs for

typing and
mypy

Any move to create a reference for typing further than what is in the typing docs should probably be in an issue on the typing repo.