Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(43472)

#24272: PEP 484 docs

Can't Edit
Can't Publish+Mail
Start Review
Created:
4 years, 4 months ago by guido
Modified:
4 years, 1 month ago
Reviewers:
levkivskyi
CC:
gvanrossum, larry, docs_python.org, Mark.Shannon, devnull_psf.upfronthosting.co.za, berkerpeksag, Daniel.Andrade.Groppe, levkivskyi
Visibility:
Public.

Patch Set 1 #

Patch Set 2 #

Total comments: 60

Patch Set 3 #

Patch Set 4 #

Patch Set 5 #

Unified diffs Side-by-side diffs Delta from patch set Stats Patch
Doc/library/typing.rst View 1 2 3 4 1 chunk +48 lines, -3 lines 0 comments Download

Messages

Total messages: 3
gvanrossum
Thank you so much for getting this started! I will try to give a more ...
4 years, 4 months ago #1
gvanrossum
Thank you again! I have made a full pass this time. I should mention that ...
4 years, 3 months ago #2
levkivskyi
4 years, 1 month ago #3
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
On 2015/06/03 02:28:22, gvanrossum wrote:
> 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.)

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode33
Doc/library/typing.rst:33: Callable
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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).

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode59
Doc/library/typing.rst:59: from typing import Mapping, Set
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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.)

Done.

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.
On 2015/06/03 02:28:23, gvanrossum wrote:
> "a generic" -> either "generic" or "a generic class".

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode84
Doc/library/typing.rst:84: from typing import TypeVar, Generic
On 2015/06/03 02:28:23, gvanrossum wrote:
> The example should also include "from logging import Logger".

Done.

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))
On 2015/06/03 02:28:23, gvanrossum wrote:
> Missing comma after self.name.

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode118
Doc/library/typing.rst:118: be constrained::
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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.)

Done.

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
On 2015/06/03 02:28:23, gvanrossum wrote:
> I'd use `object`.

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode173
Doc/library/typing.rst:173: Version and platform checking
On 2015/06/03 02:28:23, gvanrossum wrote:
> Drop this section.

Done.

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: ...
On 2015/06/03 02:28:23, gvanrossum wrote:
> There is no definition of AnyStr, so this dangles a bit.

Done.

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)
On 2015/06/03 02:28:23, gvanrossum wrote:
> Don't mention the base classes. This also applies below.

Done.

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.
On 2015/06/03 02:28:23, gvanrossum wrote:
> I'd use `Any` for all places where the word "Any" refers to the special object
> `Any`.

Done.

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.'''
On 2015/06/03 02:28:23, gvanrossum wrote:
> I strongly prefer """ for docstrings.

Done.

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
On 2015/06/03 02:28:23, gvanrossum wrote:
> You're slacking on the backticks here. :-)

Done.

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)
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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".

Done.

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.::
On 2015/06/03 02:28:23, gvanrossum wrote:
> I prefer not to document this for now.

Done.

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)
On 2015/06/03 02:28:23, gvanrossum wrote:
> Again, please don't list the base classes. (Same for every class below).

I removed base classes, except for a few at the end, where they could be
helpful, (like Generic[T_co], etc).

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
On 2015/06/03 02:28:23, gvanrossum wrote:
> This is not unique to union -- this applies everywhere. So probably move it up
> ahead.

Done.

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
On 2015/06/03 02:28:23, gvanrossum wrote:
> We're on thin ice with this bullet. I'd like to drop it. (The PEP doesn't say
> this.)

Done.

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.::
On 2015/06/03 02:28:23, gvanrossum wrote:
> I'd remove "Corollary:" -- this is just another rule.

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode298
Doc/library/typing.rst:298: * Similar for object::
On 2015/06/03 02:28:23, gvanrossum wrote:
> I'd drop this too.

Done.

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`.
On 2015/06/03 02:28:23, gvanrossum wrote:
> Drop this too.

Done.

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.
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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.

Done.

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]`.
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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.

Done.

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.
On 2015/06/03 02:28:23, gvanrossum wrote:
> 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].

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode337
Doc/library/typing.rst:337: .. class:: Generic(metaclass=GenericMeta)
On 2015/06/03 02:28:23, gvanrossum wrote:
> This looks (mostly?) redundant with the earlier discussion of Generic.

I think it is OK to keep this section, although it is a bit redundant, indeed.

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:
On 2015/06/03 02:28:23, gvanrossum wrote:
> Actually we changed our mind about this and you must write Mapping[KT, VT]
here
> (essentially making this the same as the next example).

Done.

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)
On 2015/06/03 02:28:23, gvanrossum wrote:
> I prefer not to document globalns/localns at this time.

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode453
Doc/library/typing.rst:453: .. warning::
On 2015/06/03 02:28:23, gvanrossum wrote:
> Just drop this warning.

Done.

http://bugs.python.org/review/24272/diff/14930/Doc/library/typing.rst#newcode469
Doc/library/typing.rst:469: .. function:: overload(func)
On 2015/06/03 02:28:23, gvanrossum wrote:
> Consider leaving this out.

Done.
Sign in to reply to this message.

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+