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