1"""Get useful information from live Python objects. 2 3This module encapsulates the interface provided by the internal special 4attributes (co_*, im_*, tb_*, etc.) in a friendlier fashion. 5It also provides some help for examining source code and class layout. 6 7Here are some of the useful functions provided by this module: 8 9 ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(), 10 isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(), 11 isroutine() - check object types 12 getmembers() - get members of an object that satisfy a given condition 13 14 getfile(), getsourcefile(), getsource() - find an object's source code 15 getdoc(), getcomments() - get documentation on an object 16 getmodule() - determine the module that an object came from 17 getclasstree() - arrange classes so as to represent their hierarchy 18 19 getargvalues(), getcallargs() - get info about function arguments 20 getfullargspec() - same, with support for Python 3 features 21 formatargvalues() - format an argument spec 22 getouterframes(), getinnerframes() - get info about frames 23 currentframe() - get the current stack frame 24 stack(), trace() - get info about frames on the stack or in a traceback 25 26 signature() - get a Signature object for the callable 27""" 28 29# This module is in the public domain. No warranties. 30 31__author__ = ('Ka-Ping Yee <ping@lfw.org>', 32 'Yury Selivanov <yselivanov@sprymix.com>') 33 34import abc 35import dis 36import collections.abc 37import enum 38import importlib.machinery 39import itertools 40import linecache 41import os 42import re 43import sys 44import tokenize 45import token 46import types 47import warnings 48import functools 49import builtins 50from operator import attrgetter 51from collections import namedtuple, OrderedDict 52 53# Create constants for the compiler flags in Include/code.h 54# We try to get them from dis to avoid duplication 55mod_dict = globals() 56for k, v in dis.COMPILER_FLAG_NAMES.items(): 57 mod_dict["CO_" + v] = k 58 59# See Include/object.h 60TPFLAGS_IS_ABSTRACT = 1 << 20 61 62# ----------------------------------------------------------- type-checking 63def ismodule(object): 64 """Return true if the object is a module. 65 66 Module objects provide these attributes: 67 __cached__ pathname to byte compiled file 68 __doc__ documentation string 69 __file__ filename (missing for built-in modules)""" 70 return isinstance(object, types.ModuleType) 71 72def isclass(object): 73 """Return true if the object is a class. 74 75 Class objects provide these attributes: 76 __doc__ documentation string 77 __module__ name of module in which this class was defined""" 78 return isinstance(object, type) 79 80def ismethod(object): 81 """Return true if the object is an instance method. 82 83 Instance method objects provide these attributes: 84 __doc__ documentation string 85 __name__ name with which this method was defined 86 __func__ function object containing implementation of method 87 __self__ instance to which this method is bound""" 88 return isinstance(object, types.MethodType) 89 90def ismethoddescriptor(object): 91 """Return true if the object is a method descriptor. 92 93 But not if ismethod() or isclass() or isfunction() are true. 94 95 This is new in Python 2.2, and, for example, is true of int.__add__. 96 An object passing this test has a __get__ attribute but not a __set__ 97 attribute, but beyond that the set of attributes varies. __name__ is 98 usually sensible, and __doc__ often is. 99 100 Methods implemented via descriptors that also pass one of the other 101 tests return false from the ismethoddescriptor() test, simply because 102 the other tests promise more -- you can, e.g., count on having the 103 __func__ attribute (etc) when an object passes ismethod().""" 104 if isclass(object) or ismethod(object) or isfunction(object): 105 # mutual exclusion 106 return False 107 tp = type(object) 108 return hasattr(tp, "__get__") and not hasattr(tp, "__set__") 109 110def isdatadescriptor(object): 111 """Return true if the object is a data descriptor. 112 113 Data descriptors have 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__") 123 124if hasattr(types, 'MemberDescriptorType'): 125 # CPython and equivalent 126 def ismemberdescriptor(object): 127 """Return true if the object is a member descriptor. 128 129 Member descriptors are specialized descriptors defined in extension 130 modules.""" 131 return isinstance(object, types.MemberDescriptorType) 132else: 133 # Other implementations 134 def ismemberdescriptor(object): 135 """Return true if the object is a member descriptor. 136 137 Member descriptors are specialized descriptors defined in extension 138 modules.""" 139 return False 140 141if hasattr(types, 'GetSetDescriptorType'): 142 # CPython and equivalent 143 def isgetsetdescriptor(object): 144 """Return true if the object is a getset descriptor. 145 146 getset descriptors are specialized descriptors defined in extension 147 modules.""" 148 return isinstance(object, types.GetSetDescriptorType) 149else: 150 # Other implementations 151 def isgetsetdescriptor(object): 152 """Return true if the object is a getset descriptor. 153 154 getset descriptors are specialized descriptors defined in extension 155 modules.""" 156 return False 157 158def isfunction(object): 159 """Return true if the object is a user-defined function. 160 161 Function objects provide these attributes: 162 __doc__ documentation string 163 __name__ name with which this function was defined 164 __code__ code object containing compiled function bytecode 165 __defaults__ tuple of any default values for arguments 166 __globals__ global namespace in which this function was defined 167 __annotations__ dict of parameter annotations 168 __kwdefaults__ dict of keyword only parameters with defaults""" 169 return isinstance(object, types.FunctionType) 170 171def _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) 181 182def isgeneratorfunction(obj): 183 """Return true if the object is a user-defined generator function. 184 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) 188 189def iscoroutinefunction(obj): 190 """Return true if the object is a coroutine function. 191 192 Coroutine functions are defined with "async def" syntax. 193 """ 194 return _has_code_flag(obj, CO_COROUTINE) 195 196def isasyncgenfunction(obj): 197 """Return true if the object is an asynchronous generator function. 198 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) 203 204def isasyncgen(object): 205 """Return true if the object is an asynchronous generator.""" 206 return isinstance(object, types.AsyncGeneratorType) 207 208def isgenerator(object): 209 """Return true if the object is a generator. 210 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) 224 225def iscoroutine(object): 226 """Return true if the object is a coroutine.""" 227 return isinstance(object, types.CoroutineType) 228 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)) 235 236def istraceback(object): 237 """Return true if the object is a traceback. 238 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) 245 246def isframe(object): 247 """Return true if the object is a frame object. 248 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) 259 260def iscode(object): 261 """Return true if the object is a code object. 262 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) 284 285def isbuiltin(object): 286 """Return true if the object is a built-in function or method. 287 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) 293 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)) 300 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 324 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 368 369Attribute = namedtuple('Attribute', 'name kind defining_class object') 370 371def classify_class_attrs(cls): 372 """Return list of attribute-descriptor tuples. 373 374 For each name in dir(cls), the return list contains a 4-tuple 375 with these elements: 376 377 0. The name (a string). 378 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 385 386 2. The class which defined this attribute (a class). 387 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). 392 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 """ 397 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() 413 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 484 485# ----------------------------------------------------------- class helpers 486 487def getmro(cls): 488 "Return tuple of base classes (including cls) in method resolution order." 489 return cls.__mro__ 490 491# -------------------------------------------------------- function helpers 492 493def unwrap(func, *, stop=None): 494 """Get the object wrapped by *func*. 495 496 Follows the chain of :attr:`__wrapped__` attributes returning the last 497 object in the chain. 498 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. 505 506 :exc:`ValueError` is raised if a cycle is encountered. 507 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 527 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()) 533 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 543 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 555 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 605 606def getdoc(object): 607 """Get the documentation string for an object. 608 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) 624 625def cleandoc(doc): 626 """Clean up indentation from docstrings. 627 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) 653 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__)) 679 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 691 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 713 714def getabsfile(object, _filename=None): 715 """Return an absolute path to the source or compiled file for an object. 716 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)) 722 723modulesbyfile = {} 724_filesbymodname = {} 725 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 list(sys.modules.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 771 772def findsource(object): 773 """Return the entire source file and starting line number for an object. 774 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.""" 779 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') 791 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') 799 800 if ismodule(object): 801 return lines, 0 802 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') 825 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') 844 845def getcomments(object): 846 """Get lines of comments immediately preceding an object's source code. 847 848 Returns None when source can't be found. 849 """ 850 try: 851 lines, lnum = findsource(object) 852 except (OSError, TypeError): 853 return None 854 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) 868 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) 889 890class EndOfBlock(Exception): pass 891 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 902 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 946 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] 957 958def getsourcelines(object): 959 """Return a list of source lines and starting line number for an object. 960 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) 968 969 if istraceback(object): 970 object = object.tb_frame 971 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 978 979def getsource(object): 980 """Return the text of the source code for an object. 981 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) 987 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 998 999def getclasstree(classes, unique=False): 1000 """Arrange the given list of classes into a hierarchy of nested lists. 1001 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) 1024 1025# ------------------------------------------------ argument list extraction 1026Arguments = namedtuple('Arguments', 'args, varargs, varkw') 1027 1028def getargs(co): 1029 """Get information about the arguments accepted by a code object. 1030 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)) 1037 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 1044 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) 1054 1055ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults') 1056 1057def getargspec(func): 1058 """Get the names and default values of a function's parameters. 1059 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. 1064 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. 1068 1069 For a more structured introspection API, use inspect.signature() instead. 1070 1071 Alternatively, use getfullargspec() for an API with a similar namedtuple 1072 based interface, but full support for annotations and keyword-only 1073 parameters. 1074 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) 1086 1087FullArgSpec = namedtuple('FullArgSpec', 1088 'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations') 1089 1090def getfullargspec(func): 1091 """Get the names and default values of a callable object's parameters. 1092 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. 1101 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) 1117 1118 # Re: `follow_wrapper_chains=False` 1119 # 1120 # getfullargspec() historically ignored __wrapped__ attributes, 1121 # so we ensure that remains the case in 3.3+ 1122 1123 sig = _signature_from_callable(func, 1124 follow_wrapper_chains=False, 1125 skip_bound_arg=False, 1126 sigcls=Signature) 1127 except Exception as ex: 1128 # Most of the times 'signature' will raise ValueError. 1129 # But, it can also raise AttributeError, and, maybe something 1130 # else. So to be fully backwards compatible, we catch all 1131 # possible exceptions here, and reraise a TypeError. 1132 raise TypeError('unsupported callable') from ex 1133 1134 args = [] 1135 varargs = None 1136 varkw = None 1137 posonlyargs = [] 1138 kwonlyargs = [] 1139 defaults = () 1140 annotations = {} 1141 defaults = () 1142 kwdefaults = {} 1143 1144 if sig.return_annotation is not sig.empty: 1145 annotations['return'] = sig.return_annotation 1146 1147 for param in sig.parameters.values(): 1148 kind = param.kind 1149 name = param.name 1150 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 1167 1168 if param.annotation is not param.empty: 1169 annotations[name] = param.annotation 1170 1171 if not kwdefaults: 1172 # compatibility with 'func.__kwdefaults__' 1173 kwdefaults = None 1174 1175 if not defaults: 1176 # compatibility with 'func.__defaults__' 1177 defaults = None 1178 1179 return FullArgSpec(posonlyargs + args, varargs, varkw, defaults, 1180 kwonlyargs, kwdefaults, annotations) 1181 1182 1183ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals') 1184 1185def getargvalues(frame): 1186 """Get information about arguments passed into a particular frame. 1187 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) 1194 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) 1203 1204def formatannotationrelativeto(object): 1205 module = getattr(object, '__module__', None) 1206 def _formatannotation(annotation): 1207 return formatannotation(annotation, module) 1208 return _formatannotation 1209 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. 1219 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. 1225 1226 Deprecated since Python 3.5: use the `signature` function and `Signature` 1227 objects. 1228 """ 1229 1230 from warnings import warn 1231 1232 warn("`formatargspec` is deprecated since Python 3.5. Use `signature` and " 1233 "the `Signature` object directly", 1234 DeprecationWarning, 1235 stacklevel=2) 1236 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 1267 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. 1274 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) + ')' 1290 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)) 1306 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")) 1327 1328def getcallargs(func, /, *positional, **named): 1329 """Get the mapping of arguments to values. 1330 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 = {} 1338 1339 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 1346 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 1387 1388ClosureVars = namedtuple('ClosureVars', 'nonlocals globals builtins unbound') 1389 1390def getclosurevars(func): 1391 """ 1392 Get the mapping of free variables to their current values. 1393 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 """ 1398 1399 if ismethod(func): 1400 func = func.__func__ 1401 1402 if not isfunction(func): 1403 raise TypeError("{!r} is not a Python function".format(func)) 1404 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 } 1415 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) 1437 1438 return ClosureVars(nonlocal_vars, global_vars, 1439 builtin_vars, unbound_names) 1440 1441# -------------------------------------------------- stack frame extraction 1442 1443Traceback = namedtuple('Traceback', 'filename lineno function code_context index') 1444 1445def getframeinfo(frame, context=1): 1446 """Get information about a frame or traceback object. 1447 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)) 1460 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 1474 1475 return Traceback(filename, lineno, frame.f_code.co_name, lines, index) 1476 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 1481 1482FrameInfo = namedtuple('FrameInfo', ('frame',) + Traceback._fields) 1483 1484def getouterframes(frame, context=1): 1485 """Get a list of records for a frame and all higher (calling) frames. 1486 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 1495 1496def getinnerframes(tb, context=1): 1497 """Get a list of records for a traceback's frame and all lower frames. 1498 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 1507 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 1511 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) 1515 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) 1519 1520 1521# ------------------------------------------------ static version of getattr 1522 1523_sentinel = object() 1524 1525def _static_getmro(klass): 1526 return type.__dict__['__mro__'].__get__(klass) 1527 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) 1535 1536 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 1545 1546def _is_type(obj): 1547 try: 1548 _static_getmro(obj) 1549 except TypeError: 1550 return False 1551 return True 1552 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 1566 1567def getattr_static(obj, attr, default=_sentinel): 1568 """Retrieve attributes without triggering dynamic lookup via the 1569 descriptor protocol, __getattr__ or __getattribute__. 1570 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 1587 1588 klass_result = _check_class(klass, attr) 1589 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 1594 1595 if instance_result is not _sentinel: 1596 return instance_result 1597 if klass_result is not _sentinel: 1598 return klass_result 1599 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) 1611 1612 1613# ------------------------------------------------ generator introspection 1614 1615GEN_CREATED = 'GEN_CREATED' 1616GEN_RUNNING = 'GEN_RUNNING' 1617GEN_SUSPENDED = 'GEN_SUSPENDED' 1618GEN_CLOSED = 'GEN_CLOSED' 1619 1620def getgeneratorstate(generator): 1621 """Get current state of a generator-iterator. 1622 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 1636 1637 1638def getgeneratorlocals(generator): 1639 """ 1640 Get the mapping of generator local variables to their current values. 1641 1642 A dict is returned, with the keys the local variable names and values the 1643 bound values.""" 1644 1645 if not isgenerator(generator): 1646 raise TypeError("{!r} is not a Python generator".format(generator)) 1647 1648 frame = getattr(generator, "gi_frame", None) 1649 if frame is not None: 1650 return generator.gi_frame.f_locals 1651 else: 1652 return {} 1653 1654 1655# ------------------------------------------------ coroutine introspection 1656 1657CORO_CREATED = 'CORO_CREATED' 1658CORO_RUNNING = 'CORO_RUNNING' 1659CORO_SUSPENDED = 'CORO_SUSPENDED' 1660CORO_CLOSED = 'CORO_CLOSED' 1661 1662def getcoroutinestate(coroutine): 1663 """Get current state of a coroutine object. 1664 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 1678 1679 1680def getcoroutinelocals(coroutine): 1681 """ 1682 Get the mapping of coroutine local variables to their current values. 1683 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 {} 1691 1692 1693############################################################################### 1694### Function Signature Object (PEP 362) 1695############################################################################### 1696 1697 1698_WrapperDescriptor = type(type.__call__) 1699_MethodWrapper = type(all.__call__) 1700_ClassMethodWrapper = type(int.__dict__['from_bytes']) 1701 1702_NonUserDefinedCallables = (_WrapperDescriptor, 1703 _MethodWrapper, 1704 _ClassMethodWrapper, 1705 types.BuiltinFunctionType) 1706 1707 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 1722 1723 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 """ 1729 1730 old_params = wrapped_sig.parameters 1731 new_params = OrderedDict(old_params.items()) 1732 1733 partial_args = partial.args or () 1734 partial_keywords = partial.keywords or {} 1735 1736 if extra_args: 1737 partial_args = extra_args + partial_args 1738 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 1744 1745 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 1758 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 1780 1781 if param.kind is _KEYWORD_ONLY: 1782 # Set the new default value 1783 new_params[param_name] = param.replace(default=arg_value) 1784 1785 if transform_to_kwonly: 1786 assert param.kind is not _POSITIONAL_ONLY 1787 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) 1796 1797 return wrapped_sig.replace(parameters=new_params.values()) 1798 1799 1800def _signature_bound_method(sig): 1801 """Private helper to transform signatures for unbound 1802 functions to bound methods. 1803 """ 1804 1805 params = tuple(sig.parameters.values()) 1806 1807 if not params or params[0].kind in (_VAR_KEYWORD, _KEYWORD_ONLY): 1808 raise ValueError('invalid method signature') 1809 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[, ...])' 1822 1823 return sig.replace(parameters=params) 1824 1825 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)) 1836 1837 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 """ 1844 1845 if not callable(obj) or isclass(obj): 1846 # All function-like objects are obviously callables, 1847 # and not classes. 1848 return False 1849 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) 1855 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)) 1861 1862 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 """ 1870 1871 assert spec.startswith('($') 1872 1873 pos = spec.find(',') 1874 if pos == -1: 1875 pos = spec.find(')') 1876 1877 cpos = spec.find(':') 1878 assert cpos == -1 or cpos > pos 1879 1880 cpos = spec.find('=') 1881 assert cpos == -1 or cpos > pos 1882 1883 return spec[2:pos] 1884 1885 1886def _signature_strip_non_python_syntax(signature): 1887 """ 1888 Private helper function. Takes a signature in Argument Clinic's 1889 extended signature format. 1890 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 """ 1898 1899 if not signature: 1900 return signature, None, None 1901 1902 self_parameter = None 1903 last_positional_only = None 1904 1905 lines = [l.encode('ascii') for l in signature.split('\n')] 1906 generator = iter(lines).__next__ 1907 token_stream = tokenize.tokenize(generator) 1908 1909 delayed_comma = False 1910 skip_next_comma = False 1911 text = [] 1912 add = text.append 1913 1914 current_parameter = 0 1915 OP = token.OP 1916 ERRORTOKEN = token.ERRORTOKEN 1917 1918 # token stream always starts with ENCODING token, skip it 1919 t = next(token_stream) 1920 assert t.type == tokenize.ENCODING 1921 1922 for t in token_stream: 1923 type, string = t.type, t.string 1924 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 1934 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 1941 1942 if (type == ERRORTOKEN) and (string == '$'): 1943 assert self_parameter is None 1944 self_parameter = current_parameter 1945 continue 1946 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 1956 1957 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 1965 1966 Parameter = cls._parameter_cls 1967 1968 clean_signature, self_parameter, last_positional_only = \ 1969 _signature_strip_non_python_syntax(s) 1970 1971 program = "def foo" + clean_signature + ": pass" 1972 1973 try: 1974 module = ast.parse(program) 1975 except SyntaxError: 1976 module = None 1977 1978 if not isinstance(module, ast.Module): 1979 raise ValueError("{!r} builtin has invalid signature".format(obj)) 1980 1981 f = module.body[0] 1982 1983 parameters = [] 1984 empty = Parameter.empty 1985 invalid = object() 1986 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() 1995 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 2001 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() 2010 2011 if isinstance(value, (str, int, float, bytes, bool, type(None))): 2012 return ast.Constant(value) 2013 raise RuntimeError() 2014 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) 2027 2028 def visit_Name(self, node): 2029 if not isinstance(node.ctx, ast.Load): 2030 raise ValueError() 2031 return wrap_value(node.id) 2032 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)) 2047 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 2060 2061 # *args 2062 if f.args.vararg: 2063 kind = Parameter.VAR_POSITIONAL 2064 p(f.args.vararg, empty) 2065 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) 2070 2071 # **kwargs 2072 if f.args.kwarg: 2073 kind = Parameter.VAR_KEYWORD 2074 p(f.args.kwarg, empty) 2075 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 2092 2093 return cls(parameters, return_annotation=cls.empty) 2094 2095 2096def _signature_from_builtin(cls, func, skip_bound_arg=True): 2097 """Private helper function to get signature for 2098 builtin callables. 2099 """ 2100 2101 if not _signature_is_builtin(func): 2102 raise TypeError("{!r} is not a Python builtin " 2103 "function".format(func)) 2104 2105 s = getattr(func, "__text_signature__", None) 2106 if not s: 2107 raise ValueError("no signature found for builtin {!r}".format(func)) 2108 2109 return _signature_fromstr(cls, func, s, skip_bound_arg) 2110 2111 2112def _signature_from_function(cls, func, skip_bound_arg=True): 2113 """Private helper: constructs Signature for the given python function.""" 2114 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)) 2123 2124 s = getattr(func, "__text_signature__", None) 2125 if s: 2126 return _signature_fromstr(cls, func, s, skip_bound_arg) 2127 2128 Parameter = cls._parameter_cls 2129 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__ 2141 2142 if defaults: 2143 pos_default_count = len(defaults) 2144 else: 2145 pos_default_count = 0 2146 2147 parameters = [] 2148 2149 non_default_count = pos_count - pos_default_count 2150 posonly_left = posonly_count 2151 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 2160 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 2170 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)) 2177 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) 2183 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 2193 2194 name = arg_names[index] 2195 annotation = annotations.get(name, _empty) 2196 parameters.append(Parameter(name, annotation=annotation, 2197 kind=_VAR_KEYWORD)) 2198 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) 2204 2205 2206def _signature_from_callable(obj, *, 2207 follow_wrapper_chains=True, 2208 skip_bound_arg=True, 2209 sigcls): 2210 2211 """Private helper function to get signature for arbitrary 2212 callable objects. 2213 """ 2214 2215 if not callable(obj): 2216 raise TypeError('{!r} is not a callable object'.format(obj)) 2217 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) 2226 2227 if skip_bound_arg: 2228 return _signature_bound_method(sig) 2229 else: 2230 return sig 2231 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) 2244 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 2256 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) 2269 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) 2275 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) 2288 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) 2294 2295 if _signature_is_builtin(obj): 2296 return _signature_from_builtin(sigcls, obj, 2297 skip_bound_arg=skip_bound_arg) 2298 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) 2306 2307 sig = None 2308 if isinstance(obj, type): 2309 # obj is a class or a metaclass 2310 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) 2338 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__' 2342 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) 2360 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)) 2374 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 2391 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 2399 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) 2404 2405 raise ValueError('callable {!r} is not supported by signature'.format(obj)) 2406 2407 2408class _void: 2409 """A private marker - used in Parameter & Signature.""" 2410 2411 2412class _empty: 2413 """Marker object for Signature.empty and Parameter.empty.""" 2414 2415 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 2422 2423 def __str__(self): 2424 return self._name_ 2425 2426 @property 2427 def description(self): 2428 return _PARAM_NAME_MAPPING[self] 2429 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 2435 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} 2443 2444 2445class Parameter: 2446 """Represents a parameter in a function signature. 2447 2448 Has the following public attributes: 2449 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 """ 2466 2467 __slots__ = ('_name', '_kind', '_default', '_annotation') 2468 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 2474 2475 empty = _empty 2476 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 2489 2490 if name is _empty: 2491 raise ValueError('name is a required attribute for Parameter') 2492 2493 if not isinstance(name, str): 2494 msg = 'name must be a str, not a {}'.format(type(name).__name__) 2495 raise TypeError(msg) 2496 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:]) 2511 2512 if not name.isidentifier(): 2513 raise ValueError('{!r} is not a valid parameter name'.format(name)) 2514 2515 self._name = name 2516 2517 def __reduce__(self): 2518 return (type(self), 2519 (self._name, self._kind), 2520 {'_default': self._default, 2521 '_annotation': self._annotation}) 2522 2523 def __setstate__(self, state): 2524 self._default = state['_default'] 2525 self._annotation = state['_annotation'] 2526 2527 @property 2528 def name(self): 2529 return self._name 2530 2531 @property 2532 def default(self): 2533 return self._default 2534 2535 @property 2536 def annotation(self): 2537 return self._annotation 2538 2539 @property 2540 def kind(self): 2541 return self._kind 2542 2543 def replace(self, *, name=_void, kind=_void, 2544 annotation=_void, default=_void): 2545 """Creates a customized copy of the Parameter.""" 2546 2547 if name is _void: 2548 name = self._name 2549 2550 if kind is _void: 2551 kind = self._kind 2552 2553 if annotation is _void: 2554 annotation = self._annotation 2555 2556 if default is _void: 2557 default = self._default 2558 2559 return type(self)(name, kind, default=default, annotation=annotation) 2560 2561 def __str__(self): 2562 kind = self.kind 2563 formatted = self._name 2564 2565 # Add annotation and default value 2566 if self._annotation is not _empty: 2567 formatted = '{}: {}'.format(formatted, 2568 formatannotation(self._annotation)) 2569 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)) 2575 2576 if kind == _VAR_POSITIONAL: 2577 formatted = '*' + formatted 2578 elif kind == _VAR_KEYWORD: 2579 formatted = '**' + formatted 2580 2581 return formatted 2582 2583 def __repr__(self): 2584 return '<{} "{}">'.format(self.__class__.__name__, self) 2585 2586 def __hash__(self): 2587 return hash((self.name, self.kind, self.annotation, self.default)) 2588 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) 2598 2599 2600class BoundArguments: 2601 """Result of `Signature.bind` call. Holds the mapping of arguments 2602 to the function's parameters. 2603 2604 Has the following public attributes: 2605 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 """ 2616 2617 __slots__ = ('arguments', '_signature', '__weakref__') 2618 2619 def __init__(self, signature, arguments): 2620 self.arguments = arguments 2621 self._signature = signature 2622 2623 @property 2624 def signature(self): 2625 return self._signature 2626 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 2633 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) 2647 2648 return tuple(args) 2649 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 2662 2663 if not kwargs_started: 2664 continue 2665 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 2677 2678 return kwargs 2679 2680 def apply_defaults(self): 2681 """Set default values for missing arguments. 2682 2683 For variable-positional arguments (*args) the default is an 2684 empty tuple. 2685 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) 2707 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) 2715 2716 def __setstate__(self, state): 2717 self._signature = state['_signature'] 2718 self.arguments = state['arguments'] 2719 2720 def __getstate__(self): 2721 return {'_signature': self._signature, 'arguments': self.arguments} 2722 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)) 2728 2729 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. 2734 2735 A Signature object has the following public attributes and methods: 2736 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 """ 2752 2753 __slots__ = ('_return_annotation', '_parameters') 2754 2755 _parameter_cls = Parameter 2756 _bound_arguments_cls = BoundArguments 2757 2758 empty = _empty 2759 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 """ 2765 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 2773 2774 for idx, param in enumerate(parameters): 2775 kind = param.kind 2776 name = param.name 2777 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 2789 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 2802 2803 if name in params: 2804 msg = 'duplicate parameter name: {!r}'.format(name) 2805 raise ValueError(msg) 2806 2807 params[name] = param 2808 else: 2809 params = OrderedDict(((param.name, param) 2810 for param in parameters)) 2811 2812 self._parameters = types.MappingProxyType(params) 2813 self._return_annotation = return_annotation 2814 2815 @classmethod 2816 def from_function(cls, func): 2817 """Constructs Signature for the given python function. 2818 2819 Deprecated since Python 3.5, use `Signature.from_callable()`. 2820 """ 2821 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) 2826 2827 @classmethod 2828 def from_builtin(cls, func): 2829 """Constructs Signature for the given builtin function. 2830 2831 Deprecated since Python 3.5, use `Signature.from_callable()`. 2832 """ 2833 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) 2838 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) 2844 2845 @property 2846 def parameters(self): 2847 return self._parameters 2848 2849 @property 2850 def return_annotation(self): 2851 return self._return_annotation 2852 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 """ 2858 2859 if parameters is _void: 2860 parameters = self.parameters.values() 2861 2862 if return_annotation is _void: 2863 return_annotation = self._return_annotation 2864 2865 return type(self)(parameters, 2866 return_annotation=return_annotation) 2867 2868 def _hash_basis(self): 2869 params = tuple(param for param in self.parameters.values() 2870 if param.kind != _KEYWORD_ONLY) 2871 2872 kwo_params = {param.name: param for param in self.parameters.values() 2873 if param.kind == _KEYWORD_ONLY} 2874 2875 return params, kwo_params, self.return_annotation 2876 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)) 2881 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() 2888 2889 def _bind(self, args, kwargs, *, partial=False): 2890 """Private method. Don't use directly.""" 2891 2892 arguments = OrderedDict() 2893 2894 parameters = iter(self.parameters.values()) 2895 parameters_ex = () 2896 arg_vals = iter(args) 2897 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 2953 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 2962 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 2967 2968 arguments[param.name] = arg_val 2969 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 2978 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 2984 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 2997 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)) 3006 3007 arguments[param_name] = arg_val 3008 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)))) 3017 3018 return self._bound_arguments_cls(self, arguments) 3019 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) 3026 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) 3033 3034 def __reduce__(self): 3035 return (type(self), 3036 (tuple(self._parameters.values()),), 3037 {'_return_annotation': self._return_annotation}) 3038 3039 def __setstate__(self, state): 3040 self._return_annotation = state['_return_annotation'] 3041 3042 def __repr__(self): 3043 return '<{} {}>'.format(self.__class__.__name__, self) 3044 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) 3051 3052 kind = param.kind 3053 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 3061 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 3074 3075 result.append(formatted) 3076 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('/') 3081 3082 rendered = '({})'.format(', '.join(result)) 3083 3084 if self.return_annotation is not _empty: 3085 anno = formatannotation(self.return_annotation) 3086 rendered += ' -> {}'.format(anno) 3087 3088 return rendered 3089 3090 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) 3094 3095 3096def _main(): 3097 """ Logic for inspecting an object given at command line """ 3098 import argparse 3099 import importlib 3100 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') 3109 3110 args = parser.parse_args() 3111 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) 3122 3123 if has_attrs: 3124 parts = attrs.split(".") 3125 obj = module 3126 for part in parts: 3127 obj = getattr(obj, part) 3128 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) 3132 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)) 3148 3149 print('\n') 3150 else: 3151 print(getsource(obj)) 3152 3153 3154if __name__ == "__main__": 3155 _main() 3156