Add mention of PEP 3107.

Also clean up grammar and typos.

Finally, add some open issues to work out.

pep-0362.txt

@@ -17,10 +17,10 @@ Abstract
 Python has always supported powerful introspection capabilities,
 including that for functions and methods (for the rest of this PEP the
 word "function" refers to both functions and methods).  Taking a
-function object, you can fully reconstruct the function signature
+function object, you can fully reconstruct the function's signature
 using ``func_defaults``, ``func_code.co_argcount``,
 ``func_code.co_flags``, and ``func_code.co_varnames``.  Unfortunately
-this is a little unruly having to look at four different attributes
+it is a little unruly having to look at four different attributes
 to pull together complete information for a function's signature.
 
 This PEP proposes an object representation for function signatures.
@@ -34,9 +34,9 @@ Signature Object
 ================
 
 The overall signature of an object is represented by the Signature
-object.  This object is to store Parameter objects (discussed later)
-along with any information about the function itself and any
-parameters that are highly unique (.e.g, ``*args``).
+object.  This object is to store a `Parameter Object`_ for each
+parameter in the signature.  It is also to store any information
+about the function itself that is pertinent to the signature.
 
 A Signature object has the following structure attributes:
 
@@ -46,26 +46,24 @@ A Signature object has the following structure attributes:
     contained within.  This makes functions and methods
     indistinguishable from one another when passed to decorators,
     preventing proper creation of a fully qualified name.
-    indistinguishable from
 * var_args:str
-    Name of the ``*args`` parameter, if present, else the empty
+    Name of the ``*args`` parameter, if present, or the empty
     string.
 * var_kw_args:str
-    Name of the ``**kwargs`` parameter, if present, else the empty
+    Name of the ``**kwargs`` parameter, if present, or the empty
     string.
 * parameters:list(Parameter)
-    List of the parameters of the function are represented by
-    Parameter objects (see `Parameter Object`_ for their
-    description).
+    List of the parameters of the function as represented by
+    Parameter objects (see `Parameter Object`_).
 * __str__() -> str
     Return the string representation of the signature as it might
     appear in source code.
 * bind(\*args, \*\*kwargs) -> dict
-    Create a mapping from parameter to argument for the signature (see
-    `Open Issues`_ for question of how to handle tuples).
+    Create a mapping from parameter to argument for the signature.
 
 The Signature object is stored in the ``__signature__`` attribute of
-the function.  When it is to be created is an `Open Issues`_.
+the function.  When it is to be created is discussed in
+`Open Issues`_.
 
 
 Parameter Object
@@ -122,10 +120,10 @@ unpack properly, raising TypeError if it cannot reliably prove either
 way if the argument can be unpacked.
 
 
-Relation With Other PEPs
-========================
+Relation To Other PEPs
+======================
 
-"Keyword-Only Arguments [#pep-3102]_
+Keyword-Only Arguments [#pep-3102]_
 ------------------------------------
 
 If keyword-only parameters come into existence, the Parameter object
@@ -139,7 +137,26 @@ attribute.  But that would cause different types to be used in the
 attribute that are in no way compatible.  It also removes the ability
 to know the position number within the signature from the Paramter
 object itself.  Plus Guido preferred the original approach over this
-alternative.
+alternative.  This does mean, though, that how to set the position of
+an argument when ``*args`` is not at the end of the parameter list.
+
+
+Function Annotations [#pep-3107]_
+----------------------------------
+
+Support needs to be added for function annotations.  One option is to
+have two new attributes for each Parameter object: ``has_annotation``
+and ``annotation``.  This would remove any possible ambiguity in
+terms of what an annotation could be.
+
+But one could argue that the chances of someone setting an annotation
+to ``None`` is very low and thus allows it to be used as a value
+for a single ``annotation`` attribute to signify that no annotation
+was set.  But there is the slight issue of breaking from consistency
+compared to ``has_default``/``default_value``.
+
+Regardless of which approach is taken, Signature objects will also
+need to gain support for annotations for ``*args`` and ``**kwargs``.
 
 
 Open Issues
@@ -177,6 +194,28 @@ defines ``__iter__()`` it might be okay, or raise an exception stating
 that the binding could not be calculated with full confidence.
 
 
+How should ``Signature.bind`` handle ``*args`` and ``**kwargs``?
+------------------------------------------------------------------
+
+There are two possible approaches to how ``*args`` and ``**kwargs``
+should be returned by ``Signature.bind``.  One is to have their
+names as keys in the dictionary and their values be the list and
+dictionary that would be created.  Another is to have ``bind``
+return a three-item tuple of the parameters and their values, what
+the ``*args`` value would be bound to, and a dict of what
+``**kwargs`` would be set to.
+
+
+Should ``Signature.bind`` return Parameter objects as keys?
+-----------------------------------------------------------
+
+Instead of returning a dict with keys consisting of the name of the
+parameters, would it be more useful to instead return  Parameter
+objects?  The name of the argument can easily be retrieved.  It also
+removes any need of having to map parameter name to the Parameter
+object if that is desired.
+
+
 References
 ==========
 
@@ -189,6 +228,9 @@ References
 .. [#impl] Implementation of PEP 362
    (http://www.python.org/sf/1544909)
 
+.. [#pep-3107] Function Annotations
+   (http://www.python.org/dev/peps/pep-3107/)
+
 
 Copyright
 =========