[Python-checkins] peps: Update PEP 484 with recommended Python 2 alternative.

[guido.van.rossum]

https://hg.python.org/peps/rev/06f8470390c2
changeset:   6166:06f8470390c2
user:        Guido van Rossum <guido at python.org>
date:        Mon Jan 11 09:36:24 2016 -0800
summary:
  Update PEP 484 with recommended Python 2 alternative.

files:
  pep-0484.txt |  46 ++++++++++++++++++++++++++++++++++++++++
  1 files changed, 46 insertions(+), 0 deletions(-)


diff --git a/pep-0484.txt b/pep-0484.txt
--- a/pep-0484.txt
+++ b/pep-0484.txt
@@ -1372,6 +1372,52 @@
   results (generic over ``AnyStr``)
 
 
+Suggested syntax for Python 2.7 and straddling code
+===================================================
+
+Some tools may want to support type annotations in code that must be
+compatible with Python 2.7.  For this purpose this PEP has a suggested
+(but not mandatory) extension where function annotations are placed in
+a ``# type:`` comment.  Such a comment must be placed immediately
+following the function header (before the docstring).  An example: the
+following Python 3 code::
+
+  def embezzle(self, account: str, funds: int = 1000000, *fake_receipts: str) -> None:
+      """Embezzle funds from account using fake receipts."""
+      <code goes here>
+
+is equivalent to the following::
+
+  def embezzle(self, account, funds=1000000, *fake_receipts):
+      # type: (str, int, *str) -> None
+      """Embezzle funds from account using fake receipts."""
+      <code goes here>
+
+Notes:
+
+- Tools that support this syntax should support it regardless of the
+  Python version being checked.  This is necessary in order to support
+  code that straddles Python 2 and Python 3.
+
+- Every argument must be accounted for, except the first argument of
+  instance and class methods.
+
+- The return type is mandatory.  If in Python 3 you would omit some
+  argument or the return type, the Python 2 notation should use
+  ``Any``.
+
+- For ``*args`` and ``**kwds``, put 1 or 2 stars in front of the
+  corresponding type annotation.  (As with Python 3 annotations, the
+  annotation here denotes the type of the individual argument values,
+  not of the tuple/dict that you receive as the special argument value
+  ``args`` or ``kwds``.)
+
+- Like other type comments, any names used in the annotations must be
+  imported or defined by the module containing the annotation.
+
+- The entire annotation must be one line.
+
+
 Rejected Alternatives
 =====================
 

-- 
Repository URL: https://hg.python.org/peps