Consider including discussion of "type completeness"

[erictraut]

One of the ideas we’d really like to push is the notion of “type completeness” for library interfaces. Getting to type completeness will be a journey and a large investment for many library maintainers, but I think it’s important for guidance to paint a picture of the future we want to see.

Would you be open to formalizing the notion of “type completeness” and including this in the PEP, or do you think that would be out of place?

For details about how we have been thinking about type completeness, refer to this document.

Incidentally, I already have a mode in pyright that computes the type completeness of a “py.typed” package and reports which percentage of symbols are fully typed (as opposed to partially or fully untyped).

[srittau]

I am sorry for the delay. I still plan on looking at this, but haven't found the time, yet.

[srittau]

@erictraut We're integrating this PEP into the typing docs (https://github.com/python/typing/tree/master/docs). Maybe your document would be appropriate there as well?

[erictraut]

@srittau, thanks for the suggestion.

Have you read the full document Type Completeness for Python Libraries? Do you agree with all of its contents, or do you have feedback? I haven't received much feedback, so the contents are largely unchanged from my original draft. I would want to make sure that there's a level of agreement before posting it to the python/typing site.

Do you think we should incorporate the entire document? Parts of it? Just include a link to it?

[srittau]

@erictraut I finally managed to read it, sorry for taking so long. There are certainly details that can be discussed, but nothing "outrageous" that we shouldn't recommend. For now, I think the document could be well included into the typing docs as is. After that, a few changes I would recommend:

• Convert to restructed text to fit with the rest of the typing docs (and Python docs in general).
• Update a few recommended practices like using list instead of List.
• Add a link to the existing stubs document.

In the long run, I think this would make a good basis for a "How to type annotate a library" document. It makes sense to me to split out some chapters into separate documents, possibly merging them with existing or new texts. For example, the best practices section could be merged with some recommendations from the stubs document to form a new general "best practices" document (see also python/typing#851). In python/typing#845 I have some ideas on how to structure the documentation.

[erictraut]

You're welcome to incorporate the document as is. I'm not sure where it needs to go, so I'll leave that to you.

If you'd like help writing a "How to type annotate a library" document, I'd be interested in authoring or contributing. If that's something you're interested in, it would help me get started if you would create a placeholder document in the desired location and file format. I could then work on filling in content and submit a PR (or series of PRs) for your review.