[docs] PEP 484 docs (issue 24272)

guido at python.org guido at python.org
Wed Jun 3 02:28:22 CEST 2015

Thank you again! I have made a full pass this time. I should mention
that I'm going on a long vacation starting this weekend so I may not be
available to do another round of review. But I may be able to commit
this if you address (most of) my feedback by Friday.

File Doc/library/typing.rst (right):

Doc/library/typing.rst:31: Url = str
Maybe use a more complex example, e.g.

  Vector = List[float]

? (It's okay if that's a forward reference to syntax that hasn't been
explained yet.)

Doc/library/typing.rst:33: Callable
Can you also document the special form Callable[..., <type>]? Here "..."
is a literal ellipsis, and the meaning is "don't type-check the args"
(it's described in the PEP).

Doc/library/typing.rst:59: from typing import Mapping, Set
Unfortunately we renamed the ABC Set to AbstractSet, and Set refers to
(the generic variant of) the concrete type 'set'. Maybe change the
example to use Sequence, which is an ABC?  (To clarify, the example with
Set[Employee] works, but it isn't using an ABC.)

Doc/library/typing.rst:80: A user-defined class can be defined as a
"a generic" -> either "generic" or "a generic class".

Doc/library/typing.rst:84: from typing import TypeVar, Generic
The example should also include "from logging import Logger".

Doc/library/typing.rst:103: self.logger.info('{}: {}'.format(self.name
Missing comma after self.name.

Doc/library/typing.rst:118: be constrained::
The mention of "constrained" here dangles a bit -- there's no example
immediately following of a constrained type variable.  (I think it's
different in the PEP.)

Doc/library/typing.rst:166: When the type of a value is object, the type
checker will reject almost all
I'd use `object`.

Doc/library/typing.rst:173: Version and platform checking
Drop this section.

Doc/library/typing.rst:196: def foo(x: AnyStr, y: AnyStr = ...) ->
AnyStr: ...
There is no definition of AnyStr, so this dangles a bit.

Doc/library/typing.rst:204: .. class:: Any(Final, metaclass=AnyMeta,
Don't mention the base classes. This also applies below.

Doc/library/typing.rst:208: * Any object is an instance of Any.
I'd use `Any` for all places where the word "Any" refers to the special
object `Any`.

Doc/library/typing.rst:229: '''Return a list containing n references to
I strongly prefer """ for docstrings.

Doc/library/typing.rst:237: of (str, str) -> str and (bytes, bytes) ->
bytes.  Also note
You're slacking on the backticks here. :-)

Doc/library/typing.rst:242: issubclass(C, T) is true for any class C,
and issubclass(str, A)
Actually, issubclass() involving type variables or other special objects
will probably start failing too in one of the next betas. Perhaps it's
better to say something like "you shouldn't use these".

Doc/library/typing.rst:250: Type variables can be introspected. e.g.::
I prefer not to document this for now.

Doc/library/typing.rst:258: .. class:: Union(Final, metaclass=UnionMeta,
Again, please don't list the base classes. (Same for every class below).

Doc/library/typing.rst:266: * None as an argument is a special case and
is replaced by
This is not unique to union -- this applies everywhere. So probably move
it up ahead.

Doc/library/typing.rst:285: * When two arguments have a subclass
relationship, the least
We're on thin ice with this bullet. I'd like to drop it. (The PEP
doesn't say this.)

Doc/library/typing.rst:294: * Corollary: if Any is present it is the
sole survivor, e.g.::
I'd remove "Corollary:" -- this is just another rule.

Doc/library/typing.rst:298: * Similar for object::
I'd drop this too.

Doc/library/typing.rst:302: * To cut a tie: `Union[object, Any] ==
Union[Any, object] == Any`.
Drop this too.

Doc/library/typing.rst:318: Tuple type; Tuple[X, Y] is the cross-product
type of X and Y.
I'd drop the "cross-product" concept -- it's very type-theoretic. I'd
just say this is the type of a tuple of two items with the first item of
type X and the second of type Y.

Doc/library/typing.rst:324: To specify a variable-length tuple of
homogeneous type, use `Sequence[T]`.
The PEP actually also supports Tuple[t, ...]. (And I'd use a lowercase t
because it doesn't have to be a type variable. Maybe use Tuple[int, ...]
as an example.

Doc/library/typing.rst:335: such function types are rarely used as
callback types.
But do add Callable[..., t] as a way to spell callable of any args
returning t.

Also note that plain Callable is equivalent to Callable[..., Any].

Doc/library/typing.rst:337: .. class:: Generic(metaclass=GenericMeta)
This looks (mostly?) redundant with the earlier discussion of Generic.

Doc/library/typing.rst:352: def lookup_name(mapping: Mapping, key: KT,
default: VT) -> VT:
Actually we changed our mind about this and you must write Mapping[KT,
VT] here (essentially making this the same as the next example).

Doc/library/typing.rst:445: .. function:: get_type_hints(obj,
globalns=None, localns=None)
I prefer not to document globalns/localns at this time.

Doc/library/typing.rst:453: .. warning::
Just drop this warning.

Doc/library/typing.rst:469: .. function:: overload(func)
Consider leaving this out.


More information about the docs mailing list