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