[docs] PEP 484 docs (issue 24272)

[guido at python.org]

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.


http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst
File Doc/library/typing.rst (right):

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode31
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.)

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode33
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).

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode59
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.)

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode80
Doc/library/typing.rst:80: A user-defined class can be defined as a
generic.
"a generic" -> either "generic" or "a generic class".

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode84
Doc/library/typing.rst:84: from typing import TypeVar, Generic
The example should also include "from logging import Logger".

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode103
Doc/library/typing.rst:103: self.logger.info('{}: {}'.format(self.name
message))
Missing comma after self.name.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode118
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.)

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode166
Doc/library/typing.rst:166: When the type of a value is object, the type
checker will reject almost all
I'd use `object`.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode173
Doc/library/typing.rst:173: Version and platform checking
Drop this section.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode196
Doc/library/typing.rst:196: def foo(x: AnyStr, y: AnyStr = ...) ->
AnyStr: ...
There is no definition of AnyStr, so this dangles a bit.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode204
Doc/library/typing.rst:204: .. class:: Any(Final, metaclass=AnyMeta,
_root=True)
Don't mention the base classes. This also applies below.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode208
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`.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode229
Doc/library/typing.rst:229: '''Return a list containing n references to
x.'''
I strongly prefer """ for docstrings.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode237
Doc/library/typing.rst:237: of (str, str) -> str and (bytes, bytes) ->
bytes.  Also note
You're slacking on the backticks here. :-)

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode242
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".

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode250
Doc/library/typing.rst:250: Type variables can be introspected. e.g.::
I prefer not to document this for now.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode258
Doc/library/typing.rst:258: .. class:: Union(Final, metaclass=UnionMeta,
_root=True)
Again, please don't list the base classes. (Same for every class below).

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode266
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.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode285
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.)

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode294
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.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode298
Doc/library/typing.rst:298: * Similar for object::
I'd drop this too.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode302
Doc/library/typing.rst:302: * To cut a tie: `Union[object, Any] ==
Union[Any, object] == Any`.
Drop this too.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode318
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.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode324
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.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode335
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].

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode337
Doc/library/typing.rst:337: .. class:: Generic(metaclass=GenericMeta)
This looks (mostly?) redundant with the earlier discussion of Generic.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode352
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).

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode445
Doc/library/typing.rst:445: .. function:: get_type_hints(obj,
globalns=None, localns=None)
I prefer not to document globalns/localns at this time.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode453
Doc/library/typing.rst:453: .. warning::
Just drop this warning.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode469
Doc/library/typing.rst:469: .. function:: overload(func)
Consider leaving this out.

http://bugs.python.org/review/24272/