Merge pull request #6932 from takluyver/help-signatures

Better support for wrapped function signatures in help

IPython/core/oinspect.py

@@ -1,918 +1,919 b''
 # -*- coding: utf-8 -*-
 """Tools for inspecting Python objects.
 
 Uses syntax highlighting for presenting the various information elements.
 
 Similar in spirit to the inspect module, but all calls take a name argument to
 reference the name under which an object is being read.
 """
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from __future__ import print_function
 
 __all__ = ['Inspector','InspectColors']
 
 # stdlib modules
 import inspect
 import linecache
 import os
 from textwrap import dedent
 import types
 import io as stdlib_io
 
 try:
     from itertools import izip_longest
 except ImportError:
     from itertools import zip_longest as izip_longest
 
 # IPython's own
 from IPython.core import page
 from IPython.lib.pretty import pretty
 from IPython.testing.skipdoctest import skip_doctest_py3
 from IPython.utils import PyColorize
 from IPython.utils import io
 from IPython.utils import openpy
 from IPython.utils import py3compat
 from IPython.utils.dir2 import safe_hasattr
 from IPython.utils.text import indent
 from IPython.utils.wildcard import list_namespace
 from IPython.utils.coloransi import TermColors, ColorScheme, ColorSchemeTable
 from IPython.utils.py3compat import cast_unicode, string_types, PY3
