• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1"""Get useful information from live Python objects.
2
3This module encapsulates the interface provided by the internal special
4attributes (co_*, im_*, tb_*, etc.) in a friendlier fashion.
5It also provides some help for examining source code and class layout.
6
7Here are some of the useful functions provided by this module:
8
9    ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
10        isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
11        isroutine() - check object types
12    getmembers() - get members of an object that satisfy a given condition
13
14    getfile(), getsourcefile(), getsource() - find an object's source code
15    getdoc(), getcomments() - get documentation on an object
16    getmodule() - determine the module that an object came from
17    getclasstree() - arrange classes so as to represent their hierarchy
18
19    getargvalues(), getcallargs() - get info about function arguments
20    getfullargspec() - same, with support for Python 3 features
21    formatargvalues() - format an argument spec
22    getouterframes(), getinnerframes() - get info about frames
23    currentframe() - get the current stack frame
24    stack(), trace() - get info about frames on the stack or in a traceback
25
26    signature() - get a Signature object for the callable
27"""
28
29# This module is in the public domain.  No warranties.
30
31__author__ = ('Ka-Ping Yee <ping@lfw.org>',
32              'Yury Selivanov <yselivanov@sprymix.com>')
33
34import abc
35import dis
36import collections.abc
37import enum
38import importlib.machinery
39import itertools
40import linecache
41import os
42import re
43import sys
44import tokenize
45import token
46import types
47import warnings
48import functools
49import builtins
50from operator import attrgetter
51from collections import namedtuple, OrderedDict
52
53# Create constants for the compiler flags in Include/code.h
54# We try to get them from dis to avoid duplication
55mod_dict = globals()
56for k, v in dis.COMPILER_FLAG_NAMES.items():
57    mod_dict["CO_" + v] = k
58
59# See Include/object.h
60TPFLAGS_IS_ABSTRACT = 1 << 20
61
62# ----------------------------------------------------------- type-checking
63def ismodule(object):
64    """Return true if the object is a module.
65
66    Module objects provide these attributes:
67        __cached__      pathname to byte compiled file
68        __doc__         documentation string
69        __file__        filename (missing for built-in modules)"""
70    return isinstance(object, types.ModuleType)
71
72def isclass(object):
73    """Return true if the object is a class.
74
75    Class objects provide these attributes:
76        __doc__         documentation string
77        __module__      name of module in which this class was defined"""
78    return isinstance(object, type)
79
80def ismethod(object):
81    """Return true if the object is an instance method.
82
83    Instance method objects provide these attributes:
84        __doc__         documentation string
85        __name__        name with which this method was defined
86        __func__        function object containing implementation of method
87        __self__        instance to which this method is bound"""
88    return isinstance(object, types.MethodType)
89
90def ismethoddescriptor(object):
91    """Return true if the object is a method descriptor.
92
93    But not if ismethod() or isclass() or isfunction() are true.
94
95    This is new in Python 2.2, and, for example, is true of int.__add__.
96    An object passing this test has a __get__ attribute but not a __set__
97    attribute, but beyond that the set of attributes varies.  __name__ is
98    usually sensible, and __doc__ often is.
99
100    Methods implemented via descriptors that also pass one of the other
101    tests return false from the ismethoddescriptor() test, simply because
102    the other tests promise more -- you can, e.g., count on having the
103    __func__ attribute (etc) when an object passes ismethod()."""
104    if isclass(object) or ismethod(object) or isfunction(object):
105        # mutual exclusion
106        return False
107    tp = type(object)
108    return hasattr(tp, "__get__") and not hasattr(tp, "__set__")
109
110def isdatadescriptor(object):
111    """Return true if the object is a data descriptor.
112
113    Data descriptors have both a __get__ and a __set__ attribute.  Examples are
114    properties (defined in Python) and getsets and members (defined in C).
115    Typically, data descriptors will also have __name__ and __doc__ attributes
116    (properties, getsets, and members have both of these attributes), but this
117    is not guaranteed."""
118    if isclass(object) or ismethod(object) or isfunction(object):
119        # mutual exclusion
120        return False
121    tp = type(object)
122    return hasattr(tp, "__set__") and hasattr(tp, "__get__")
123
124if hasattr(types, 'MemberDescriptorType'):
125    # CPython and equivalent
126    def ismemberdescriptor(object):
127        """Return true if the object is a member descriptor.
128
129        Member descriptors are specialized descriptors defined in extension
130        modules."""
131        return isinstance(object, types.MemberDescriptorType)
132else:
133    # Other implementations
134    def ismemberdescriptor(object):
135        """Return true if the object is a member descriptor.
136
137        Member descriptors are specialized descriptors defined in extension
138        modules."""
139        return False
140
141if hasattr(types, 'GetSetDescriptorType'):
142    # CPython and equivalent
143    def isgetsetdescriptor(object):
144        """Return true if the object is a getset descriptor.
145
146        getset descriptors are specialized descriptors defined in extension
147        modules."""
148        return isinstance(object, types.GetSetDescriptorType)
149else:
150    # Other implementations
151    def isgetsetdescriptor(object):
152        """Return true if the object is a getset descriptor.
153
154        getset descriptors are specialized descriptors defined in extension
155        modules."""
156        return False
157
158def isfunction(object):
159    """Return true if the object is a user-defined function.
160
161    Function objects provide these attributes:
162        __doc__         documentation string
163        __name__        name with which this function was defined
164        __code__        code object containing compiled function bytecode
165        __defaults__    tuple of any default values for arguments
166        __globals__     global namespace in which this function was defined
167        __annotations__ dict of parameter annotations
168        __kwdefaults__  dict of keyword only parameters with defaults"""
169    return isinstance(object, types.FunctionType)
170
171def isgeneratorfunction(object):
172    """Return true if the object is a user-defined generator function.
173
174    Generator function objects provide the same attributes as functions.
175    See help(isfunction) for a list of attributes."""
176    return bool((isfunction(object) or ismethod(object)) and
177                object.__code__.co_flags & CO_GENERATOR)
178
179def iscoroutinefunction(object):
180    """Return true if the object is a coroutine function.
181
182    Coroutine functions are defined with "async def" syntax.
183    """
184    return bool((isfunction(object) or ismethod(object)) and
185                object.__code__.co_flags & CO_COROUTINE)
186
187def isasyncgenfunction(object):
188    """Return true if the object is an asynchronous generator function.
189
190    Asynchronous generator functions are defined with "async def"
191    syntax and have "yield" expressions in their body.
192    """
193    return bool((isfunction(object) or ismethod(object)) and
194                object.__code__.co_flags & CO_ASYNC_GENERATOR)
195
196def isasyncgen(object):
197    """Return true if the object is an asynchronous generator."""
198    return isinstance(object, types.AsyncGeneratorType)
199
200def isgenerator(object):
201    """Return true if the object is a generator.
202
203    Generator objects provide these attributes:
204        __iter__        defined to support iteration over container
205        close           raises a new GeneratorExit exception inside the
206                        generator to terminate the iteration
207        gi_code         code object
208        gi_frame        frame object or possibly None once the generator has
209                        been exhausted
210        gi_running      set to 1 when generator is executing, 0 otherwise
211        next            return the next item from the container
212        send            resumes the generator and "sends" a value that becomes
213                        the result of the current yield-expression
214        throw           used to raise an exception inside the generator"""
215    return isinstance(object, types.GeneratorType)
216
217def iscoroutine(object):
218    """Return true if the object is a coroutine."""
219    return isinstance(object, types.CoroutineType)
220
221def isawaitable(object):
222    """Return true if object can be passed to an ``await`` expression."""
223    return (isinstance(object, types.CoroutineType) or
224            isinstance(object, types.GeneratorType) and
225                bool(object.gi_code.co_flags & CO_ITERABLE_COROUTINE) or
226            isinstance(object, collections.abc.Awaitable))
227
228def istraceback(object):
229    """Return true if the object is a traceback.
230
231    Traceback objects provide these attributes:
232        tb_frame        frame object at this level
233        tb_lasti        index of last attempted instruction in bytecode
234        tb_lineno       current line number in Python source code
235        tb_next         next inner traceback object (called by this level)"""
236    return isinstance(object, types.TracebackType)
237
238def isframe(object):
239    """Return true if the object is a frame object.
240
241    Frame objects provide these attributes:
242        f_back          next outer frame object (this frame's caller)
243        f_builtins      built-in namespace seen by this frame
244        f_code          code object being executed in this frame
245        f_globals       global namespace seen by this frame
246        f_lasti         index of last attempted instruction in bytecode
247        f_lineno        current line number in Python source code
248        f_locals        local namespace seen by this frame
249        f_trace         tracing function for this frame, or None"""
250    return isinstance(object, types.FrameType)
251
252def iscode(object):
253    """Return true if the object is a code object.
254
255    Code objects provide these attributes:
256        co_argcount         number of arguments (not including *, ** args
257                            or keyword only arguments)
258        co_code             string of raw compiled bytecode
259        co_cellvars         tuple of names of cell variables
260        co_consts           tuple of constants used in the bytecode
261        co_filename         name of file in which this code object was created
262        co_firstlineno      number of first line in Python source code
263        co_flags            bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
264                            | 16=nested | 32=generator | 64=nofree | 128=coroutine
265                            | 256=iterable_coroutine | 512=async_generator
266        co_freevars         tuple of names of free variables
267        co_kwonlyargcount   number of keyword only arguments (not including ** arg)
268        co_lnotab           encoded mapping of line numbers to bytecode indices
269        co_name             name with which this code object was defined
270        co_names            tuple of names of local variables
271        co_nlocals          number of local variables
272        co_stacksize        virtual machine stack space required
273        co_varnames         tuple of names of arguments and local variables"""
274    return isinstance(object, types.CodeType)
275
276def isbuiltin(object):
277    """Return true if the object is a built-in function or method.
278
279    Built-in functions and methods provide these attributes:
280        __doc__         documentation string
281        __name__        original name of this function or method
282        __self__        instance to which a method is bound, or None"""
283    return isinstance(object, types.BuiltinFunctionType)
284
285def isroutine(object):
286    """Return true if the object is any kind of function or method."""
287    return (isbuiltin(object)
288            or isfunction(object)
289            or ismethod(object)
290            or ismethoddescriptor(object))
291
292def isabstract(object):
293    """Return true if the object is an abstract base class (ABC)."""
294    if not isinstance(object, type):
295        return False
296    if object.__flags__ & TPFLAGS_IS_ABSTRACT:
297        return True
298    if not issubclass(type(object), abc.ABCMeta):
299        return False
300    if hasattr(object, '__abstractmethods__'):
301        # It looks like ABCMeta.__new__ has finished running;
302        # TPFLAGS_IS_ABSTRACT should have been accurate.
303        return False
304    # It looks like ABCMeta.__new__ has not finished running yet; we're
305    # probably in __init_subclass__. We'll look for abstractmethods manually.
306    for name, value in object.__dict__.items():
307        if getattr(value, "__isabstractmethod__", False):
308            return True
309    for base in object.__bases__:
310        for name in getattr(base, "__abstractmethods__", ()):
311            value = getattr(object, name, None)
312            if getattr(value, "__isabstractmethod__", False):
313                return True
314    return False
315
316def getmembers(object, predicate=None):
317    """Return all members of an object as (name, value) pairs sorted by name.
318    Optionally, only return members that satisfy a given predicate."""
319    if isclass(object):
320        mro = (object,) + getmro(object)
321    else:
322        mro = ()
323    results = []
324    processed = set()
325    names = dir(object)
326    # :dd any DynamicClassAttributes to the list of names if object is a class;
327    # this may result in duplicate entries if, for example, a virtual
328    # attribute with the same name as a DynamicClassAttribute exists
329    try:
330        for base in object.__bases__:
331            for k, v in base.__dict__.items():
332                if isinstance(v, types.DynamicClassAttribute):
333                    names.append(k)
334    except AttributeError:
335        pass
336    for key in names:
337        # First try to get the value via getattr.  Some descriptors don't
338        # like calling their __get__ (see bug #1785), so fall back to
339        # looking in the __dict__.
340        try:
341            value = getattr(object, key)
342            # handle the duplicate key
343            if key in processed:
344                raise AttributeError
345        except AttributeError:
346            for base in mro:
347                if key in base.__dict__:
348                    value = base.__dict__[key]
349                    break
350            else:
351                # could be a (currently) missing slot member, or a buggy
352                # __dir__; discard and move on
353                continue
354        if not predicate or predicate(value):
355            results.append((key, value))
356        processed.add(key)
357    results.sort(key=lambda pair: pair[0])
358    return results
359
360Attribute = namedtuple('Attribute', 'name kind defining_class object')
361
362def classify_class_attrs(cls):
363    """Return list of attribute-descriptor tuples.
364
365    For each name in dir(cls), the return list contains a 4-tuple
366    with these elements:
367
368        0. The name (a string).
369
370        1. The kind of attribute this is, one of these strings:
371               'class method'    created via classmethod()
372               'static method'   created via staticmethod()
373               'property'        created via property()
374               'method'          any other flavor of method or descriptor
375               'data'            not a method
376
377        2. The class which defined this attribute (a class).
378
379        3. The object as obtained by calling getattr; if this fails, or if the
380           resulting object does not live anywhere in the class' mro (including
381           metaclasses) then the object is looked up in the defining class's
382           dict (found by walking the mro).
383
384    If one of the items in dir(cls) is stored in the metaclass it will now
385    be discovered and not have None be listed as the class in which it was
386    defined.  Any items whose home class cannot be discovered are skipped.
387    """
388
389    mro = getmro(cls)
390    metamro = getmro(type(cls)) # for attributes stored in the metaclass
391    metamro = tuple(cls for cls in metamro if cls not in (type, object))
392    class_bases = (cls,) + mro
393    all_bases = class_bases + metamro
394    names = dir(cls)
395    # :dd any DynamicClassAttributes to the list of names;
396    # this may result in duplicate entries if, for example, a virtual
397    # attribute with the same name as a DynamicClassAttribute exists.
398    for base in mro:
399        for k, v in base.__dict__.items():
400            if isinstance(v, types.DynamicClassAttribute):
401                names.append(k)
402    result = []
403    processed = set()
404
405    for name in names:
406        # Get the object associated with the name, and where it was defined.
407        # Normal objects will be looked up with both getattr and directly in
408        # its class' dict (in case getattr fails [bug #1785], and also to look
409        # for a docstring).
410        # For DynamicClassAttributes on the second pass we only look in the
411        # class's dict.
412        #
413        # Getting an obj from the __dict__ sometimes reveals more than
414        # using getattr.  Static and class methods are dramatic examples.
415        homecls = None
416        get_obj = None
417        dict_obj = None
418        if name not in processed:
419            try:
420                if name == '__dict__':
421                    raise Exception("__dict__ is special, don't want the proxy")
422                get_obj = getattr(cls, name)
423            except Exception as exc:
424                pass
425            else:
426                homecls = getattr(get_obj, "__objclass__", homecls)
427                if homecls not in class_bases:
428                    # if the resulting object does not live somewhere in the
429                    # mro, drop it and search the mro manually
430                    homecls = None
431                    last_cls = None
432                    # first look in the classes
433                    for srch_cls in class_bases:
434                        srch_obj = getattr(srch_cls, name, None)
435                        if srch_obj is get_obj:
436                            last_cls = srch_cls
437                    # then check the metaclasses
438                    for srch_cls in metamro:
439                        try:
440                            srch_obj = srch_cls.__getattr__(cls, name)
441                        except AttributeError:
442                            continue
443                        if srch_obj is get_obj:
444                            last_cls = srch_cls
445                    if last_cls is not None:
446                        homecls = last_cls
447        for base in all_bases:
448            if name in base.__dict__:
449                dict_obj = base.__dict__[name]
450                if homecls not in metamro:
451                    homecls = base
452                break
453        if homecls is None:
454            # unable to locate the attribute anywhere, most likely due to
455            # buggy custom __dir__; discard and move on
456            continue
457        obj = get_obj if get_obj is not None else dict_obj
458        # Classify the object or its descriptor.
459        if isinstance(dict_obj, (staticmethod, types.BuiltinMethodType)):
460            kind = "static method"
461            obj = dict_obj
462        elif isinstance(dict_obj, (classmethod, types.ClassMethodDescriptorType)):
463            kind = "class method"
464            obj = dict_obj
465        elif isinstance(dict_obj, property):
466            kind = "property"
467            obj = dict_obj
468        elif isroutine(obj):
469            kind = "method"
470        else:
471            kind = "data"
472        result.append(Attribute(name, kind, homecls, obj))
473        processed.add(name)
474    return result
475
476# ----------------------------------------------------------- class helpers
477
478def getmro(cls):
479    "Return tuple of base classes (including cls) in method resolution order."
480    return cls.__mro__
481
482# -------------------------------------------------------- function helpers
483
484def unwrap(func, *, stop=None):
485    """Get the object wrapped by *func*.
486
487   Follows the chain of :attr:`__wrapped__` attributes returning the last
488   object in the chain.
489
490   *stop* is an optional callback accepting an object in the wrapper chain
491   as its sole argument that allows the unwrapping to be terminated early if
492   the callback returns a true value. If the callback never returns a true
493   value, the last object in the chain is returned as usual. For example,
494   :func:`signature` uses this to stop unwrapping if any object in the
495   chain has a ``__signature__`` attribute defined.
496
497   :exc:`ValueError` is raised if a cycle is encountered.
498
499    """
500    if stop is None:
501        def _is_wrapper(f):
502            return hasattr(f, '__wrapped__')
503    else:
504        def _is_wrapper(f):
505            return hasattr(f, '__wrapped__') and not stop(f)
506    f = func  # remember the original func for error reporting
507    # Memoise by id to tolerate non-hashable objects, but store objects to
508    # ensure they aren't destroyed, which would allow their IDs to be reused.
509    memo = {id(f): f}
510    recursion_limit = sys.getrecursionlimit()
511    while _is_wrapper(func):
512        func = func.__wrapped__
513        id_func = id(func)
514        if (id_func in memo) or (len(memo) >= recursion_limit):
515            raise ValueError('wrapper loop when unwrapping {!r}'.format(f))
516        memo[id_func] = func
517    return func
518
519# -------------------------------------------------- source code extraction
520def indentsize(line):
521    """Return the indent size, in spaces, at the start of a line of text."""
522    expline = line.expandtabs()
523    return len(expline) - len(expline.lstrip())
524
525def _findclass(func):
526    cls = sys.modules.get(func.__module__)
527    if cls is None:
528        return None
529    for name in func.__qualname__.split('.')[:-1]:
530        cls = getattr(cls, name)
531    if not isclass(cls):
532        return None
533    return cls
534
535def _finddoc(obj):
536    if isclass(obj):
537        for base in obj.__mro__:
538            if base is not object:
539                try:
540                    doc = base.__doc__
541                except AttributeError:
542                    continue
543                if doc is not None:
544                    return doc
545        return None
546
547    if ismethod(obj):
548        name = obj.__func__.__name__
549        self = obj.__self__
550        if (isclass(self) and
551            getattr(getattr(self, name, None), '__func__') is obj.__func__):
552            # classmethod
553            cls = self
554        else:
555            cls = self.__class__
556    elif isfunction(obj):
557        name = obj.__name__
558        cls = _findclass(obj)
559        if cls is None or getattr(cls, name) is not obj:
560            return None
561    elif isbuiltin(obj):
562        name = obj.__name__
563        self = obj.__self__
564        if (isclass(self) and
565            self.__qualname__ + '.' + name == obj.__qualname__):
566            # classmethod
567            cls = self
568        else:
569            cls = self.__class__
570    # Should be tested before isdatadescriptor().
571    elif isinstance(obj, property):
572        func = obj.fget
573        name = func.__name__
574        cls = _findclass(func)
575        if cls is None or getattr(cls, name) is not obj:
576            return None
577    elif ismethoddescriptor(obj) or isdatadescriptor(obj):
578        name = obj.__name__
579        cls = obj.__objclass__
580        if getattr(cls, name) is not obj:
581            return None
582    else:
583        return None
584
585    for base in cls.__mro__:
586        try:
587            doc = getattr(base, name).__doc__
588        except AttributeError:
589            continue
590        if doc is not None:
591            return doc
592    return None
593
594def getdoc(object):
595    """Get the documentation string for an object.
596
597    All tabs are expanded to spaces.  To clean up docstrings that are
598    indented to line up with blocks of code, any whitespace than can be
599    uniformly removed from the second line onwards is removed."""
600    try:
601        doc = object.__doc__
602    except AttributeError:
603        return None
604    if doc is None:
605        try:
606            doc = _finddoc(object)
607        except (AttributeError, TypeError):
608            return None
609    if not isinstance(doc, str):
610        return None
611    return cleandoc(doc)
612
613def cleandoc(doc):
614    """Clean up indentation from docstrings.
615
616    Any whitespace that can be uniformly removed from the second line
617    onwards is removed."""
618    try:
619        lines = doc.expandtabs().split('\n')
620    except UnicodeError:
621        return None
622    else:
623        # Find minimum indentation of any non-blank lines after first line.
624        margin = sys.maxsize
625        for line in lines[1:]:
626            content = len(line.lstrip())
627            if content:
628                indent = len(line) - content
629                margin = min(margin, indent)
630        # Remove indentation.
631        if lines:
632            lines[0] = lines[0].lstrip()
633        if margin < sys.maxsize:
634            for i in range(1, len(lines)): lines[i] = lines[i][margin:]
635        # Remove any trailing or leading blank lines.
636        while lines and not lines[-1]:
637            lines.pop()
638        while lines and not lines[0]:
639            lines.pop(0)
640        return '\n'.join(lines)
641
642def getfile(object):
643    """Work out which source or compiled file an object was defined in."""
644    if ismodule(object):
645        if getattr(object, '__file__', None):
646            return object.__file__
647        raise TypeError('{!r} is a built-in module'.format(object))
648    if isclass(object):
649        if hasattr(object, '__module__'):
650            object = sys.modules.get(object.__module__)
651            if getattr(object, '__file__', None):
652                return object.__file__
653        raise TypeError('{!r} is a built-in class'.format(object))
654    if ismethod(object):
655        object = object.__func__
656    if isfunction(object):
657        object = object.__code__
658    if istraceback(object):
659        object = object.tb_frame
660    if isframe(object):
661        object = object.f_code
662    if iscode(object):
663        return object.co_filename
664    raise TypeError('module, class, method, function, traceback, frame, or '
665                    'code object was expected, got {}'.format(
666                    type(object).__name__))
667
668def getmodulename(path):
669    """Return the module name for a given file, or None."""
670    fname = os.path.basename(path)
671    # Check for paths that look like an actual module file
672    suffixes = [(-len(suffix), suffix)
673                    for suffix in importlib.machinery.all_suffixes()]
674    suffixes.sort() # try longest suffixes first, in case they overlap
675    for neglen, suffix in suffixes:
676        if fname.endswith(suffix):
677            return fname[:neglen]
678    return None
679
680def getsourcefile(object):
681    """Return the filename that can be used to locate an object's source.
682    Return None if no way can be identified to get the source.
683    """
684    filename = getfile(object)
685    all_bytecode_suffixes = importlib.machinery.DEBUG_BYTECODE_SUFFIXES[:]
686    all_bytecode_suffixes += importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES[:]
687    if any(filename.endswith(s) for s in all_bytecode_suffixes):
688        filename = (os.path.splitext(filename)[0] +
689                    importlib.machinery.SOURCE_SUFFIXES[0])
690    elif any(filename.endswith(s) for s in
691                 importlib.machinery.EXTENSION_SUFFIXES):
692        return None
693    if os.path.exists(filename):
694        return filename
695    # only return a non-existent filename if the module has a PEP 302 loader
696    if getattr(getmodule(object, filename), '__loader__', None) is not None:
697        return filename
698    # or it is in the linecache
699    if filename in linecache.cache:
700        return filename
701
702def getabsfile(object, _filename=None):
703    """Return an absolute path to the source or compiled file for an object.
704
705    The idea is for each object to have a unique origin, so this routine
706    normalizes the result as much as possible."""
707    if _filename is None:
708        _filename = getsourcefile(object) or getfile(object)
709    return os.path.normcase(os.path.abspath(_filename))
710
711modulesbyfile = {}
712_filesbymodname = {}
713
714def getmodule(object, _filename=None):
715    """Return the module an object was defined in, or None if not found."""
716    if ismodule(object):
717        return object
718    if hasattr(object, '__module__'):
719        return sys.modules.get(object.__module__)
720    # Try the filename to modulename cache
721    if _filename is not None and _filename in modulesbyfile:
722        return sys.modules.get(modulesbyfile[_filename])
723    # Try the cache again with the absolute file name
724    try:
725        file = getabsfile(object, _filename)
726    except TypeError:
727        return None
728    if file in modulesbyfile:
729        return sys.modules.get(modulesbyfile[file])
730    # Update the filename to module name cache and check yet again
731    # Copy sys.modules in order to cope with changes while iterating
732    for modname, module in list(sys.modules.items()):
733        if ismodule(module) and hasattr(module, '__file__'):
734            f = module.__file__
735            if f == _filesbymodname.get(modname, None):
736                # Have already mapped this module, so skip it
737                continue
738            _filesbymodname[modname] = f
739            f = getabsfile(module)
740            # Always map to the name the module knows itself by
741            modulesbyfile[f] = modulesbyfile[
742                os.path.realpath(f)] = module.__name__
743    if file in modulesbyfile:
744        return sys.modules.get(modulesbyfile[file])
745    # Check the main module
746    main = sys.modules['__main__']
747    if not hasattr(object, '__name__'):
748        return None
749    if hasattr(main, object.__name__):
750        mainobject = getattr(main, object.__name__)
751        if mainobject is object:
752            return main
753    # Check builtins
754    builtin = sys.modules['builtins']
755    if hasattr(builtin, object.__name__):
756        builtinobject = getattr(builtin, object.__name__)
757        if builtinobject is object:
758            return builtin
759
760def findsource(object):
761    """Return the entire source file and starting line number for an object.
762
763    The argument may be a module, class, method, function, traceback, frame,
764    or code object.  The source code is returned as a list of all the lines
765    in the file and the line number indexes a line in that list.  An OSError
766    is raised if the source code cannot be retrieved."""
767
768    file = getsourcefile(object)
769    if file:
770        # Invalidate cache if needed.
771        linecache.checkcache(file)
772    else:
773        file = getfile(object)
774        # Allow filenames in form of "<something>" to pass through.
775        # `doctest` monkeypatches `linecache` module to enable
776        # inspection, so let `linecache.getlines` to be called.
777        if not (file.startswith('<') and file.endswith('>')):
778            raise OSError('source code not available')
779
780    module = getmodule(object, file)
781    if module:
782        lines = linecache.getlines(file, module.__dict__)
783    else:
784        lines = linecache.getlines(file)
785    if not lines:
786        raise OSError('could not get source code')
787
788    if ismodule(object):
789        return lines, 0
790
791    if isclass(object):
792        name = object.__name__
793        pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
794        # make some effort to find the best matching class definition:
795        # use the one with the least indentation, which is the one
796        # that's most probably not inside a function definition.
797        candidates = []
798        for i in range(len(lines)):
799            match = pat.match(lines[i])
800            if match:
801                # if it's at toplevel, it's already the best one
802                if lines[i][0] == 'c':
803                    return lines, i
804                # else add whitespace to candidate list
805                candidates.append((match.group(1), i))
806        if candidates:
807            # this will sort by whitespace, and by line number,
808            # less whitespace first
809            candidates.sort()
810            return lines, candidates[0][1]
811        else:
812            raise OSError('could not find class definition')
813
814    if ismethod(object):
815        object = object.__func__
816    if isfunction(object):
817        object = object.__code__
818    if istraceback(object):
819        object = object.tb_frame
820    if isframe(object):
821        object = object.f_code
822    if iscode(object):
823        if not hasattr(object, 'co_firstlineno'):
824            raise OSError('could not find function definition')
825        lnum = object.co_firstlineno - 1
826        pat = re.compile(r'^(\s*def\s)|(\s*async\s+def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
827        while lnum > 0:
828            if pat.match(lines[lnum]): break
829            lnum = lnum - 1
830        return lines, lnum
831    raise OSError('could not find code object')
832
833def getcomments(object):
834    """Get lines of comments immediately preceding an object's source code.
835
836    Returns None when source can't be found.
837    """
838    try:
839        lines, lnum = findsource(object)
840    except (OSError, TypeError):
841        return None
842
843    if ismodule(object):
844        # Look for a comment block at the top of the file.
845        start = 0
846        if lines and lines[0][:2] == '#!': start = 1
847        while start < len(lines) and lines[start].strip() in ('', '#'):
848            start = start + 1
849        if start < len(lines) and lines[start][:1] == '#':
850            comments = []
851            end = start
852            while end < len(lines) and lines[end][:1] == '#':
853                comments.append(lines[end].expandtabs())
854                end = end + 1
855            return ''.join(comments)
856
857    # Look for a preceding block of comments at the same indentation.
858    elif lnum > 0:
859        indent = indentsize(lines[lnum])
860        end = lnum - 1
861        if end >= 0 and lines[end].lstrip()[:1] == '#' and \
862            indentsize(lines[end]) == indent:
863            comments = [lines[end].expandtabs().lstrip()]
864            if end > 0:
865                end = end - 1
866                comment = lines[end].expandtabs().lstrip()
867                while comment[:1] == '#' and indentsize(lines[end]) == indent:
868                    comments[:0] = [comment]
869                    end = end - 1
870                    if end < 0: break
871                    comment = lines[end].expandtabs().lstrip()
872            while comments and comments[0].strip() == '#':
873                comments[:1] = []
874            while comments and comments[-1].strip() == '#':
875                comments[-1:] = []
876            return ''.join(comments)
877
878class EndOfBlock(Exception): pass
879
880class BlockFinder:
881    """Provide a tokeneater() method to detect the end of a code block."""
882    def __init__(self):
883        self.indent = 0
884        self.islambda = False
885        self.started = False
886        self.passline = False
887        self.indecorator = False
888        self.decoratorhasargs = False
889        self.last = 1
890
891    def tokeneater(self, type, token, srowcol, erowcol, line):
892        if not self.started and not self.indecorator:
893            # skip any decorators
894            if token == "@":
895                self.indecorator = True
896            # look for the first "def", "class" or "lambda"
897            elif token in ("def", "class", "lambda"):
898                if token == "lambda":
899                    self.islambda = True
900                self.started = True
901            self.passline = True    # skip to the end of the line
902        elif token == "(":
903            if self.indecorator:
904                self.decoratorhasargs = True
905        elif token == ")":
906            if self.indecorator:
907                self.indecorator = False
908                self.decoratorhasargs = False
909        elif type == tokenize.NEWLINE:
910            self.passline = False   # stop skipping when a NEWLINE is seen
911            self.last = srowcol[0]
912            if self.islambda:       # lambdas always end at the first NEWLINE
913                raise EndOfBlock
914            # hitting a NEWLINE when in a decorator without args
915            # ends the decorator
916            if self.indecorator and not self.decoratorhasargs:
917                self.indecorator = False
918        elif self.passline:
919            pass
920        elif type == tokenize.INDENT:
921            self.indent = self.indent + 1
922            self.passline = True
923        elif type == tokenize.DEDENT:
924            self.indent = self.indent - 1
925            # the end of matching indent/dedent pairs end a block
926            # (note that this only works for "def"/"class" blocks,
927            #  not e.g. for "if: else:" or "try: finally:" blocks)
928            if self.indent <= 0:
929                raise EndOfBlock
930        elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
931            # any other token on the same indentation level end the previous
932            # block as well, except the pseudo-tokens COMMENT and NL.
933            raise EndOfBlock
934
935def getblock(lines):
936    """Extract the block of code at the top of the given list of lines."""
937    blockfinder = BlockFinder()
938    try:
939        tokens = tokenize.generate_tokens(iter(lines).__next__)
940        for _token in tokens:
941            blockfinder.tokeneater(*_token)
942    except (EndOfBlock, IndentationError):
943        pass
944    return lines[:blockfinder.last]
945
946def getsourcelines(object):
947    """Return a list of source lines and starting line number for an object.
948
949    The argument may be a module, class, method, function, traceback, frame,
950    or code object.  The source code is returned as a list of the lines
951    corresponding to the object and the line number indicates where in the
952    original source file the first line of code was found.  An OSError is
953    raised if the source code cannot be retrieved."""
954    object = unwrap(object)
955    lines, lnum = findsource(object)
956
957    if istraceback(object):
958        object = object.tb_frame
959
960    # for module or frame that corresponds to module, return all source lines
961    if (ismodule(object) or
962        (isframe(object) and object.f_code.co_name == "<module>")):
963        return lines, 0
964    else:
965        return getblock(lines[lnum:]), lnum + 1
966
967def getsource(object):
968    """Return the text of the source code for an object.
969
970    The argument may be a module, class, method, function, traceback, frame,
971    or code object.  The source code is returned as a single string.  An
972    OSError is raised if the source code cannot be retrieved."""
973    lines, lnum = getsourcelines(object)
974    return ''.join(lines)
975
976# --------------------------------------------------- class tree extraction
977def walktree(classes, children, parent):
978    """Recursive helper function for getclasstree()."""
979    results = []
980    classes.sort(key=attrgetter('__module__', '__name__'))
981    for c in classes:
982        results.append((c, c.__bases__))
983        if c in children:
984            results.append(walktree(children[c], children, c))
985    return results
986
987def getclasstree(classes, unique=False):
988    """Arrange the given list of classes into a hierarchy of nested lists.
989
990    Where a nested list appears, it contains classes derived from the class
991    whose entry immediately precedes the list.  Each entry is a 2-tuple
992    containing a class and a tuple of its base classes.  If the 'unique'
993    argument is true, exactly one entry appears in the returned structure
994    for each class in the given list.  Otherwise, classes using multiple
995    inheritance and their descendants will appear multiple times."""
996    children = {}
997    roots = []
998    for c in classes:
999        if c.__bases__:
1000            for parent in c.__bases__:
1001                if not parent in children:
1002                    children[parent] = []
1003                if c not in children[parent]:
1004                    children[parent].append(c)
1005                if unique and parent in classes: break
1006        elif c not in roots:
1007            roots.append(c)
1008    for parent in children:
1009        if parent not in classes:
1010            roots.append(parent)
1011    return walktree(roots, children, None)
1012
1013# ------------------------------------------------ argument list extraction
1014Arguments = namedtuple('Arguments', 'args, varargs, varkw')
1015
1016def getargs(co):
1017    """Get information about the arguments accepted by a code object.
1018
1019    Three things are returned: (args, varargs, varkw), where
1020    'args' is the list of argument names. Keyword-only arguments are
1021    appended. 'varargs' and 'varkw' are the names of the * and **
1022    arguments or None."""
1023    args, varargs, kwonlyargs, varkw = _getfullargs(co)
1024    return Arguments(args + kwonlyargs, varargs, varkw)
1025
1026def _getfullargs(co):
1027    """Get information about the arguments accepted by a code object.
1028
1029    Four things are returned: (args, varargs, kwonlyargs, varkw), where
1030    'args' and 'kwonlyargs' are lists of argument names, and 'varargs'
1031    and 'varkw' are the names of the * and ** arguments or None."""
1032
1033    if not iscode(co):
1034        raise TypeError('{!r} is not a code object'.format(co))
1035
1036    nargs = co.co_argcount
1037    names = co.co_varnames
1038    nkwargs = co.co_kwonlyargcount
1039    args = list(names[:nargs])
1040    kwonlyargs = list(names[nargs:nargs+nkwargs])
1041    step = 0
1042
1043    nargs += nkwargs
1044    varargs = None
1045    if co.co_flags & CO_VARARGS:
1046        varargs = co.co_varnames[nargs]
1047        nargs = nargs + 1
1048    varkw = None
1049    if co.co_flags & CO_VARKEYWORDS:
1050        varkw = co.co_varnames[nargs]
1051    return args, varargs, kwonlyargs, varkw
1052
1053
1054ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
1055
1056def getargspec(func):
1057    """Get the names and default values of a function's parameters.
1058
1059    A tuple of four things is returned: (args, varargs, keywords, defaults).
1060    'args' is a list of the argument names, including keyword-only argument names.
1061    'varargs' and 'keywords' are the names of the * and ** parameters or None.
1062    'defaults' is an n-tuple of the default values of the last n parameters.
1063
1064    This function is deprecated, as it does not support annotations or
1065    keyword-only parameters and will raise ValueError if either is present
1066    on the supplied callable.
1067
1068    For a more structured introspection API, use inspect.signature() instead.
1069
1070    Alternatively, use getfullargspec() for an API with a similar namedtuple
1071    based interface, but full support for annotations and keyword-only
1072    parameters.
1073
1074    Deprecated since Python 3.5, use `inspect.getfullargspec()`.
1075    """
1076    warnings.warn("inspect.getargspec() is deprecated since Python 3.0, "
1077                  "use inspect.signature() or inspect.getfullargspec()",
1078                  DeprecationWarning, stacklevel=2)
1079    args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \
1080        getfullargspec(func)
1081    if kwonlyargs or ann:
1082        raise ValueError("Function has keyword-only parameters or annotations"
1083                         ", use getfullargspec() API which can support them")
1084    return ArgSpec(args, varargs, varkw, defaults)
1085
1086FullArgSpec = namedtuple('FullArgSpec',
1087    'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations')
1088
1089def getfullargspec(func):
1090    """Get the names and default values of a callable object's parameters.
1091
1092    A tuple of seven things is returned:
1093    (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations).
1094    'args' is a list of the parameter names.
1095    'varargs' and 'varkw' are the names of the * and ** parameters or None.
1096    'defaults' is an n-tuple of the default values of the last n parameters.
1097    'kwonlyargs' is a list of keyword-only parameter names.
1098    'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults.
1099    'annotations' is a dictionary mapping parameter names to annotations.
1100
1101    Notable differences from inspect.signature():
1102      - the "self" parameter is always reported, even for bound methods
1103      - wrapper chains defined by __wrapped__ *not* unwrapped automatically
1104    """
1105
1106    try:
1107        # Re: `skip_bound_arg=False`
1108        #
1109        # There is a notable difference in behaviour between getfullargspec
1110        # and Signature: the former always returns 'self' parameter for bound
1111        # methods, whereas the Signature always shows the actual calling
1112        # signature of the passed object.
1113        #
1114        # To simulate this behaviour, we "unbind" bound methods, to trick
1115        # inspect.signature to always return their first parameter ("self",
1116        # usually)
1117
1118        # Re: `follow_wrapper_chains=False`
1119        #
1120        # getfullargspec() historically ignored __wrapped__ attributes,
1121        # so we ensure that remains the case in 3.3+
1122
1123        sig = _signature_from_callable(func,
1124                                       follow_wrapper_chains=False,
1125                                       skip_bound_arg=False,
1126                                       sigcls=Signature)
1127    except Exception as ex:
1128        # Most of the times 'signature' will raise ValueError.
1129        # But, it can also raise AttributeError, and, maybe something
1130        # else. So to be fully backwards compatible, we catch all
1131        # possible exceptions here, and reraise a TypeError.
1132        raise TypeError('unsupported callable') from ex
1133
1134    args = []
1135    varargs = None
1136    varkw = None
1137    kwonlyargs = []
1138    defaults = ()
1139    annotations = {}
1140    defaults = ()
1141    kwdefaults = {}
1142
1143    if sig.return_annotation is not sig.empty:
1144        annotations['return'] = sig.return_annotation
1145
1146    for param in sig.parameters.values():
1147        kind = param.kind
1148        name = param.name
1149
1150        if kind is _POSITIONAL_ONLY:
1151            args.append(name)
1152        elif kind is _POSITIONAL_OR_KEYWORD:
1153            args.append(name)
1154            if param.default is not param.empty:
1155                defaults += (param.default,)
1156        elif kind is _VAR_POSITIONAL:
1157            varargs = name
1158        elif kind is _KEYWORD_ONLY:
1159            kwonlyargs.append(name)
1160            if param.default is not param.empty:
1161                kwdefaults[name] = param.default
1162        elif kind is _VAR_KEYWORD:
1163            varkw = name
1164
1165        if param.annotation is not param.empty:
1166            annotations[name] = param.annotation
1167
1168    if not kwdefaults:
1169        # compatibility with 'func.__kwdefaults__'
1170        kwdefaults = None
1171
1172    if not defaults:
1173        # compatibility with 'func.__defaults__'
1174        defaults = None
1175
1176    return FullArgSpec(args, varargs, varkw, defaults,
1177                       kwonlyargs, kwdefaults, annotations)
1178
1179
1180ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
1181
1182def getargvalues(frame):
1183    """Get information about arguments passed into a particular frame.
1184
1185    A tuple of four things is returned: (args, varargs, varkw, locals).
1186    'args' is a list of the argument names.
1187    'varargs' and 'varkw' are the names of the * and ** arguments or None.
1188    'locals' is the locals dictionary of the given frame."""
1189    args, varargs, varkw = getargs(frame.f_code)
1190    return ArgInfo(args, varargs, varkw, frame.f_locals)
1191
1192def formatannotation(annotation, base_module=None):
1193    if getattr(annotation, '__module__', None) == 'typing':
1194        return repr(annotation).replace('typing.', '')
1195    if isinstance(annotation, type):
1196        if annotation.__module__ in ('builtins', base_module):
1197            return annotation.__qualname__
1198        return annotation.__module__+'.'+annotation.__qualname__
1199    return repr(annotation)
1200
1201def formatannotationrelativeto(object):
1202    module = getattr(object, '__module__', None)
1203    def _formatannotation(annotation):
1204        return formatannotation(annotation, module)
1205    return _formatannotation
1206
1207def formatargspec(args, varargs=None, varkw=None, defaults=None,
1208                  kwonlyargs=(), kwonlydefaults={}, annotations={},
1209                  formatarg=str,
1210                  formatvarargs=lambda name: '*' + name,
1211                  formatvarkw=lambda name: '**' + name,
1212                  formatvalue=lambda value: '=' + repr(value),
1213                  formatreturns=lambda text: ' -> ' + text,
1214                  formatannotation=formatannotation):
1215    """Format an argument spec from the values returned by getfullargspec.
1216
1217    The first seven arguments are (args, varargs, varkw, defaults,
1218    kwonlyargs, kwonlydefaults, annotations).  The other five arguments
1219    are the corresponding optional formatting functions that are called to
1220    turn names and values into strings.  The last argument is an optional
1221    function to format the sequence of arguments.
1222
1223    Deprecated since Python 3.5: use the `signature` function and `Signature`
1224    objects.
1225    """
1226
1227    from warnings import warn
1228
1229    warn("`formatargspec` is deprecated since Python 3.5. Use `signature` and "
1230         "the `Signature` object directly",
1231         DeprecationWarning,
1232         stacklevel=2)
1233
1234    def formatargandannotation(arg):
1235        result = formatarg(arg)
1236        if arg in annotations:
1237            result += ': ' + formatannotation(annotations[arg])
1238        return result
1239    specs = []
1240    if defaults:
1241        firstdefault = len(args) - len(defaults)
1242    for i, arg in enumerate(args):
1243        spec = formatargandannotation(arg)
1244        if defaults and i >= firstdefault:
1245            spec = spec + formatvalue(defaults[i - firstdefault])
1246        specs.append(spec)
1247    if varargs is not None:
1248        specs.append(formatvarargs(formatargandannotation(varargs)))
1249    else:
1250        if kwonlyargs:
1251            specs.append('*')
1252    if kwonlyargs:
1253        for kwonlyarg in kwonlyargs:
1254            spec = formatargandannotation(kwonlyarg)
1255            if kwonlydefaults and kwonlyarg in kwonlydefaults:
1256                spec += formatvalue(kwonlydefaults[kwonlyarg])
1257            specs.append(spec)
1258    if varkw is not None:
1259        specs.append(formatvarkw(formatargandannotation(varkw)))
1260    result = '(' + ', '.join(specs) + ')'
1261    if 'return' in annotations:
1262        result += formatreturns(formatannotation(annotations['return']))
1263    return result
1264
1265def formatargvalues(args, varargs, varkw, locals,
1266                    formatarg=str,
1267                    formatvarargs=lambda name: '*' + name,
1268                    formatvarkw=lambda name: '**' + name,
1269                    formatvalue=lambda value: '=' + repr(value)):
1270    """Format an argument spec from the 4 values returned by getargvalues.
1271
1272    The first four arguments are (args, varargs, varkw, locals).  The
1273    next four arguments are the corresponding optional formatting functions
1274    that are called to turn names and values into strings.  The ninth
1275    argument is an optional function to format the sequence of arguments."""
1276    def convert(name, locals=locals,
1277                formatarg=formatarg, formatvalue=formatvalue):
1278        return formatarg(name) + formatvalue(locals[name])
1279    specs = []
1280    for i in range(len(args)):
1281        specs.append(convert(args[i]))
1282    if varargs:
1283        specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
1284    if varkw:
1285        specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
1286    return '(' + ', '.join(specs) + ')'
1287
1288def _missing_arguments(f_name, argnames, pos, values):
1289    names = [repr(name) for name in argnames if name not in values]
1290    missing = len(names)
1291    if missing == 1:
1292        s = names[0]
1293    elif missing == 2:
1294        s = "{} and {}".format(*names)
1295    else:
1296        tail = ", {} and {}".format(*names[-2:])
1297        del names[-2:]
1298        s = ", ".join(names) + tail
1299    raise TypeError("%s() missing %i required %s argument%s: %s" %
1300                    (f_name, missing,
1301                      "positional" if pos else "keyword-only",
1302                      "" if missing == 1 else "s", s))
1303
1304def _too_many(f_name, args, kwonly, varargs, defcount, given, values):
1305    atleast = len(args) - defcount
1306    kwonly_given = len([arg for arg in kwonly if arg in values])
1307    if varargs:
1308        plural = atleast != 1
1309        sig = "at least %d" % (atleast,)
1310    elif defcount:
1311        plural = True
1312        sig = "from %d to %d" % (atleast, len(args))
1313    else:
1314        plural = len(args) != 1
1315        sig = str(len(args))
1316    kwonly_sig = ""
1317    if kwonly_given:
1318        msg = " positional argument%s (and %d keyword-only argument%s)"
1319        kwonly_sig = (msg % ("s" if given != 1 else "", kwonly_given,
1320                             "s" if kwonly_given != 1 else ""))
1321    raise TypeError("%s() takes %s positional argument%s but %d%s %s given" %
1322            (f_name, sig, "s" if plural else "", given, kwonly_sig,
1323             "was" if given == 1 and not kwonly_given else "were"))
1324
1325def getcallargs(*func_and_positional, **named):
1326    """Get the mapping of arguments to values.
1327
1328    A dict is returned, with keys the function argument names (including the
1329    names of the * and ** arguments, if any), and values the respective bound
1330    values from 'positional' and 'named'."""
1331    func = func_and_positional[0]
1332    positional = func_and_positional[1:]
1333    spec = getfullargspec(func)
1334    args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = spec
1335    f_name = func.__name__
1336    arg2value = {}
1337
1338
1339    if ismethod(func) and func.__self__ is not None:
1340        # implicit 'self' (or 'cls' for classmethods) argument
1341        positional = (func.__self__,) + positional
1342    num_pos = len(positional)
1343    num_args = len(args)
1344    num_defaults = len(defaults) if defaults else 0
1345
1346    n = min(num_pos, num_args)
1347    for i in range(n):
1348        arg2value[args[i]] = positional[i]
1349    if varargs:
1350        arg2value[varargs] = tuple(positional[n:])
1351    possible_kwargs = set(args + kwonlyargs)
1352    if varkw:
1353        arg2value[varkw] = {}
1354    for kw, value in named.items():
1355        if kw not in possible_kwargs:
1356            if not varkw:
1357                raise TypeError("%s() got an unexpected keyword argument %r" %
1358                                (f_name, kw))
1359            arg2value[varkw][kw] = value
1360            continue
1361        if kw in arg2value:
1362            raise TypeError("%s() got multiple values for argument %r" %
1363                            (f_name, kw))
1364        arg2value[kw] = value
1365    if num_pos > num_args and not varargs:
1366        _too_many(f_name, args, kwonlyargs, varargs, num_defaults,
1367                   num_pos, arg2value)
1368    if num_pos < num_args:
1369        req = args[:num_args - num_defaults]
1370        for arg in req:
1371            if arg not in arg2value:
1372                _missing_arguments(f_name, req, True, arg2value)
1373        for i, arg in enumerate(args[num_args - num_defaults:]):
1374            if arg not in arg2value:
1375                arg2value[arg] = defaults[i]
1376    missing = 0
1377    for kwarg in kwonlyargs:
1378        if kwarg not in arg2value:
1379            if kwonlydefaults and kwarg in kwonlydefaults:
1380                arg2value[kwarg] = kwonlydefaults[kwarg]
1381            else:
1382                missing += 1
1383    if missing:
1384        _missing_arguments(f_name, kwonlyargs, False, arg2value)
1385    return arg2value
1386
1387ClosureVars = namedtuple('ClosureVars', 'nonlocals globals builtins unbound')
1388
1389def getclosurevars(func):
1390    """
1391    Get the mapping of free variables to their current values.
1392
1393    Returns a named tuple of dicts mapping the current nonlocal, global
1394    and builtin references as seen by the body of the function. A final
1395    set of unbound names that could not be resolved is also provided.
1396    """
1397
1398    if ismethod(func):
1399        func = func.__func__
1400
1401    if not isfunction(func):
1402        raise TypeError("{!r} is not a Python function".format(func))
1403
1404    code = func.__code__
1405    # Nonlocal references are named in co_freevars and resolved
1406    # by looking them up in __closure__ by positional index
1407    if func.__closure__ is None:
1408        nonlocal_vars = {}
1409    else:
1410        nonlocal_vars = {
1411            var : cell.cell_contents
1412            for var, cell in zip(code.co_freevars, func.__closure__)
1413       }
1414
1415    # Global and builtin references are named in co_names and resolved
1416    # by looking them up in __globals__ or __builtins__
1417    global_ns = func.__globals__
1418    builtin_ns = global_ns.get("__builtins__", builtins.__dict__)
1419    if ismodule(builtin_ns):
1420        builtin_ns = builtin_ns.__dict__
1421    global_vars = {}
1422    builtin_vars = {}
1423    unbound_names = set()
1424    for name in code.co_names:
1425        if name in ("None", "True", "False"):
1426            # Because these used to be builtins instead of keywords, they
1427            # may still show up as name references. We ignore them.
1428            continue
1429        try:
1430            global_vars[name] = global_ns[name]
1431        except KeyError:
1432            try:
1433                builtin_vars[name] = builtin_ns[name]
1434            except KeyError:
1435                unbound_names.add(name)
1436
1437    return ClosureVars(nonlocal_vars, global_vars,
1438                       builtin_vars, unbound_names)
1439
1440# -------------------------------------------------- stack frame extraction
1441
1442Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
1443
1444def getframeinfo(frame, context=1):
1445    """Get information about a frame or traceback object.
1446
1447    A tuple of five things is returned: the filename, the line number of
1448    the current line, the function name, a list of lines of context from
1449    the source code, and the index of the current line within that list.
1450    The optional second argument specifies the number of lines of context
1451    to return, which are centered around the current line."""
1452    if istraceback(frame):
1453        lineno = frame.tb_lineno
1454        frame = frame.tb_frame
1455    else:
1456        lineno = frame.f_lineno
1457    if not isframe(frame):
1458        raise TypeError('{!r} is not a frame or traceback object'.format(frame))
1459
1460    filename = getsourcefile(frame) or getfile(frame)
1461    if context > 0:
1462        start = lineno - 1 - context//2
1463        try:
1464            lines, lnum = findsource(frame)
1465        except OSError:
1466            lines = index = None
1467        else:
1468            start = max(0, min(start, len(lines) - context))
1469            lines = lines[start:start+context]
1470            index = lineno - 1 - start
1471    else:
1472        lines = index = None
1473
1474    return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
1475
1476def getlineno(frame):
1477    """Get the line number from a frame object, allowing for optimization."""
1478    # FrameType.f_lineno is now a descriptor that grovels co_lnotab
1479    return frame.f_lineno
1480
1481FrameInfo = namedtuple('FrameInfo', ('frame',) + Traceback._fields)
1482
1483def getouterframes(frame, context=1):
1484    """Get a list of records for a frame and all higher (calling) frames.
1485
1486    Each record contains a frame object, filename, line number, function
1487    name, a list of lines of context, and index within the context."""
1488    framelist = []
1489    while frame:
1490        frameinfo = (frame,) + getframeinfo(frame, context)
1491        framelist.append(FrameInfo(*frameinfo))
1492        frame = frame.f_back
1493    return framelist
1494
1495def getinnerframes(tb, context=1):
1496    """Get a list of records for a traceback's frame and all lower frames.
1497
1498    Each record contains a frame object, filename, line number, function
1499    name, a list of lines of context, and index within the context."""
1500    framelist = []
1501    while tb:
1502        frameinfo = (tb.tb_frame,) + getframeinfo(tb, context)
1503        framelist.append(FrameInfo(*frameinfo))
1504        tb = tb.tb_next
1505    return framelist
1506
1507def currentframe():
1508    """Return the frame of the caller or None if this is not possible."""
1509    return sys._getframe(1) if hasattr(sys, "_getframe") else None
1510
1511def stack(context=1):
1512    """Return a list of records for the stack above the caller's frame."""
1513    return getouterframes(sys._getframe(1), context)
1514
1515def trace(context=1):
1516    """Return a list of records for the stack below the current exception."""
1517    return getinnerframes(sys.exc_info()[2], context)
1518
1519
1520# ------------------------------------------------ static version of getattr
1521
1522_sentinel = object()
1523
1524def _static_getmro(klass):
1525    return type.__dict__['__mro__'].__get__(klass)
1526
1527def _check_instance(obj, attr):
1528    instance_dict = {}
1529    try:
1530        instance_dict = object.__getattribute__(obj, "__dict__")
1531    except AttributeError:
1532        pass
1533    return dict.get(instance_dict, attr, _sentinel)
1534
1535
1536def _check_class(klass, attr):
1537    for entry in _static_getmro(klass):
1538        if _shadowed_dict(type(entry)) is _sentinel:
1539            try:
1540                return entry.__dict__[attr]
1541            except KeyError:
1542                pass
1543    return _sentinel
1544
1545def _is_type(obj):
1546    try:
1547        _static_getmro(obj)
1548    except TypeError:
1549        return False
1550    return True
1551
1552def _shadowed_dict(klass):
1553    dict_attr = type.__dict__["__dict__"]
1554    for entry in _static_getmro(klass):
1555        try:
1556            class_dict = dict_attr.__get__(entry)["__dict__"]
1557        except KeyError:
1558            pass
1559        else:
1560            if not (type(class_dict) is types.GetSetDescriptorType and
1561                    class_dict.__name__ == "__dict__" and
1562                    class_dict.__objclass__ is entry):
1563                return class_dict
1564    return _sentinel
1565
1566def getattr_static(obj, attr, default=_sentinel):
1567    """Retrieve attributes without triggering dynamic lookup via the
1568       descriptor protocol,  __getattr__ or __getattribute__.
1569
1570       Note: this function may not be able to retrieve all attributes
1571       that getattr can fetch (like dynamically created attributes)
1572       and may find attributes that getattr can't (like descriptors
1573       that raise AttributeError). It can also return descriptor objects
1574       instead of instance members in some cases. See the
1575       documentation for details.
1576    """
1577    instance_result = _sentinel
1578    if not _is_type(obj):
1579        klass = type(obj)
1580        dict_attr = _shadowed_dict(klass)
1581        if (dict_attr is _sentinel or
1582            type(dict_attr) is types.MemberDescriptorType):
1583            instance_result = _check_instance(obj, attr)
1584    else:
1585        klass = obj
1586
1587    klass_result = _check_class(klass, attr)
1588
1589    if instance_result is not _sentinel and klass_result is not _sentinel:
1590        if (_check_class(type(klass_result), '__get__') is not _sentinel and
1591            _check_class(type(klass_result), '__set__') is not _sentinel):
1592            return klass_result
1593
1594    if instance_result is not _sentinel:
1595        return instance_result
1596    if klass_result is not _sentinel:
1597        return klass_result
1598
1599    if obj is klass:
1600        # for types we check the metaclass too
1601        for entry in _static_getmro(type(klass)):
1602            if _shadowed_dict(type(entry)) is _sentinel:
1603                try:
1604                    return entry.__dict__[attr]
1605                except KeyError:
1606                    pass
1607    if default is not _sentinel:
1608        return default
1609    raise AttributeError(attr)
1610
1611
1612# ------------------------------------------------ generator introspection
1613
1614GEN_CREATED = 'GEN_CREATED'
1615GEN_RUNNING = 'GEN_RUNNING'
1616GEN_SUSPENDED = 'GEN_SUSPENDED'
1617GEN_CLOSED = 'GEN_CLOSED'
1618
1619def getgeneratorstate(generator):
1620    """Get current state of a generator-iterator.
1621
1622    Possible states are:
1623      GEN_CREATED: Waiting to start execution.
1624      GEN_RUNNING: Currently being executed by the interpreter.
1625      GEN_SUSPENDED: Currently suspended at a yield expression.
1626      GEN_CLOSED: Execution has completed.
1627    """
1628    if generator.gi_running:
1629        return GEN_RUNNING
1630    if generator.gi_frame is None:
1631        return GEN_CLOSED
1632    if generator.gi_frame.f_lasti == -1:
1633        return GEN_CREATED
1634    return GEN_SUSPENDED
1635
1636
1637def getgeneratorlocals(generator):
1638    """
1639    Get the mapping of generator local variables to their current values.
1640
1641    A dict is returned, with the keys the local variable names and values the
1642    bound values."""
1643
1644    if not isgenerator(generator):
1645        raise TypeError("{!r} is not a Python generator".format(generator))
1646
1647    frame = getattr(generator, "gi_frame", None)
1648    if frame is not None:
1649        return generator.gi_frame.f_locals
1650    else:
1651        return {}
1652
1653
1654# ------------------------------------------------ coroutine introspection
1655
1656CORO_CREATED = 'CORO_CREATED'
1657CORO_RUNNING = 'CORO_RUNNING'
1658CORO_SUSPENDED = 'CORO_SUSPENDED'
1659CORO_CLOSED = 'CORO_CLOSED'
1660
1661def getcoroutinestate(coroutine):
1662    """Get current state of a coroutine object.
1663
1664    Possible states are:
1665      CORO_CREATED: Waiting to start execution.
1666      CORO_RUNNING: Currently being executed by the interpreter.
1667      CORO_SUSPENDED: Currently suspended at an await expression.
1668      CORO_CLOSED: Execution has completed.
1669    """
1670    if coroutine.cr_running:
1671        return CORO_RUNNING
1672    if coroutine.cr_frame is None:
1673        return CORO_CLOSED
1674    if coroutine.cr_frame.f_lasti == -1:
1675        return CORO_CREATED
1676    return CORO_SUSPENDED
1677
1678
1679def getcoroutinelocals(coroutine):
1680    """
1681    Get the mapping of coroutine local variables to their current values.
1682
1683    A dict is returned, with the keys the local variable names and values the
1684    bound values."""
1685    frame = getattr(coroutine, "cr_frame", None)
1686    if frame is not None:
1687        return frame.f_locals
1688    else:
1689        return {}
1690
1691
1692###############################################################################
1693### Function Signature Object (PEP 362)
1694###############################################################################
1695
1696
1697_WrapperDescriptor = type(type.__call__)
1698_MethodWrapper = type(all.__call__)
1699_ClassMethodWrapper = type(int.__dict__['from_bytes'])
1700
1701_NonUserDefinedCallables = (_WrapperDescriptor,
1702                            _MethodWrapper,
1703                            _ClassMethodWrapper,
1704                            types.BuiltinFunctionType)
1705
1706
1707def _signature_get_user_defined_method(cls, method_name):
1708    """Private helper. Checks if ``cls`` has an attribute
1709    named ``method_name`` and returns it only if it is a
1710    pure python function.
1711    """
1712    try:
1713        meth = getattr(cls, method_name)
1714    except AttributeError:
1715        return
1716    else:
1717        if not isinstance(meth, _NonUserDefinedCallables):
1718            # Once '__signature__' will be added to 'C'-level
1719            # callables, this check won't be necessary
1720            return meth
1721
1722
1723def _signature_get_partial(wrapped_sig, partial, extra_args=()):
1724    """Private helper to calculate how 'wrapped_sig' signature will
1725    look like after applying a 'functools.partial' object (or alike)
1726    on it.
1727    """
1728
1729    old_params = wrapped_sig.parameters
1730    new_params = OrderedDict(old_params.items())
1731
1732    partial_args = partial.args or ()
1733    partial_keywords = partial.keywords or {}
1734
1735    if extra_args:
1736        partial_args = extra_args + partial_args
1737
1738    try:
1739        ba = wrapped_sig.bind_partial(*partial_args, **partial_keywords)
1740    except TypeError as ex:
1741        msg = 'partial object {!r} has incorrect arguments'.format(partial)
1742        raise ValueError(msg) from ex
1743
1744
1745    transform_to_kwonly = False
1746    for param_name, param in old_params.items():
1747        try:
1748            arg_value = ba.arguments[param_name]
1749        except KeyError:
1750            pass
1751        else:
1752            if param.kind is _POSITIONAL_ONLY:
1753                # If positional-only parameter is bound by partial,
1754                # it effectively disappears from the signature
1755                new_params.pop(param_name)
1756                continue
1757
1758            if param.kind is _POSITIONAL_OR_KEYWORD:
1759                if param_name in partial_keywords:
1760                    # This means that this parameter, and all parameters
1761                    # after it should be keyword-only (and var-positional
1762                    # should be removed). Here's why. Consider the following
1763                    # function:
1764                    #     foo(a, b, *args, c):
1765                    #         pass
1766                    #
1767                    # "partial(foo, a='spam')" will have the following
1768                    # signature: "(*, a='spam', b, c)". Because attempting
1769                    # to call that partial with "(10, 20)" arguments will
1770                    # raise a TypeError, saying that "a" argument received
1771                    # multiple values.
1772                    transform_to_kwonly = True
1773                    # Set the new default value
1774                    new_params[param_name] = param.replace(default=arg_value)
1775                else:
1776                    # was passed as a positional argument
1777                    new_params.pop(param.name)
1778                    continue
1779
1780            if param.kind is _KEYWORD_ONLY:
1781                # Set the new default value
1782                new_params[param_name] = param.replace(default=arg_value)
1783
1784        if transform_to_kwonly:
1785            assert param.kind is not _POSITIONAL_ONLY
1786
1787            if param.kind is _POSITIONAL_OR_KEYWORD:
1788                new_param = new_params[param_name].replace(kind=_KEYWORD_ONLY)
1789                new_params[param_name] = new_param
1790                new_params.move_to_end(param_name)
1791            elif param.kind in (_KEYWORD_ONLY, _VAR_KEYWORD):
1792                new_params.move_to_end(param_name)
1793            elif param.kind is _VAR_POSITIONAL:
1794                new_params.pop(param.name)
1795
1796    return wrapped_sig.replace(parameters=new_params.values())
1797
1798
1799def _signature_bound_method(sig):
1800    """Private helper to transform signatures for unbound
1801    functions to bound methods.
1802    """
1803
1804    params = tuple(sig.parameters.values())
1805
1806    if not params or params[0].kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
1807        raise ValueError('invalid method signature')
1808
1809    kind = params[0].kind
1810    if kind in (_POSITIONAL_OR_KEYWORD, _POSITIONAL_ONLY):
1811        # Drop first parameter:
1812        # '(p1, p2[, ...])' -> '(p2[, ...])'
1813        params = params[1:]
1814    else:
1815        if kind is not _VAR_POSITIONAL:
1816            # Unless we add a new parameter type we never
1817            # get here
1818            raise ValueError('invalid argument type')
1819        # It's a var-positional parameter.
1820        # Do nothing. '(*args[, ...])' -> '(*args[, ...])'
1821
1822    return sig.replace(parameters=params)
1823
1824
1825def _signature_is_builtin(obj):
1826    """Private helper to test if `obj` is a callable that might
1827    support Argument Clinic's __text_signature__ protocol.
1828    """
1829    return (isbuiltin(obj) or
1830            ismethoddescriptor(obj) or
1831            isinstance(obj, _NonUserDefinedCallables) or
1832            # Can't test 'isinstance(type)' here, as it would
1833            # also be True for regular python classes
1834            obj in (type, object))
1835
1836
1837def _signature_is_functionlike(obj):
1838    """Private helper to test if `obj` is a duck type of FunctionType.
1839    A good example of such objects are functions compiled with
1840    Cython, which have all attributes that a pure Python function
1841    would have, but have their code statically compiled.
1842    """
1843
1844    if not callable(obj) or isclass(obj):
1845        # All function-like objects are obviously callables,
1846        # and not classes.
1847        return False
1848
1849    name = getattr(obj, '__name__', None)
1850    code = getattr(obj, '__code__', None)
1851    defaults = getattr(obj, '__defaults__', _void) # Important to use _void ...
1852    kwdefaults = getattr(obj, '__kwdefaults__', _void) # ... and not None here
1853    annotations = getattr(obj, '__annotations__', None)
1854
1855    return (isinstance(code, types.CodeType) and
1856            isinstance(name, str) and
1857            (defaults is None or isinstance(defaults, tuple)) and
1858            (kwdefaults is None or isinstance(kwdefaults, dict)) and
1859            isinstance(annotations, dict))
1860
1861
1862def _signature_get_bound_param(spec):
1863    """ Private helper to get first parameter name from a
1864    __text_signature__ of a builtin method, which should
1865    be in the following format: '($param1, ...)'.
1866    Assumptions are that the first argument won't have
1867    a default value or an annotation.
1868    """
1869
1870    assert spec.startswith('($')
1871
1872    pos = spec.find(',')
1873    if pos == -1:
1874        pos = spec.find(')')
1875
1876    cpos = spec.find(':')
1877    assert cpos == -1 or cpos > pos
1878
1879    cpos = spec.find('=')
1880    assert cpos == -1 or cpos > pos
1881
1882    return spec[2:pos]
1883
1884
1885def _signature_strip_non_python_syntax(signature):
1886    """
1887    Private helper function. Takes a signature in Argument Clinic's
1888    extended signature format.
1889
1890    Returns a tuple of three things:
1891      * that signature re-rendered in standard Python syntax,
1892      * the index of the "self" parameter (generally 0), or None if
1893        the function does not have a "self" parameter, and
1894      * the index of the last "positional only" parameter,
1895        or None if the signature has no positional-only parameters.
1896    """
1897
1898    if not signature:
1899        return signature, None, None
1900
1901    self_parameter = None
1902    last_positional_only = None
1903
1904    lines = [l.encode('ascii') for l in signature.split('\n')]
1905    generator = iter(lines).__next__
1906    token_stream = tokenize.tokenize(generator)
1907
1908    delayed_comma = False
1909    skip_next_comma = False
1910    text = []
1911    add = text.append
1912
1913    current_parameter = 0
1914    OP = token.OP
1915    ERRORTOKEN = token.ERRORTOKEN
1916
1917    # token stream always starts with ENCODING token, skip it
1918    t = next(token_stream)
1919    assert t.type == tokenize.ENCODING
1920
1921    for t in token_stream:
1922        type, string = t.type, t.string
1923
1924        if type == OP:
1925            if string == ',':
1926                if skip_next_comma:
1927                    skip_next_comma = False
1928                else:
1929                    assert not delayed_comma
1930                    delayed_comma = True
1931                    current_parameter += 1
1932                continue
1933
1934            if string == '/':
1935                assert not skip_next_comma
1936                assert last_positional_only is None
1937                skip_next_comma = True
1938                last_positional_only = current_parameter - 1
1939                continue
1940
1941        if (type == ERRORTOKEN) and (string == '$'):
1942            assert self_parameter is None
1943            self_parameter = current_parameter
1944            continue
1945
1946        if delayed_comma:
1947            delayed_comma = False
1948            if not ((type == OP) and (string == ')')):
1949                add(', ')
1950        add(string)
1951        if (string == ','):
1952            add(' ')
1953    clean_signature = ''.join(text)
1954    return clean_signature, self_parameter, last_positional_only
1955
1956
1957def _signature_fromstr(cls, obj, s, skip_bound_arg=True):
1958    """Private helper to parse content of '__text_signature__'
1959    and return a Signature based on it.
1960    """
1961    # Lazy import ast because it's relatively heavy and
1962    # it's not used for other than this function.
1963    import ast
1964
1965    Parameter = cls._parameter_cls
1966
1967    clean_signature, self_parameter, last_positional_only = \
1968        _signature_strip_non_python_syntax(s)
1969
1970    program = "def foo" + clean_signature + ": pass"
1971
1972    try:
1973        module = ast.parse(program)
1974    except SyntaxError:
1975        module = None
1976
1977    if not isinstance(module, ast.Module):
1978        raise ValueError("{!r} builtin has invalid signature".format(obj))
1979
1980    f = module.body[0]
1981
1982    parameters = []
1983    empty = Parameter.empty
1984    invalid = object()
1985
1986    module = None
1987    module_dict = {}
1988    module_name = getattr(obj, '__module__', None)
1989    if module_name:
1990        module = sys.modules.get(module_name, None)
1991        if module:
1992            module_dict = module.__dict__
1993    sys_module_dict = sys.modules.copy()
1994
1995    def parse_name(node):
1996        assert isinstance(node, ast.arg)
1997        if node.annotation != None:
1998            raise ValueError("Annotations are not currently supported")
1999        return node.arg
2000
2001    def wrap_value(s):
2002        try:
2003            value = eval(s, module_dict)
2004        except NameError:
2005            try:
2006                value = eval(s, sys_module_dict)
2007            except NameError:
2008                raise RuntimeError()
2009
2010        if isinstance(value, str):
2011            return ast.Str(value)
2012        if isinstance(value, (int, float)):
2013            return ast.Num(value)
2014        if isinstance(value, bytes):
2015            return ast.Bytes(value)
2016        if value in (True, False, None):
2017            return ast.NameConstant(value)
2018        raise RuntimeError()
2019
2020    class RewriteSymbolics(ast.NodeTransformer):
2021        def visit_Attribute(self, node):
2022            a = []
2023            n = node
2024            while isinstance(n, ast.Attribute):
2025                a.append(n.attr)
2026                n = n.value
2027            if not isinstance(n, ast.Name):
2028                raise RuntimeError()
2029            a.append(n.id)
2030            value = ".".join(reversed(a))
2031            return wrap_value(value)
2032
2033        def visit_Name(self, node):
2034            if not isinstance(node.ctx, ast.Load):
2035                raise ValueError()
2036            return wrap_value(node.id)
2037
2038    def p(name_node, default_node, default=empty):
2039        name = parse_name(name_node)
2040        if name is invalid:
2041            return None
2042        if default_node and default_node is not _empty:
2043            try:
2044                default_node = RewriteSymbolics().visit(default_node)
2045                o = ast.literal_eval(default_node)
2046            except ValueError:
2047                o = invalid
2048            if o is invalid:
2049                return None
2050            default = o if o is not invalid else default
2051        parameters.append(Parameter(name, kind, default=default, annotation=empty))
2052
2053    # non-keyword-only parameters
2054    args = reversed(f.args.args)
2055    defaults = reversed(f.args.defaults)
2056    iter = itertools.zip_longest(args, defaults, fillvalue=None)
2057    if last_positional_only is not None:
2058        kind = Parameter.POSITIONAL_ONLY
2059    else:
2060        kind = Parameter.POSITIONAL_OR_KEYWORD
2061    for i, (name, default) in enumerate(reversed(list(iter))):
2062        p(name, default)
2063        if i == last_positional_only:
2064            kind = Parameter.POSITIONAL_OR_KEYWORD
2065
2066    # *args
2067    if f.args.vararg:
2068        kind = Parameter.VAR_POSITIONAL
2069        p(f.args.vararg, empty)
2070
2071    # keyword-only arguments
2072    kind = Parameter.KEYWORD_ONLY
2073    for name, default in zip(f.args.kwonlyargs, f.args.kw_defaults):
2074        p(name, default)
2075
2076    # **kwargs
2077    if f.args.kwarg:
2078        kind = Parameter.VAR_KEYWORD
2079        p(f.args.kwarg, empty)
2080
2081    if self_parameter is not None:
2082        # Possibly strip the bound argument:
2083        #    - We *always* strip first bound argument if
2084        #      it is a module.
2085        #    - We don't strip first bound argument if
2086        #      skip_bound_arg is False.
2087        assert parameters
2088        _self = getattr(obj, '__self__', None)
2089        self_isbound = _self is not None
2090        self_ismodule = ismodule(_self)
2091        if self_isbound and (self_ismodule or skip_bound_arg):
2092            parameters.pop(0)
2093        else:
2094            # for builtins, self parameter is always positional-only!
2095            p = parameters[0].replace(kind=Parameter.POSITIONAL_ONLY)
2096            parameters[0] = p
2097
2098    return cls(parameters, return_annotation=cls.empty)
2099
2100
2101def _signature_from_builtin(cls, func, skip_bound_arg=True):
2102    """Private helper function to get signature for
2103    builtin callables.
2104    """
2105
2106    if not _signature_is_builtin(func):
2107        raise TypeError("{!r} is not a Python builtin "
2108                        "function".format(func))
2109
2110    s = getattr(func, "__text_signature__", None)
2111    if not s:
2112        raise ValueError("no signature found for builtin {!r}".format(func))
2113
2114    return _signature_fromstr(cls, func, s, skip_bound_arg)
2115
2116
2117def _signature_from_function(cls, func):
2118    """Private helper: constructs Signature for the given python function."""
2119
2120    is_duck_function = False
2121    if not isfunction(func):
2122        if _signature_is_functionlike(func):
2123            is_duck_function = True
2124        else:
2125            # If it's not a pure Python function, and not a duck type
2126            # of pure function:
2127            raise TypeError('{!r} is not a Python function'.format(func))
2128
2129    Parameter = cls._parameter_cls
2130
2131    # Parameter information.
2132    func_code = func.__code__
2133    pos_count = func_code.co_argcount
2134    arg_names = func_code.co_varnames
2135    positional = tuple(arg_names[:pos_count])
2136    keyword_only_count = func_code.co_kwonlyargcount
2137    keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
2138    annotations = func.__annotations__
2139    defaults = func.__defaults__
2140    kwdefaults = func.__kwdefaults__
2141
2142    if defaults:
2143        pos_default_count = len(defaults)
2144    else:
2145        pos_default_count = 0
2146
2147    parameters = []
2148
2149    # Non-keyword-only parameters w/o defaults.
2150    non_default_count = pos_count - pos_default_count
2151    for name in positional[:non_default_count]:
2152        annotation = annotations.get(name, _empty)
2153        parameters.append(Parameter(name, annotation=annotation,
2154                                    kind=_POSITIONAL_OR_KEYWORD))
2155
2156    # ... w/ defaults.
2157    for offset, name in enumerate(positional[non_default_count:]):
2158        annotation = annotations.get(name, _empty)
2159        parameters.append(Parameter(name, annotation=annotation,
2160                                    kind=_POSITIONAL_OR_KEYWORD,
2161                                    default=defaults[offset]))
2162
2163    # *args
2164    if func_code.co_flags & CO_VARARGS:
2165        name = arg_names[pos_count + keyword_only_count]
2166        annotation = annotations.get(name, _empty)
2167        parameters.append(Parameter(name, annotation=annotation,
2168                                    kind=_VAR_POSITIONAL))
2169
2170    # Keyword-only parameters.
2171    for name in keyword_only:
2172        default = _empty
2173        if kwdefaults is not None:
2174            default = kwdefaults.get(name, _empty)
2175
2176        annotation = annotations.get(name, _empty)
2177        parameters.append(Parameter(name, annotation=annotation,
2178                                    kind=_KEYWORD_ONLY,
2179                                    default=default))
2180    # **kwargs
2181    if func_code.co_flags & CO_VARKEYWORDS:
2182        index = pos_count + keyword_only_count
2183        if func_code.co_flags & CO_VARARGS:
2184            index += 1
2185
2186        name = arg_names[index]
2187        annotation = annotations.get(name, _empty)
2188        parameters.append(Parameter(name, annotation=annotation,
2189                                    kind=_VAR_KEYWORD))
2190
2191    # Is 'func' is a pure Python function - don't validate the
2192    # parameters list (for correct order and defaults), it should be OK.
2193    return cls(parameters,
2194               return_annotation=annotations.get('return', _empty),
2195               __validate_parameters__=is_duck_function)
2196
2197
2198def _signature_from_callable(obj, *,
2199                             follow_wrapper_chains=True,
2200                             skip_bound_arg=True,
2201                             sigcls):
2202
2203    """Private helper function to get signature for arbitrary
2204    callable objects.
2205    """
2206
2207    if not callable(obj):
2208        raise TypeError('{!r} is not a callable object'.format(obj))
2209
2210    if isinstance(obj, types.MethodType):
2211        # In this case we skip the first parameter of the underlying
2212        # function (usually `self` or `cls`).
2213        sig = _signature_from_callable(
2214            obj.__func__,
2215            follow_wrapper_chains=follow_wrapper_chains,
2216            skip_bound_arg=skip_bound_arg,
2217            sigcls=sigcls)
2218
2219        if skip_bound_arg:
2220            return _signature_bound_method(sig)
2221        else:
2222            return sig
2223
2224    # Was this function wrapped by a decorator?
2225    if follow_wrapper_chains:
2226        obj = unwrap(obj, stop=(lambda f: hasattr(f, "__signature__")))
2227        if isinstance(obj, types.MethodType):
2228            # If the unwrapped object is a *method*, we might want to
2229            # skip its first parameter (self).
2230            # See test_signature_wrapped_bound_method for details.
2231            return _signature_from_callable(
2232                obj,
2233                follow_wrapper_chains=follow_wrapper_chains,
2234                skip_bound_arg=skip_bound_arg,
2235                sigcls=sigcls)
2236
2237    try:
2238        sig = obj.__signature__
2239    except AttributeError:
2240        pass
2241    else:
2242        if sig is not None:
2243            if not isinstance(sig, Signature):
2244                raise TypeError(
2245                    'unexpected object {!r} in __signature__ '
2246                    'attribute'.format(sig))
2247            return sig
2248
2249    try:
2250        partialmethod = obj._partialmethod
2251    except AttributeError:
2252        pass
2253    else:
2254        if isinstance(partialmethod, functools.partialmethod):
2255            # Unbound partialmethod (see functools.partialmethod)
2256            # This means, that we need to calculate the signature
2257            # as if it's a regular partial object, but taking into
2258            # account that the first positional argument
2259            # (usually `self`, or `cls`) will not be passed
2260            # automatically (as for boundmethods)
2261
2262            wrapped_sig = _signature_from_callable(
2263                partialmethod.func,
2264                follow_wrapper_chains=follow_wrapper_chains,
2265                skip_bound_arg=skip_bound_arg,
2266                sigcls=sigcls)
2267
2268            sig = _signature_get_partial(wrapped_sig, partialmethod, (None,))
2269            first_wrapped_param = tuple(wrapped_sig.parameters.values())[0]
2270            if first_wrapped_param.kind is Parameter.VAR_POSITIONAL:
2271                # First argument of the wrapped callable is `*args`, as in
2272                # `partialmethod(lambda *args)`.
2273                return sig
2274            else:
2275                sig_params = tuple(sig.parameters.values())
2276                assert (not sig_params or
2277                        first_wrapped_param is not sig_params[0])
2278                new_params = (first_wrapped_param,) + sig_params
2279                return sig.replace(parameters=new_params)
2280
2281    if isfunction(obj) or _signature_is_functionlike(obj):
2282        # If it's a pure Python function, or an object that is duck type
2283        # of a Python function (Cython functions, for instance), then:
2284        return _signature_from_function(sigcls, obj)
2285
2286    if _signature_is_builtin(obj):
2287        return _signature_from_builtin(sigcls, obj,
2288                                       skip_bound_arg=skip_bound_arg)
2289
2290    if isinstance(obj, functools.partial):
2291        wrapped_sig = _signature_from_callable(
2292            obj.func,
2293            follow_wrapper_chains=follow_wrapper_chains,
2294            skip_bound_arg=skip_bound_arg,
2295            sigcls=sigcls)
2296        return _signature_get_partial(wrapped_sig, obj)
2297
2298    sig = None
2299    if isinstance(obj, type):
2300        # obj is a class or a metaclass
2301
2302        # First, let's see if it has an overloaded __call__ defined
2303        # in its metaclass
2304        call = _signature_get_user_defined_method(type(obj), '__call__')
2305        if call is not None:
2306            sig = _signature_from_callable(
2307                call,
2308                follow_wrapper_chains=follow_wrapper_chains,
2309                skip_bound_arg=skip_bound_arg,
2310                sigcls=sigcls)
2311        else:
2312            # Now we check if the 'obj' class has a '__new__' method
2313            new = _signature_get_user_defined_method(obj, '__new__')
2314            if new is not None:
2315                sig = _signature_from_callable(
2316                    new,
2317                    follow_wrapper_chains=follow_wrapper_chains,
2318                    skip_bound_arg=skip_bound_arg,
2319                    sigcls=sigcls)
2320            else:
2321                # Finally, we should have at least __init__ implemented
2322                init = _signature_get_user_defined_method(obj, '__init__')
2323                if init is not None:
2324                    sig = _signature_from_callable(
2325                        init,
2326                        follow_wrapper_chains=follow_wrapper_chains,
2327                        skip_bound_arg=skip_bound_arg,
2328                        sigcls=sigcls)
2329
2330        if sig is None:
2331            # At this point we know, that `obj` is a class, with no user-
2332            # defined '__init__', '__new__', or class-level '__call__'
2333
2334            for base in obj.__mro__[:-1]:
2335                # Since '__text_signature__' is implemented as a
2336                # descriptor that extracts text signature from the
2337                # class docstring, if 'obj' is derived from a builtin
2338                # class, its own '__text_signature__' may be 'None'.
2339                # Therefore, we go through the MRO (except the last
2340                # class in there, which is 'object') to find the first
2341                # class with non-empty text signature.
2342                try:
2343                    text_sig = base.__text_signature__
2344                except AttributeError:
2345                    pass
2346                else:
2347                    if text_sig:
2348                        # If 'obj' class has a __text_signature__ attribute:
2349                        # return a signature based on it
2350                        return _signature_fromstr(sigcls, obj, text_sig)
2351
2352            # No '__text_signature__' was found for the 'obj' class.
2353            # Last option is to check if its '__init__' is
2354            # object.__init__ or type.__init__.
2355            if type not in obj.__mro__:
2356                # We have a class (not metaclass), but no user-defined
2357                # __init__ or __new__ for it
2358                if (obj.__init__ is object.__init__ and
2359                    obj.__new__ is object.__new__):
2360                    # Return a signature of 'object' builtin.
2361                    return signature(object)
2362                else:
2363                    raise ValueError(
2364                        'no signature found for builtin type {!r}'.format(obj))
2365
2366    elif not isinstance(obj, _NonUserDefinedCallables):
2367        # An object with __call__
2368        # We also check that the 'obj' is not an instance of
2369        # _WrapperDescriptor or _MethodWrapper to avoid
2370        # infinite recursion (and even potential segfault)
2371        call = _signature_get_user_defined_method(type(obj), '__call__')
2372        if call is not None:
2373            try:
2374                sig = _signature_from_callable(
2375                    call,
2376                    follow_wrapper_chains=follow_wrapper_chains,
2377                    skip_bound_arg=skip_bound_arg,
2378                    sigcls=sigcls)
2379            except ValueError as ex:
2380                msg = 'no signature found for {!r}'.format(obj)
2381                raise ValueError(msg) from ex
2382
2383    if sig is not None:
2384        # For classes and objects we skip the first parameter of their
2385        # __call__, __new__, or __init__ methods
2386        if skip_bound_arg:
2387            return _signature_bound_method(sig)
2388        else:
2389            return sig
2390
2391    if isinstance(obj, types.BuiltinFunctionType):
2392        # Raise a nicer error message for builtins
2393        msg = 'no signature found for builtin function {!r}'.format(obj)
2394        raise ValueError(msg)
2395
2396    raise ValueError('callable {!r} is not supported by signature'.format(obj))
2397
2398
2399class _void:
2400    """A private marker - used in Parameter & Signature."""
2401
2402
2403class _empty:
2404    """Marker object for Signature.empty and Parameter.empty."""
2405
2406
2407class _ParameterKind(enum.IntEnum):
2408    POSITIONAL_ONLY = 0
2409    POSITIONAL_OR_KEYWORD = 1
2410    VAR_POSITIONAL = 2
2411    KEYWORD_ONLY = 3
2412    VAR_KEYWORD = 4
2413
2414    def __str__(self):
2415        return self._name_
2416
2417
2418_POSITIONAL_ONLY         = _ParameterKind.POSITIONAL_ONLY
2419_POSITIONAL_OR_KEYWORD   = _ParameterKind.POSITIONAL_OR_KEYWORD
2420_VAR_POSITIONAL          = _ParameterKind.VAR_POSITIONAL
2421_KEYWORD_ONLY            = _ParameterKind.KEYWORD_ONLY
2422_VAR_KEYWORD             = _ParameterKind.VAR_KEYWORD
2423
2424_PARAM_NAME_MAPPING = {
2425    _POSITIONAL_ONLY: 'positional-only',
2426    _POSITIONAL_OR_KEYWORD: 'positional or keyword',
2427    _VAR_POSITIONAL: 'variadic positional',
2428    _KEYWORD_ONLY: 'keyword-only',
2429    _VAR_KEYWORD: 'variadic keyword'
2430}
2431
2432_get_paramkind_descr = _PARAM_NAME_MAPPING.__getitem__
2433
2434
2435class Parameter:
2436    """Represents a parameter in a function signature.
2437
2438    Has the following public attributes:
2439
2440    * name : str
2441        The name of the parameter as a string.
2442    * default : object
2443        The default value for the parameter if specified.  If the
2444        parameter has no default value, this attribute is set to
2445        `Parameter.empty`.
2446    * annotation
2447        The annotation for the parameter if specified.  If the
2448        parameter has no annotation, this attribute is set to
2449        `Parameter.empty`.
2450    * kind : str
2451        Describes how argument values are bound to the parameter.
2452        Possible values: `Parameter.POSITIONAL_ONLY`,
2453        `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
2454        `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
2455    """
2456
2457    __slots__ = ('_name', '_kind', '_default', '_annotation')
2458
2459    POSITIONAL_ONLY         = _POSITIONAL_ONLY
2460    POSITIONAL_OR_KEYWORD   = _POSITIONAL_OR_KEYWORD
2461    VAR_POSITIONAL          = _VAR_POSITIONAL
2462    KEYWORD_ONLY            = _KEYWORD_ONLY
2463    VAR_KEYWORD             = _VAR_KEYWORD
2464
2465    empty = _empty
2466
2467    def __init__(self, name, kind, *, default=_empty, annotation=_empty):
2468        try:
2469            self._kind = _ParameterKind(kind)
2470        except ValueError:
2471            raise ValueError(f'value {kind!r} is not a valid Parameter.kind')
2472        if default is not _empty:
2473            if self._kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
2474                msg = '{} parameters cannot have default values'
2475                msg = msg.format(_get_paramkind_descr(self._kind))
2476                raise ValueError(msg)
2477        self._default = default
2478        self._annotation = annotation
2479
2480        if name is _empty:
2481            raise ValueError('name is a required attribute for Parameter')
2482
2483        if not isinstance(name, str):
2484            msg = 'name must be a str, not a {}'.format(type(name).__name__)
2485            raise TypeError(msg)
2486
2487        if name[0] == '.' and name[1:].isdigit():
2488            # These are implicit arguments generated by comprehensions. In
2489            # order to provide a friendlier interface to users, we recast
2490            # their name as "implicitN" and treat them as positional-only.
2491            # See issue 19611.
2492            if self._kind != _POSITIONAL_OR_KEYWORD:
2493                msg = (
2494                    'implicit arguments must be passed as '
2495                    'positional or keyword arguments, not {}'
2496                )
2497                msg = msg.format(_get_paramkind_descr(self._kind))
2498                raise ValueError(msg)
2499            self._kind = _POSITIONAL_ONLY
2500            name = 'implicit{}'.format(name[1:])
2501
2502        if not name.isidentifier():
2503            raise ValueError('{!r} is not a valid parameter name'.format(name))
2504
2505        self._name = name
2506
2507    def __reduce__(self):
2508        return (type(self),
2509                (self._name, self._kind),
2510                {'_default': self._default,
2511                 '_annotation': self._annotation})
2512
2513    def __setstate__(self, state):
2514        self._default = state['_default']
2515        self._annotation = state['_annotation']
2516
2517    @property
2518    def name(self):
2519        return self._name
2520
2521    @property
2522    def default(self):
2523        return self._default
2524
2525    @property
2526    def annotation(self):
2527        return self._annotation
2528
2529    @property
2530    def kind(self):
2531        return self._kind
2532
2533    def replace(self, *, name=_void, kind=_void,
2534                annotation=_void, default=_void):
2535        """Creates a customized copy of the Parameter."""
2536
2537        if name is _void:
2538            name = self._name
2539
2540        if kind is _void:
2541            kind = self._kind
2542
2543        if annotation is _void:
2544            annotation = self._annotation
2545
2546        if default is _void:
2547            default = self._default
2548
2549        return type(self)(name, kind, default=default, annotation=annotation)
2550
2551    def __str__(self):
2552        kind = self.kind
2553        formatted = self._name
2554
2555        # Add annotation and default value
2556        if self._annotation is not _empty:
2557            formatted = '{}: {}'.format(formatted,
2558                                       formatannotation(self._annotation))
2559
2560        if self._default is not _empty:
2561            if self._annotation is not _empty:
2562                formatted = '{} = {}'.format(formatted, repr(self._default))
2563            else:
2564                formatted = '{}={}'.format(formatted, repr(self._default))
2565
2566        if kind == _VAR_POSITIONAL:
2567            formatted = '*' + formatted
2568        elif kind == _VAR_KEYWORD:
2569            formatted = '**' + formatted
2570
2571        return formatted
2572
2573    def __repr__(self):
2574        return '<{} "{}">'.format(self.__class__.__name__, self)
2575
2576    def __hash__(self):
2577        return hash((self.name, self.kind, self.annotation, self.default))
2578
2579    def __eq__(self, other):
2580        if self is other:
2581            return True
2582        if not isinstance(other, Parameter):
2583            return NotImplemented
2584        return (self._name == other._name and
2585                self._kind == other._kind and
2586                self._default == other._default and
2587                self._annotation == other._annotation)
2588
2589
2590class BoundArguments:
2591    """Result of `Signature.bind` call.  Holds the mapping of arguments
2592    to the function's parameters.
2593
2594    Has the following public attributes:
2595
2596    * arguments : OrderedDict
2597        An ordered mutable mapping of parameters' names to arguments' values.
2598        Does not contain arguments' default values.
2599    * signature : Signature
2600        The Signature object that created this instance.
2601    * args : tuple
2602        Tuple of positional arguments values.
2603    * kwargs : dict
2604        Dict of keyword arguments values.
2605    """
2606
2607    __slots__ = ('arguments', '_signature', '__weakref__')
2608
2609    def __init__(self, signature, arguments):
2610        self.arguments = arguments
2611        self._signature = signature
2612
2613    @property
2614    def signature(self):
2615        return self._signature
2616
2617    @property
2618    def args(self):
2619        args = []
2620        for param_name, param in self._signature.parameters.items():
2621            if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
2622                break
2623
2624            try:
2625                arg = self.arguments[param_name]
2626            except KeyError:
2627                # We're done here. Other arguments
2628                # will be mapped in 'BoundArguments.kwargs'
2629                break
2630            else:
2631                if param.kind == _VAR_POSITIONAL:
2632                    # *args
2633                    args.extend(arg)
2634                else:
2635                    # plain argument
2636                    args.append(arg)
2637
2638        return tuple(args)
2639
2640    @property
2641    def kwargs(self):
2642        kwargs = {}
2643        kwargs_started = False
2644        for param_name, param in self._signature.parameters.items():
2645            if not kwargs_started:
2646                if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
2647                    kwargs_started = True
2648                else:
2649                    if param_name not in self.arguments:
2650                        kwargs_started = True
2651                        continue
2652
2653            if not kwargs_started:
2654                continue
2655
2656            try:
2657                arg = self.arguments[param_name]
2658            except KeyError:
2659                pass
2660            else:
2661                if param.kind == _VAR_KEYWORD:
2662                    # **kwargs
2663                    kwargs.update(arg)
2664                else:
2665                    # plain keyword argument
2666                    kwargs[param_name] = arg
2667
2668        return kwargs
2669
2670    def apply_defaults(self):
2671        """Set default values for missing arguments.
2672
2673        For variable-positional arguments (*args) the default is an
2674        empty tuple.
2675
2676        For variable-keyword arguments (**kwargs) the default is an
2677        empty dict.
2678        """
2679        arguments = self.arguments
2680        new_arguments = []
2681        for name, param in self._signature.parameters.items():
2682            try:
2683                new_arguments.append((name, arguments[name]))
2684            except KeyError:
2685                if param.default is not _empty:
2686                    val = param.default
2687                elif param.kind is _VAR_POSITIONAL:
2688                    val = ()
2689                elif param.kind is _VAR_KEYWORD:
2690                    val = {}
2691                else:
2692                    # This BoundArguments was likely produced by
2693                    # Signature.bind_partial().
2694                    continue
2695                new_arguments.append((name, val))
2696        self.arguments = OrderedDict(new_arguments)
2697
2698    def __eq__(self, other):
2699        if self is other:
2700            return True
2701        if not isinstance(other, BoundArguments):
2702            return NotImplemented
2703        return (self.signature == other.signature and
2704                self.arguments == other.arguments)
2705
2706    def __setstate__(self, state):
2707        self._signature = state['_signature']
2708        self.arguments = state['arguments']
2709
2710    def __getstate__(self):
2711        return {'_signature': self._signature, 'arguments': self.arguments}
2712
2713    def __repr__(self):
2714        args = []
2715        for arg, value in self.arguments.items():
2716            args.append('{}={!r}'.format(arg, value))
2717        return '<{} ({})>'.format(self.__class__.__name__, ', '.join(args))
2718
2719
2720class Signature:
2721    """A Signature object represents the overall signature of a function.
2722    It stores a Parameter object for each parameter accepted by the
2723    function, as well as information specific to the function itself.
2724
2725    A Signature object has the following public attributes and methods:
2726
2727    * parameters : OrderedDict
2728        An ordered mapping of parameters' names to the corresponding
2729        Parameter objects (keyword-only arguments are in the same order
2730        as listed in `code.co_varnames`).
2731    * return_annotation : object
2732        The annotation for the return type of the function if specified.
2733        If the function has no annotation for its return type, this
2734        attribute is set to `Signature.empty`.
2735    * bind(*args, **kwargs) -> BoundArguments
2736        Creates a mapping from positional and keyword arguments to
2737        parameters.
2738    * bind_partial(*args, **kwargs) -> BoundArguments
2739        Creates a partial mapping from positional and keyword arguments
2740        to parameters (simulating 'functools.partial' behavior.)
2741    """
2742
2743    __slots__ = ('_return_annotation', '_parameters')
2744
2745    _parameter_cls = Parameter
2746    _bound_arguments_cls = BoundArguments
2747
2748    empty = _empty
2749
2750    def __init__(self, parameters=None, *, return_annotation=_empty,
2751                 __validate_parameters__=True):
2752        """Constructs Signature from the given list of Parameter
2753        objects and 'return_annotation'.  All arguments are optional.
2754        """
2755
2756        if parameters is None:
2757            params = OrderedDict()
2758        else:
2759            if __validate_parameters__:
2760                params = OrderedDict()
2761                top_kind = _POSITIONAL_ONLY
2762                kind_defaults = False
2763
2764                for idx, param in enumerate(parameters):
2765                    kind = param.kind
2766                    name = param.name
2767
2768                    if kind < top_kind:
2769                        msg = (
2770                            'wrong parameter order: {} parameter before {} '
2771                            'parameter'
2772                        )
2773                        msg = msg.format(_get_paramkind_descr(top_kind),
2774                                         _get_paramkind_descr(kind))
2775                        raise ValueError(msg)
2776                    elif kind > top_kind:
2777                        kind_defaults = False
2778                        top_kind = kind
2779
2780                    if kind in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD):
2781                        if param.default is _empty:
2782                            if kind_defaults:
2783                                # No default for this parameter, but the
2784                                # previous parameter of the same kind had
2785                                # a default
2786                                msg = 'non-default argument follows default ' \
2787                                      'argument'
2788                                raise ValueError(msg)
2789                        else:
2790                            # There is a default for this parameter.
2791                            kind_defaults = True
2792
2793                    if name in params:
2794                        msg = 'duplicate parameter name: {!r}'.format(name)
2795                        raise ValueError(msg)
2796
2797                    params[name] = param
2798            else:
2799                params = OrderedDict(((param.name, param)
2800                                                for param in parameters))
2801
2802        self._parameters = types.MappingProxyType(params)
2803        self._return_annotation = return_annotation
2804
2805    @classmethod
2806    def from_function(cls, func):
2807        """Constructs Signature for the given python function.
2808
2809        Deprecated since Python 3.5, use `Signature.from_callable()`.
2810        """
2811
2812        warnings.warn("inspect.Signature.from_function() is deprecated since "
2813                      "Python 3.5, use Signature.from_callable()",
2814                      DeprecationWarning, stacklevel=2)
2815        return _signature_from_function(cls, func)
2816
2817    @classmethod
2818    def from_builtin(cls, func):
2819        """Constructs Signature for the given builtin function.
2820
2821        Deprecated since Python 3.5, use `Signature.from_callable()`.
2822        """
2823
2824        warnings.warn("inspect.Signature.from_builtin() is deprecated since "
2825                      "Python 3.5, use Signature.from_callable()",
2826                      DeprecationWarning, stacklevel=2)
2827        return _signature_from_builtin(cls, func)
2828
2829    @classmethod
2830    def from_callable(cls, obj, *, follow_wrapped=True):
2831        """Constructs Signature for the given callable object."""
2832        return _signature_from_callable(obj, sigcls=cls,
2833                                        follow_wrapper_chains=follow_wrapped)
2834
2835    @property
2836    def parameters(self):
2837        return self._parameters
2838
2839    @property
2840    def return_annotation(self):
2841        return self._return_annotation
2842
2843    def replace(self, *, parameters=_void, return_annotation=_void):
2844        """Creates a customized copy of the Signature.
2845        Pass 'parameters' and/or 'return_annotation' arguments
2846        to override them in the new copy.
2847        """
2848
2849        if parameters is _void:
2850            parameters = self.parameters.values()
2851
2852        if return_annotation is _void:
2853            return_annotation = self._return_annotation
2854
2855        return type(self)(parameters,
2856                          return_annotation=return_annotation)
2857
2858    def _hash_basis(self):
2859        params = tuple(param for param in self.parameters.values()
2860                             if param.kind != _KEYWORD_ONLY)
2861
2862        kwo_params = {param.name: param for param in self.parameters.values()
2863                                        if param.kind == _KEYWORD_ONLY}
2864
2865        return params, kwo_params, self.return_annotation
2866
2867    def __hash__(self):
2868        params, kwo_params, return_annotation = self._hash_basis()
2869        kwo_params = frozenset(kwo_params.values())
2870        return hash((params, kwo_params, return_annotation))
2871
2872    def __eq__(self, other):
2873        if self is other:
2874            return True
2875        if not isinstance(other, Signature):
2876            return NotImplemented
2877        return self._hash_basis() == other._hash_basis()
2878
2879    def _bind(self, args, kwargs, *, partial=False):
2880        """Private method. Don't use directly."""
2881
2882        arguments = OrderedDict()
2883
2884        parameters = iter(self.parameters.values())
2885        parameters_ex = ()
2886        arg_vals = iter(args)
2887
2888        while True:
2889            # Let's iterate through the positional arguments and corresponding
2890            # parameters
2891            try:
2892                arg_val = next(arg_vals)
2893            except StopIteration:
2894                # No more positional arguments
2895                try:
2896                    param = next(parameters)
2897                except StopIteration:
2898                    # No more parameters. That's it. Just need to check that
2899                    # we have no `kwargs` after this while loop
2900                    break
2901                else:
2902                    if param.kind == _VAR_POSITIONAL:
2903                        # That's OK, just empty *args.  Let's start parsing
2904                        # kwargs
2905                        break
2906                    elif param.name in kwargs:
2907                        if param.kind == _POSITIONAL_ONLY:
2908                            msg = '{arg!r} parameter is positional only, ' \
2909                                  'but was passed as a keyword'
2910                            msg = msg.format(arg=param.name)
2911                            raise TypeError(msg) from None
2912                        parameters_ex = (param,)
2913                        break
2914                    elif (param.kind == _VAR_KEYWORD or
2915                                                param.default is not _empty):
2916                        # That's fine too - we have a default value for this
2917                        # parameter.  So, lets start parsing `kwargs`, starting
2918                        # with the current parameter
2919                        parameters_ex = (param,)
2920                        break
2921                    else:
2922                        # No default, not VAR_KEYWORD, not VAR_POSITIONAL,
2923                        # not in `kwargs`
2924                        if partial:
2925                            parameters_ex = (param,)
2926                            break
2927                        else:
2928                            msg = 'missing a required argument: {arg!r}'
2929                            msg = msg.format(arg=param.name)
2930                            raise TypeError(msg) from None
2931            else:
2932                # We have a positional argument to process
2933                try:
2934                    param = next(parameters)
2935                except StopIteration:
2936                    raise TypeError('too many positional arguments') from None
2937                else:
2938                    if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
2939                        # Looks like we have no parameter for this positional
2940                        # argument
2941                        raise TypeError(
2942                            'too many positional arguments') from None
2943
2944                    if param.kind == _VAR_POSITIONAL:
2945                        # We have an '*args'-like argument, let's fill it with
2946                        # all positional arguments we have left and move on to
2947                        # the next phase
2948                        values = [arg_val]
2949                        values.extend(arg_vals)
2950                        arguments[param.name] = tuple(values)
2951                        break
2952
2953                    if param.name in kwargs:
2954                        raise TypeError(
2955                            'multiple values for argument {arg!r}'.format(
2956                                arg=param.name)) from None
2957
2958                    arguments[param.name] = arg_val
2959
2960        # Now, we iterate through the remaining parameters to process
2961        # keyword arguments
2962        kwargs_param = None
2963        for param in itertools.chain(parameters_ex, parameters):
2964            if param.kind == _VAR_KEYWORD:
2965                # Memorize that we have a '**kwargs'-like parameter
2966                kwargs_param = param
2967                continue
2968
2969            if param.kind == _VAR_POSITIONAL:
2970                # Named arguments don't refer to '*args'-like parameters.
2971                # We only arrive here if the positional arguments ended
2972                # before reaching the last parameter before *args.
2973                continue
2974
2975            param_name = param.name
2976            try:
2977                arg_val = kwargs.pop(param_name)
2978            except KeyError:
2979                # We have no value for this parameter.  It's fine though,
2980                # if it has a default value, or it is an '*args'-like
2981                # parameter, left alone by the processing of positional
2982                # arguments.
2983                if (not partial and param.kind != _VAR_POSITIONAL and
2984                                                    param.default is _empty):
2985                    raise TypeError('missing a required argument: {arg!r}'. \
2986                                    format(arg=param_name)) from None
2987
2988            else:
2989                if param.kind == _POSITIONAL_ONLY:
2990                    # This should never happen in case of a properly built
2991                    # Signature object (but let's have this check here
2992                    # to ensure correct behaviour just in case)
2993                    raise TypeError('{arg!r} parameter is positional only, '
2994                                    'but was passed as a keyword'. \
2995                                    format(arg=param.name))
2996
2997                arguments[param_name] = arg_val
2998
2999        if kwargs:
3000            if kwargs_param is not None:
3001                # Process our '**kwargs'-like parameter
3002                arguments[kwargs_param.name] = kwargs
3003            else:
3004                raise TypeError(
3005                    'got an unexpected keyword argument {arg!r}'.format(
3006                        arg=next(iter(kwargs))))
3007
3008        return self._bound_arguments_cls(self, arguments)
3009
3010    def bind(*args, **kwargs):
3011        """Get a BoundArguments object, that maps the passed `args`
3012        and `kwargs` to the function's signature.  Raises `TypeError`
3013        if the passed arguments can not be bound.
3014        """
3015        return args[0]._bind(args[1:], kwargs)
3016
3017    def bind_partial(*args, **kwargs):
3018        """Get a BoundArguments object, that partially maps the
3019        passed `args` and `kwargs` to the function's signature.
3020        Raises `TypeError` if the passed arguments can not be bound.
3021        """
3022        return args[0]._bind(args[1:], kwargs, partial=True)
3023
3024    def __reduce__(self):
3025        return (type(self),
3026                (tuple(self._parameters.values()),),
3027                {'_return_annotation': self._return_annotation})
3028
3029    def __setstate__(self, state):
3030        self._return_annotation = state['_return_annotation']
3031
3032    def __repr__(self):
3033        return '<{} {}>'.format(self.__class__.__name__, self)
3034
3035    def __str__(self):
3036        result = []
3037        render_pos_only_separator = False
3038        render_kw_only_separator = True
3039        for param in self.parameters.values():
3040            formatted = str(param)
3041
3042            kind = param.kind
3043
3044            if kind == _POSITIONAL_ONLY:
3045                render_pos_only_separator = True
3046            elif render_pos_only_separator:
3047                # It's not a positional-only parameter, and the flag
3048                # is set to 'True' (there were pos-only params before.)
3049                result.append('/')
3050                render_pos_only_separator = False
3051
3052            if kind == _VAR_POSITIONAL:
3053                # OK, we have an '*args'-like parameter, so we won't need
3054                # a '*' to separate keyword-only arguments
3055                render_kw_only_separator = False
3056            elif kind == _KEYWORD_ONLY and render_kw_only_separator:
3057                # We have a keyword-only parameter to render and we haven't
3058                # rendered an '*args'-like parameter before, so add a '*'
3059                # separator to the parameters list ("foo(arg1, *, arg2)" case)
3060                result.append('*')
3061                # This condition should be only triggered once, so
3062                # reset the flag
3063                render_kw_only_separator = False
3064
3065            result.append(formatted)
3066
3067        if render_pos_only_separator:
3068            # There were only positional-only parameters, hence the
3069            # flag was not reset to 'False'
3070            result.append('/')
3071
3072        rendered = '({})'.format(', '.join(result))
3073
3074        if self.return_annotation is not _empty:
3075            anno = formatannotation(self.return_annotation)
3076            rendered += ' -> {}'.format(anno)
3077
3078        return rendered
3079
3080
3081def signature(obj, *, follow_wrapped=True):
3082    """Get a signature object for the passed callable."""
3083    return Signature.from_callable(obj, follow_wrapped=follow_wrapped)
3084
3085
3086def _main():
3087    """ Logic for inspecting an object given at command line """
3088    import argparse
3089    import importlib
3090
3091    parser = argparse.ArgumentParser()
3092    parser.add_argument(
3093        'object',
3094         help="The object to be analysed. "
3095              "It supports the 'module:qualname' syntax")
3096    parser.add_argument(
3097        '-d', '--details', action='store_true',
3098        help='Display info about the module rather than its source code')
3099
3100    args = parser.parse_args()
3101
3102    target = args.object
3103    mod_name, has_attrs, attrs = target.partition(":")
3104    try:
3105        obj = module = importlib.import_module(mod_name)
3106    except Exception as exc:
3107        msg = "Failed to import {} ({}: {})".format(mod_name,
3108                                                    type(exc).__name__,
3109                                                    exc)
3110        print(msg, file=sys.stderr)
3111        exit(2)
3112
3113    if has_attrs:
3114        parts = attrs.split(".")
3115        obj = module
3116        for part in parts:
3117            obj = getattr(obj, part)
3118
3119    if module.__name__ in sys.builtin_module_names:
3120        print("Can't get info for builtin modules.", file=sys.stderr)
3121        exit(1)
3122
3123    if args.details:
3124        print('Target: {}'.format(target))
3125        print('Origin: {}'.format(getsourcefile(module)))
3126        print('Cached: {}'.format(module.__cached__))
3127        if obj is module:
3128            print('Loader: {}'.format(repr(module.__loader__)))
3129            if hasattr(module, '__path__'):
3130                print('Submodule search path: {}'.format(module.__path__))
3131        else:
3132            try:
3133                __, lineno = findsource(obj)
3134            except Exception:
3135                pass
3136            else:
3137                print('Line: {}'.format(lineno))
3138
3139        print('\n')
3140    else:
3141        print(getsource(obj))
3142
3143
3144if __name__ == "__main__":
3145    _main()
3146