logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

inspect.py (123637B)


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