+from IPython.utils.signatures import signature
 
 # builtin docstrings to ignore
 _func_call_docstring = types.FunctionType.__call__.__doc__
 _object_init_docstring = object.__init__.__doc__
 _builtin_type_docstrings = {
     inspect.getdoc(t) for t in (types.ModuleType, types.MethodType,
                                 types.FunctionType, property)
 }
 
 _builtin_func_type = type(all)
 _builtin_meth_type = type(str.upper)  # Bound methods have the same type as builtin functions
 #****************************************************************************
 # Builtin color schemes
 
 Colors = TermColors  # just a shorthand
 
 # Build a few color schemes
 NoColor = ColorScheme(
     'NoColor',{
     'header' : Colors.NoColor,
     'normal' : Colors.NoColor  # color off (usu. Colors.Normal)
     }  )
 
 LinuxColors = ColorScheme(
     'Linux',{
     'header' : Colors.LightRed,
     'normal' : Colors.Normal  # color off (usu. Colors.Normal)
     } )
 
 LightBGColors = ColorScheme(
     'LightBG',{
     'header' : Colors.Red,
     'normal' : Colors.Normal  # color off (usu. Colors.Normal)
     }  )
 
 # Build table of color schemes (needed by the parser)
 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
                                  'Linux')
 
 #****************************************************************************
 # Auxiliary functions and objects
 
 # See the messaging spec for the definition of all these fields.  This list
 # effectively defines the order of display
 info_fields = ['type_name', 'base_class', 'string_form', 'namespace',
                'length', 'file', 'definition', 'docstring', 'source',
                'init_definition', 'class_docstring', 'init_docstring',
                'call_def', 'call_docstring',
                # These won't be printed but will be used to determine how to
                # format the object
                'ismagic', 'isalias', 'isclass', 'argspec', 'found', 'name'
                ]
 
 
 def object_info(**kw):
     """Make an object info dict with all fields present."""
     infodict = dict(izip_longest(info_fields, [None]))
     infodict.update(kw)
     return infodict
 
 
 def get_encoding(obj):
     """Get encoding for python source file defining obj
 
     Returns None if obj is not defined in a sourcefile.
     """
     ofile = find_file(obj)
     # run contents of file through pager starting at line where the object
     # is defined, as long as the file isn't binary and is actually on the
     # filesystem.
     if ofile is None:
         return None
     elif ofile.endswith(('.so', '.dll', '.pyd')):
         return None
     elif not os.path.isfile(ofile):
         return None
     else:
         # Print only text files, not extension binaries.  Note that
         # getsourcelines returns lineno with 1-offset and page() uses
         # 0-offset, so we must adjust.
         with stdlib_io.open(ofile, 'rb') as buffer:   # Tweaked to use io.open for Python 2
             encoding, lines = openpy.detect_encoding(buffer.readline)
         return encoding
 
 def getdoc(obj):
     """Stable wrapper around inspect.getdoc.
 
     This can't crash because of attribute problems.
 
     It also attempts to call a getdoc() method on the given object.  This
     allows objects which provide their docstrings via non-standard mechanisms
     (like Pyro proxies) to still be inspected by ipython's ? system."""
     # Allow objects to offer customized documentation via a getdoc method:
     try:
         ds = obj.getdoc()
     except Exception:
         pass
     else:
         # if we get extra info, we add it to the normal docstring.
         if isinstance(ds, string_types):
             return inspect.cleandoc(ds)
     
     try:
         docstr = inspect.getdoc(obj)
         encoding = get_encoding(obj)
         return py3compat.cast_unicode(docstr, encoding=encoding)
     except Exception:
         # Harden against an inspect failure, which can occur with
         # SWIG-wrapped extensions.
         raise
         return None
 
 
 def getsource(obj, oname=''):
     """Wrapper around inspect.getsource.
 
     This can be modified by other projects to provide customized source
     extraction.
 
     Parameters
     ----------
     obj : object
         an object whose source code we will attempt to extract
     oname : str
         (optional) a name under which the object is known
 
     Returns
     -------
     src : unicode or None
 
     """
 
     if isinstance(obj, property):
         sources = []
         for attrname in ['fget', 'fset', 'fdel']:
             fn = getattr(obj, attrname)
             if fn is not None:
                 encoding = get_encoding(fn)
                 oname_prefix = ('%s.' % oname) if oname else ''
                 sources.append(cast_unicode(
                     ''.join(('# ', oname_prefix, attrname)),
                     encoding=encoding))
                 if inspect.isfunction(fn):
                     sources.append(dedent(getsource(fn)))
                 else:
                     # Default str/repr only prints function name,
                     # pretty.pretty prints module name too.
                     sources.append(cast_unicode(
                         '%s%s = %s\n' % (
                             oname_prefix, attrname, pretty(fn)),
                         encoding=encoding))
         if sources:
             return '\n'.join(sources)
         else:
             return None
 
     else:
         # Get source for non-property objects.
 
         # '__wrapped__' attribute is used by some decorators (e.g. ones defined
         # functools) to provide access to the decorated function.
         if hasattr(obj, "__wrapped__"):
             obj = obj.__wrapped__
 
         try:
             src = inspect.getsource(obj)
         except TypeError:
             # The object itself provided no meaningful source, try looking for
             # its class definition instead.
             if hasattr(obj, '__class__'):
                 try:
                     src = inspect.getsource(obj.__class__)
                 except TypeError:
                     return None
 
         encoding = get_encoding(obj)
         return cast_unicode(src, encoding=encoding)
 
 
 def is_simple_callable(obj):
     """True if obj is a function ()"""
     return (inspect.isfunction(obj) or inspect.ismethod(obj) or \
             isinstance(obj, _builtin_func_type) or isinstance(obj, _builtin_meth_type))
 
 
 def getargspec(obj):
     """Wrapper around :func:`inspect.getfullargspec` on Python 3, and
     :func:inspect.getargspec` on Python 2.
     
     In addition to functions and methods, this can also handle objects with a
     ``__call__`` attribute.
     """
     if safe_hasattr(obj, '__call__') and not is_simple_callable(obj):
         obj = obj.__call__
 
     return inspect.getfullargspec(obj) if PY3 else inspect.getargspec(obj)
 
 
 def format_argspec(argspec):
     """Format argspect, convenience wrapper around inspect's.
 
     This takes a dict instead of ordered arguments and calls
     inspect.format_argspec with the arguments in the necessary order.
     """
     return inspect.formatargspec(argspec['args'], argspec['varargs'],
                                  argspec['varkw'], argspec['defaults'])
 
 
 def call_tip(oinfo, format_call=True):
     """Extract call tip data from an oinfo dict.
 
     Parameters
     ----------
     oinfo : dict
 
     format_call : bool, optional
       If True, the call line is formatted and returned as a string.  If not, a
       tuple of (name, argspec) is returned.
 
     Returns
     -------
     call_info : None, str or (str, dict) tuple.
       When format_call is True, the whole call information is formattted as a
       single string.  Otherwise, the object's name and its argspec dict are
       returned.  If no call information is available, None is returned.
 
     docstring : str or None
       The most relevant docstring for calling purposes is returned, if
       available.  The priority is: call docstring for callable instances, then
       constructor docstring for classes, then main object's docstring otherwise
       (regular functions).
     """
     # Get call definition
     argspec = oinfo.get('argspec')
     if argspec is None:
         call_line = None
     else:
         # Callable objects will have 'self' as their first argument, prune
         # it out if it's there for clarity (since users do *not* pass an
         # extra first argument explicitly).
         try:
             has_self = argspec['args'][0] == 'self'
         except (KeyError, IndexError):
             pass
         else:
             if has_self:
                 argspec['args'] = argspec['args'][1:]
 
         call_line = oinfo['name']+format_argspec(argspec)
 
     # Now get docstring.
     # The priority is: call docstring, constructor docstring, main one.
     doc = oinfo.get('call_docstring')
     if doc is None:
         doc = oinfo.get('init_docstring')
     if doc is None:
         doc = oinfo.get('docstring','')
 
     return call_line, doc
 
 
 def find_file(obj):
     """Find the absolute path to the file where an object was defined.
 
     This is essentially a robust wrapper around `inspect.getabsfile`.
 
     Returns None if no file can be found.
 
     Parameters
     ----------
     obj : any Python object
 
     Returns
     -------
     fname : str
       The absolute path to the file where the object was defined.
     """
     # get source if obj was decorated with @decorator
     if safe_hasattr(obj, '__wrapped__'):
         obj = obj.__wrapped__
 
     fname = None
     try:
         fname = inspect.getabsfile(obj)
     except TypeError:
         # For an instance, the file that matters is where its class was
         # declared.
         if hasattr(obj, '__class__'):
             try:
                 fname = inspect.getabsfile(obj.__class__)
             except TypeError:
                 # Can happen for builtins
                 pass
     except:
         pass
     return cast_unicode(fname)
 
 
 def find_source_lines(obj):
     """Find the line number in a file where an object was defined.
 
     This is essentially a robust wrapper around `inspect.getsourcelines`.
 
     Returns None if no file can be found.
 
     Parameters
     ----------
     obj : any Python object
 
     Returns
     -------
     lineno : int
       The line number where the object definition starts.
     """
     # get source if obj was decorated with @decorator
     if safe_hasattr(obj, '__wrapped__'):
         obj = obj.__wrapped__
     
     try:
         try:
             lineno = inspect.getsourcelines(obj)[1]
         except TypeError:
             # For instances, try the class object like getsource() does
             if hasattr(obj, '__class__'):
                 lineno = inspect.getsourcelines(obj.__class__)[1]
             else:
                 lineno = None
     except:
         return None
 
     return lineno
 
 
 class Inspector:
     def __init__(self, color_table=InspectColors,
                  code_color_table=PyColorize.ANSICodeColors,
                  scheme='NoColor',
                  str_detail_level=0):
         self.color_table = color_table
         self.parser = PyColorize.Parser(code_color_table,out='str')
         self.format = self.parser.format
         self.str_detail_level = str_detail_level
         self.set_active_scheme(scheme)
 
     def _getdef(self,obj,oname=''):
         """Return the call signature for any callable object.
 
         If any exception is generated, None is returned instead and the
         exception is suppressed."""
         try:
