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