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