[prev in list] [next in list] [prev in thread] [next in thread] 

List:       python-dev
Subject:    [Python-Dev] Enhancing generic type documentation in the standard library
From:       Luciano Ramalho <luciano () ramalho ! org>
Date:       2022-03-23 17:59:47
Message-ID: CALxg4FWb05Opi1=eSFc3Z0FfL3asKh1_1RkfFPo32ZX-80sZMw () mail ! gmail ! com
[Download RAW message or body]

Hello, everyone!

I believe our documentation about types needs another overhaul.

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-leave@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/


[prev in list] [next in list] [prev in thread] [next in thread]