-            hdef = oname + inspect.formatargspec(*getargspec(obj))
+            hdef = oname + str(signature(obj))
             return cast_unicode(hdef)
         except:
             return None
 
     def __head(self,h):
         """Return a header string with proper colors."""
         return '%s%s%s' % (self.color_table.active_colors.header,h,
                            self.color_table.active_colors.normal)
 
     def set_active_scheme(self, scheme):
         self.color_table.set_active_scheme(scheme)
         self.parser.color_table.set_active_scheme(scheme)
 
     def noinfo(self, msg, oname):
         """Generic message when no information is found."""
         print('No %s found' % msg, end=' ')
         if oname:
             print('for %s' % oname)
         else:
             print()
 
     def pdef(self, obj, oname=''):
         """Print the call signature for any callable object.
 
         If the object is a class, print the constructor information."""
 
         if not callable(obj):
             print('Object is not callable.')
             return
 
         header = ''
 
         if inspect.isclass(obj):
             header = self.__head('Class constructor information:\n')
             obj = obj.__init__
         elif (not py3compat.PY3) and type(obj) is types.InstanceType:
             obj = obj.__call__
 
         output = self._getdef(obj,oname)
         if output is None:
             self.noinfo('definition header',oname)
         else:
             print(header,self.format(output), end=' ', file=io.stdout)
 
     # In Python 3, all classes are new-style, so they all have __init__.
     @skip_doctest_py3
     def pdoc(self,obj,oname='',formatter = None):
         """Print the docstring for any object.
 
         Optional:
         -formatter: a function to run the docstring through for specially
         formatted docstrings.
 
         Examples
         --------
 
         In [1]: class NoInit:
            ...:     pass
 
         In [2]: class NoDoc:
            ...:     def __init__(self):
            ...:         pass
 
         In [3]: %pdoc NoDoc
         No documentation found for NoDoc
 
         In [4]: %pdoc NoInit
         No documentation found for NoInit
 
         In [5]: obj = NoInit()
 
         In [6]: %pdoc obj
         No documentation found for obj
 
         In [5]: obj2 = NoDoc()
 
         In [6]: %pdoc obj2
         No documentation found for obj2
         """
 
         head = self.__head  # For convenience
         lines = []
         ds = getdoc(obj)
         if formatter:
             ds = formatter(ds)
         if ds:
             lines.append(head("Class docstring:"))
             lines.append(indent(ds))
         if inspect.isclass(obj) and hasattr(obj, '__init__'):
             init_ds = getdoc(obj.__init__)
             if init_ds is not None:
                 lines.append(head("Init docstring:"))
                 lines.append(indent(init_ds))
         elif hasattr(obj,'__call__'):
             call_ds = getdoc(obj.__call__)
             if call_ds:
                 lines.append(head("Call docstring:"))
                 lines.append(indent(call_ds))
 
         if not lines:
             self.noinfo('documentation',oname)
         else:
             page.page('\n'.join(lines))
 
     def psource(self, obj, oname=''):
         """Print the source code for an object."""
 
         # Flush the source cache because inspect can return out-of-date source
         linecache.checkcache()
         try:
             src = getsource(obj, oname=oname)
         except Exception:
             src = None
 
         if src is None:
             self.noinfo('source', oname)
         else:
             page.page(self.format(src))
 
     def pfile(self, obj, oname=''):
         """Show the whole file where an object was defined."""
         
         lineno = find_source_lines(obj)
         if lineno is None:
             self.noinfo('file', oname)
             return
 
         ofile = find_file(obj)
         # run contents of file through pager starting at line where the object
         # is defined, as long as the file isn't binary and is actually on the
         # filesystem.
         if ofile.endswith(('.so', '.dll', '.pyd')):
             print('File %r is binary, not printing.' % ofile)
         elif not os.path.isfile(ofile):
             print('File %r does not exist, not printing.' % ofile)
         else:
             # Print only text files, not extension binaries.  Note that
             # getsourcelines returns lineno with 1-offset and page() uses
             # 0-offset, so we must adjust.
             page.page(self.format(openpy.read_py_file(ofile, skip_encoding_cookie=False)), lineno - 1)
 
     def _format_fields(self, fields, title_width=0):
         """Formats a list of fields for display.
 
         Parameters
         ----------
         fields : list
           A list of 2-tuples: (field_title, field_content)
         title_width : int
           How many characters to pad titles to. Default to longest title.
         """
         out = []
         header = self.__head
         if title_width == 0:
             title_width = max(len(title) + 2 for title, _ in fields)
         for title, content in fields:
             if len(content.splitlines()) > 1:
                 title = header(title + ":") + "\n"
             else:
                 title = header((title+":").ljust(title_width))
             out.append(cast_unicode(title) + cast_unicode(content))
         return "\n".join(out)
 
     # The fields to be displayed by pinfo: (fancy_name, key_in_info_dict)
     pinfo_fields1 = [("Type", "type_name"),
                     ]
                     
     pinfo_fields2 = [("String form", "string_form"),
                     ]
 
     pinfo_fields3 = [("Length", "length"),
                     ("File", "file"),
                     ("Definition", "definition"),
                     ]
 
     pinfo_fields_obj = [("Class docstring", "class_docstring"),
                         ("Init docstring", "init_docstring"),
                         ("Call def", "call_def"),
                         ("Call docstring", "call_docstring")]
     
     def _format_info(self, obj, oname='', formatter=None, info=None, detail_level=0):
         """Format an info dict as text"""
         info = self.info(obj, oname=oname, formatter=formatter,
                             info=info, detail_level=detail_level)
         displayfields = []
         def add_fields(fields):
             for title, key in fields:
                 field = info[key]
                 if field is not None:
                     displayfields.append((title, field.rstrip()))
         
         add_fields(self.pinfo_fields1)
         
         # Base class for old-style instances
         if (not py3compat.PY3) and isinstance(obj, types.InstanceType) and info['base_class']:
             displayfields.append(("Base Class", info['base_class'].rstrip()))
         
         add_fields(self.pinfo_fields2)
         
         # Namespace
         if info['namespace'] != 'Interactive':
             displayfields.append(("Namespace", info['namespace'].rstrip()))
 
         add_fields(self.pinfo_fields3)
         if info['isclass'] and info['init_definition']:
             displayfields.append(("Init definition",
                             info['init_definition'].rstrip()))
         
         # Source or docstring, depending on detail level and whether
         # source found.
         if detail_level > 0 and info['source'] is not None:
             displayfields.append(("Source", 
                                   self.format(cast_unicode(info['source']))))
         elif info['docstring'] is not None:
             displayfields.append(("Docstring", info["docstring"]))
 
         # Constructor info for classes
         if info['isclass']:
             if info['init_docstring'] is not None:
                 displayfields.append(("Init docstring",
                                     info['init_docstring']))
 
         # Info for objects:
         else:
             add_fields(self.pinfo_fields_obj)
         
         if displayfields:
             return self._format_fields(displayfields)
         else:
             return u''
     
     def pinfo(self, obj, oname='', formatter=None, info=None, detail_level=0):
         """Show detailed information about an object.
 
         Optional arguments:
 
         - oname: name of the variable pointing to the object.
 
         - formatter: special formatter for docstrings (see pdoc)
 
         - info: a structure with some information fields which may have been
           precomputed already.
 
         - detail_level: if set to 1, more information is given.
         """
         text = self._format_info(obj, oname, formatter, info, detail_level)
         if text:
             page.page(text)
     
     def info(self, obj, oname='', formatter=None, info=None, detail_level=0):
         """Compute a dict with detailed information about an object.
 
         Optional arguments:
 
         - oname: name of the variable pointing to the object.
 
         - formatter: special formatter for docstrings (see pdoc)
 
         - info: a structure with some information fields which may have been
           precomputed already.
 
         - detail_level: if set to 1, more information is given.
         """
 
         obj_type = type(obj)
 
         if info is None:
             ismagic = 0
             isalias = 0
             ospace = ''
         else:
             ismagic = info.ismagic
             isalias = info.isalias
             ospace = info.namespace
 
         # Get docstring, special-casing aliases:
         if isalias:
             if not callable(obj):
                 try:
                     ds = "Alias to the system command:\n  %s" % obj[1]
                 except:
                     ds = "Alias: " + str(obj)
             else:
                 ds = "Alias to " + str(obj)
                 if obj.__doc__:
                     ds += "\nDocstring:\n" + obj.__doc__
         else:
             ds = getdoc(obj)
             if ds is None:
                 ds = '<no docstring>'
         if formatter is not None:
             ds = formatter(ds)
 
         # store output in a dict, we initialize it here and fill it as we go
         out = dict(name=oname, found=True, isalias=isalias, ismagic=ismagic)
 
         string_max = 200 # max size of strings to show (snipped if longer)
         shalf = int((string_max -5)/2)
 
         if ismagic:
             obj_type_name = 'Magic function'
         elif isalias:
             obj_type_name = 'System alias'
         else:
             obj_type_name = obj_type.__name__
         out['type_name'] = obj_type_name
 
         try:
             bclass = obj.__class__
             out['base_class'] = str(bclass)
         except: pass
 
         # String form, but snip if too long in ? form (full in ??)
         if detail_level >= self.str_detail_level:
             try:
                 ostr = str(obj)
                 str_head = 'string_form'
                 if not detail_level and len(ostr)>string_max:
                     ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
                     ostr = ("\n" + " " * len(str_head.expandtabs())).\
                             join(q.strip() for q in ostr.split("\n"))
                 out[str_head] = ostr
             except:
                 pass
 
         if ospace:
             out['namespace'] = ospace
 
         # Length (for strings and lists)
         try:
             out['length'] = str(len(obj))
         except: pass
 
         # Filename where object was defined
         binary_file = False
         fname = find_file(obj)
         if fname is None:
             # if anything goes wrong, we don't want to show source, so it's as
             # if the file was binary
             binary_file = True
         else:
             if fname.endswith(('.so', '.dll', '.pyd')):
                 binary_file = True
             elif fname.endswith('<string>'):
                 fname = 'Dynamically generated function. No source code available.'
             out['file'] = fname
 
         # Original source code for a callable, class or property.
         if detail_level:
             # Flush the source cache because inspect can return out-of-date
             # source
             linecache.checkcache()
             try:
                 if isinstance(obj, property) or not binary_file:
                     src = getsource(obj, oname)
                     if src is not None:
                         src = src.rstrip()
                     out['source'] = src
 
             except Exception:
                 pass
 
         # Add docstring only if no source is to be shown (avoid repetitions).
         if ds and out.get('source', None) is None:
             out['docstring'] = ds
 
         # Constructor docstring for classes
         if inspect.isclass(obj):
             out['isclass'] = True
             # reconstruct the function definition and print it:
             try:
                 obj_init =  obj.__init__
             except AttributeError:
                 init_def = init_ds = None
             else:
                 init_def = self._getdef(obj_init,oname)
                 init_ds  = getdoc(obj_init)
                 # Skip Python's auto-generated docstrings
                 if init_ds == _object_init_docstring:
                     init_ds = None
 
             if init_def or init_ds:
                 if init_def:
                     out['init_definition'] = self.format(init_def)
                 if init_ds:
                     out['init_docstring'] = init_ds
 
         # and class docstring for instances:
         else:
             # reconstruct the function definition and print it:
             defln = self._getdef(obj, oname)
             if defln:
                 out['definition'] = self.format(defln)
 
             # First, check whether the instance docstring is identical to the
             # class one, and print it separately if they don't coincide.  In
             # most cases they will, but it's nice to print all the info for
             # objects which use instance-customized docstrings.
             if ds:
                 try:
                     cls = getattr(obj,'__class__')
                 except:
                     class_ds = None
                 else:
                     class_ds = getdoc(cls)
                 # Skip Python's auto-generated docstrings
                 if class_ds in _builtin_type_docstrings:
                     class_ds = None
                 if class_ds and ds != class_ds:
                     out['class_docstring'] = class_ds
 
             # Next, try to show constructor docstrings
             try:
                 init_ds = getdoc(obj.__init__)
                 # Skip Python's auto-generated docstrings
                 if init_ds == _object_init_docstring:
                     init_ds = None
             except AttributeError:
                 init_ds = None
             if init_ds:
                 out['init_docstring'] = init_ds
 
             # Call form docstring for callable instances
             if safe_hasattr(obj, '__call__') and not is_simple_callable(obj):
                 call_def = self._getdef(obj.__call__, oname)
                 if call_def:
                     call_def = self.format(call_def)
                     # it may never be the case that call def and definition differ,
                     # but don't include the same signature twice
                     if call_def != out.get('definition'):
                         out['call_def'] = call_def
                 call_ds = getdoc(obj.__call__)
                 # Skip Python's auto-generated docstrings
                 if call_ds == _func_call_docstring:
                     call_ds = None
                 if call_ds:
                     out['call_docstring'] = call_ds
 
         # Compute the object's argspec as a callable.  The key is to decide
         # whether to pull it from the object itself, from its __init__ or
         # from its __call__ method.
 
         if inspect.isclass(obj):
             # Old-style classes need not have an __init__
             callable_obj = getattr(obj, "__init__", None)
         elif callable(obj):
             callable_obj = obj
         else:
             callable_obj = None
 
         if callable_obj:
             try:
                 argspec = getargspec(callable_obj)
             except (TypeError, AttributeError):
                 # For extensions/builtins we can't retrieve the argspec
                 pass
             else:
                 # named tuples' _asdict() method returns an OrderedDict, but we
                 # we want a normal
                 out['argspec'] = argspec_dict = dict(argspec._asdict())
                 # We called this varkw before argspec became a named tuple.
                 # With getfullargspec it's also called varkw.
                 if 'varkw' not in argspec_dict:
                     argspec_dict['varkw'] = argspec_dict.pop('keywords')
 
         return object_info(**out)
 
     def psearch(self,pattern,ns_table,ns_search=[],
                 ignore_case=False,show_all=False):
         """Search namespaces with wildcards for objects.
 
         Arguments:
 
         - pattern: string containing shell-like wildcards to use in namespace
           searches and optionally a type specification to narrow the search to
           objects of that type.
 
         - ns_table: dict of name->namespaces for search.
 
         Optional arguments:
 
           - ns_search: list of namespace names to include in search.
 
           - ignore_case(False): make the search case-insensitive.
 
           - show_all(False): show all names, including those starting with
             underscores.
         """
         #print 'ps pattern:<%r>' % pattern # dbg
 
         # defaults
         type_pattern = 'all'
         filter = ''
 
         cmds = pattern.split()
         len_cmds  =  len(cmds)
         if len_cmds == 1:
             # Only filter pattern given
             filter = cmds[0]
         elif len_cmds == 2:
             # Both filter and type specified
             filter,type_pattern = cmds
         else:
             raise ValueError('invalid argument string for psearch: <%s>' %
                              pattern)
 
         # filter search namespaces
         for name in ns_search:
             if name not in ns_table:
                 raise ValueError('invalid namespace <%s>. Valid names: %s' %
                                  (name,ns_table.keys()))
 
         #print 'type_pattern:',type_pattern # dbg
         search_result, namespaces_seen = set(), set()
         for ns_name in ns_search:
             ns = ns_table[ns_name]
             # Normally, locals and globals are the same, so we just check one.
             if id(ns) in namespaces_seen:
                 continue
             namespaces_seen.add(id(ns))
             tmp_res = list_namespace(ns, type_pattern, filter,
                                     ignore_case=ignore_case, show_all=show_all)
             search_result.update(tmp_res)
 
         page.page('\n'.join(sorted(search_result)))

