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