Clarify that stdlib experiments with annotations are not encouraged.

This commit is contained in:
Guido van Rossum 2016-01-05 15:25:40 -08:00
parent 544e54168a
commit 2d2ea7a703
1 changed files with 12 additions and 11 deletions

View File

@ -1257,10 +1257,11 @@ annotations are changing.
- The experimentation with annotation styles that was recommended
previously in this PEP is no longer encouraged.
- However, experiments within the rules of PEP 484 are now encouraged.
For example, marking up a large library with PEP 484 style type
annotations, reviewing how easy it was to add those annotations, and
observing whether their presence increases code understandabilty.
- However, outside the stdlib, experiments within the rules of PEP 484
are now encouraged. For example, marking up a large third party
library or application with PEP 484 style type annotations,
reviewing how easy it was to add those annotations, and observing
whether their presence increases code understandabilty.
- The Python standard library should be conservative in adopting such
annotations, but their use is allowed for new code and for big
@ -1280,12 +1281,12 @@ annotations are changing.
checking and should not alter their behavior based on annotations.
- Users who don't want to use type checkers are free to ignore them.
However, it is expected that users of library packages may want to
run type checkers over those library packages. For this purpose PEP
484 recommends the use of stub files: .pyi files that are read by
the type checker in preference of the corresponding .py files. Stub
files can be distributed with a library, or separately (with the
library author's permission) through the _typeshed_ repo [5]_.
However, it is expected that users of third party library packages
may want to run type checkers over those packages. For this purpose
PEP 484 recommends the use of stub files: .pyi files that are read
by the type checker in preference of the corresponding .py files.
Stub files can be distributed with a library, or separately (with
the library author's permission) through the typeshed repo [5]_.
- For code that needs to be backwards compatible, function annotations
can be added in the form of comments. Basically, this Python 3 annotation::
@ -1301,7 +1302,7 @@ annotations are changing.
"""Embezzle funds from account using fake receipts."""
<code goes here>
The _mypy_ type checker [6]_ currently supports this syntax, and other
The mypy type checker [6]_ currently supports this syntax, and other
type checkers are encouraged to adopt it.