IPython/utils/signatures.py

@@ -1,813 +1,816 b''
 """Function signature objects for callables.
 
 Back port of Python 3.3's function signature tools from the inspect module,
 modified to be compatible with Python 2.7 and 3.2+.
 """
 
 #-----------------------------------------------------------------------------
 #  Python 3.3 stdlib inspect.py is public domain
 # 
 #  Backports Copyright (C) 2013 Aaron Iles
 #  Used under Apache License Version 2.0
 #
 #  Further Changes are Copyright (C) 2013 The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #-----------------------------------------------------------------------------
 
 from __future__ import absolute_import, division, print_function
 import itertools
 import functools
 import re
 import types
 
 
 # patch for single-file
 # we don't support 2.6, so we can just import OrderedDict
 from collections import OrderedDict
 
 __version__ = '0.3'
 # end patch
 
 __all__ = ['BoundArguments', 'Parameter', 'Signature', 'signature']
 
 
 _WrapperDescriptor = type(type.__call__)
 _MethodWrapper = type(all.__call__)
 
 _NonUserDefinedCallables = (_WrapperDescriptor,
                             _MethodWrapper,
                             types.BuiltinFunctionType)
 
 
 def formatannotation(annotation, base_module=None):
     if isinstance(annotation, type):
         if annotation.__module__ in ('builtins', '__builtin__', base_module):
             return annotation.__name__
         return annotation.__module__+'.'+annotation.__name__
     return repr(annotation)
 
 
 def _get_user_defined_method(cls, method_name, *nested):
     try:
         if cls is type:
             return
         meth = getattr(cls, method_name)
         for name in nested:
             meth = getattr(meth, name, meth)
     except AttributeError:
         return
     else:
         if not isinstance(meth, _NonUserDefinedCallables):
             # Once '__signature__' will be added to 'C'-level
             # callables, this check won't be necessary
             return meth
 
 
 def signature(obj):
     '''Get a signature object for the passed callable.'''
 
     if not callable(obj):
         raise TypeError('{0!r} is not a callable object'.format(obj))
 
     if isinstance(obj, types.MethodType):
