On Wed, 30 Mar 2022, 3:49 am Brett Cannon, <br...@python.org> wrote: > > > On Mon, Mar 28, 2022 at 3:58 PM Luciano Ramalho <luci...@ramalho.org> > wrote: > >> >> Documenting the generic types in the standard library is a much >> smaller task than turning the typing PEPs into specs. It seems like a >> good next step on the way to better typing docs. >> > > Since the typing-sig will likely be doing the work and driving such an > effort I would ask over there. I personally would love for a > typing.python.org or equivalent subsection of docs.python.org to exist. >
The import system gained its own subsection of the language reference to get info out of the historical PEPs. Perhaps gradual typing could go the same way, with the initial content being: * the type hinting docs for the builtin generics * pointers to the PEPs that provide the interim docs until the reference section is fleshed out (we used the latter trick to bootstrap the PyPA specs page without having to rewrite all the content: some of the pages are just pointers to the relevant PEP) Cheers, Nick. > -Brett > > >> >> Cheers, >> >> Luciano >> >> >> >> > >> > -Brett >> > >> >> >> >> >> >> We now have lots of generic types in the standard library, but their >> >> formal type parameters are poorly documented—or not documented at >> >> all—in the standard library documentation. >> >> >> >> More importantly: the documentation we have about specific >> >> covariant/contravariant types is now in entries in the `typing` module >> >> that are all deprecated since PEP 585 was implemented in Python 3.9. >> >> >> >> Below I present two of many examples where the documentation of a >> >> generic type is not great. >> >> >> >> However, if people agree this is a problem, we need to discuss where >> >> and how to put the documentation in a way that is not too disruptive >> >> to users of Python who don't know or don't care about type hints, for >> >> many reasons that we should not judge. >> >> >> >> For example, where do we document the fact that `dict` accepts two >> >> invariant formal type parameters, and that `frozenset` accepts one >> >> contravariant type parameter? >> >> >> >> What do you think? >> >> >> >> Cheers, >> >> >> >> Luciano >> >> >> >> _________________________________________ >> >> EXAMPLE 1: `Callable` variance is not documented >> >> >> >> For example, in the `Callable` type, the `ReturnType` parameter is >> >> covariant, and the `ParameterType` parameters are all contravariant. >> >> >> >> But there is no mention of variance in this entry: >> >> >> https://docs.python.org/3/library/typing.html?highlight=typing#typing.Callable >> >> >> >> Also, no mention of the fact that `collections.abc.Callable` is >> generic here: >> >> >> https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable >> >> >> >> PEP 483—The Theory of Type Hints—is the only official Python doc where >> >> I found the information about the variance of the formal type >> >> parameters of `Callable`. The explanation there is brilliant [0]. >> >> >> >> [0] https://peps.python.org/pep-0483/#covariance-and-contravariance >> >> >> >> Regardless, the intended audience of PEPs is "core developers"—which >> >> is neither a superset nor a subset of "Python devs now using type >> >> hints". We should not rely on PEPs to document features for Python >> >> users in general. >> >> >> >> _________________________________________ >> >> EXAMPLE 2: `Generator` variance could be better documented >> >> >> >> The entry for `typing.Generator` [1] has this heading: >> >> >> >> class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co]) >> >> >> >> Answer quickly: how many formal type parameters does `Generator` >> >> require? Which are covariant? Which are contravariant? >> >> >> >> [1] >> https://docs.python.org/3/library/typing.html?highlight=typing#typing.Generator >> >> >> >> Nowhere in that page [1] there's an explanation of the `*_co` and >> >> `*_contra` naming convention, much less their semantics. >> >> >> >> Fortunately, the text of the `typing.Generator` entry says: "A >> >> generator can be annotated by the generic type `Generator[YieldType, >> >> SendType, ReturnType]". >> >> >> >> Unfortunately, `typing.Generator` is deprecated and will be gone in 5 >> >> years or so... >> >> >> >> The same issue applies to all the other generic types: builtins >> >> (`dict`, `frozenset`), ABCs, etc. >> >> Their formal type parameters they accept as generics are either >> >> undocumented, or documented in parts of the `typing` module that are >> >> already deprecated. >> >> >> >> Thoughts? >> >> >> >> -- >> >> Luciano Ramalho >> >> | Author of Fluent Python (O'Reilly, 2015) >> >> | http://shop.oreilly.com/product/0636920032519.do >> >> | Technical Principal at ThoughtWorks >> >> | Twitter: @ramalhoorg >> >> _______________________________________________ >> >> Python-Dev mailing list -- python-dev@python.org >> >> To unsubscribe send an email to python-dev-le...@python.org >> >> https://mail.python.org/mailman3/lists/python-dev.python.org/ >> >> Message archived at >> https://mail.python.org/archives/list/python-dev@python.org/message/UGXWIADYG37N3ML4NBAKYF2C536HR273/ >> >> Code of Conduct: http://python.org/psf/codeofconduct/ >> >> >> >> -- >> Luciano Ramalho >> | Author of Fluent Python (O'Reilly, 2015) >> | http://shop.oreilly.com/product/0636920032519.do >> | Technical Principal at ThoughtWorks >> | Twitter: @ramalhoorg >> > _______________________________________________ > Python-Dev mailing list -- python-dev@python.org > To unsubscribe send an email to python-dev-le...@python.org > https://mail.python.org/mailman3/lists/python-dev.python.org/ > Message archived at > https://mail.python.org/archives/list/python-dev@python.org/message/UTTPDQ4KV37FM7GA73W6VF5NADS27BNS/ > Code of Conduct: http://python.org/psf/codeofconduct/ >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/5BXALS2452OOKJJXPZ2SM6J4627LJ3G6/ Code of Conduct: http://python.org/psf/codeofconduct/
