[docs] Tutorial section on function annotations is out of date re: PEP 484 (issue 23932)

zachary.ware at gmail.com zachary.ware at gmail.com
Mon Apr 13 17:41:36 CEST 2015


Reviewers: ,


http://bugs.python.org/review/23932/diff/14513/Doc/tutorial/controlflow.rst
File Doc/tutorial/controlflow.rst (right):

http://bugs.python.org/review/23932/diff/14513/Doc/tutorial/controlflow.rst#newcode678
Doc/tutorial/controlflow.rst:678: Python will use annotations as type
hints for static analyzer and overloading
Python itself won't use them, though; we're leaving that up to
third-party type-checking tools (for now and the foreseeable future).

http://bugs.python.org/review/23932/diff/14513/Doc/tutorial/controlflow.rst#newcode690
Doc/tutorial/controlflow.rst:690: >>> def f(a: str, b: str = 'bar') ->
str:
Can come up with a better example keeping with something referring to
the Flying Circus? Foo and bar are boring and this is Python :)

http://bugs.python.org/review/23932/diff/14513/Doc/tutorial/controlflow.rst#newcode700
Doc/tutorial/controlflow.rst:700: .. warning::
I think this can just be left out, really.  Since this is in the
tutorial, we don't need to go into all of the nitty-gritty details, just
show the syntax and give a link to more information (the PEP link).



Please review this at http://bugs.python.org/review/23932/

Affected files:
  Doc/tutorial/controlflow.rst


diff -r 37905786b34b Doc/tutorial/controlflow.rst
--- a/Doc/tutorial/controlflow.rst	Sun Apr 12 23:24:17 2015 -0500
+++ b/Doc/tutorial/controlflow.rst	Mon Apr 13 11:25:56 2015 -0400
@@ -673,11 +673,10 @@
    pair: function; annotations
    single: -> (return annotation assignment)
 
-:ref:`Function annotations <function>` are completely optional,
-arbitrary metadata information about user-defined functions.  Neither Python
-itself nor the standard library use function annotations in any way; this
-section just shows the syntax. Third-party projects are free to use function
-annotations for documentation, type checking, and other uses.
+:ref:`Function annotations <function>` are completely optional metadata
+information about user-defined functions. If the annotations are provided,
+Python will use annotations as type hints for static analyzer and overloading
+methods (:pep:`484`).
 
 Annotations are stored in the :attr:`__annotations__` attribute of the function
 as a dictionary and have no effect on any other part of the function.  Parameter
@@ -688,14 +687,23 @@
 following example has a positional argument, a keyword argument, and the return
 value annotated with nonsense::
 
-   >>> def f(ham: 42, eggs: int = 'spam') -> "Nothing to see here":
+   >>> def f(a: str, b: str = 'bar') -> str:
    ...     print("Annotations:", f.__annotations__)
-   ...     print("Arguments:", ham, eggs)
+   ...     print("Arguments:", a, b)
+   ...     return a + b
    ...
-   >>> f('wonderful')
-   Annotations: {'eggs': <class 'int'>, 'return': 'Nothing to see here', 'ham': 42}
-   Arguments: wonderful spam
+   >>> f('sample')
+   Annotations: {'a': <class 'str'>, 'return': <class 'str'>, 'b': <class 'str'>}
+   Arguments: sample bar
+   'samplebar'
 
+.. warning::
+
+   In Python 3.0-3.5, :ref:`function annotations <function>` are still completely
+   optional, arbitrary metadata information about user-defined functions.
+   Neither Python itself nor the standard library use function annotations in
+   any way; this section just shows the syntax. Third-party projects are free to
+   use function annotations for documentation, type checking, and other uses.
 
 .. _tut-codingstyle:
 




More information about the docs mailing list