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