Restore the prohibition against using function annotations in the standard library.

At Guido's request, added notes regarding issues observed with various developer's
early attempts to use function annotations.
This commit is contained in:
Raymond Hettinger 2012-04-22 21:32:34 -07:00
parent 4535decca5
commit c0b1eb3d65
1 changed files with 52 additions and 1 deletions

View File

@ -140,7 +140,7 @@ appropriately. The preferred place to break around a binary operator
is *after* the operator, not before it. Some examples::
class Rectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if (width == 0 and height == 0 and
@ -887,6 +887,57 @@ Programming Recommendations
No: if greeting == True:
Worse: if greeting is True:
- The Python standard library will not use function annotations as
that would result in a premature commitment to a particular
annotation style. Instead, the annotations are left for users to
discover and experiment with useful annotation styles.
Early core developer attempts to use function annotations revealed
inconsistent, ad-hoc annotation styles. For example:
* ``[str]`` was ambiguous as to whether it represented a list of
strings or a value that could be either *str* or *None*.
* The notation ``open(file:(str,bytes))`` was used for a value that
could be either *bytes* or *str* rather than a 2-tuple containing
a *str* value followed by a *bytes* value.
* The annotation ``seek(whence:int)`` exhibited an mix of
over-specification and under-specification: *int* is too
restrictive (anything with ``__index__`` would be allowed) and it
is not restrictive enough (only the values 0, 1, and 2 are
allowed). Likewise, the annotation ``write(b: bytes)`` was also
too restrictive (anything supporting the buffer protocol would be
allowed).
* Annotations such as ``read1(n: int=None)`` were self-contradictory
since *None* is not an *int*. Annotations such as
``source_path(self, fullname:str) -> object`` were confusing about
what the return type should be.
* In addition to the above, annotations were inconsistent in the use
of concrete types versus abstract types: *int* versus *Integral*
and set/frozenset versus MutableSet/Set.
* Some annotations in the abstract base classes were incorrect
specifications. For example, set-to-set operations require
*other* to be another instance of *Set* rather than just an
*Iterable*.
* A further issue was that annotations become part of the
specification but weren't being tested.
* In most cases, the docstrings already included the type
specifications and did so with greater clarity than the function
annotations. In the remaining cases, the docstrings were improved
once the annotations were removed.
* The observed function annotations were too ad-hoc and inconsistent
to work with a coherent system of automatic type checking or
argument validation. Leaving these annotations in the code would
have made it more difficult to make changes later so that
automated utilities could be supported.
References
==========