-        # In this case we skip the first parameter of the underlying
-        # function (usually `self` or `cls`).
-        sig = signature(obj.__func__)
-        return sig.replace(parameters=tuple(sig.parameters.values())[1:])
+        if obj.__self__ is None:
+            # Unbound method - treat it as a function (no distinction in Py 3)
+            obj = obj.__func__
+        else:
+            # Bound method: trim off the first parameter (typically self or cls)
+            sig = signature(obj.__func__)
+            return sig.replace(parameters=tuple(sig.parameters.values())[1:])
 
     try:
         sig = obj.__signature__
     except AttributeError:
         pass
     else:
         if sig is not None:
             return sig
 
     try:
         # Was this function wrapped by a decorator?
         wrapped = obj.__wrapped__
     except AttributeError:
         pass
     else:
         return signature(wrapped)
 
     if isinstance(obj, types.FunctionType):
         return Signature.from_function(obj)
 
     if isinstance(obj, functools.partial):
         sig = signature(obj.func)
 
         new_params = OrderedDict(sig.parameters.items())
 
         partial_args = obj.args or ()
         partial_keywords = obj.keywords or {}
         try:
             ba = sig.bind_partial(*partial_args, **partial_keywords)
         except TypeError as ex:
             msg = 'partial object {0!r} has incorrect arguments'.format(obj)
             raise ValueError(msg)
 
         for arg_name, arg_value in ba.arguments.items():
             param = new_params[arg_name]
             if arg_name in partial_keywords:
                 # We set a new default value, because the following code
                 # is correct:
                 #
                 #   >>> def foo(a): print(a)
                 #   >>> print(partial(partial(foo, a=10), a=20)())
                 #   20
                 #   >>> print(partial(partial(foo, a=10), a=20)(a=30))
                 #   30
                 #
                 # So, with 'partial' objects, passing a keyword argument is
                 # like setting a new default value for the corresponding
                 # parameter
                 #
                 # We also mark this parameter with '_partial_kwarg'
                 # flag.  Later, in '_bind', the 'default' value of this
                 # parameter will be added to 'kwargs', to simulate
                 # the 'functools.partial' real call.
                 new_params[arg_name] = param.replace(default=arg_value,
                                                      _partial_kwarg=True)
 
             elif (param.kind not in (_VAR_KEYWORD, _VAR_POSITIONAL) and
                             not param._partial_kwarg):
                 new_params.pop(arg_name)
 
         return sig.replace(parameters=new_params.values())
 
     sig = None
     if isinstance(obj, type):
         # obj is a class or a metaclass
 
         # First, let's see if it has an overloaded __call__ defined
         # in its metaclass
         call = _get_user_defined_method(type(obj), '__call__')
         if call is not None:
             sig = signature(call)
         else:
             # Now we check if the 'obj' class has a '__new__' method
             new = _get_user_defined_method(obj, '__new__')
             if new is not None:
                 sig = signature(new)
             else:
                 # Finally, we should have at least __init__ implemented
                 init = _get_user_defined_method(obj, '__init__')
                 if init is not None:
                     sig = signature(init)
     elif not isinstance(obj, _NonUserDefinedCallables):
         # An object with __call__
         # We also check that the 'obj' is not an instance of
         # _WrapperDescriptor or _MethodWrapper to avoid
         # infinite recursion (and even potential segfault)
         call = _get_user_defined_method(type(obj), '__call__', 'im_func')
         if call is not None:
             sig = signature(call)
 
     if sig is not None:
         return sig
 
     if isinstance(obj, types.BuiltinFunctionType):
         # Raise a nicer error message for builtins
         msg = 'no signature found for builtin function {0!r}'.format(obj)
         raise ValueError(msg)
 
     raise ValueError('callable {0!r} is not supported by signature'.format(obj))
 
 
 class _void(object):
     '''A private marker - used in Parameter & Signature'''
 
 
 class _empty(object):
     pass
 
 
 class _ParameterKind(int):
     def __new__(self, *args, **kwargs):
         obj = int.__new__(self, *args)
         obj._name = kwargs['name']
         return obj
 
     def __str__(self):
         return self._name
 
     def __repr__(self):
         return '<_ParameterKind: {0!r}>'.format(self._name)
 
 
 _POSITIONAL_ONLY        = _ParameterKind(0, name='POSITIONAL_ONLY')
 _POSITIONAL_OR_KEYWORD  = _ParameterKind(1, name='POSITIONAL_OR_KEYWORD')
 _VAR_POSITIONAL         = _ParameterKind(2, name='VAR_POSITIONAL')
 _KEYWORD_ONLY           = _ParameterKind(3, name='KEYWORD_ONLY')
 _VAR_KEYWORD            = _ParameterKind(4, name='VAR_KEYWORD')
 
 
 class Parameter(object):
     '''Represents a parameter in a function signature.
 
     Has the following public attributes:
 
     * name : str
         The name of the parameter as a string.
     * default : object
         The default value for the parameter if specified.  If the
         parameter has no default value, this attribute is not set.
     * annotation
         The annotation for the parameter if specified.  If the
         parameter has no annotation, this attribute is not set.
     * kind : str
         Describes how argument values are bound to the parameter.
         Possible values: `Parameter.POSITIONAL_ONLY`,
         `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
         `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
     '''
 
     __slots__ = ('_name', '_kind', '_default', '_annotation', '_partial_kwarg')
 
     POSITIONAL_ONLY         = _POSITIONAL_ONLY
     POSITIONAL_OR_KEYWORD   = _POSITIONAL_OR_KEYWORD
     VAR_POSITIONAL          = _VAR_POSITIONAL
     KEYWORD_ONLY            = _KEYWORD_ONLY
     VAR_KEYWORD             = _VAR_KEYWORD
 
     empty = _empty
 
     def __init__(self, name, kind, default=_empty, annotation=_empty,
                  _partial_kwarg=False):
 
         if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
                         _VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
             raise ValueError("invalid value for 'Parameter.kind' attribute")
         self._kind = kind
 
         if default is not _empty:
             if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
                 msg = '{0} parameters cannot have default values'.format(kind)
                 raise ValueError(msg)
         self._default = default
         self._annotation = annotation
 
         if name is None:
             if kind != _POSITIONAL_ONLY:
                 raise ValueError("None is not a valid name for a "
                                  "non-positional-only parameter")
             self._name = name
         else:
             name = str(name)
             if kind != _POSITIONAL_ONLY and not re.match(r'[a-z_]\w*$', name, re.I):
                 msg = '{0!r} is not a valid parameter name'.format(name)
                 raise ValueError(msg)
             self._name = name
 
         self._partial_kwarg = _partial_kwarg
 
     @property
     def name(self):
         return self._name
 
     @property
     def default(self):
         return self._default
 
     @property
     def annotation(self):
         return self._annotation
 
     @property
     def kind(self):
         return self._kind
 
     def replace(self, name=_void, kind=_void, annotation=_void,
                 default=_void, _partial_kwarg=_void):
         '''Creates a customized copy of the Parameter.'''
 
         if name is _void:
             name = self._name
 
         if kind is _void:
             kind = self._kind
 
         if annotation is _void:
             annotation = self._annotation
 
         if default is _void:
             default = self._default
 
         if _partial_kwarg is _void:
             _partial_kwarg = self._partial_kwarg
 
         return type(self)(name, kind, default=default, annotation=annotation,
                           _partial_kwarg=_partial_kwarg)
 
     def __str__(self):
         kind = self.kind
 
         formatted = self._name
         if kind == _POSITIONAL_ONLY:
             if formatted is None:
                 formatted = ''
             formatted = '<{0}>'.format(formatted)
 
         # Add annotation and default value
         if self._annotation is not _empty:
             formatted = '{0}:{1}'.format(formatted,
                                        formatannotation(self._annotation))
 
         if self._default is not _empty:
             formatted = '{0}={1}'.format(formatted, repr(self._default))
 
         if kind == _VAR_POSITIONAL:
             formatted = '*' + formatted
         elif kind == _VAR_KEYWORD:
             formatted = '**' + formatted
 
         return formatted
 
     def __repr__(self):
         return '<{0} at {1:#x} {2!r}>'.format(self.__class__.__name__,
                                            id(self), self.name)
 
     def __hash__(self):
         msg = "unhashable type: '{0}'".format(self.__class__.__name__)
         raise TypeError(msg)
 
     def __eq__(self, other):
         return (issubclass(other.__class__, Parameter) and
                 self._name == other._name and
                 self._kind == other._kind and
                 self._default == other._default and
                 self._annotation == other._annotation)
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
 
 class BoundArguments(object):
     '''Result of :meth:`Signature.bind` call.  Holds the mapping of arguments
     to the function's parameters.
 
     Has the following public attributes:
 
     arguments : :class:`collections.OrderedDict`
       An ordered mutable mapping of parameters' names to arguments' values.
       Does not contain arguments' default values.
     signature : :class:`Signature`
       The Signature object that created this instance.
     args : tuple
       Tuple of positional arguments values.
     kwargs : dict
       Dict of keyword arguments values.
     '''
 
     def __init__(self, signature, arguments):
         self.arguments = arguments
         self._signature = signature
 
     @property
     def signature(self):
         return self._signature
 
     @property
     def args(self):
         args = []
         for param_name, param in self._signature.parameters.items():
             if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
                                                     param._partial_kwarg):
                 # Keyword arguments mapped by 'functools.partial'
                 # (Parameter._partial_kwarg is True) are mapped
                 # in 'BoundArguments.kwargs', along with VAR_KEYWORD &
                 # KEYWORD_ONLY
                 break
 
             try:
                 arg = self.arguments[param_name]
             except KeyError:
                 # We're done here. Other arguments
                 # will be mapped in 'BoundArguments.kwargs'
                 break
             else:
                 if param.kind == _VAR_POSITIONAL:
                     # *args
                     args.extend(arg)
                 else:
                     # plain argument
                     args.append(arg)
 
         return tuple(args)
 
     @property
     def kwargs(self):
         kwargs = {}
         kwargs_started = False
         for param_name, param in self._signature.parameters.items():
             if not kwargs_started:
                 if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
                                                 param._partial_kwarg):
                     kwargs_started = True
                 else:
                     if param_name not in self.arguments:
                         kwargs_started = True
                         continue
 
             if not kwargs_started:
                 continue
 
             try:
                 arg = self.arguments[param_name]
             except KeyError:
                 pass
             else:
                 if param.kind == _VAR_KEYWORD:
                     # **kwargs
                     kwargs.update(arg)
                 else:
                     # plain keyword argument
                     kwargs[param_name] = arg
 
         return kwargs
 
     def __hash__(self):
         msg = "unhashable type: '{0}'".format(self.__class__.__name__)
         raise TypeError(msg)
 
     def __eq__(self, other):
         return (issubclass(other.__class__, BoundArguments) and
                 self.signature == other.signature and
                 self.arguments == other.arguments)
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
 
 class Signature(object):
     '''A Signature object represents the overall signature of a function.
     It stores a Parameter object for each parameter accepted by the
     function, as well as information specific to the function itself.
 
     A Signature object has the following public attributes:
 
     parameters : :class:`collections.OrderedDict`
       An ordered mapping of parameters' names to the corresponding
       Parameter objects (keyword-only arguments are in the same order
       as listed in `code.co_varnames`).
     return_annotation
       The annotation for the return type of the function if specified.
       If the function has no annotation for its return type, this
       attribute is not set.
     '''
 
     __slots__ = ('_return_annotation', '_parameters')
 
     _parameter_cls = Parameter
     _bound_arguments_cls = BoundArguments
 
     empty = _empty
 
     def __init__(self, parameters=None, return_annotation=_empty,
                  __validate_parameters__=True):
         '''Constructs Signature from the given list of Parameter
         objects and 'return_annotation'.  All arguments are optional.
         '''
 
         if parameters is None:
             params = OrderedDict()
         else:
             if __validate_parameters__:
                 params = OrderedDict()
                 top_kind = _POSITIONAL_ONLY
 
                 for idx, param in enumerate(parameters):
                     kind = param.kind
                     if kind < top_kind:
                         msg = 'wrong parameter order: {0} before {1}'
                         msg = msg.format(top_kind, param.kind)
                         raise ValueError(msg)
                     else:
                         top_kind = kind
 
                     name = param.name
                     if name is None:
                         name = str(idx)
                         param = param.replace(name=name)
 
                     if name in params:
                         msg = 'duplicate parameter name: {0!r}'.format(name)
                         raise ValueError(msg)
                     params[name] = param
             else:
                 params = OrderedDict(((param.name, param)
                                                 for param in parameters))
 
         self._parameters = params
         self._return_annotation = return_annotation
 
     @classmethod
     def from_function(cls, func):
         '''Constructs Signature for the given python function'''
 
         if not isinstance(func, types.FunctionType):
             raise TypeError('{0!r} is not a Python function'.format(func))
 
         Parameter = cls._parameter_cls
 
         # Parameter information.
         func_code = func.__code__
         pos_count = func_code.co_argcount
         arg_names = func_code.co_varnames
         positional = tuple(arg_names[:pos_count])
         keyword_only_count = getattr(func_code, 'co_kwonlyargcount', 0)
         keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
         annotations = getattr(func, '__annotations__', {})
         defaults = func.__defaults__
         kwdefaults = getattr(func, '__kwdefaults__', None)
 
         if defaults:
             pos_default_count = len(defaults)
         else:
             pos_default_count = 0
 
         parameters = []
 
         # Non-keyword-only parameters w/o defaults.
         non_default_count = pos_count - pos_default_count
         for name in positional[:non_default_count]:
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_POSITIONAL_OR_KEYWORD))
 
         # ... w/ defaults.
         for offset, name in enumerate(positional[non_default_count:]):
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_POSITIONAL_OR_KEYWORD,
                                         default=defaults[offset]))
 
         # *args
         if func_code.co_flags & 0x04:
             name = arg_names[pos_count + keyword_only_count]
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_VAR_POSITIONAL))
 
         # Keyword-only parameters.
         for name in keyword_only:
             default = _empty
             if kwdefaults is not None:
                 default = kwdefaults.get(name, _empty)
 
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_KEYWORD_ONLY,
                                         default=default))
         # **kwargs
         if func_code.co_flags & 0x08:
             index = pos_count + keyword_only_count
             if func_code.co_flags & 0x04:
                 index += 1
 
             name = arg_names[index]
             annotation = annotations.get(name, _empty)
             parameters.append(Parameter(name, annotation=annotation,
                                         kind=_VAR_KEYWORD))
 
         return cls(parameters,
                    return_annotation=annotations.get('return', _empty),
                    __validate_parameters__=False)
 
     @property
     def parameters(self):
         try:
             return types.MappingProxyType(self._parameters)
         except AttributeError:
             return OrderedDict(self._parameters.items())
 
     @property
     def return_annotation(self):
         return self._return_annotation
 
     def replace(self, parameters=_void, return_annotation=_void):
         '''Creates a customized copy of the Signature.
         Pass 'parameters' and/or 'return_annotation' arguments
         to override them in the new copy.
         '''
 
         if parameters is _void:
             parameters = self.parameters.values()
 
         if return_annotation is _void:
             return_annotation = self._return_annotation
 
         return type(self)(parameters,
                           return_annotation=return_annotation)
 
     def __hash__(self):
         msg = "unhashable type: '{0}'".format(self.__class__.__name__)
         raise TypeError(msg)
 
     def __eq__(self, other):
         if (not issubclass(type(other), Signature) or
                     self.return_annotation != other.return_annotation or
                     len(self.parameters) != len(other.parameters)):
             return False
 
         other_positions = dict((param, idx)
                            for idx, param in enumerate(other.parameters.keys()))
 
         for idx, (param_name, param) in enumerate(self.parameters.items()):
             if param.kind == _KEYWORD_ONLY:
                 try:
                     other_param = other.parameters[param_name]
                 except KeyError:
                     return False
                 else:
                     if param != other_param:
                         return False
             else:
                 try:
                     other_idx = other_positions[param_name]
                 except KeyError:
                     return False
                 else:
                     if (idx != other_idx or
                                     param != other.parameters[param_name]):
                         return False
 
         return True
 
     def __ne__(self, other):
         return not self.__eq__(other)
 
     def _bind(self, args, kwargs, partial=False):
         '''Private method.  Don't use directly.'''
 
         arguments = OrderedDict()
 
         parameters = iter(self.parameters.values())
         parameters_ex = ()
         arg_vals = iter(args)
 
         if partial:
             # Support for binding arguments to 'functools.partial' objects.
             # See 'functools.partial' case in 'signature()' implementation
             # for details.
             for param_name, param in self.parameters.items():
                 if (param._partial_kwarg and param_name not in kwargs):
                     # Simulating 'functools.partial' behavior
                     kwargs[param_name] = param.default
 
         while True:
             # Let's iterate through the positional arguments and corresponding
             # parameters
             try:
                 arg_val = next(arg_vals)
             except StopIteration:
                 # No more positional arguments
                 try:
                     param = next(parameters)
                 except StopIteration:
                     # No more parameters. That's it. Just need to check that
                     # we have no `kwargs` after this while loop
                     break
                 else:
                     if param.kind == _VAR_POSITIONAL:
                         # That's OK, just empty *args.  Let's start parsing
                         # kwargs
                         break
                     elif param.name in kwargs:
                         if param.kind == _POSITIONAL_ONLY:
                             msg = '{arg!r} parameter is positional only, ' \
                                   'but was passed as a keyword'
                             msg = msg.format(arg=param.name)
                             raise TypeError(msg)
                         parameters_ex = (param,)
                         break
                     elif (param.kind == _VAR_KEYWORD or
                                                 param.default is not _empty):
                         # That's fine too - we have a default value for this
                         # parameter.  So, lets start parsing `kwargs`, starting
                         # with the current parameter
                         parameters_ex = (param,)
                         break
                     else:
                         if partial:
                             parameters_ex = (param,)
                             break
                         else:
                             msg = '{arg!r} parameter lacking default value'
                             msg = msg.format(arg=param.name)
                             raise TypeError(msg)
             else:
                 # We have a positional argument to process
                 try:
                     param = next(parameters)
                 except StopIteration:
                     raise TypeError('too many positional arguments')
                 else:
                     if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
                         # Looks like we have no parameter for this positional
                         # argument
                         raise TypeError('too many positional arguments')
 
                     if param.kind == _VAR_POSITIONAL:
                         # We have an '*args'-like argument, let's fill it with
                         # all positional arguments we have left and move on to
                         # the next phase
                         values = [arg_val]
                         values.extend(arg_vals)
                         arguments[param.name] = tuple(values)
                         break
 
                     if param.name in kwargs:
                         raise TypeError('multiple values for argument '
                                         '{arg!r}'.format(arg=param.name))
 
                     arguments[param.name] = arg_val
 
         # Now, we iterate through the remaining parameters to process
         # keyword arguments
         kwargs_param = None
         for param in itertools.chain(parameters_ex, parameters):
             if param.kind == _POSITIONAL_ONLY:
                 # This should never happen in case of a properly built
                 # Signature object (but let's have this check here
                 # to ensure correct behaviour just in case)
                 raise TypeError('{arg!r} parameter is positional only, '
                                 'but was passed as a keyword'. \
                                 format(arg=param.name))
 
             if param.kind == _VAR_KEYWORD:
                 # Memorize that we have a '**kwargs'-like parameter
                 kwargs_param = param
                 continue
 
             param_name = param.name
             try:
                 arg_val = kwargs.pop(param_name)
             except KeyError:
                 # We have no value for this parameter.  It's fine though,
                 # if it has a default value, or it is an '*args'-like
                 # parameter, left alone by the processing of positional
                 # arguments.
                 if (not partial and param.kind != _VAR_POSITIONAL and
                                                     param.default is _empty):
                     raise TypeError('{arg!r} parameter lacking default value'. \
                                     format(arg=param_name))
 
             else:
                 arguments[param_name] = arg_val
 
         if kwargs:
             if kwargs_param is not None:
                 # Process our '**kwargs'-like parameter
                 arguments[kwargs_param.name] = kwargs
             else:
                 raise TypeError('too many keyword arguments')
 
         return self._bound_arguments_cls(self, arguments)
 
     def bind(self, *args, **kwargs):
         '''Get a :class:`BoundArguments` object, that maps the passed `args`
         and `kwargs` to the function's signature.  Raises :exc:`TypeError`
         if the passed arguments can not be bound.
         '''
         return self._bind(args, kwargs)
 
     def bind_partial(self, *args, **kwargs):
         '''Get a :class:`BoundArguments` object, that partially maps the
         passed `args` and `kwargs` to the function's signature.
         Raises :exc:`TypeError` if the passed arguments can not be bound.
         '''
         return self._bind(args, kwargs, partial=True)
 
     def __str__(self):
         result = []
         render_kw_only_separator = True
         for idx, param in enumerate(self.parameters.values()):
             formatted = str(param)
 
             kind = param.kind
             if kind == _VAR_POSITIONAL:
                 # OK, we have an '*args'-like parameter, so we won't need
                 # a '*' to separate keyword-only arguments
                 render_kw_only_separator = False
             elif kind == _KEYWORD_ONLY and render_kw_only_separator:
                 # We have a keyword-only parameter to render and we haven't
                 # rendered an '*args'-like parameter before, so add a '*'
                 # separator to the parameters list ("foo(arg1, *, arg2)" case)
                 result.append('*')
                 # This condition should be only triggered once, so
                 # reset the flag
                 render_kw_only_separator = False
 
             result.append(formatted)
 
         rendered = '({0})'.format(', '.join(result))
 
         if self.return_annotation is not _empty:
             anno = formatannotation(self.return_annotation)
             rendered += ' -> {0}'.format(anno)
 
         return rendered