Add __str__() and bind() to Signature and __str__() to Parameter.

pep-0362.txt

@@ -57,6 +57,12 @@ A Signature object has the following structure attributes:
     List of the parameters of the function are represented by
     Parameter objects (see `Parameter Object`_ for their
     description).
+* __str__() -> str
+    Return the string representation of the signature as it might
+    appear in source code.
+* bind(\*args, \*\*kwargs) -> dict
+    Create a mapping from argument to parameter for the signature (see
+    `Open Issues`_ for question of how to handle tuples).
 
 The Signature object is stored in the ``__signature__`` attribute of
 the function.  When it is to be created is an `Open Issues`_.
@@ -95,6 +101,9 @@ The structure of the Parameter object is:
     attribute does not exist.  This is done so that the attribute is
     not accidentally used if no default value is set as any default
     value could be a legitimate default value itself.
+* __str__() -> str
+    Return the string representation of the parameter as it might
+    appear in source code in a function signature.
 
 
 Implementation
@@ -107,6 +116,11 @@ returns the value stored on the ``__signature__`` attribute (for
 methods this is stored directly on the im_func function object since
 that is what decorators will work with).
 
+For the `Open Issues`_ question of how to handle tuples, the current
+implementation does the best it can to determine if the argument will
+unpack properly, raising TypeError if it cannot reliably prove either
+way if the argument can be unpacked.
+
 
 Relation With Other PEPs
 ========================
@@ -142,6 +156,27 @@ generate the Signature object and store it to ``__signature__`` if
 needed, and then return the value of ``__signature__``.
 
 
+How to handle tuples for ``Signature.bind()``?
+----------------------------------------------
+
+Tuples pose an interesting problem for generating the mapping from
+arguments to parameters.  If one wants ``Signature.bind()`` to do the
+full mapping, then the unpacking of an argument tuple's values must be
+done and then have those values bound to the proper parameter.  This
+could be a problem since this would require using the iterator to
+verify the binding and thus could possibly make the iterator worthless
+for actual use in a function call later.
+
+But if one wants parameters to be based on what is a single positional
+argument, then the tuple should not be unpacked.  This means that for
+tuples one can do the best they can to verify that the argument will
+unpack properly without running an iterator.  But if an object is
+passed in that does not define ``__len__()`` and ``__getitem__()`` for
+verifying unpacking, then one can either just assume that if it
+defines ``__iter__()`` it might be okay, or raise an exception stating
+that the binding could not be calculated with full confidence.
+
+
 References
 ==========