[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