blob: ca1d551a697043784182d97996fb051f879e5b63 [file] [log] [blame]
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001"""Get useful information from live Python objects.
2
3This module encapsulates the interface provided by the internal special
Neal Norwitz221085d2007-02-25 20:55:47 +00004attributes (co_*, im_*, tb_*, etc.) in a friendlier fashion.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00005It also provides some help for examining source code and class layout.
6
7Here are some of the useful functions provided by this module:
8
Christian Heimes7131fd92008-02-19 14:21:46 +00009 ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
10 isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
11 isroutine() - check object types
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000012 getmembers() - get members of an object that satisfy a given condition
13
14 getfile(), getsourcefile(), getsource() - find an object's source code
15 getdoc(), getcomments() - get documentation on an object
16 getmodule() - determine the module that an object came from
17 getclasstree() - arrange classes so as to represent their hierarchy
18
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +000019 getargspec(), getargvalues(), getcallargs() - get info about function arguments
Yury Selivanov0cf3ed62014-04-01 10:17:08 -040020 getfullargspec() - same, with support for Python 3 features
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000021 formatargspec(), formatargvalues() - format an argument spec
22 getouterframes(), getinnerframes() - get info about frames
23 currentframe() - get the current stack frame
24 stack(), trace() - get info about frames on the stack or in a traceback
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070025
26 signature() - get a Signature object for the callable
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000027"""
28
29# This module is in the public domain. No warranties.
30
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070031__author__ = ('Ka-Ping Yee <ping@lfw.org>',
32 'Yury Selivanov <yselivanov@sprymix.com>')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000033
Larry Hastings44e2eaa2013-11-23 15:37:55 -080034import ast
Antoine Pitroua8723a02015-04-15 00:41:29 +020035import dis
Yury Selivanov75445082015-05-11 22:57:16 -040036import collections.abc
Yury Selivanov21e83a52014-03-27 11:23:13 -040037import enum
Brett Cannoncb66eb02012-05-11 12:58:42 -040038import importlib.machinery
39import itertools
Christian Heimes7131fd92008-02-19 14:21:46 +000040import linecache
Brett Cannoncb66eb02012-05-11 12:58:42 -040041import os
42import re
43import sys
44import tokenize
Larry Hastings2623c8c2014-02-08 22:15:29 -080045import token
Brett Cannoncb66eb02012-05-11 12:58:42 -040046import types
Brett Cannon2b88fcf2012-06-02 22:28:42 -040047import warnings
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070048import functools
Nick Coghlan2f92e542012-06-23 19:39:55 +100049import builtins
Raymond Hettingera1a992c2005-03-11 06:46:45 +000050from operator import attrgetter
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070051from collections import namedtuple, OrderedDict
Nick Coghlan09c81232010-08-17 10:18:16 +000052
53# Create constants for the compiler flags in Include/code.h
Antoine Pitroua8723a02015-04-15 00:41:29 +020054# We try to get them from dis to avoid duplication
55mod_dict = globals()
56for k, v in dis.COMPILER_FLAG_NAMES.items():
57 mod_dict["CO_" + v] = k
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000058
Christian Heimesbe5b30b2008-03-03 19:18:51 +000059# See Include/object.h
60TPFLAGS_IS_ABSTRACT = 1 << 20
61
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000062# ----------------------------------------------------------- type-checking
63def ismodule(object):
64 """Return true if the object is a module.
65
66 Module objects provide these attributes:
Barry Warsaw28a691b2010-04-17 00:19:56 +000067 __cached__ pathname to byte compiled file
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000068 __doc__ documentation string
69 __file__ filename (missing for built-in modules)"""
Tim Peters28bc59f2001-09-16 08:40:16 +000070 return isinstance(object, types.ModuleType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000071
72def isclass(object):
73 """Return true if the object is a class.
74
75 Class objects provide these attributes:
76 __doc__ documentation string
77 __module__ name of module in which this class was defined"""
Benjamin Petersonc4656002009-01-17 22:41:18 +000078 return isinstance(object, type)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000079
80def ismethod(object):
81 """Return true if the object is an instance method.
82
83 Instance method objects provide these attributes:
84 __doc__ documentation string
85 __name__ name with which this method was defined
Christian Heimesff737952007-11-27 10:40:20 +000086 __func__ function object containing implementation of method
87 __self__ instance to which this method is bound"""
Tim Peters28bc59f2001-09-16 08:40:16 +000088 return isinstance(object, types.MethodType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000089
Tim Peters536d2262001-09-20 05:13:38 +000090def ismethoddescriptor(object):
Tim Petersf1d90b92001-09-20 05:47:55 +000091 """Return true if the object is a method descriptor.
92
93 But not if ismethod() or isclass() or isfunction() are true.
Tim Peters536d2262001-09-20 05:13:38 +000094
95 This is new in Python 2.2, and, for example, is true of int.__add__.
96 An object passing this test has a __get__ attribute but not a __set__
97 attribute, but beyond that the set of attributes varies. __name__ is
98 usually sensible, and __doc__ often is.
99
Tim Petersf1d90b92001-09-20 05:47:55 +0000100 Methods implemented via descriptors that also pass one of the other
101 tests return false from the ismethoddescriptor() test, simply because
102 the other tests promise more -- you can, e.g., count on having the
Christian Heimesff737952007-11-27 10:40:20 +0000103 __func__ attribute (etc) when an object passes ismethod()."""
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100104 if isclass(object) or ismethod(object) or isfunction(object):
105 # mutual exclusion
106 return False
107 tp = type(object)
108 return hasattr(tp, "__get__") and not hasattr(tp, "__set__")
Tim Peters536d2262001-09-20 05:13:38 +0000109
Martin v. Löwise59e2ba2003-05-03 09:09:02 +0000110def isdatadescriptor(object):
111 """Return true if the object is a data descriptor.
112
113 Data descriptors have both a __get__ and a __set__ attribute. Examples are
114 properties (defined in Python) and getsets and members (defined in C).
115 Typically, data descriptors will also have __name__ and __doc__ attributes
116 (properties, getsets, and members have both of these attributes), but this
117 is not guaranteed."""
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100118 if isclass(object) or ismethod(object) or isfunction(object):
119 # mutual exclusion
120 return False
121 tp = type(object)
122 return hasattr(tp, "__set__") and hasattr(tp, "__get__")
Martin v. Löwise59e2ba2003-05-03 09:09:02 +0000123
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000124if hasattr(types, 'MemberDescriptorType'):
125 # CPython and equivalent
126 def ismemberdescriptor(object):
127 """Return true if the object is a member descriptor.
128
129 Member descriptors are specialized descriptors defined in extension
130 modules."""
131 return isinstance(object, types.MemberDescriptorType)
132else:
133 # Other implementations
134 def ismemberdescriptor(object):
135 """Return true if the object is a member descriptor.
136
137 Member descriptors are specialized descriptors defined in extension
138 modules."""
139 return False
140
141if hasattr(types, 'GetSetDescriptorType'):
142 # CPython and equivalent
143 def isgetsetdescriptor(object):
144 """Return true if the object is a getset descriptor.
145
146 getset descriptors are specialized descriptors defined in extension
147 modules."""
148 return isinstance(object, types.GetSetDescriptorType)
149else:
150 # Other implementations
151 def isgetsetdescriptor(object):
152 """Return true if the object is a getset descriptor.
153
154 getset descriptors are specialized descriptors defined in extension
155 modules."""
156 return False
157
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000158def isfunction(object):
159 """Return true if the object is a user-defined function.
160
161 Function objects provide these attributes:
162 __doc__ documentation string
163 __name__ name with which this function was defined
Neal Norwitz221085d2007-02-25 20:55:47 +0000164 __code__ code object containing compiled function bytecode
165 __defaults__ tuple of any default values for arguments
166 __globals__ global namespace in which this function was defined
167 __annotations__ dict of parameter annotations
168 __kwdefaults__ dict of keyword only parameters with defaults"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000169 return isinstance(object, types.FunctionType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000170
Christian Heimes7131fd92008-02-19 14:21:46 +0000171def isgeneratorfunction(object):
172 """Return true if the object is a user-defined generator function.
173
Martin Panter0f0eac42016-09-07 11:04:41 +0000174 Generator function objects provide the same attributes as functions.
175 See help(isfunction) for a list of attributes."""
Georg Brandlb1441c72009-01-03 22:33:39 +0000176 return bool((isfunction(object) or ismethod(object)) and
Yury Selivanov5376ba92015-06-22 12:19:30 -0400177 object.__code__.co_flags & CO_GENERATOR)
Yury Selivanov75445082015-05-11 22:57:16 -0400178
179def iscoroutinefunction(object):
180 """Return true if the object is a coroutine function.
181
182 Coroutine functions are defined with "async def" syntax,
183 or generators decorated with "types.coroutine".
184 """
185 return bool((isfunction(object) or ismethod(object)) and
Yury Selivanov5376ba92015-06-22 12:19:30 -0400186 object.__code__.co_flags & CO_COROUTINE)
Yury Selivanov75445082015-05-11 22:57:16 -0400187
Christian Heimes7131fd92008-02-19 14:21:46 +0000188def isgenerator(object):
189 """Return true if the object is a generator.
190
191 Generator objects provide these attributes:
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300192 __iter__ defined to support iteration over container
Christian Heimes7131fd92008-02-19 14:21:46 +0000193 close raises a new GeneratorExit exception inside the
194 generator to terminate the iteration
195 gi_code code object
196 gi_frame frame object or possibly None once the generator has
197 been exhausted
198 gi_running set to 1 when generator is executing, 0 otherwise
199 next return the next item from the container
200 send resumes the generator and "sends" a value that becomes
201 the result of the current yield-expression
202 throw used to raise an exception inside the generator"""
Yury Selivanov5376ba92015-06-22 12:19:30 -0400203 return isinstance(object, types.GeneratorType)
Yury Selivanov75445082015-05-11 22:57:16 -0400204
205def iscoroutine(object):
206 """Return true if the object is a coroutine."""
Yury Selivanov5376ba92015-06-22 12:19:30 -0400207 return isinstance(object, types.CoroutineType)
Christian Heimes7131fd92008-02-19 14:21:46 +0000208
Yury Selivanovfdbeb2b2015-07-03 13:11:35 -0400209def isawaitable(object):
210 """Return true is object can be passed to an ``await`` expression."""
211 return (isinstance(object, types.CoroutineType) or
212 isinstance(object, types.GeneratorType) and
213 object.gi_code.co_flags & CO_ITERABLE_COROUTINE or
214 isinstance(object, collections.abc.Awaitable))
215
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000216def istraceback(object):
217 """Return true if the object is a traceback.
218
219 Traceback objects provide these attributes:
220 tb_frame frame object at this level
221 tb_lasti index of last attempted instruction in bytecode
222 tb_lineno current line number in Python source code
223 tb_next next inner traceback object (called by this level)"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000224 return isinstance(object, types.TracebackType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000225
226def isframe(object):
227 """Return true if the object is a frame object.
228
229 Frame objects provide these attributes:
230 f_back next outer frame object (this frame's caller)
231 f_builtins built-in namespace seen by this frame
232 f_code code object being executed in this frame
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000233 f_globals global namespace seen by this frame
234 f_lasti index of last attempted instruction in bytecode
235 f_lineno current line number in Python source code
236 f_locals local namespace seen by this frame
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000237 f_trace tracing function for this frame, or None"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000238 return isinstance(object, types.FrameType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000239
240def iscode(object):
241 """Return true if the object is a code object.
242
243 Code objects provide these attributes:
244 co_argcount number of arguments (not including * or ** args)
245 co_code string of raw compiled bytecode
246 co_consts tuple of constants used in the bytecode
247 co_filename name of file in which this code object was created
248 co_firstlineno number of first line in Python source code
249 co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
250 co_lnotab encoded mapping of line numbers to bytecode indices
251 co_name name with which this code object was defined
252 co_names tuple of names of local variables
253 co_nlocals number of local variables
254 co_stacksize virtual machine stack space required
255 co_varnames tuple of names of arguments and local variables"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000256 return isinstance(object, types.CodeType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000257
258def isbuiltin(object):
259 """Return true if the object is a built-in function or method.
260
261 Built-in functions and methods provide these attributes:
262 __doc__ documentation string
263 __name__ original name of this function or method
264 __self__ instance to which a method is bound, or None"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000265 return isinstance(object, types.BuiltinFunctionType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000266
267def isroutine(object):
268 """Return true if the object is any kind of function or method."""
Tim Peters536d2262001-09-20 05:13:38 +0000269 return (isbuiltin(object)
270 or isfunction(object)
271 or ismethod(object)
272 or ismethoddescriptor(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000273
Christian Heimesbe5b30b2008-03-03 19:18:51 +0000274def isabstract(object):
275 """Return true if the object is an abstract base class (ABC)."""
Benjamin Petersona0dfa822009-11-13 02:25:08 +0000276 return bool(isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT)
Christian Heimesbe5b30b2008-03-03 19:18:51 +0000277
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000278def getmembers(object, predicate=None):
279 """Return all members of an object as (name, value) pairs sorted by name.
280 Optionally, only return members that satisfy a given predicate."""
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100281 if isclass(object):
282 mro = (object,) + getmro(object)
283 else:
284 mro = ()
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000285 results = []
Ethan Furmane03ea372013-09-25 07:14:41 -0700286 processed = set()
287 names = dir(object)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700288 # :dd any DynamicClassAttributes to the list of names if object is a class;
Ethan Furmane03ea372013-09-25 07:14:41 -0700289 # this may result in duplicate entries if, for example, a virtual
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700290 # attribute with the same name as a DynamicClassAttribute exists
Ethan Furmane03ea372013-09-25 07:14:41 -0700291 try:
292 for base in object.__bases__:
293 for k, v in base.__dict__.items():
294 if isinstance(v, types.DynamicClassAttribute):
295 names.append(k)
296 except AttributeError:
297 pass
298 for key in names:
Ethan Furman63c141c2013-10-18 00:27:39 -0700299 # First try to get the value via getattr. Some descriptors don't
300 # like calling their __get__ (see bug #1785), so fall back to
301 # looking in the __dict__.
302 try:
303 value = getattr(object, key)
304 # handle the duplicate key
305 if key in processed:
306 raise AttributeError
307 except AttributeError:
308 for base in mro:
309 if key in base.__dict__:
310 value = base.__dict__[key]
311 break
312 else:
313 # could be a (currently) missing slot member, or a buggy
314 # __dir__; discard and move on
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100315 continue
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000316 if not predicate or predicate(value):
317 results.append((key, value))
Ethan Furmane03ea372013-09-25 07:14:41 -0700318 processed.add(key)
319 results.sort(key=lambda pair: pair[0])
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000320 return results
321
Christian Heimes25bb7832008-01-11 16:17:00 +0000322Attribute = namedtuple('Attribute', 'name kind defining_class object')
323
Tim Peters13b49d32001-09-23 02:00:29 +0000324def classify_class_attrs(cls):
325 """Return list of attribute-descriptor tuples.
326
327 For each name in dir(cls), the return list contains a 4-tuple
328 with these elements:
329
330 0. The name (a string).
331
332 1. The kind of attribute this is, one of these strings:
333 'class method' created via classmethod()
334 'static method' created via staticmethod()
335 'property' created via property()
Ethan Furmane03ea372013-09-25 07:14:41 -0700336 'method' any other flavor of method or descriptor
Tim Peters13b49d32001-09-23 02:00:29 +0000337 'data' not a method
338
339 2. The class which defined this attribute (a class).
340
Ethan Furmane03ea372013-09-25 07:14:41 -0700341 3. The object as obtained by calling getattr; if this fails, or if the
342 resulting object does not live anywhere in the class' mro (including
343 metaclasses) then the object is looked up in the defining class's
344 dict (found by walking the mro).
Ethan Furman668dede2013-09-14 18:53:26 -0700345
346 If one of the items in dir(cls) is stored in the metaclass it will now
347 be discovered and not have None be listed as the class in which it was
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700348 defined. Any items whose home class cannot be discovered are skipped.
Tim Peters13b49d32001-09-23 02:00:29 +0000349 """
350
351 mro = getmro(cls)
Ethan Furman668dede2013-09-14 18:53:26 -0700352 metamro = getmro(type(cls)) # for attributes stored in the metaclass
Ethan Furmane03ea372013-09-25 07:14:41 -0700353 metamro = tuple([cls for cls in metamro if cls not in (type, object)])
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700354 class_bases = (cls,) + mro
355 all_bases = class_bases + metamro
Tim Peters13b49d32001-09-23 02:00:29 +0000356 names = dir(cls)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700357 # :dd any DynamicClassAttributes to the list of names;
Ethan Furmane03ea372013-09-25 07:14:41 -0700358 # this may result in duplicate entries if, for example, a virtual
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700359 # attribute with the same name as a DynamicClassAttribute exists.
Ethan Furman63c141c2013-10-18 00:27:39 -0700360 for base in mro:
Ethan Furmane03ea372013-09-25 07:14:41 -0700361 for k, v in base.__dict__.items():
362 if isinstance(v, types.DynamicClassAttribute):
363 names.append(k)
Tim Peters13b49d32001-09-23 02:00:29 +0000364 result = []
Ethan Furmane03ea372013-09-25 07:14:41 -0700365 processed = set()
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700366
Tim Peters13b49d32001-09-23 02:00:29 +0000367 for name in names:
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100368 # Get the object associated with the name, and where it was defined.
Ethan Furmane03ea372013-09-25 07:14:41 -0700369 # Normal objects will be looked up with both getattr and directly in
370 # its class' dict (in case getattr fails [bug #1785], and also to look
371 # for a docstring).
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700372 # For DynamicClassAttributes on the second pass we only look in the
Ethan Furmane03ea372013-09-25 07:14:41 -0700373 # class's dict.
374 #
Tim Peters13b49d32001-09-23 02:00:29 +0000375 # Getting an obj from the __dict__ sometimes reveals more than
376 # using getattr. Static and class methods are dramatic examples.
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100377 homecls = None
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700378 get_obj = None
379 dict_obj = None
Ethan Furmane03ea372013-09-25 07:14:41 -0700380 if name not in processed:
381 try:
Ethan Furmana8b07072013-10-18 01:22:08 -0700382 if name == '__dict__':
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700383 raise Exception("__dict__ is special, don't want the proxy")
Ethan Furmane03ea372013-09-25 07:14:41 -0700384 get_obj = getattr(cls, name)
385 except Exception as exc:
386 pass
387 else:
Ethan Furmane03ea372013-09-25 07:14:41 -0700388 homecls = getattr(get_obj, "__objclass__", homecls)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700389 if homecls not in class_bases:
Ethan Furmane03ea372013-09-25 07:14:41 -0700390 # if the resulting object does not live somewhere in the
Ethan Furman63c141c2013-10-18 00:27:39 -0700391 # mro, drop it and search the mro manually
Ethan Furmane03ea372013-09-25 07:14:41 -0700392 homecls = None
Ethan Furman63c141c2013-10-18 00:27:39 -0700393 last_cls = None
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700394 # first look in the classes
395 for srch_cls in class_bases:
Ethan Furman63c141c2013-10-18 00:27:39 -0700396 srch_obj = getattr(srch_cls, name, None)
Yury Selivanovbf341fb2015-05-21 15:41:57 -0400397 if srch_obj is get_obj:
Ethan Furman63c141c2013-10-18 00:27:39 -0700398 last_cls = srch_cls
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700399 # then check the metaclasses
400 for srch_cls in metamro:
401 try:
402 srch_obj = srch_cls.__getattr__(cls, name)
403 except AttributeError:
404 continue
Yury Selivanovbf341fb2015-05-21 15:41:57 -0400405 if srch_obj is get_obj:
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700406 last_cls = srch_cls
Ethan Furman63c141c2013-10-18 00:27:39 -0700407 if last_cls is not None:
408 homecls = last_cls
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700409 for base in all_bases:
Ethan Furmane03ea372013-09-25 07:14:41 -0700410 if name in base.__dict__:
411 dict_obj = base.__dict__[name]
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700412 if homecls not in metamro:
413 homecls = base
Ethan Furmane03ea372013-09-25 07:14:41 -0700414 break
Ethan Furman63c141c2013-10-18 00:27:39 -0700415 if homecls is None:
416 # unable to locate the attribute anywhere, most likely due to
417 # buggy custom __dir__; discard and move on
418 continue
Yury Selivanovbf341fb2015-05-21 15:41:57 -0400419 obj = get_obj if get_obj is not None else dict_obj
Ethan Furmane03ea372013-09-25 07:14:41 -0700420 # Classify the object or its descriptor.
Ethan Furman63c141c2013-10-18 00:27:39 -0700421 if isinstance(dict_obj, staticmethod):
Tim Peters13b49d32001-09-23 02:00:29 +0000422 kind = "static method"
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700423 obj = dict_obj
Ethan Furman63c141c2013-10-18 00:27:39 -0700424 elif isinstance(dict_obj, classmethod):
Tim Peters13b49d32001-09-23 02:00:29 +0000425 kind = "class method"
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700426 obj = dict_obj
427 elif isinstance(dict_obj, property):
Tim Peters13b49d32001-09-23 02:00:29 +0000428 kind = "property"
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700429 obj = dict_obj
Yury Selivanov0860a0b2014-01-31 14:28:44 -0500430 elif isroutine(obj):
Tim Peters13b49d32001-09-23 02:00:29 +0000431 kind = "method"
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100432 else:
Ethan Furmane03ea372013-09-25 07:14:41 -0700433 kind = "data"
Christian Heimes25bb7832008-01-11 16:17:00 +0000434 result.append(Attribute(name, kind, homecls, obj))
Ethan Furmane03ea372013-09-25 07:14:41 -0700435 processed.add(name)
Tim Peters13b49d32001-09-23 02:00:29 +0000436 return result
437
Tim Peterse0b2d7a2001-09-22 06:10:55 +0000438# ----------------------------------------------------------- class helpers
Tim Peterse0b2d7a2001-09-22 06:10:55 +0000439
440def getmro(cls):
441 "Return tuple of base classes (including cls) in method resolution order."
Benjamin Petersonb82c8e52010-11-04 00:38:49 +0000442 return cls.__mro__
Tim Peterse0b2d7a2001-09-22 06:10:55 +0000443
Nick Coghlane8c45d62013-07-28 20:00:01 +1000444# -------------------------------------------------------- function helpers
445
446def unwrap(func, *, stop=None):
447 """Get the object wrapped by *func*.
448
449 Follows the chain of :attr:`__wrapped__` attributes returning the last
450 object in the chain.
451
452 *stop* is an optional callback accepting an object in the wrapper chain
453 as its sole argument that allows the unwrapping to be terminated early if
454 the callback returns a true value. If the callback never returns a true
455 value, the last object in the chain is returned as usual. For example,
456 :func:`signature` uses this to stop unwrapping if any object in the
457 chain has a ``__signature__`` attribute defined.
458
459 :exc:`ValueError` is raised if a cycle is encountered.
460
461 """
462 if stop is None:
463 def _is_wrapper(f):
464 return hasattr(f, '__wrapped__')
465 else:
466 def _is_wrapper(f):
467 return hasattr(f, '__wrapped__') and not stop(f)
468 f = func # remember the original func for error reporting
469 memo = {id(f)} # Memoise by id to tolerate non-hashable objects
470 while _is_wrapper(func):
471 func = func.__wrapped__
472 id_func = id(func)
473 if id_func in memo:
474 raise ValueError('wrapper loop when unwrapping {!r}'.format(f))
475 memo.add(id_func)
476 return func
477
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000478# -------------------------------------------------- source code extraction
479def indentsize(line):
480 """Return the indent size, in spaces, at the start of a line of text."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000481 expline = line.expandtabs()
482 return len(expline) - len(expline.lstrip())
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000483
Serhiy Storchaka5cf2b722015-04-03 22:38:53 +0300484def _findclass(func):
485 cls = sys.modules.get(func.__module__)
486 if cls is None:
487 return None
488 for name in func.__qualname__.split('.')[:-1]:
489 cls = getattr(cls, name)
490 if not isclass(cls):
491 return None
492 return cls
493
494def _finddoc(obj):
495 if isclass(obj):
496 for base in obj.__mro__:
497 if base is not object:
498 try:
499 doc = base.__doc__
500 except AttributeError:
501 continue
502 if doc is not None:
503 return doc
504 return None
505
506 if ismethod(obj):
507 name = obj.__func__.__name__
508 self = obj.__self__
509 if (isclass(self) and
510 getattr(getattr(self, name, None), '__func__') is obj.__func__):
511 # classmethod
512 cls = self
513 else:
514 cls = self.__class__
515 elif isfunction(obj):
516 name = obj.__name__
517 cls = _findclass(obj)
518 if cls is None or getattr(cls, name) is not obj:
519 return None
520 elif isbuiltin(obj):
521 name = obj.__name__
522 self = obj.__self__
523 if (isclass(self) and
524 self.__qualname__ + '.' + name == obj.__qualname__):
525 # classmethod
526 cls = self
527 else:
528 cls = self.__class__
Serhiy Storchakaac4bdcc2015-10-29 08:15:50 +0200529 # Should be tested before isdatadescriptor().
530 elif isinstance(obj, property):
531 func = obj.fget
532 name = func.__name__
533 cls = _findclass(func)
534 if cls is None or getattr(cls, name) is not obj:
535 return None
Serhiy Storchaka5cf2b722015-04-03 22:38:53 +0300536 elif ismethoddescriptor(obj) or isdatadescriptor(obj):
537 name = obj.__name__
538 cls = obj.__objclass__
539 if getattr(cls, name) is not obj:
540 return None
Serhiy Storchaka5cf2b722015-04-03 22:38:53 +0300541 else:
542 return None
543
544 for base in cls.__mro__:
545 try:
546 doc = getattr(base, name).__doc__
547 except AttributeError:
548 continue
549 if doc is not None:
550 return doc
551 return None
552
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000553def getdoc(object):
554 """Get the documentation string for an object.
555
556 All tabs are expanded to spaces. To clean up docstrings that are
557 indented to line up with blocks of code, any whitespace than can be
558 uniformly removed from the second line onwards is removed."""
Tim Peters24008312002-03-17 18:56:20 +0000559 try:
560 doc = object.__doc__
561 except AttributeError:
562 return None
Serhiy Storchaka5cf2b722015-04-03 22:38:53 +0300563 if doc is None:
564 try:
565 doc = _finddoc(object)
566 except (AttributeError, TypeError):
567 return None
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000568 if not isinstance(doc, str):
Tim Peters24008312002-03-17 18:56:20 +0000569 return None
Georg Brandl0c77a822008-06-10 16:37:50 +0000570 return cleandoc(doc)
571
572def cleandoc(doc):
573 """Clean up indentation from docstrings.
574
575 Any whitespace that can be uniformly removed from the second line
576 onwards is removed."""
Tim Peters24008312002-03-17 18:56:20 +0000577 try:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000578 lines = doc.expandtabs().split('\n')
Tim Peters24008312002-03-17 18:56:20 +0000579 except UnicodeError:
580 return None
581 else:
Ka-Ping Yeea59ef7b2002-11-30 03:53:15 +0000582 # Find minimum indentation of any non-blank lines after first line.
Christian Heimesa37d4c62007-12-04 23:02:19 +0000583 margin = sys.maxsize
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000584 for line in lines[1:]:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000585 content = len(line.lstrip())
Ka-Ping Yeea59ef7b2002-11-30 03:53:15 +0000586 if content:
587 indent = len(line) - content
588 margin = min(margin, indent)
589 # Remove indentation.
590 if lines:
591 lines[0] = lines[0].lstrip()
Christian Heimesa37d4c62007-12-04 23:02:19 +0000592 if margin < sys.maxsize:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000593 for i in range(1, len(lines)): lines[i] = lines[i][margin:]
Ka-Ping Yeea59ef7b2002-11-30 03:53:15 +0000594 # Remove any trailing or leading blank lines.
595 while lines and not lines[-1]:
596 lines.pop()
597 while lines and not lines[0]:
598 lines.pop(0)
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000599 return '\n'.join(lines)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000600
601def getfile(object):
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000602 """Work out which source or compiled file an object was defined in."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000603 if ismodule(object):
604 if hasattr(object, '__file__'):
605 return object.__file__
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000606 raise TypeError('{!r} is a built-in module'.format(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000607 if isclass(object):
Yury Selivanov2eed8b72014-01-27 13:24:56 -0500608 if hasattr(object, '__module__'):
609 object = sys.modules.get(object.__module__)
610 if hasattr(object, '__file__'):
611 return object.__file__
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000612 raise TypeError('{!r} is a built-in class'.format(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000613 if ismethod(object):
Christian Heimesff737952007-11-27 10:40:20 +0000614 object = object.__func__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000615 if isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000616 object = object.__code__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000617 if istraceback(object):
618 object = object.tb_frame
619 if isframe(object):
620 object = object.f_code
621 if iscode(object):
622 return object.co_filename
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000623 raise TypeError('{!r} is not a module, class, method, '
624 'function, traceback, frame, or code object'.format(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000625
Christian Heimes25bb7832008-01-11 16:17:00 +0000626ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')
627
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000628def getmoduleinfo(path):
629 """Get the module name, suffix, mode, and module type for a given file."""
Brett Cannoncb66eb02012-05-11 12:58:42 -0400630 warnings.warn('inspect.getmoduleinfo() is deprecated', DeprecationWarning,
631 2)
Brett Cannone4f41de2013-06-16 13:13:40 -0400632 with warnings.catch_warnings():
633 warnings.simplefilter('ignore', PendingDeprecationWarning)
634 import imp
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000635 filename = os.path.basename(path)
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000636 suffixes = [(-len(suffix), suffix, mode, mtype)
637 for suffix, mode, mtype in imp.get_suffixes()]
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000638 suffixes.sort() # try longest suffixes first, in case they overlap
639 for neglen, suffix, mode, mtype in suffixes:
640 if filename[neglen:] == suffix:
Christian Heimes25bb7832008-01-11 16:17:00 +0000641 return ModuleInfo(filename[:neglen], suffix, mode, mtype)
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000642
643def getmodulename(path):
644 """Return the module name for a given file, or None."""
Nick Coghlan76e07702012-07-18 23:14:57 +1000645 fname = os.path.basename(path)
646 # Check for paths that look like an actual module file
647 suffixes = [(-len(suffix), suffix)
648 for suffix in importlib.machinery.all_suffixes()]
649 suffixes.sort() # try longest suffixes first, in case they overlap
650 for neglen, suffix in suffixes:
651 if fname.endswith(suffix):
652 return fname[:neglen]
653 return None
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000654
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000655def getsourcefile(object):
R. David Murraya1b37402010-06-17 02:04:29 +0000656 """Return the filename that can be used to locate an object's source.
657 Return None if no way can be identified to get the source.
658 """
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000659 filename = getfile(object)
Brett Cannoncb66eb02012-05-11 12:58:42 -0400660 all_bytecode_suffixes = importlib.machinery.DEBUG_BYTECODE_SUFFIXES[:]
661 all_bytecode_suffixes += importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES[:]
662 if any(filename.endswith(s) for s in all_bytecode_suffixes):
663 filename = (os.path.splitext(filename)[0] +
664 importlib.machinery.SOURCE_SUFFIXES[0])
665 elif any(filename.endswith(s) for s in
666 importlib.machinery.EXTENSION_SUFFIXES):
667 return None
Thomas Wouters477c8d52006-05-27 19:21:47 +0000668 if os.path.exists(filename):
669 return filename
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000670 # only return a non-existent filename if the module has a PEP 302 loader
Brett Cannon4c14b5d2013-05-04 13:56:58 -0400671 if getattr(getmodule(object, filename), '__loader__', None) is not None:
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000672 return filename
R. David Murraya1b37402010-06-17 02:04:29 +0000673 # or it is in the linecache
674 if filename in linecache.cache:
675 return filename
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000676
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000677def getabsfile(object, _filename=None):
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000678 """Return an absolute path to the source or compiled file for an object.
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000679
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000680 The idea is for each object to have a unique origin, so this routine
681 normalizes the result as much as possible."""
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000682 if _filename is None:
683 _filename = getsourcefile(object) or getfile(object)
684 return os.path.normcase(os.path.abspath(_filename))
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000685
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000686modulesbyfile = {}
Thomas Wouters89f507f2006-12-13 04:49:30 +0000687_filesbymodname = {}
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000688
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000689def getmodule(object, _filename=None):
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000690 """Return the module an object was defined in, or None if not found."""
Ka-Ping Yee202c99b2001-04-13 09:15:08 +0000691 if ismodule(object):
692 return object
Johannes Gijsbers93245262004-09-11 15:53:22 +0000693 if hasattr(object, '__module__'):
Ka-Ping Yee8b58b842001-03-01 13:56:16 +0000694 return sys.modules.get(object.__module__)
Thomas Wouters89f507f2006-12-13 04:49:30 +0000695 # Try the filename to modulename cache
696 if _filename is not None and _filename in modulesbyfile:
697 return sys.modules.get(modulesbyfile[_filename])
698 # Try the cache again with the absolute file name
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000699 try:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000700 file = getabsfile(object, _filename)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000701 except TypeError:
702 return None
Raymond Hettinger54f02222002-06-01 14:18:47 +0000703 if file in modulesbyfile:
Ka-Ping Yeeb38bbbd2003-03-28 16:29:50 +0000704 return sys.modules.get(modulesbyfile[file])
Thomas Wouters89f507f2006-12-13 04:49:30 +0000705 # Update the filename to module name cache and check yet again
706 # Copy sys.modules in order to cope with changes while iterating
Éric Araujoa74f8ef2011-11-29 16:58:53 +0100707 for modname, module in list(sys.modules.items()):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000708 if ismodule(module) and hasattr(module, '__file__'):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000709 f = module.__file__
710 if f == _filesbymodname.get(modname, None):
711 # Have already mapped this module, so skip it
712 continue
713 _filesbymodname[modname] = f
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000714 f = getabsfile(module)
Thomas Wouters89f507f2006-12-13 04:49:30 +0000715 # Always map to the name the module knows itself by
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000716 modulesbyfile[f] = modulesbyfile[
717 os.path.realpath(f)] = module.__name__
Raymond Hettinger54f02222002-06-01 14:18:47 +0000718 if file in modulesbyfile:
Ka-Ping Yeeb38bbbd2003-03-28 16:29:50 +0000719 return sys.modules.get(modulesbyfile[file])
Thomas Wouters89f507f2006-12-13 04:49:30 +0000720 # Check the main module
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000721 main = sys.modules['__main__']
Brett Cannon4a671fe2003-06-15 22:33:28 +0000722 if not hasattr(object, '__name__'):
723 return None
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000724 if hasattr(main, object.__name__):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000725 mainobject = getattr(main, object.__name__)
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000726 if mainobject is object:
727 return main
Thomas Wouters89f507f2006-12-13 04:49:30 +0000728 # Check builtins
Georg Brandl1a3284e2007-12-02 09:40:06 +0000729 builtin = sys.modules['builtins']
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000730 if hasattr(builtin, object.__name__):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000731 builtinobject = getattr(builtin, object.__name__)
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000732 if builtinobject is object:
733 return builtin
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000734
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000735def findsource(object):
736 """Return the entire source file and starting line number for an object.
737
738 The argument may be a module, class, method, function, traceback, frame,
739 or code object. The source code is returned as a list of all the lines
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200740 in the file and the line number indexes a line in that list. An OSError
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000741 is raised if the source code cannot be retrieved."""
Benjamin Peterson9620cc02011-06-11 15:53:11 -0500742
Yury Selivanovef1e7502014-12-08 16:05:34 -0500743 file = getsourcefile(object)
744 if file:
745 # Invalidate cache if needed.
746 linecache.checkcache(file)
747 else:
748 file = getfile(object)
749 # Allow filenames in form of "<something>" to pass through.
750 # `doctest` monkeypatches `linecache` module to enable
751 # inspection, so let `linecache.getlines` to be called.
752 if not (file.startswith('<') and file.endswith('>')):
753 raise OSError('source code not available')
Benjamin Peterson9620cc02011-06-11 15:53:11 -0500754
Thomas Wouters89f507f2006-12-13 04:49:30 +0000755 module = getmodule(object, file)
Thomas Wouters477c8d52006-05-27 19:21:47 +0000756 if module:
757 lines = linecache.getlines(file, module.__dict__)
758 else:
759 lines = linecache.getlines(file)
Neil Schemenauerf06f8532002-03-23 23:51:04 +0000760 if not lines:
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200761 raise OSError('could not get source code')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000762
763 if ismodule(object):
764 return lines, 0
765
766 if isclass(object):
767 name = object.__name__
Thomas Wouters89f507f2006-12-13 04:49:30 +0000768 pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
769 # make some effort to find the best matching class definition:
770 # use the one with the least indentation, which is the one
771 # that's most probably not inside a function definition.
772 candidates = []
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000773 for i in range(len(lines)):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000774 match = pat.match(lines[i])
775 if match:
776 # if it's at toplevel, it's already the best one
777 if lines[i][0] == 'c':
778 return lines, i
779 # else add whitespace to candidate list
780 candidates.append((match.group(1), i))
781 if candidates:
782 # this will sort by whitespace, and by line number,
783 # less whitespace first
784 candidates.sort()
785 return lines, candidates[0][1]
Jeremy Hyltonab919022003-06-27 18:41:20 +0000786 else:
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200787 raise OSError('could not find class definition')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000788
789 if ismethod(object):
Christian Heimesff737952007-11-27 10:40:20 +0000790 object = object.__func__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000791 if isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000792 object = object.__code__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000793 if istraceback(object):
794 object = object.tb_frame
795 if isframe(object):
796 object = object.f_code
797 if iscode(object):
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000798 if not hasattr(object, 'co_firstlineno'):
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200799 raise OSError('could not find function definition')
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000800 lnum = object.co_firstlineno - 1
Yury Selivanove4e811d2015-07-21 19:01:52 +0300801 pat = re.compile(r'^(\s*def\s)|(\s*async\s+def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000802 while lnum > 0:
Ka-Ping Yeea6e59712001-03-10 09:31:55 +0000803 if pat.match(lines[lnum]): break
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000804 lnum = lnum - 1
805 return lines, lnum
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200806 raise OSError('could not find code object')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000807
808def getcomments(object):
Jeremy Hyltonb4c17c82002-03-28 23:01:56 +0000809 """Get lines of comments immediately preceding an object's source code.
810
811 Returns None when source can't be found.
812 """
813 try:
814 lines, lnum = findsource(object)
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200815 except (OSError, TypeError):
Jeremy Hyltonb4c17c82002-03-28 23:01:56 +0000816 return None
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000817
818 if ismodule(object):
819 # Look for a comment block at the top of the file.
820 start = 0
Ka-Ping Yeeb910efe2001-04-12 13:17:17 +0000821 if lines and lines[0][:2] == '#!': start = 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000822 while start < len(lines) and lines[start].strip() in ('', '#'):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000823 start = start + 1
Ka-Ping Yeeb910efe2001-04-12 13:17:17 +0000824 if start < len(lines) and lines[start][:1] == '#':
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000825 comments = []
826 end = start
827 while end < len(lines) and lines[end][:1] == '#':
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000828 comments.append(lines[end].expandtabs())
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000829 end = end + 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000830 return ''.join(comments)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000831
832 # Look for a preceding block of comments at the same indentation.
833 elif lnum > 0:
834 indent = indentsize(lines[lnum])
835 end = lnum - 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000836 if end >= 0 and lines[end].lstrip()[:1] == '#' and \
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000837 indentsize(lines[end]) == indent:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000838 comments = [lines[end].expandtabs().lstrip()]
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000839 if end > 0:
840 end = end - 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000841 comment = lines[end].expandtabs().lstrip()
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000842 while comment[:1] == '#' and indentsize(lines[end]) == indent:
843 comments[:0] = [comment]
844 end = end - 1
845 if end < 0: break
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000846 comment = lines[end].expandtabs().lstrip()
847 while comments and comments[0].strip() == '#':
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000848 comments[:1] = []
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000849 while comments and comments[-1].strip() == '#':
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000850 comments[-1:] = []
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000851 return ''.join(comments)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000852
Tim Peters4efb6e92001-06-29 23:51:08 +0000853class EndOfBlock(Exception): pass
854
855class BlockFinder:
856 """Provide a tokeneater() method to detect the end of a code block."""
857 def __init__(self):
858 self.indent = 0
Johannes Gijsbersa5855d52005-03-12 16:37:11 +0000859 self.islambda = False
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000860 self.started = False
861 self.passline = False
Meador Inge5b718d72015-07-23 22:49:37 -0500862 self.indecorator = False
863 self.decoratorhasargs = False
Armin Rigodd5c0232005-09-25 11:45:45 +0000864 self.last = 1
Tim Peters4efb6e92001-06-29 23:51:08 +0000865
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000866 def tokeneater(self, type, token, srowcol, erowcol, line):
Meador Inge5b718d72015-07-23 22:49:37 -0500867 if not self.started and not self.indecorator:
868 # skip any decorators
869 if token == "@":
870 self.indecorator = True
Armin Rigodd5c0232005-09-25 11:45:45 +0000871 # look for the first "def", "class" or "lambda"
Meador Inge5b718d72015-07-23 22:49:37 -0500872 elif token in ("def", "class", "lambda"):
Johannes Gijsbersa5855d52005-03-12 16:37:11 +0000873 if token == "lambda":
874 self.islambda = True
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000875 self.started = True
Armin Rigodd5c0232005-09-25 11:45:45 +0000876 self.passline = True # skip to the end of the line
Meador Inge5b718d72015-07-23 22:49:37 -0500877 elif token == "(":
878 if self.indecorator:
879 self.decoratorhasargs = True
880 elif token == ")":
881 if self.indecorator:
882 self.indecorator = False
883 self.decoratorhasargs = False
Tim Peters4efb6e92001-06-29 23:51:08 +0000884 elif type == tokenize.NEWLINE:
Armin Rigodd5c0232005-09-25 11:45:45 +0000885 self.passline = False # stop skipping when a NEWLINE is seen
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000886 self.last = srowcol[0]
Armin Rigodd5c0232005-09-25 11:45:45 +0000887 if self.islambda: # lambdas always end at the first NEWLINE
888 raise EndOfBlock
Meador Inge5b718d72015-07-23 22:49:37 -0500889 # hitting a NEWLINE when in a decorator without args
890 # ends the decorator
891 if self.indecorator and not self.decoratorhasargs:
892 self.indecorator = False
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000893 elif self.passline:
894 pass
Tim Peters4efb6e92001-06-29 23:51:08 +0000895 elif type == tokenize.INDENT:
896 self.indent = self.indent + 1
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000897 self.passline = True
Tim Peters4efb6e92001-06-29 23:51:08 +0000898 elif type == tokenize.DEDENT:
899 self.indent = self.indent - 1
Armin Rigodd5c0232005-09-25 11:45:45 +0000900 # the end of matching indent/dedent pairs end a block
901 # (note that this only works for "def"/"class" blocks,
902 # not e.g. for "if: else:" or "try: finally:" blocks)
903 if self.indent <= 0:
904 raise EndOfBlock
905 elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
906 # any other token on the same indentation level end the previous
907 # block as well, except the pseudo-tokens COMMENT and NL.
908 raise EndOfBlock
Tim Peters4efb6e92001-06-29 23:51:08 +0000909
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000910def getblock(lines):
911 """Extract the block of code at the top of the given list of lines."""
Armin Rigodd5c0232005-09-25 11:45:45 +0000912 blockfinder = BlockFinder()
Tim Peters4efb6e92001-06-29 23:51:08 +0000913 try:
Trent Nelson428de652008-03-18 22:41:35 +0000914 tokens = tokenize.generate_tokens(iter(lines).__next__)
915 for _token in tokens:
916 blockfinder.tokeneater(*_token)
Armin Rigodd5c0232005-09-25 11:45:45 +0000917 except (EndOfBlock, IndentationError):
918 pass
919 return lines[:blockfinder.last]
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000920
921def getsourcelines(object):
922 """Return a list of source lines and starting line number for an object.
923
924 The argument may be a module, class, method, function, traceback, frame,
925 or code object. The source code is returned as a list of the lines
926 corresponding to the object and the line number indicates where in the
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200927 original source file the first line of code was found. An OSError is
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000928 raised if the source code cannot be retrieved."""
Yury Selivanov081bbf62014-09-26 17:34:54 -0400929 object = unwrap(object)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000930 lines, lnum = findsource(object)
931
Meador Inge5b718d72015-07-23 22:49:37 -0500932 if ismodule(object):
933 return lines, 0
934 else:
935 return getblock(lines[lnum:]), lnum + 1
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000936
937def getsource(object):
938 """Return the text of the source code for an object.
939
940 The argument may be a module, class, method, function, traceback, frame,
941 or code object. The source code is returned as a single string. An
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200942 OSError is raised if the source code cannot be retrieved."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000943 lines, lnum = getsourcelines(object)
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000944 return ''.join(lines)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000945
946# --------------------------------------------------- class tree extraction
947def walktree(classes, children, parent):
948 """Recursive helper function for getclasstree()."""
949 results = []
Raymond Hettingera1a992c2005-03-11 06:46:45 +0000950 classes.sort(key=attrgetter('__module__', '__name__'))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000951 for c in classes:
952 results.append((c, c.__bases__))
Raymond Hettinger54f02222002-06-01 14:18:47 +0000953 if c in children:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000954 results.append(walktree(children[c], children, c))
955 return results
956
Georg Brandl5ce83a02009-06-01 17:23:51 +0000957def getclasstree(classes, unique=False):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000958 """Arrange the given list of classes into a hierarchy of nested lists.
959
960 Where a nested list appears, it contains classes derived from the class
961 whose entry immediately precedes the list. Each entry is a 2-tuple
962 containing a class and a tuple of its base classes. If the 'unique'
963 argument is true, exactly one entry appears in the returned structure
964 for each class in the given list. Otherwise, classes using multiple
965 inheritance and their descendants will appear multiple times."""
966 children = {}
967 roots = []
968 for c in classes:
969 if c.__bases__:
970 for parent in c.__bases__:
Raymond Hettinger54f02222002-06-01 14:18:47 +0000971 if not parent in children:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000972 children[parent] = []
Serhiy Storchaka362c1b52013-09-05 17:14:32 +0300973 if c not in children[parent]:
974 children[parent].append(c)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000975 if unique and parent in classes: break
976 elif c not in roots:
977 roots.append(c)
Raymond Hettingere0d49722002-06-02 18:55:56 +0000978 for parent in children:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000979 if parent not in classes:
980 roots.append(parent)
981 return walktree(roots, children, None)
982
983# ------------------------------------------------ argument list extraction
Christian Heimes25bb7832008-01-11 16:17:00 +0000984Arguments = namedtuple('Arguments', 'args, varargs, varkw')
985
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000986def getargs(co):
987 """Get information about the arguments accepted by a code object.
988
Guido van Rossum2e65f892007-02-28 22:03:49 +0000989 Three things are returned: (args, varargs, varkw), where
Georg Brandlc1c4bf82010-10-15 16:07:41 +0000990 'args' is the list of argument names. Keyword-only arguments are
991 appended. 'varargs' and 'varkw' are the names of the * and **
992 arguments or None."""
Guido van Rossum2e65f892007-02-28 22:03:49 +0000993 args, varargs, kwonlyargs, varkw = _getfullargs(co)
Christian Heimes25bb7832008-01-11 16:17:00 +0000994 return Arguments(args + kwonlyargs, varargs, varkw)
Guido van Rossum2e65f892007-02-28 22:03:49 +0000995
996def _getfullargs(co):
997 """Get information about the arguments accepted by a code object.
998
999 Four things are returned: (args, varargs, kwonlyargs, varkw), where
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001000 'args' and 'kwonlyargs' are lists of argument names, and 'varargs'
1001 and 'varkw' are the names of the * and ** arguments or None."""
Jeremy Hylton64967882003-06-27 18:14:39 +00001002
1003 if not iscode(co):
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001004 raise TypeError('{!r} is not a code object'.format(co))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001005
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001006 nargs = co.co_argcount
1007 names = co.co_varnames
Guido van Rossum2e65f892007-02-28 22:03:49 +00001008 nkwargs = co.co_kwonlyargcount
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001009 args = list(names[:nargs])
Guido van Rossum2e65f892007-02-28 22:03:49 +00001010 kwonlyargs = list(names[nargs:nargs+nkwargs])
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001011 step = 0
1012
Guido van Rossum2e65f892007-02-28 22:03:49 +00001013 nargs += nkwargs
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001014 varargs = None
1015 if co.co_flags & CO_VARARGS:
1016 varargs = co.co_varnames[nargs]
1017 nargs = nargs + 1
1018 varkw = None
1019 if co.co_flags & CO_VARKEYWORDS:
1020 varkw = co.co_varnames[nargs]
Guido van Rossum2e65f892007-02-28 22:03:49 +00001021 return args, varargs, kwonlyargs, varkw
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001022
Christian Heimes25bb7832008-01-11 16:17:00 +00001023
1024ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
1025
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001026def getargspec(func):
1027 """Get the names and default values of a function's arguments.
1028
Guido van Rossume82881c2014-07-15 12:29:11 -07001029 A tuple of four things is returned: (args, varargs, keywords, defaults).
1030 'args' is a list of the argument names, including keyword-only argument names.
1031 'varargs' and 'keywords' are the names of the * and ** arguments or None.
Jeremy Hylton64967882003-06-27 18:14:39 +00001032 'defaults' is an n-tuple of the default values of the last n arguments.
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001033
Yury Selivanov0cf3ed62014-04-01 10:17:08 -04001034 Use the getfullargspec() API for Python 3 code, as annotations
Guido van Rossum2e65f892007-02-28 22:03:49 +00001035 and keyword arguments are supported. getargspec() will raise ValueError
1036 if the func has either annotations or keyword arguments.
1037 """
Yury Selivanov3cfec2e2015-05-22 11:38:38 -04001038 warnings.warn("inspect.getargspec() is deprecated, "
Yury Selivanovc8386f72015-05-22 16:09:44 -04001039 "use inspect.signature() instead", DeprecationWarning,
1040 stacklevel=2)
Guido van Rossum2e65f892007-02-28 22:03:49 +00001041 args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \
1042 getfullargspec(func)
1043 if kwonlyargs or ann:
Collin Winterce36ad82007-08-30 01:19:48 +00001044 raise ValueError("Function has keyword-only arguments or annotations"
1045 ", use getfullargspec() API which can support them")
Christian Heimes25bb7832008-01-11 16:17:00 +00001046 return ArgSpec(args, varargs, varkw, defaults)
1047
1048FullArgSpec = namedtuple('FullArgSpec',
Benjamin Peterson3d4ca742008-11-12 21:39:01 +00001049 'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations')
Guido van Rossum2e65f892007-02-28 22:03:49 +00001050
1051def getfullargspec(func):
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001052 """Get the names and default values of a callable object's arguments.
Guido van Rossum2e65f892007-02-28 22:03:49 +00001053
Brett Cannon504d8852007-09-07 02:12:14 +00001054 A tuple of seven things is returned:
1055 (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations).
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001056 'args' is a list of the argument names.
Guido van Rossum2e65f892007-02-28 22:03:49 +00001057 'varargs' and 'varkw' are the names of the * and ** arguments or None.
1058 'defaults' is an n-tuple of the default values of the last n arguments.
1059 'kwonlyargs' is a list of keyword-only argument names.
1060 'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults.
1061 'annotations' is a dictionary mapping argument names to annotations.
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001062
Guido van Rossum2e65f892007-02-28 22:03:49 +00001063 The first four items in the tuple correspond to getargspec().
Yury Selivanov3cfec2e2015-05-22 11:38:38 -04001064
1065 This function is deprecated, use inspect.signature() instead.
Jeremy Hylton64967882003-06-27 18:14:39 +00001066 """
1067
Yury Selivanov57d240e2014-02-19 16:27:23 -05001068 try:
1069 # Re: `skip_bound_arg=False`
1070 #
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001071 # There is a notable difference in behaviour between getfullargspec
1072 # and Signature: the former always returns 'self' parameter for bound
1073 # methods, whereas the Signature always shows the actual calling
1074 # signature of the passed object.
1075 #
1076 # To simulate this behaviour, we "unbind" bound methods, to trick
1077 # inspect.signature to always return their first parameter ("self",
1078 # usually)
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001079
Yury Selivanov57d240e2014-02-19 16:27:23 -05001080 # Re: `follow_wrapper_chains=False`
1081 #
1082 # getfullargspec() historically ignored __wrapped__ attributes,
1083 # so we ensure that remains the case in 3.3+
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001084
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001085 sig = _signature_from_callable(func,
1086 follow_wrapper_chains=False,
1087 skip_bound_arg=False,
1088 sigcls=Signature)
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001089 except Exception as ex:
1090 # Most of the times 'signature' will raise ValueError.
1091 # But, it can also raise AttributeError, and, maybe something
1092 # else. So to be fully backwards compatible, we catch all
1093 # possible exceptions here, and reraise a TypeError.
1094 raise TypeError('unsupported callable') from ex
1095
1096 args = []
1097 varargs = None
1098 varkw = None
1099 kwonlyargs = []
1100 defaults = ()
1101 annotations = {}
1102 defaults = ()
1103 kwdefaults = {}
1104
1105 if sig.return_annotation is not sig.empty:
1106 annotations['return'] = sig.return_annotation
1107
1108 for param in sig.parameters.values():
1109 kind = param.kind
1110 name = param.name
1111
1112 if kind is _POSITIONAL_ONLY:
1113 args.append(name)
1114 elif kind is _POSITIONAL_OR_KEYWORD:
1115 args.append(name)
1116 if param.default is not param.empty:
1117 defaults += (param.default,)
1118 elif kind is _VAR_POSITIONAL:
1119 varargs = name
1120 elif kind is _KEYWORD_ONLY:
1121 kwonlyargs.append(name)
1122 if param.default is not param.empty:
1123 kwdefaults[name] = param.default
1124 elif kind is _VAR_KEYWORD:
1125 varkw = name
1126
1127 if param.annotation is not param.empty:
1128 annotations[name] = param.annotation
1129
1130 if not kwdefaults:
1131 # compatibility with 'func.__kwdefaults__'
1132 kwdefaults = None
1133
1134 if not defaults:
1135 # compatibility with 'func.__defaults__'
1136 defaults = None
1137
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001138 return FullArgSpec(args, varargs, varkw, defaults,
1139 kwonlyargs, kwdefaults, annotations)
1140
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001141
Christian Heimes25bb7832008-01-11 16:17:00 +00001142ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
1143
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001144def getargvalues(frame):
1145 """Get information about arguments passed into a particular frame.
1146
1147 A tuple of four things is returned: (args, varargs, varkw, locals).
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001148 'args' is a list of the argument names.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001149 'varargs' and 'varkw' are the names of the * and ** arguments or None.
1150 'locals' is the locals dictionary of the given frame."""
1151 args, varargs, varkw = getargs(frame.f_code)
Benjamin Peterson1a6e0d02008-10-25 15:49:17 +00001152 return ArgInfo(args, varargs, varkw, frame.f_locals)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001153
Guido van Rossum2e65f892007-02-28 22:03:49 +00001154def formatannotation(annotation, base_module=None):
1155 if isinstance(annotation, type):
Georg Brandl1a3284e2007-12-02 09:40:06 +00001156 if annotation.__module__ in ('builtins', base_module):
Serhiy Storchaka521e5862014-07-22 15:00:37 +03001157 return annotation.__qualname__
1158 return annotation.__module__+'.'+annotation.__qualname__
Guido van Rossum2e65f892007-02-28 22:03:49 +00001159 return repr(annotation)
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001160
Guido van Rossum2e65f892007-02-28 22:03:49 +00001161def formatannotationrelativeto(object):
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001162 module = getattr(object, '__module__', None)
1163 def _formatannotation(annotation):
1164 return formatannotation(annotation, module)
1165 return _formatannotation
Guido van Rossum2e65f892007-02-28 22:03:49 +00001166
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001167def formatargspec(args, varargs=None, varkw=None, defaults=None,
Guido van Rossum2e65f892007-02-28 22:03:49 +00001168 kwonlyargs=(), kwonlydefaults={}, annotations={},
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001169 formatarg=str,
1170 formatvarargs=lambda name: '*' + name,
1171 formatvarkw=lambda name: '**' + name,
1172 formatvalue=lambda value: '=' + repr(value),
Guido van Rossum2e65f892007-02-28 22:03:49 +00001173 formatreturns=lambda text: ' -> ' + text,
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001174 formatannotation=formatannotation):
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001175 """Format an argument spec from the values returned by getargspec
Guido van Rossum2e65f892007-02-28 22:03:49 +00001176 or getfullargspec.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001177
Guido van Rossum2e65f892007-02-28 22:03:49 +00001178 The first seven arguments are (args, varargs, varkw, defaults,
1179 kwonlyargs, kwonlydefaults, annotations). The other five arguments
1180 are the corresponding optional formatting functions that are called to
1181 turn names and values into strings. The last argument is an optional
1182 function to format the sequence of arguments."""
1183 def formatargandannotation(arg):
1184 result = formatarg(arg)
1185 if arg in annotations:
1186 result += ': ' + formatannotation(annotations[arg])
1187 return result
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001188 specs = []
1189 if defaults:
1190 firstdefault = len(args) - len(defaults)
Benjamin Petersonb58dda72009-01-18 22:27:04 +00001191 for i, arg in enumerate(args):
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001192 spec = formatargandannotation(arg)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001193 if defaults and i >= firstdefault:
1194 spec = spec + formatvalue(defaults[i - firstdefault])
1195 specs.append(spec)
Raymond Hettinger936654b2002-06-01 03:06:31 +00001196 if varargs is not None:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001197 specs.append(formatvarargs(formatargandannotation(varargs)))
1198 else:
1199 if kwonlyargs:
1200 specs.append('*')
1201 if kwonlyargs:
1202 for kwonlyarg in kwonlyargs:
1203 spec = formatargandannotation(kwonlyarg)
Benjamin Peterson9953a8d2009-01-17 04:15:01 +00001204 if kwonlydefaults and kwonlyarg in kwonlydefaults:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001205 spec += formatvalue(kwonlydefaults[kwonlyarg])
1206 specs.append(spec)
Raymond Hettinger936654b2002-06-01 03:06:31 +00001207 if varkw is not None:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001208 specs.append(formatvarkw(formatargandannotation(varkw)))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001209 result = '(' + ', '.join(specs) + ')'
Guido van Rossum2e65f892007-02-28 22:03:49 +00001210 if 'return' in annotations:
1211 result += formatreturns(formatannotation(annotations['return']))
1212 return result
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001213
1214def formatargvalues(args, varargs, varkw, locals,
1215 formatarg=str,
1216 formatvarargs=lambda name: '*' + name,
1217 formatvarkw=lambda name: '**' + name,
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001218 formatvalue=lambda value: '=' + repr(value)):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001219 """Format an argument spec from the 4 values returned by getargvalues.
1220
1221 The first four arguments are (args, varargs, varkw, locals). The
1222 next four arguments are the corresponding optional formatting functions
1223 that are called to turn names and values into strings. The ninth
1224 argument is an optional function to format the sequence of arguments."""
1225 def convert(name, locals=locals,
1226 formatarg=formatarg, formatvalue=formatvalue):
1227 return formatarg(name) + formatvalue(locals[name])
1228 specs = []
1229 for i in range(len(args)):
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001230 specs.append(convert(args[i]))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001231 if varargs:
1232 specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
1233 if varkw:
1234 specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001235 return '(' + ', '.join(specs) + ')'
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001236
Benjamin Petersone109c702011-06-24 09:37:26 -05001237def _missing_arguments(f_name, argnames, pos, values):
1238 names = [repr(name) for name in argnames if name not in values]
1239 missing = len(names)
1240 if missing == 1:
1241 s = names[0]
1242 elif missing == 2:
1243 s = "{} and {}".format(*names)
1244 else:
Yury Selivanovdccfa132014-03-27 18:42:52 -04001245 tail = ", {} and {}".format(*names[-2:])
Benjamin Petersone109c702011-06-24 09:37:26 -05001246 del names[-2:]
1247 s = ", ".join(names) + tail
1248 raise TypeError("%s() missing %i required %s argument%s: %s" %
1249 (f_name, missing,
1250 "positional" if pos else "keyword-only",
1251 "" if missing == 1 else "s", s))
1252
1253def _too_many(f_name, args, kwonly, varargs, defcount, given, values):
Benjamin Petersonb204a422011-06-05 22:04:07 -05001254 atleast = len(args) - defcount
Benjamin Petersonb204a422011-06-05 22:04:07 -05001255 kwonly_given = len([arg for arg in kwonly if arg in values])
1256 if varargs:
1257 plural = atleast != 1
1258 sig = "at least %d" % (atleast,)
1259 elif defcount:
1260 plural = True
1261 sig = "from %d to %d" % (atleast, len(args))
1262 else:
1263 plural = len(args) != 1
1264 sig = str(len(args))
1265 kwonly_sig = ""
1266 if kwonly_given:
1267 msg = " positional argument%s (and %d keyword-only argument%s)"
1268 kwonly_sig = (msg % ("s" if given != 1 else "", kwonly_given,
1269 "s" if kwonly_given != 1 else ""))
1270 raise TypeError("%s() takes %s positional argument%s but %d%s %s given" %
1271 (f_name, sig, "s" if plural else "", given, kwonly_sig,
1272 "was" if given == 1 and not kwonly_given else "were"))
1273
Benjamin Peterson3e6ab172014-01-02 12:24:08 -06001274def getcallargs(*func_and_positional, **named):
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001275 """Get the mapping of arguments to values.
1276
1277 A dict is returned, with keys the function argument names (including the
1278 names of the * and ** arguments, if any), and values the respective bound
1279 values from 'positional' and 'named'."""
Benjamin Peterson3e6ab172014-01-02 12:24:08 -06001280 func = func_and_positional[0]
1281 positional = func_and_positional[1:]
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001282 spec = getfullargspec(func)
1283 args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = spec
1284 f_name = func.__name__
1285 arg2value = {}
1286
Benjamin Petersonb204a422011-06-05 22:04:07 -05001287
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001288 if ismethod(func) and func.__self__ is not None:
1289 # implicit 'self' (or 'cls' for classmethods) argument
1290 positional = (func.__self__,) + positional
1291 num_pos = len(positional)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001292 num_args = len(args)
1293 num_defaults = len(defaults) if defaults else 0
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001294
Benjamin Petersonb204a422011-06-05 22:04:07 -05001295 n = min(num_pos, num_args)
1296 for i in range(n):
1297 arg2value[args[i]] = positional[i]
1298 if varargs:
1299 arg2value[varargs] = tuple(positional[n:])
1300 possible_kwargs = set(args + kwonlyargs)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001301 if varkw:
Benjamin Petersonb204a422011-06-05 22:04:07 -05001302 arg2value[varkw] = {}
1303 for kw, value in named.items():
1304 if kw not in possible_kwargs:
1305 if not varkw:
1306 raise TypeError("%s() got an unexpected keyword argument %r" %
1307 (f_name, kw))
1308 arg2value[varkw][kw] = value
1309 continue
1310 if kw in arg2value:
1311 raise TypeError("%s() got multiple values for argument %r" %
1312 (f_name, kw))
1313 arg2value[kw] = value
1314 if num_pos > num_args and not varargs:
Benjamin Petersone109c702011-06-24 09:37:26 -05001315 _too_many(f_name, args, kwonlyargs, varargs, num_defaults,
1316 num_pos, arg2value)
Benjamin Petersonb204a422011-06-05 22:04:07 -05001317 if num_pos < num_args:
Benjamin Petersone109c702011-06-24 09:37:26 -05001318 req = args[:num_args - num_defaults]
1319 for arg in req:
Benjamin Petersonb204a422011-06-05 22:04:07 -05001320 if arg not in arg2value:
Benjamin Petersone109c702011-06-24 09:37:26 -05001321 _missing_arguments(f_name, req, True, arg2value)
Benjamin Petersonb204a422011-06-05 22:04:07 -05001322 for i, arg in enumerate(args[num_args - num_defaults:]):
1323 if arg not in arg2value:
1324 arg2value[arg] = defaults[i]
Benjamin Petersone109c702011-06-24 09:37:26 -05001325 missing = 0
Benjamin Petersonb204a422011-06-05 22:04:07 -05001326 for kwarg in kwonlyargs:
1327 if kwarg not in arg2value:
Yury Selivanov875df202014-03-27 18:23:03 -04001328 if kwonlydefaults and kwarg in kwonlydefaults:
Benjamin Petersone109c702011-06-24 09:37:26 -05001329 arg2value[kwarg] = kwonlydefaults[kwarg]
1330 else:
1331 missing += 1
1332 if missing:
1333 _missing_arguments(f_name, kwonlyargs, False, arg2value)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001334 return arg2value
1335
Nick Coghlan2f92e542012-06-23 19:39:55 +10001336ClosureVars = namedtuple('ClosureVars', 'nonlocals globals builtins unbound')
1337
1338def getclosurevars(func):
1339 """
1340 Get the mapping of free variables to their current values.
1341
Meador Inge8fda3592012-07-19 21:33:21 -05001342 Returns a named tuple of dicts mapping the current nonlocal, global
Nick Coghlan2f92e542012-06-23 19:39:55 +10001343 and builtin references as seen by the body of the function. A final
1344 set of unbound names that could not be resolved is also provided.
1345 """
1346
1347 if ismethod(func):
1348 func = func.__func__
1349
1350 if not isfunction(func):
1351 raise TypeError("'{!r}' is not a Python function".format(func))
1352
1353 code = func.__code__
1354 # Nonlocal references are named in co_freevars and resolved
1355 # by looking them up in __closure__ by positional index
1356 if func.__closure__ is None:
1357 nonlocal_vars = {}
1358 else:
1359 nonlocal_vars = {
1360 var : cell.cell_contents
1361 for var, cell in zip(code.co_freevars, func.__closure__)
1362 }
1363
1364 # Global and builtin references are named in co_names and resolved
1365 # by looking them up in __globals__ or __builtins__
1366 global_ns = func.__globals__
1367 builtin_ns = global_ns.get("__builtins__", builtins.__dict__)
1368 if ismodule(builtin_ns):
1369 builtin_ns = builtin_ns.__dict__
1370 global_vars = {}
1371 builtin_vars = {}
1372 unbound_names = set()
1373 for name in code.co_names:
1374 if name in ("None", "True", "False"):
1375 # Because these used to be builtins instead of keywords, they
1376 # may still show up as name references. We ignore them.
1377 continue
1378 try:
1379 global_vars[name] = global_ns[name]
1380 except KeyError:
1381 try:
1382 builtin_vars[name] = builtin_ns[name]
1383 except KeyError:
1384 unbound_names.add(name)
1385
1386 return ClosureVars(nonlocal_vars, global_vars,
1387 builtin_vars, unbound_names)
1388
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001389# -------------------------------------------------- stack frame extraction
Christian Heimes25bb7832008-01-11 16:17:00 +00001390
1391Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
1392
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001393def getframeinfo(frame, context=1):
1394 """Get information about a frame or traceback object.
1395
1396 A tuple of five things is returned: the filename, the line number of
1397 the current line, the function name, a list of lines of context from
1398 the source code, and the index of the current line within that list.
1399 The optional second argument specifies the number of lines of context
1400 to return, which are centered around the current line."""
1401 if istraceback(frame):
Andrew M. Kuchlingba8b6bc2004-06-05 14:11:59 +00001402 lineno = frame.tb_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001403 frame = frame.tb_frame
Andrew M. Kuchlingba8b6bc2004-06-05 14:11:59 +00001404 else:
1405 lineno = frame.f_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001406 if not isframe(frame):
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001407 raise TypeError('{!r} is not a frame or traceback object'.format(frame))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001408
Neil Schemenauerf06f8532002-03-23 23:51:04 +00001409 filename = getsourcefile(frame) or getfile(frame)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001410 if context > 0:
Guido van Rossum54e54c62001-09-04 19:14:14 +00001411 start = lineno - 1 - context//2
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001412 try:
1413 lines, lnum = findsource(frame)
Andrew Svetlovf7a17b42012-12-25 16:47:37 +02001414 except OSError:
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +00001415 lines = index = None
1416 else:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001417 start = max(start, 1)
Raymond Hettingera0501712004-06-15 11:22:53 +00001418 start = max(0, min(start, len(lines) - context))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001419 lines = lines[start:start+context]
Ka-Ping Yee59ade082001-03-01 03:55:35 +00001420 index = lineno - 1 - start
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001421 else:
1422 lines = index = None
1423
Christian Heimes25bb7832008-01-11 16:17:00 +00001424 return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
Ka-Ping Yee59ade082001-03-01 03:55:35 +00001425
1426def getlineno(frame):
1427 """Get the line number from a frame object, allowing for optimization."""
Michael W. Hudsondd32a912002-08-15 14:59:02 +00001428 # FrameType.f_lineno is now a descriptor that grovels co_lnotab
1429 return frame.f_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001430
Antoine Pitroucdcafb72014-08-24 10:50:28 -04001431FrameInfo = namedtuple('FrameInfo', ('frame',) + Traceback._fields)
1432
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001433def getouterframes(frame, context=1):
1434 """Get a list of records for a frame and all higher (calling) frames.
1435
1436 Each record contains a frame object, filename, line number, function
1437 name, a list of lines of context, and index within the context."""
1438 framelist = []
1439 while frame:
Antoine Pitroucdcafb72014-08-24 10:50:28 -04001440 frameinfo = (frame,) + getframeinfo(frame, context)
1441 framelist.append(FrameInfo(*frameinfo))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001442 frame = frame.f_back
1443 return framelist
1444
1445def getinnerframes(tb, context=1):
1446 """Get a list of records for a traceback's frame and all lower frames.
1447
1448 Each record contains a frame object, filename, line number, function
1449 name, a list of lines of context, and index within the context."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001450 framelist = []
1451 while tb:
Antoine Pitroucdcafb72014-08-24 10:50:28 -04001452 frameinfo = (tb.tb_frame,) + getframeinfo(tb, context)
1453 framelist.append(FrameInfo(*frameinfo))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001454 tb = tb.tb_next
1455 return framelist
1456
Benjamin Peterson42ac4752010-08-09 13:05:35 +00001457def currentframe():
Benjamin Petersona3a3fc62010-08-09 15:49:56 +00001458 """Return the frame of the caller or None if this is not possible."""
Benjamin Peterson42ac4752010-08-09 13:05:35 +00001459 return sys._getframe(1) if hasattr(sys, "_getframe") else None
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001460
1461def stack(context=1):
1462 """Return a list of records for the stack above the caller's frame."""
Jeremy Hyltonab919022003-06-27 18:41:20 +00001463 return getouterframes(sys._getframe(1), context)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001464
1465def trace(context=1):
Tim Peters85ba6732001-02-28 08:26:44 +00001466 """Return a list of records for the stack below the current exception."""
Fred Draked451ec12002-04-26 02:29:55 +00001467 return getinnerframes(sys.exc_info()[2], context)
Michael Foord95fc51d2010-11-20 15:07:30 +00001468
1469
1470# ------------------------------------------------ static version of getattr
1471
1472_sentinel = object()
1473
Michael Foorde5162652010-11-20 16:40:44 +00001474def _static_getmro(klass):
1475 return type.__dict__['__mro__'].__get__(klass)
1476
Michael Foord95fc51d2010-11-20 15:07:30 +00001477def _check_instance(obj, attr):
1478 instance_dict = {}
1479 try:
1480 instance_dict = object.__getattribute__(obj, "__dict__")
1481 except AttributeError:
1482 pass
Michael Foorddcebe0f2011-03-15 19:20:44 -04001483 return dict.get(instance_dict, attr, _sentinel)
Michael Foord95fc51d2010-11-20 15:07:30 +00001484
1485
1486def _check_class(klass, attr):
Michael Foorde5162652010-11-20 16:40:44 +00001487 for entry in _static_getmro(klass):
Michael Foorda51623b2011-12-18 22:01:40 +00001488 if _shadowed_dict(type(entry)) is _sentinel:
Michael Foorddcebe0f2011-03-15 19:20:44 -04001489 try:
1490 return entry.__dict__[attr]
1491 except KeyError:
1492 pass
Michael Foord95fc51d2010-11-20 15:07:30 +00001493 return _sentinel
1494
Michael Foord35184ed2010-11-20 16:58:30 +00001495def _is_type(obj):
1496 try:
1497 _static_getmro(obj)
1498 except TypeError:
1499 return False
1500 return True
1501
Michael Foorddcebe0f2011-03-15 19:20:44 -04001502def _shadowed_dict(klass):
1503 dict_attr = type.__dict__["__dict__"]
1504 for entry in _static_getmro(klass):
1505 try:
1506 class_dict = dict_attr.__get__(entry)["__dict__"]
1507 except KeyError:
1508 pass
1509 else:
1510 if not (type(class_dict) is types.GetSetDescriptorType and
1511 class_dict.__name__ == "__dict__" and
1512 class_dict.__objclass__ is entry):
Michael Foorda51623b2011-12-18 22:01:40 +00001513 return class_dict
1514 return _sentinel
Michael Foord95fc51d2010-11-20 15:07:30 +00001515
1516def getattr_static(obj, attr, default=_sentinel):
1517 """Retrieve attributes without triggering dynamic lookup via the
1518 descriptor protocol, __getattr__ or __getattribute__.
1519
1520 Note: this function may not be able to retrieve all attributes
1521 that getattr can fetch (like dynamically created attributes)
1522 and may find attributes that getattr can't (like descriptors
1523 that raise AttributeError). It can also return descriptor objects
1524 instead of instance members in some cases. See the
1525 documentation for details.
1526 """
1527 instance_result = _sentinel
Michael Foord35184ed2010-11-20 16:58:30 +00001528 if not _is_type(obj):
Michael Foordcc7ebb82010-11-20 16:20:16 +00001529 klass = type(obj)
Michael Foorda51623b2011-12-18 22:01:40 +00001530 dict_attr = _shadowed_dict(klass)
1531 if (dict_attr is _sentinel or
1532 type(dict_attr) is types.MemberDescriptorType):
Michael Foorddcebe0f2011-03-15 19:20:44 -04001533 instance_result = _check_instance(obj, attr)
Michael Foord95fc51d2010-11-20 15:07:30 +00001534 else:
1535 klass = obj
1536
1537 klass_result = _check_class(klass, attr)
1538
1539 if instance_result is not _sentinel and klass_result is not _sentinel:
1540 if (_check_class(type(klass_result), '__get__') is not _sentinel and
1541 _check_class(type(klass_result), '__set__') is not _sentinel):
1542 return klass_result
1543
1544 if instance_result is not _sentinel:
1545 return instance_result
1546 if klass_result is not _sentinel:
1547 return klass_result
1548
1549 if obj is klass:
1550 # for types we check the metaclass too
Michael Foorde5162652010-11-20 16:40:44 +00001551 for entry in _static_getmro(type(klass)):
Michael Foord3ba95f82011-12-22 01:13:37 +00001552 if _shadowed_dict(type(entry)) is _sentinel:
1553 try:
1554 return entry.__dict__[attr]
1555 except KeyError:
1556 pass
Michael Foord95fc51d2010-11-20 15:07:30 +00001557 if default is not _sentinel:
1558 return default
1559 raise AttributeError(attr)
Nick Coghlane0f04652010-11-21 03:44:04 +00001560
1561
Nick Coghlan04e2e3f2012-06-23 19:52:05 +10001562# ------------------------------------------------ generator introspection
1563
Nick Coghlan7921b9f2010-11-30 06:36:04 +00001564GEN_CREATED = 'GEN_CREATED'
1565GEN_RUNNING = 'GEN_RUNNING'
1566GEN_SUSPENDED = 'GEN_SUSPENDED'
1567GEN_CLOSED = 'GEN_CLOSED'
Nick Coghlane0f04652010-11-21 03:44:04 +00001568
1569def getgeneratorstate(generator):
1570 """Get current state of a generator-iterator.
1571
1572 Possible states are:
1573 GEN_CREATED: Waiting to start execution.
1574 GEN_RUNNING: Currently being executed by the interpreter.
1575 GEN_SUSPENDED: Currently suspended at a yield expression.
1576 GEN_CLOSED: Execution has completed.
1577 """
1578 if generator.gi_running:
1579 return GEN_RUNNING
1580 if generator.gi_frame is None:
1581 return GEN_CLOSED
1582 if generator.gi_frame.f_lasti == -1:
1583 return GEN_CREATED
1584 return GEN_SUSPENDED
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001585
1586
Nick Coghlan04e2e3f2012-06-23 19:52:05 +10001587def getgeneratorlocals(generator):
1588 """
1589 Get the mapping of generator local variables to their current values.
1590
1591 A dict is returned, with the keys the local variable names and values the
1592 bound values."""
1593
1594 if not isgenerator(generator):
1595 raise TypeError("'{!r}' is not a Python generator".format(generator))
1596
1597 frame = getattr(generator, "gi_frame", None)
1598 if frame is not None:
1599 return generator.gi_frame.f_locals
1600 else:
1601 return {}
1602
Yury Selivanov5376ba92015-06-22 12:19:30 -04001603
1604# ------------------------------------------------ coroutine introspection
1605
1606CORO_CREATED = 'CORO_CREATED'
1607CORO_RUNNING = 'CORO_RUNNING'
1608CORO_SUSPENDED = 'CORO_SUSPENDED'
1609CORO_CLOSED = 'CORO_CLOSED'
1610
1611def getcoroutinestate(coroutine):
1612 """Get current state of a coroutine object.
1613
1614 Possible states are:
1615 CORO_CREATED: Waiting to start execution.
1616 CORO_RUNNING: Currently being executed by the interpreter.
1617 CORO_SUSPENDED: Currently suspended at an await expression.
1618 CORO_CLOSED: Execution has completed.
1619 """
1620 if coroutine.cr_running:
1621 return CORO_RUNNING
1622 if coroutine.cr_frame is None:
1623 return CORO_CLOSED
1624 if coroutine.cr_frame.f_lasti == -1:
1625 return CORO_CREATED
1626 return CORO_SUSPENDED
1627
1628
1629def getcoroutinelocals(coroutine):
1630 """
1631 Get the mapping of coroutine local variables to their current values.
1632
1633 A dict is returned, with the keys the local variable names and values the
1634 bound values."""
1635 frame = getattr(coroutine, "cr_frame", None)
1636 if frame is not None:
1637 return frame.f_locals
1638 else:
1639 return {}
1640
1641
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001642###############################################################################
1643### Function Signature Object (PEP 362)
1644###############################################################################
1645
1646
1647_WrapperDescriptor = type(type.__call__)
1648_MethodWrapper = type(all.__call__)
Larry Hastings5c661892014-01-24 06:17:25 -08001649_ClassMethodWrapper = type(int.__dict__['from_bytes'])
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001650
1651_NonUserDefinedCallables = (_WrapperDescriptor,
1652 _MethodWrapper,
Larry Hastings5c661892014-01-24 06:17:25 -08001653 _ClassMethodWrapper,
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001654 types.BuiltinFunctionType)
1655
1656
Yury Selivanov421f0c72014-01-29 12:05:40 -05001657def _signature_get_user_defined_method(cls, method_name):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001658 """Private helper. Checks if ``cls`` has an attribute
1659 named ``method_name`` and returns it only if it is a
1660 pure python function.
1661 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001662 try:
1663 meth = getattr(cls, method_name)
1664 except AttributeError:
1665 return
1666 else:
1667 if not isinstance(meth, _NonUserDefinedCallables):
1668 # Once '__signature__' will be added to 'C'-level
1669 # callables, this check won't be necessary
1670 return meth
1671
1672
Yury Selivanov62560fb2014-01-28 12:26:24 -05001673def _signature_get_partial(wrapped_sig, partial, extra_args=()):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001674 """Private helper to calculate how 'wrapped_sig' signature will
1675 look like after applying a 'functools.partial' object (or alike)
1676 on it.
1677 """
Yury Selivanov62560fb2014-01-28 12:26:24 -05001678
Yury Selivanov3f73ca22014-04-08 11:30:45 -04001679 old_params = wrapped_sig.parameters
1680 new_params = OrderedDict(old_params.items())
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001681
1682 partial_args = partial.args or ()
1683 partial_keywords = partial.keywords or {}
1684
1685 if extra_args:
1686 partial_args = extra_args + partial_args
1687
1688 try:
1689 ba = wrapped_sig.bind_partial(*partial_args, **partial_keywords)
1690 except TypeError as ex:
1691 msg = 'partial object {!r} has incorrect arguments'.format(partial)
1692 raise ValueError(msg) from ex
1693
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001694
Yury Selivanov3f73ca22014-04-08 11:30:45 -04001695 transform_to_kwonly = False
1696 for param_name, param in old_params.items():
1697 try:
1698 arg_value = ba.arguments[param_name]
1699 except KeyError:
1700 pass
1701 else:
1702 if param.kind is _POSITIONAL_ONLY:
1703 # If positional-only parameter is bound by partial,
1704 # it effectively disappears from the signature
1705 new_params.pop(param_name)
1706 continue
1707
1708 if param.kind is _POSITIONAL_OR_KEYWORD:
1709 if param_name in partial_keywords:
1710 # This means that this parameter, and all parameters
1711 # after it should be keyword-only (and var-positional
1712 # should be removed). Here's why. Consider the following
1713 # function:
1714 # foo(a, b, *args, c):
1715 # pass
1716 #
1717 # "partial(foo, a='spam')" will have the following
1718 # signature: "(*, a='spam', b, c)". Because attempting
1719 # to call that partial with "(10, 20)" arguments will
1720 # raise a TypeError, saying that "a" argument received
1721 # multiple values.
1722 transform_to_kwonly = True
1723 # Set the new default value
1724 new_params[param_name] = param.replace(default=arg_value)
1725 else:
1726 # was passed as a positional argument
1727 new_params.pop(param.name)
1728 continue
1729
1730 if param.kind is _KEYWORD_ONLY:
1731 # Set the new default value
1732 new_params[param_name] = param.replace(default=arg_value)
1733
1734 if transform_to_kwonly:
1735 assert param.kind is not _POSITIONAL_ONLY
1736
1737 if param.kind is _POSITIONAL_OR_KEYWORD:
1738 new_param = new_params[param_name].replace(kind=_KEYWORD_ONLY)
1739 new_params[param_name] = new_param
1740 new_params.move_to_end(param_name)
1741 elif param.kind in (_KEYWORD_ONLY, _VAR_KEYWORD):
1742 new_params.move_to_end(param_name)
1743 elif param.kind is _VAR_POSITIONAL:
1744 new_params.pop(param.name)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001745
1746 return wrapped_sig.replace(parameters=new_params.values())
1747
1748
Yury Selivanov62560fb2014-01-28 12:26:24 -05001749def _signature_bound_method(sig):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001750 """Private helper to transform signatures for unbound
1751 functions to bound methods.
1752 """
Yury Selivanov62560fb2014-01-28 12:26:24 -05001753
1754 params = tuple(sig.parameters.values())
1755
1756 if not params or params[0].kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
1757 raise ValueError('invalid method signature')
1758
1759 kind = params[0].kind
1760 if kind in (_POSITIONAL_OR_KEYWORD, _POSITIONAL_ONLY):
1761 # Drop first parameter:
1762 # '(p1, p2[, ...])' -> '(p2[, ...])'
1763 params = params[1:]
1764 else:
1765 if kind is not _VAR_POSITIONAL:
1766 # Unless we add a new parameter type we never
1767 # get here
1768 raise ValueError('invalid argument type')
1769 # It's a var-positional parameter.
1770 # Do nothing. '(*args[, ...])' -> '(*args[, ...])'
1771
1772 return sig.replace(parameters=params)
1773
1774
Yury Selivanovb77511d2014-01-29 10:46:14 -05001775def _signature_is_builtin(obj):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001776 """Private helper to test if `obj` is a callable that might
1777 support Argument Clinic's __text_signature__ protocol.
1778 """
Yury Selivanov1d241832014-02-02 12:51:20 -05001779 return (isbuiltin(obj) or
Yury Selivanovb77511d2014-01-29 10:46:14 -05001780 ismethoddescriptor(obj) or
Yury Selivanov1d241832014-02-02 12:51:20 -05001781 isinstance(obj, _NonUserDefinedCallables) or
Yury Selivanovb77511d2014-01-29 10:46:14 -05001782 # Can't test 'isinstance(type)' here, as it would
1783 # also be True for regular python classes
1784 obj in (type, object))
1785
1786
Yury Selivanov63da7c72014-01-31 14:48:37 -05001787def _signature_is_functionlike(obj):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001788 """Private helper to test if `obj` is a duck type of FunctionType.
1789 A good example of such objects are functions compiled with
1790 Cython, which have all attributes that a pure Python function
1791 would have, but have their code statically compiled.
1792 """
Yury Selivanov63da7c72014-01-31 14:48:37 -05001793
1794 if not callable(obj) or isclass(obj):
1795 # All function-like objects are obviously callables,
1796 # and not classes.
1797 return False
1798
1799 name = getattr(obj, '__name__', None)
1800 code = getattr(obj, '__code__', None)
1801 defaults = getattr(obj, '__defaults__', _void) # Important to use _void ...
1802 kwdefaults = getattr(obj, '__kwdefaults__', _void) # ... and not None here
1803 annotations = getattr(obj, '__annotations__', None)
1804
1805 return (isinstance(code, types.CodeType) and
1806 isinstance(name, str) and
1807 (defaults is None or isinstance(defaults, tuple)) and
1808 (kwdefaults is None or isinstance(kwdefaults, dict)) and
1809 isinstance(annotations, dict))
1810
1811
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001812def _signature_get_bound_param(spec):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001813 """ Private helper to get first parameter name from a
1814 __text_signature__ of a builtin method, which should
1815 be in the following format: '($param1, ...)'.
1816 Assumptions are that the first argument won't have
1817 a default value or an annotation.
1818 """
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001819
1820 assert spec.startswith('($')
1821
1822 pos = spec.find(',')
1823 if pos == -1:
1824 pos = spec.find(')')
1825
1826 cpos = spec.find(':')
1827 assert cpos == -1 or cpos > pos
1828
1829 cpos = spec.find('=')
1830 assert cpos == -1 or cpos > pos
1831
1832 return spec[2:pos]
1833
1834
Larry Hastings2623c8c2014-02-08 22:15:29 -08001835def _signature_strip_non_python_syntax(signature):
1836 """
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001837 Private helper function. Takes a signature in Argument Clinic's
1838 extended signature format.
1839
Larry Hastings2623c8c2014-02-08 22:15:29 -08001840 Returns a tuple of three things:
1841 * that signature re-rendered in standard Python syntax,
1842 * the index of the "self" parameter (generally 0), or None if
1843 the function does not have a "self" parameter, and
1844 * the index of the last "positional only" parameter,
1845 or None if the signature has no positional-only parameters.
1846 """
1847
1848 if not signature:
1849 return signature, None, None
1850
1851 self_parameter = None
1852 last_positional_only = None
1853
1854 lines = [l.encode('ascii') for l in signature.split('\n')]
1855 generator = iter(lines).__next__
1856 token_stream = tokenize.tokenize(generator)
1857
1858 delayed_comma = False
1859 skip_next_comma = False
1860 text = []
1861 add = text.append
1862
1863 current_parameter = 0
1864 OP = token.OP
1865 ERRORTOKEN = token.ERRORTOKEN
1866
1867 # token stream always starts with ENCODING token, skip it
1868 t = next(token_stream)
1869 assert t.type == tokenize.ENCODING
1870
1871 for t in token_stream:
1872 type, string = t.type, t.string
1873
1874 if type == OP:
1875 if string == ',':
1876 if skip_next_comma:
1877 skip_next_comma = False
1878 else:
1879 assert not delayed_comma
1880 delayed_comma = True
1881 current_parameter += 1
1882 continue
1883
1884 if string == '/':
1885 assert not skip_next_comma
1886 assert last_positional_only is None
1887 skip_next_comma = True
1888 last_positional_only = current_parameter - 1
1889 continue
1890
1891 if (type == ERRORTOKEN) and (string == '$'):
1892 assert self_parameter is None
1893 self_parameter = current_parameter
1894 continue
1895
1896 if delayed_comma:
1897 delayed_comma = False
1898 if not ((type == OP) and (string == ')')):
1899 add(', ')
1900 add(string)
1901 if (string == ','):
1902 add(' ')
1903 clean_signature = ''.join(text)
1904 return clean_signature, self_parameter, last_positional_only
1905
1906
Yury Selivanov57d240e2014-02-19 16:27:23 -05001907def _signature_fromstr(cls, obj, s, skip_bound_arg=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001908 """Private helper to parse content of '__text_signature__'
1909 and return a Signature based on it.
1910 """
1911
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001912 Parameter = cls._parameter_cls
1913
Larry Hastings2623c8c2014-02-08 22:15:29 -08001914 clean_signature, self_parameter, last_positional_only = \
1915 _signature_strip_non_python_syntax(s)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001916
Larry Hastings2623c8c2014-02-08 22:15:29 -08001917 program = "def foo" + clean_signature + ": pass"
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001918
1919 try:
Larry Hastings2623c8c2014-02-08 22:15:29 -08001920 module = ast.parse(program)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001921 except SyntaxError:
1922 module = None
1923
1924 if not isinstance(module, ast.Module):
1925 raise ValueError("{!r} builtin has invalid signature".format(obj))
1926
1927 f = module.body[0]
1928
1929 parameters = []
1930 empty = Parameter.empty
1931 invalid = object()
1932
1933 module = None
1934 module_dict = {}
1935 module_name = getattr(obj, '__module__', None)
1936 if module_name:
1937 module = sys.modules.get(module_name, None)
1938 if module:
1939 module_dict = module.__dict__
1940 sys_module_dict = sys.modules
1941
1942 def parse_name(node):
1943 assert isinstance(node, ast.arg)
1944 if node.annotation != None:
1945 raise ValueError("Annotations are not currently supported")
1946 return node.arg
1947
1948 def wrap_value(s):
1949 try:
1950 value = eval(s, module_dict)
1951 except NameError:
1952 try:
1953 value = eval(s, sys_module_dict)
1954 except NameError:
1955 raise RuntimeError()
1956
1957 if isinstance(value, str):
1958 return ast.Str(value)
1959 if isinstance(value, (int, float)):
1960 return ast.Num(value)
1961 if isinstance(value, bytes):
1962 return ast.Bytes(value)
1963 if value in (True, False, None):
1964 return ast.NameConstant(value)
1965 raise RuntimeError()
1966
1967 class RewriteSymbolics(ast.NodeTransformer):
1968 def visit_Attribute(self, node):
1969 a = []
1970 n = node
1971 while isinstance(n, ast.Attribute):
1972 a.append(n.attr)
1973 n = n.value
1974 if not isinstance(n, ast.Name):
1975 raise RuntimeError()
1976 a.append(n.id)
1977 value = ".".join(reversed(a))
1978 return wrap_value(value)
1979
1980 def visit_Name(self, node):
1981 if not isinstance(node.ctx, ast.Load):
1982 raise ValueError()
1983 return wrap_value(node.id)
1984
1985 def p(name_node, default_node, default=empty):
1986 name = parse_name(name_node)
1987 if name is invalid:
1988 return None
1989 if default_node and default_node is not _empty:
1990 try:
1991 default_node = RewriteSymbolics().visit(default_node)
1992 o = ast.literal_eval(default_node)
1993 except ValueError:
1994 o = invalid
1995 if o is invalid:
1996 return None
1997 default = o if o is not invalid else default
1998 parameters.append(Parameter(name, kind, default=default, annotation=empty))
1999
2000 # non-keyword-only parameters
2001 args = reversed(f.args.args)
2002 defaults = reversed(f.args.defaults)
2003 iter = itertools.zip_longest(args, defaults, fillvalue=None)
Larry Hastings2623c8c2014-02-08 22:15:29 -08002004 if last_positional_only is not None:
2005 kind = Parameter.POSITIONAL_ONLY
2006 else:
2007 kind = Parameter.POSITIONAL_OR_KEYWORD
2008 for i, (name, default) in enumerate(reversed(list(iter))):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002009 p(name, default)
Larry Hastings2623c8c2014-02-08 22:15:29 -08002010 if i == last_positional_only:
2011 kind = Parameter.POSITIONAL_OR_KEYWORD
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002012
2013 # *args
2014 if f.args.vararg:
2015 kind = Parameter.VAR_POSITIONAL
2016 p(f.args.vararg, empty)
2017
2018 # keyword-only arguments
2019 kind = Parameter.KEYWORD_ONLY
2020 for name, default in zip(f.args.kwonlyargs, f.args.kw_defaults):
2021 p(name, default)
2022
2023 # **kwargs
2024 if f.args.kwarg:
2025 kind = Parameter.VAR_KEYWORD
2026 p(f.args.kwarg, empty)
2027
Larry Hastings2623c8c2014-02-08 22:15:29 -08002028 if self_parameter is not None:
Yury Selivanov8c185ee2014-02-21 01:32:42 -05002029 # Possibly strip the bound argument:
2030 # - We *always* strip first bound argument if
2031 # it is a module.
2032 # - We don't strip first bound argument if
2033 # skip_bound_arg is False.
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002034 assert parameters
Yury Selivanov8c185ee2014-02-21 01:32:42 -05002035 _self = getattr(obj, '__self__', None)
2036 self_isbound = _self is not None
2037 self_ismodule = ismodule(_self)
2038 if self_isbound and (self_ismodule or skip_bound_arg):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002039 parameters.pop(0)
2040 else:
2041 # for builtins, self parameter is always positional-only!
2042 p = parameters[0].replace(kind=Parameter.POSITIONAL_ONLY)
2043 parameters[0] = p
2044
2045 return cls(parameters, return_annotation=cls.empty)
2046
2047
Yury Selivanov57d240e2014-02-19 16:27:23 -05002048def _signature_from_builtin(cls, func, skip_bound_arg=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002049 """Private helper function to get signature for
2050 builtin callables.
2051 """
2052
Yury Selivanov57d240e2014-02-19 16:27:23 -05002053 if not _signature_is_builtin(func):
2054 raise TypeError("{!r} is not a Python builtin "
2055 "function".format(func))
2056
2057 s = getattr(func, "__text_signature__", None)
2058 if not s:
2059 raise ValueError("no signature found for builtin {!r}".format(func))
2060
2061 return _signature_fromstr(cls, func, s, skip_bound_arg)
2062
2063
Yury Selivanovcf45f022015-05-20 14:38:50 -04002064def _signature_from_function(cls, func):
2065 """Private helper: constructs Signature for the given python function."""
2066
2067 is_duck_function = False
2068 if not isfunction(func):
2069 if _signature_is_functionlike(func):
2070 is_duck_function = True
2071 else:
2072 # If it's not a pure Python function, and not a duck type
2073 # of pure function:
2074 raise TypeError('{!r} is not a Python function'.format(func))
2075
2076 Parameter = cls._parameter_cls
2077
2078 # Parameter information.
2079 func_code = func.__code__
2080 pos_count = func_code.co_argcount
2081 arg_names = func_code.co_varnames
2082 positional = tuple(arg_names[:pos_count])
2083 keyword_only_count = func_code.co_kwonlyargcount
2084 keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
2085 annotations = func.__annotations__
2086 defaults = func.__defaults__
2087 kwdefaults = func.__kwdefaults__
2088
2089 if defaults:
2090 pos_default_count = len(defaults)
2091 else:
2092 pos_default_count = 0
2093
2094 parameters = []
2095
2096 # Non-keyword-only parameters w/o defaults.
2097 non_default_count = pos_count - pos_default_count
2098 for name in positional[:non_default_count]:
2099 annotation = annotations.get(name, _empty)
2100 parameters.append(Parameter(name, annotation=annotation,
2101 kind=_POSITIONAL_OR_KEYWORD))
2102
2103 # ... w/ defaults.
2104 for offset, name in enumerate(positional[non_default_count:]):
2105 annotation = annotations.get(name, _empty)
2106 parameters.append(Parameter(name, annotation=annotation,
2107 kind=_POSITIONAL_OR_KEYWORD,
2108 default=defaults[offset]))
2109
2110 # *args
2111 if func_code.co_flags & CO_VARARGS:
2112 name = arg_names[pos_count + keyword_only_count]
2113 annotation = annotations.get(name, _empty)
2114 parameters.append(Parameter(name, annotation=annotation,
2115 kind=_VAR_POSITIONAL))
2116
2117 # Keyword-only parameters.
2118 for name in keyword_only:
2119 default = _empty
2120 if kwdefaults is not None:
2121 default = kwdefaults.get(name, _empty)
2122
2123 annotation = annotations.get(name, _empty)
2124 parameters.append(Parameter(name, annotation=annotation,
2125 kind=_KEYWORD_ONLY,
2126 default=default))
2127 # **kwargs
2128 if func_code.co_flags & CO_VARKEYWORDS:
2129 index = pos_count + keyword_only_count
2130 if func_code.co_flags & CO_VARARGS:
2131 index += 1
2132
2133 name = arg_names[index]
2134 annotation = annotations.get(name, _empty)
2135 parameters.append(Parameter(name, annotation=annotation,
2136 kind=_VAR_KEYWORD))
2137
2138 # Is 'func' is a pure Python function - don't validate the
2139 # parameters list (for correct order and defaults), it should be OK.
2140 return cls(parameters,
2141 return_annotation=annotations.get('return', _empty),
2142 __validate_parameters__=is_duck_function)
2143
2144
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002145def _signature_from_callable(obj, *,
2146 follow_wrapper_chains=True,
2147 skip_bound_arg=True,
2148 sigcls):
2149
2150 """Private helper function to get signature for arbitrary
2151 callable objects.
2152 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002153
2154 if not callable(obj):
2155 raise TypeError('{!r} is not a callable object'.format(obj))
2156
2157 if isinstance(obj, types.MethodType):
2158 # In this case we skip the first parameter of the underlying
2159 # function (usually `self` or `cls`).
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002160 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002161 obj.__func__,
2162 follow_wrapper_chains=follow_wrapper_chains,
2163 skip_bound_arg=skip_bound_arg,
2164 sigcls=sigcls)
2165
Yury Selivanov57d240e2014-02-19 16:27:23 -05002166 if skip_bound_arg:
2167 return _signature_bound_method(sig)
2168 else:
2169 return sig
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002170
Nick Coghlane8c45d62013-07-28 20:00:01 +10002171 # Was this function wrapped by a decorator?
Yury Selivanov57d240e2014-02-19 16:27:23 -05002172 if follow_wrapper_chains:
2173 obj = unwrap(obj, stop=(lambda f: hasattr(f, "__signature__")))
Yury Selivanov46c759d2015-05-27 21:56:53 -04002174 if isinstance(obj, types.MethodType):
2175 # If the unwrapped object is a *method*, we might want to
2176 # skip its first parameter (self).
2177 # See test_signature_wrapped_bound_method for details.
Yury Selivanov507cd3c2015-05-27 21:59:03 -04002178 return _signature_from_callable(
Yury Selivanov46c759d2015-05-27 21:56:53 -04002179 obj,
2180 follow_wrapper_chains=follow_wrapper_chains,
Yury Selivanov507cd3c2015-05-27 21:59:03 -04002181 skip_bound_arg=skip_bound_arg,
2182 sigcls=sigcls)
Nick Coghlane8c45d62013-07-28 20:00:01 +10002183
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002184 try:
2185 sig = obj.__signature__
2186 except AttributeError:
2187 pass
2188 else:
2189 if sig is not None:
Yury Selivanov42407ab2014-06-23 10:23:50 -07002190 if not isinstance(sig, Signature):
2191 raise TypeError(
2192 'unexpected object {!r} in __signature__ '
2193 'attribute'.format(sig))
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002194 return sig
2195
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05002196 try:
2197 partialmethod = obj._partialmethod
2198 except AttributeError:
2199 pass
2200 else:
Yury Selivanov0486f812014-01-29 12:18:59 -05002201 if isinstance(partialmethod, functools.partialmethod):
2202 # Unbound partialmethod (see functools.partialmethod)
2203 # This means, that we need to calculate the signature
2204 # as if it's a regular partial object, but taking into
2205 # account that the first positional argument
2206 # (usually `self`, or `cls`) will not be passed
2207 # automatically (as for boundmethods)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05002208
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002209 wrapped_sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002210 partialmethod.func,
2211 follow_wrapper_chains=follow_wrapper_chains,
2212 skip_bound_arg=skip_bound_arg,
2213 sigcls=sigcls)
2214
Yury Selivanov0486f812014-01-29 12:18:59 -05002215 sig = _signature_get_partial(wrapped_sig, partialmethod, (None,))
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05002216
Yury Selivanov0486f812014-01-29 12:18:59 -05002217 first_wrapped_param = tuple(wrapped_sig.parameters.values())[0]
2218 new_params = (first_wrapped_param,) + tuple(sig.parameters.values())
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05002219
Yury Selivanov0486f812014-01-29 12:18:59 -05002220 return sig.replace(parameters=new_params)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05002221
Yury Selivanov63da7c72014-01-31 14:48:37 -05002222 if isfunction(obj) or _signature_is_functionlike(obj):
2223 # If it's a pure Python function, or an object that is duck type
2224 # of a Python function (Cython functions, for instance), then:
Yury Selivanovcf45f022015-05-20 14:38:50 -04002225 return _signature_from_function(sigcls, obj)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002226
Yury Selivanova773de02014-02-21 18:30:53 -05002227 if _signature_is_builtin(obj):
Yury Selivanovda396452014-03-27 12:09:24 -04002228 return _signature_from_builtin(sigcls, obj,
Yury Selivanova773de02014-02-21 18:30:53 -05002229 skip_bound_arg=skip_bound_arg)
2230
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002231 if isinstance(obj, functools.partial):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002232 wrapped_sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002233 obj.func,
2234 follow_wrapper_chains=follow_wrapper_chains,
2235 skip_bound_arg=skip_bound_arg,
2236 sigcls=sigcls)
Yury Selivanov62560fb2014-01-28 12:26:24 -05002237 return _signature_get_partial(wrapped_sig, obj)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002238
2239 sig = None
2240 if isinstance(obj, type):
2241 # obj is a class or a metaclass
2242
2243 # First, let's see if it has an overloaded __call__ defined
2244 # in its metaclass
Yury Selivanov421f0c72014-01-29 12:05:40 -05002245 call = _signature_get_user_defined_method(type(obj), '__call__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002246 if call is not None:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002247 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002248 call,
2249 follow_wrapper_chains=follow_wrapper_chains,
2250 skip_bound_arg=skip_bound_arg,
2251 sigcls=sigcls)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002252 else:
2253 # Now we check if the 'obj' class has a '__new__' method
Yury Selivanov421f0c72014-01-29 12:05:40 -05002254 new = _signature_get_user_defined_method(obj, '__new__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002255 if new is not None:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002256 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002257 new,
2258 follow_wrapper_chains=follow_wrapper_chains,
2259 skip_bound_arg=skip_bound_arg,
2260 sigcls=sigcls)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002261 else:
2262 # Finally, we should have at least __init__ implemented
Yury Selivanov421f0c72014-01-29 12:05:40 -05002263 init = _signature_get_user_defined_method(obj, '__init__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002264 if init is not None:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002265 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002266 init,
2267 follow_wrapper_chains=follow_wrapper_chains,
2268 skip_bound_arg=skip_bound_arg,
2269 sigcls=sigcls)
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002270
2271 if sig is None:
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002272 # At this point we know, that `obj` is a class, with no user-
2273 # defined '__init__', '__new__', or class-level '__call__'
2274
Larry Hastings2623c8c2014-02-08 22:15:29 -08002275 for base in obj.__mro__[:-1]:
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002276 # Since '__text_signature__' is implemented as a
2277 # descriptor that extracts text signature from the
2278 # class docstring, if 'obj' is derived from a builtin
2279 # class, its own '__text_signature__' may be 'None'.
Larry Hastings2623c8c2014-02-08 22:15:29 -08002280 # Therefore, we go through the MRO (except the last
2281 # class in there, which is 'object') to find the first
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002282 # class with non-empty text signature.
2283 try:
2284 text_sig = base.__text_signature__
2285 except AttributeError:
2286 pass
2287 else:
2288 if text_sig:
2289 # If 'obj' class has a __text_signature__ attribute:
2290 # return a signature based on it
Yury Selivanovda396452014-03-27 12:09:24 -04002291 return _signature_fromstr(sigcls, obj, text_sig)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002292
2293 # No '__text_signature__' was found for the 'obj' class.
2294 # Last option is to check if its '__init__' is
2295 # object.__init__ or type.__init__.
Larry Hastings2623c8c2014-02-08 22:15:29 -08002296 if type not in obj.__mro__:
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002297 # We have a class (not metaclass), but no user-defined
2298 # __init__ or __new__ for it
Yury Selivanovbf304fc2015-05-30 17:08:36 -04002299 if (obj.__init__ is object.__init__ and
2300 obj.__new__ is object.__new__):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002301 # Return a signature of 'object' builtin.
2302 return signature(object)
Yury Selivanovbf304fc2015-05-30 17:08:36 -04002303 else:
2304 raise ValueError(
2305 'no signature found for builtin type {!r}'.format(obj))
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002306
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002307 elif not isinstance(obj, _NonUserDefinedCallables):
2308 # An object with __call__
2309 # We also check that the 'obj' is not an instance of
2310 # _WrapperDescriptor or _MethodWrapper to avoid
2311 # infinite recursion (and even potential segfault)
Yury Selivanov421f0c72014-01-29 12:05:40 -05002312 call = _signature_get_user_defined_method(type(obj), '__call__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002313 if call is not None:
Larry Hastings2623c8c2014-02-08 22:15:29 -08002314 try:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002315 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002316 call,
2317 follow_wrapper_chains=follow_wrapper_chains,
2318 skip_bound_arg=skip_bound_arg,
2319 sigcls=sigcls)
Larry Hastings2623c8c2014-02-08 22:15:29 -08002320 except ValueError as ex:
2321 msg = 'no signature found for {!r}'.format(obj)
2322 raise ValueError(msg) from ex
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002323
2324 if sig is not None:
2325 # For classes and objects we skip the first parameter of their
2326 # __call__, __new__, or __init__ methods
Yury Selivanov57d240e2014-02-19 16:27:23 -05002327 if skip_bound_arg:
2328 return _signature_bound_method(sig)
2329 else:
2330 return sig
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002331
2332 if isinstance(obj, types.BuiltinFunctionType):
2333 # Raise a nicer error message for builtins
2334 msg = 'no signature found for builtin function {!r}'.format(obj)
2335 raise ValueError(msg)
2336
2337 raise ValueError('callable {!r} is not supported by signature'.format(obj))
2338
2339
2340class _void:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002341 """A private marker - used in Parameter & Signature."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002342
2343
2344class _empty:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002345 """Marker object for Signature.empty and Parameter.empty."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002346
2347
Yury Selivanov21e83a52014-03-27 11:23:13 -04002348class _ParameterKind(enum.IntEnum):
2349 POSITIONAL_ONLY = 0
2350 POSITIONAL_OR_KEYWORD = 1
2351 VAR_POSITIONAL = 2
2352 KEYWORD_ONLY = 3
2353 VAR_KEYWORD = 4
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002354
2355 def __str__(self):
Yury Selivanov21e83a52014-03-27 11:23:13 -04002356 return self._name_
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002357
2358
Yury Selivanov21e83a52014-03-27 11:23:13 -04002359_POSITIONAL_ONLY = _ParameterKind.POSITIONAL_ONLY
2360_POSITIONAL_OR_KEYWORD = _ParameterKind.POSITIONAL_OR_KEYWORD
2361_VAR_POSITIONAL = _ParameterKind.VAR_POSITIONAL
2362_KEYWORD_ONLY = _ParameterKind.KEYWORD_ONLY
2363_VAR_KEYWORD = _ParameterKind.VAR_KEYWORD
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002364
2365
2366class Parameter:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002367 """Represents a parameter in a function signature.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002368
2369 Has the following public attributes:
2370
2371 * name : str
2372 The name of the parameter as a string.
2373 * default : object
2374 The default value for the parameter if specified. If the
Yury Selivanov8757ead2014-01-28 16:39:25 -05002375 parameter has no default value, this attribute is set to
2376 `Parameter.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002377 * annotation
2378 The annotation for the parameter if specified. If the
Yury Selivanov8757ead2014-01-28 16:39:25 -05002379 parameter has no annotation, this attribute is set to
2380 `Parameter.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002381 * kind : str
2382 Describes how argument values are bound to the parameter.
2383 Possible values: `Parameter.POSITIONAL_ONLY`,
2384 `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
2385 `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002386 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002387
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002388 __slots__ = ('_name', '_kind', '_default', '_annotation')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002389
2390 POSITIONAL_ONLY = _POSITIONAL_ONLY
2391 POSITIONAL_OR_KEYWORD = _POSITIONAL_OR_KEYWORD
2392 VAR_POSITIONAL = _VAR_POSITIONAL
2393 KEYWORD_ONLY = _KEYWORD_ONLY
2394 VAR_KEYWORD = _VAR_KEYWORD
2395
2396 empty = _empty
2397
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002398 def __init__(self, name, kind, *, default=_empty, annotation=_empty):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002399
2400 if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
2401 _VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
2402 raise ValueError("invalid value for 'Parameter.kind' attribute")
2403 self._kind = kind
2404
2405 if default is not _empty:
2406 if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
2407 msg = '{} parameters cannot have default values'.format(kind)
2408 raise ValueError(msg)
2409 self._default = default
2410 self._annotation = annotation
2411
Yury Selivanov2393dca2014-01-27 15:07:58 -05002412 if name is _empty:
2413 raise ValueError('name is a required attribute for Parameter')
2414
2415 if not isinstance(name, str):
2416 raise TypeError("name must be a str, not a {!r}".format(name))
2417
2418 if not name.isidentifier():
2419 raise ValueError('{!r} is not a valid parameter name'.format(name))
2420
2421 self._name = name
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002422
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002423 def __reduce__(self):
2424 return (type(self),
2425 (self._name, self._kind),
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002426 {'_default': self._default,
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002427 '_annotation': self._annotation})
2428
2429 def __setstate__(self, state):
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002430 self._default = state['_default']
2431 self._annotation = state['_annotation']
2432
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002433 @property
2434 def name(self):
2435 return self._name
2436
2437 @property
2438 def default(self):
2439 return self._default
2440
2441 @property
2442 def annotation(self):
2443 return self._annotation
2444
2445 @property
2446 def kind(self):
2447 return self._kind
2448
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002449 def replace(self, *, name=_void, kind=_void,
2450 annotation=_void, default=_void):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002451 """Creates a customized copy of the Parameter."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002452
2453 if name is _void:
2454 name = self._name
2455
2456 if kind is _void:
2457 kind = self._kind
2458
2459 if annotation is _void:
2460 annotation = self._annotation
2461
2462 if default is _void:
2463 default = self._default
2464
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002465 return type(self)(name, kind, default=default, annotation=annotation)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002466
2467 def __str__(self):
2468 kind = self.kind
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002469 formatted = self._name
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002470
2471 # Add annotation and default value
2472 if self._annotation is not _empty:
2473 formatted = '{}:{}'.format(formatted,
2474 formatannotation(self._annotation))
2475
2476 if self._default is not _empty:
2477 formatted = '{}={}'.format(formatted, repr(self._default))
2478
2479 if kind == _VAR_POSITIONAL:
2480 formatted = '*' + formatted
2481 elif kind == _VAR_KEYWORD:
2482 formatted = '**' + formatted
2483
2484 return formatted
2485
2486 def __repr__(self):
Yury Selivanovf229bc52015-05-15 12:53:56 -04002487 return '<{} "{}">'.format(self.__class__.__name__, self)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002488
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002489 def __hash__(self):
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002490 return hash((self.name, self.kind, self.annotation, self.default))
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002491
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002492 def __eq__(self, other):
Serhiy Storchaka2489bd52015-07-18 23:20:50 +03002493 if self is other:
2494 return True
Serhiy Storchaka3018cc42015-07-18 23:19:05 +03002495 if not isinstance(other, Parameter):
2496 return NotImplemented
2497 return (self._name == other._name and
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002498 self._kind == other._kind and
2499 self._default == other._default and
2500 self._annotation == other._annotation)
2501
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002502
2503class BoundArguments:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002504 """Result of `Signature.bind` call. Holds the mapping of arguments
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002505 to the function's parameters.
2506
2507 Has the following public attributes:
2508
2509 * arguments : OrderedDict
2510 An ordered mutable mapping of parameters' names to arguments' values.
2511 Does not contain arguments' default values.
2512 * signature : Signature
2513 The Signature object that created this instance.
2514 * args : tuple
2515 Tuple of positional arguments values.
2516 * kwargs : dict
2517 Dict of keyword arguments values.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002518 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002519
Yury Selivanov6abe0322015-05-13 17:18:41 -04002520 __slots__ = ('arguments', '_signature', '__weakref__')
2521
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002522 def __init__(self, signature, arguments):
2523 self.arguments = arguments
2524 self._signature = signature
2525
2526 @property
2527 def signature(self):
2528 return self._signature
2529
2530 @property
2531 def args(self):
2532 args = []
2533 for param_name, param in self._signature.parameters.items():
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002534 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002535 break
2536
2537 try:
2538 arg = self.arguments[param_name]
2539 except KeyError:
2540 # We're done here. Other arguments
2541 # will be mapped in 'BoundArguments.kwargs'
2542 break
2543 else:
2544 if param.kind == _VAR_POSITIONAL:
2545 # *args
2546 args.extend(arg)
2547 else:
2548 # plain argument
2549 args.append(arg)
2550
2551 return tuple(args)
2552
2553 @property
2554 def kwargs(self):
2555 kwargs = {}
2556 kwargs_started = False
2557 for param_name, param in self._signature.parameters.items():
2558 if not kwargs_started:
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002559 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002560 kwargs_started = True
2561 else:
2562 if param_name not in self.arguments:
2563 kwargs_started = True
2564 continue
2565
2566 if not kwargs_started:
2567 continue
2568
2569 try:
2570 arg = self.arguments[param_name]
2571 except KeyError:
2572 pass
2573 else:
2574 if param.kind == _VAR_KEYWORD:
2575 # **kwargs
2576 kwargs.update(arg)
2577 else:
2578 # plain keyword argument
2579 kwargs[param_name] = arg
2580
2581 return kwargs
2582
Yury Selivanovb907a512015-05-16 13:45:09 -04002583 def apply_defaults(self):
2584 """Set default values for missing arguments.
2585
2586 For variable-positional arguments (*args) the default is an
2587 empty tuple.
2588
2589 For variable-keyword arguments (**kwargs) the default is an
2590 empty dict.
2591 """
2592 arguments = self.arguments
Yury Selivanovb907a512015-05-16 13:45:09 -04002593 new_arguments = []
2594 for name, param in self._signature.parameters.items():
2595 try:
2596 new_arguments.append((name, arguments[name]))
2597 except KeyError:
2598 if param.default is not _empty:
2599 val = param.default
2600 elif param.kind is _VAR_POSITIONAL:
2601 val = ()
2602 elif param.kind is _VAR_KEYWORD:
2603 val = {}
2604 else:
2605 # This BoundArguments was likely produced by
2606 # Signature.bind_partial().
2607 continue
2608 new_arguments.append((name, val))
2609 self.arguments = OrderedDict(new_arguments)
2610
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002611 def __eq__(self, other):
Serhiy Storchaka2489bd52015-07-18 23:20:50 +03002612 if self is other:
2613 return True
Serhiy Storchaka3018cc42015-07-18 23:19:05 +03002614 if not isinstance(other, BoundArguments):
2615 return NotImplemented
2616 return (self.signature == other.signature and
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002617 self.arguments == other.arguments)
2618
Yury Selivanov6abe0322015-05-13 17:18:41 -04002619 def __setstate__(self, state):
2620 self._signature = state['_signature']
2621 self.arguments = state['arguments']
2622
2623 def __getstate__(self):
2624 return {'_signature': self._signature, 'arguments': self.arguments}
2625
Yury Selivanov3f6538f2015-05-14 18:47:17 -04002626 def __repr__(self):
2627 args = []
2628 for arg, value in self.arguments.items():
2629 args.append('{}={!r}'.format(arg, value))
Yury Selivanovf229bc52015-05-15 12:53:56 -04002630 return '<{} ({})>'.format(self.__class__.__name__, ', '.join(args))
Yury Selivanov3f6538f2015-05-14 18:47:17 -04002631
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002632
2633class Signature:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002634 """A Signature object represents the overall signature of a function.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002635 It stores a Parameter object for each parameter accepted by the
2636 function, as well as information specific to the function itself.
2637
2638 A Signature object has the following public attributes and methods:
2639
2640 * parameters : OrderedDict
2641 An ordered mapping of parameters' names to the corresponding
2642 Parameter objects (keyword-only arguments are in the same order
2643 as listed in `code.co_varnames`).
2644 * return_annotation : object
2645 The annotation for the return type of the function if specified.
2646 If the function has no annotation for its return type, this
Yury Selivanov8757ead2014-01-28 16:39:25 -05002647 attribute is set to `Signature.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002648 * bind(*args, **kwargs) -> BoundArguments
2649 Creates a mapping from positional and keyword arguments to
2650 parameters.
2651 * bind_partial(*args, **kwargs) -> BoundArguments
2652 Creates a partial mapping from positional and keyword arguments
2653 to parameters (simulating 'functools.partial' behavior.)
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002654 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002655
2656 __slots__ = ('_return_annotation', '_parameters')
2657
2658 _parameter_cls = Parameter
2659 _bound_arguments_cls = BoundArguments
2660
2661 empty = _empty
2662
2663 def __init__(self, parameters=None, *, return_annotation=_empty,
2664 __validate_parameters__=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002665 """Constructs Signature from the given list of Parameter
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002666 objects and 'return_annotation'. All arguments are optional.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002667 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002668
2669 if parameters is None:
2670 params = OrderedDict()
2671 else:
2672 if __validate_parameters__:
2673 params = OrderedDict()
2674 top_kind = _POSITIONAL_ONLY
Yury Selivanov07a9e452014-01-29 10:58:16 -05002675 kind_defaults = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002676
2677 for idx, param in enumerate(parameters):
2678 kind = param.kind
Yury Selivanov2393dca2014-01-27 15:07:58 -05002679 name = param.name
2680
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002681 if kind < top_kind:
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002682 msg = 'wrong parameter order: {!r} before {!r}'
Yury Selivanov2393dca2014-01-27 15:07:58 -05002683 msg = msg.format(top_kind, kind)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002684 raise ValueError(msg)
Yury Selivanov07a9e452014-01-29 10:58:16 -05002685 elif kind > top_kind:
2686 kind_defaults = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002687 top_kind = kind
2688
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002689 if kind in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD):
Yury Selivanov07a9e452014-01-29 10:58:16 -05002690 if param.default is _empty:
2691 if kind_defaults:
2692 # No default for this parameter, but the
2693 # previous parameter of the same kind had
2694 # a default
2695 msg = 'non-default argument follows default ' \
2696 'argument'
2697 raise ValueError(msg)
2698 else:
2699 # There is a default for this parameter.
2700 kind_defaults = True
2701
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002702 if name in params:
2703 msg = 'duplicate parameter name: {!r}'.format(name)
2704 raise ValueError(msg)
Yury Selivanov2393dca2014-01-27 15:07:58 -05002705
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002706 params[name] = param
2707 else:
2708 params = OrderedDict(((param.name, param)
2709 for param in parameters))
2710
2711 self._parameters = types.MappingProxyType(params)
2712 self._return_annotation = return_annotation
2713
2714 @classmethod
2715 def from_function(cls, func):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002716 """Constructs Signature for the given python function."""
Yury Selivanov57c74fc2015-05-20 23:07:02 -04002717
2718 warnings.warn("inspect.Signature.from_function() is deprecated, "
Berker Peksagb5601582015-05-21 23:40:54 +03002719 "use Signature.from_callable()",
2720 DeprecationWarning, stacklevel=2)
Yury Selivanovcf45f022015-05-20 14:38:50 -04002721 return _signature_from_function(cls, func)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002722
Larry Hastings44e2eaa2013-11-23 15:37:55 -08002723 @classmethod
2724 def from_builtin(cls, func):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002725 """Constructs Signature for the given builtin function."""
Yury Selivanov57c74fc2015-05-20 23:07:02 -04002726
2727 warnings.warn("inspect.Signature.from_builtin() is deprecated, "
Berker Peksagb5601582015-05-21 23:40:54 +03002728 "use Signature.from_callable()",
2729 DeprecationWarning, stacklevel=2)
Yury Selivanov57d240e2014-02-19 16:27:23 -05002730 return _signature_from_builtin(cls, func)
Larry Hastings44e2eaa2013-11-23 15:37:55 -08002731
Yury Selivanovda396452014-03-27 12:09:24 -04002732 @classmethod
Yury Selivanovbcd4fc12015-05-20 14:30:08 -04002733 def from_callable(cls, obj, *, follow_wrapped=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002734 """Constructs Signature for the given callable object."""
Yury Selivanovbcd4fc12015-05-20 14:30:08 -04002735 return _signature_from_callable(obj, sigcls=cls,
2736 follow_wrapper_chains=follow_wrapped)
Yury Selivanovda396452014-03-27 12:09:24 -04002737
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002738 @property
2739 def parameters(self):
2740 return self._parameters
2741
2742 @property
2743 def return_annotation(self):
2744 return self._return_annotation
2745
2746 def replace(self, *, parameters=_void, return_annotation=_void):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002747 """Creates a customized copy of the Signature.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002748 Pass 'parameters' and/or 'return_annotation' arguments
2749 to override them in the new copy.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002750 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002751
2752 if parameters is _void:
2753 parameters = self.parameters.values()
2754
2755 if return_annotation is _void:
2756 return_annotation = self._return_annotation
2757
2758 return type(self)(parameters,
2759 return_annotation=return_annotation)
2760
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002761 def _hash_basis(self):
2762 params = tuple(param for param in self.parameters.values()
2763 if param.kind != _KEYWORD_ONLY)
2764
2765 kwo_params = {param.name: param for param in self.parameters.values()
2766 if param.kind == _KEYWORD_ONLY}
2767
2768 return params, kwo_params, self.return_annotation
2769
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002770 def __hash__(self):
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002771 params, kwo_params, return_annotation = self._hash_basis()
2772 kwo_params = frozenset(kwo_params.values())
2773 return hash((params, kwo_params, return_annotation))
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002774
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002775 def __eq__(self, other):
Serhiy Storchaka2489bd52015-07-18 23:20:50 +03002776 if self is other:
2777 return True
Serhiy Storchaka3018cc42015-07-18 23:19:05 +03002778 if not isinstance(other, Signature):
2779 return NotImplemented
Serhiy Storchaka2489bd52015-07-18 23:20:50 +03002780 return self._hash_basis() == other._hash_basis()
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002781
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002782 def _bind(self, args, kwargs, *, partial=False):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002783 """Private method. Don't use directly."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002784
2785 arguments = OrderedDict()
2786
2787 parameters = iter(self.parameters.values())
2788 parameters_ex = ()
2789 arg_vals = iter(args)
2790
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002791 while True:
2792 # Let's iterate through the positional arguments and corresponding
2793 # parameters
2794 try:
2795 arg_val = next(arg_vals)
2796 except StopIteration:
2797 # No more positional arguments
2798 try:
2799 param = next(parameters)
2800 except StopIteration:
2801 # No more parameters. That's it. Just need to check that
2802 # we have no `kwargs` after this while loop
2803 break
2804 else:
2805 if param.kind == _VAR_POSITIONAL:
2806 # That's OK, just empty *args. Let's start parsing
2807 # kwargs
2808 break
2809 elif param.name in kwargs:
2810 if param.kind == _POSITIONAL_ONLY:
2811 msg = '{arg!r} parameter is positional only, ' \
2812 'but was passed as a keyword'
2813 msg = msg.format(arg=param.name)
2814 raise TypeError(msg) from None
2815 parameters_ex = (param,)
2816 break
2817 elif (param.kind == _VAR_KEYWORD or
2818 param.default is not _empty):
2819 # That's fine too - we have a default value for this
2820 # parameter. So, lets start parsing `kwargs`, starting
2821 # with the current parameter
2822 parameters_ex = (param,)
2823 break
2824 else:
Yury Selivanov38b0d5a2014-01-28 17:27:39 -05002825 # No default, not VAR_KEYWORD, not VAR_POSITIONAL,
2826 # not in `kwargs`
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002827 if partial:
2828 parameters_ex = (param,)
2829 break
2830 else:
Yury Selivanov86872752015-05-19 00:27:49 -04002831 msg = 'missing a required argument: {arg!r}'
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002832 msg = msg.format(arg=param.name)
2833 raise TypeError(msg) from None
2834 else:
2835 # We have a positional argument to process
2836 try:
2837 param = next(parameters)
2838 except StopIteration:
2839 raise TypeError('too many positional arguments') from None
2840 else:
2841 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
2842 # Looks like we have no parameter for this positional
2843 # argument
Yury Selivanov86872752015-05-19 00:27:49 -04002844 raise TypeError(
2845 'too many positional arguments') from None
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002846
2847 if param.kind == _VAR_POSITIONAL:
2848 # We have an '*args'-like argument, let's fill it with
2849 # all positional arguments we have left and move on to
2850 # the next phase
2851 values = [arg_val]
2852 values.extend(arg_vals)
2853 arguments[param.name] = tuple(values)
2854 break
2855
2856 if param.name in kwargs:
Yury Selivanov86872752015-05-19 00:27:49 -04002857 raise TypeError(
2858 'multiple values for argument {arg!r}'.format(
2859 arg=param.name)) from None
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002860
2861 arguments[param.name] = arg_val
2862
2863 # Now, we iterate through the remaining parameters to process
2864 # keyword arguments
2865 kwargs_param = None
2866 for param in itertools.chain(parameters_ex, parameters):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002867 if param.kind == _VAR_KEYWORD:
2868 # Memorize that we have a '**kwargs'-like parameter
2869 kwargs_param = param
2870 continue
2871
Yury Selivanov38b0d5a2014-01-28 17:27:39 -05002872 if param.kind == _VAR_POSITIONAL:
2873 # Named arguments don't refer to '*args'-like parameters.
2874 # We only arrive here if the positional arguments ended
2875 # before reaching the last parameter before *args.
2876 continue
2877
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002878 param_name = param.name
2879 try:
2880 arg_val = kwargs.pop(param_name)
2881 except KeyError:
2882 # We have no value for this parameter. It's fine though,
2883 # if it has a default value, or it is an '*args'-like
2884 # parameter, left alone by the processing of positional
2885 # arguments.
2886 if (not partial and param.kind != _VAR_POSITIONAL and
2887 param.default is _empty):
Yury Selivanov86872752015-05-19 00:27:49 -04002888 raise TypeError('missing a required argument: {arg!r}'. \
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002889 format(arg=param_name)) from None
2890
2891 else:
Yury Selivanov9b9ac952014-01-28 20:54:28 -05002892 if param.kind == _POSITIONAL_ONLY:
2893 # This should never happen in case of a properly built
2894 # Signature object (but let's have this check here
2895 # to ensure correct behaviour just in case)
2896 raise TypeError('{arg!r} parameter is positional only, '
2897 'but was passed as a keyword'. \
2898 format(arg=param.name))
2899
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002900 arguments[param_name] = arg_val
2901
2902 if kwargs:
2903 if kwargs_param is not None:
2904 # Process our '**kwargs'-like parameter
2905 arguments[kwargs_param.name] = kwargs
2906 else:
Yury Selivanov86872752015-05-19 00:27:49 -04002907 raise TypeError(
2908 'got an unexpected keyword argument {arg!r}'.format(
2909 arg=next(iter(kwargs))))
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002910
2911 return self._bound_arguments_cls(self, arguments)
2912
Yury Selivanovc45873e2014-01-29 12:10:27 -05002913 def bind(*args, **kwargs):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002914 """Get a BoundArguments object, that maps the passed `args`
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002915 and `kwargs` to the function's signature. Raises `TypeError`
2916 if the passed arguments can not be bound.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002917 """
Yury Selivanovc45873e2014-01-29 12:10:27 -05002918 return args[0]._bind(args[1:], kwargs)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002919
Yury Selivanovc45873e2014-01-29 12:10:27 -05002920 def bind_partial(*args, **kwargs):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002921 """Get a BoundArguments object, that partially maps the
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002922 passed `args` and `kwargs` to the function's signature.
2923 Raises `TypeError` if the passed arguments can not be bound.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002924 """
Yury Selivanovc45873e2014-01-29 12:10:27 -05002925 return args[0]._bind(args[1:], kwargs, partial=True)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002926
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002927 def __reduce__(self):
2928 return (type(self),
2929 (tuple(self._parameters.values()),),
2930 {'_return_annotation': self._return_annotation})
2931
2932 def __setstate__(self, state):
2933 self._return_annotation = state['_return_annotation']
2934
Yury Selivanov374375d2014-03-27 12:41:53 -04002935 def __repr__(self):
Yury Selivanovf229bc52015-05-15 12:53:56 -04002936 return '<{} {}>'.format(self.__class__.__name__, self)
Yury Selivanov374375d2014-03-27 12:41:53 -04002937
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002938 def __str__(self):
2939 result = []
Yury Selivanov2393dca2014-01-27 15:07:58 -05002940 render_pos_only_separator = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002941 render_kw_only_separator = True
Yury Selivanov2393dca2014-01-27 15:07:58 -05002942 for param in self.parameters.values():
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002943 formatted = str(param)
2944
2945 kind = param.kind
Yury Selivanov2393dca2014-01-27 15:07:58 -05002946
2947 if kind == _POSITIONAL_ONLY:
2948 render_pos_only_separator = True
2949 elif render_pos_only_separator:
2950 # It's not a positional-only parameter, and the flag
2951 # is set to 'True' (there were pos-only params before.)
2952 result.append('/')
2953 render_pos_only_separator = False
2954
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002955 if kind == _VAR_POSITIONAL:
2956 # OK, we have an '*args'-like parameter, so we won't need
2957 # a '*' to separate keyword-only arguments
2958 render_kw_only_separator = False
2959 elif kind == _KEYWORD_ONLY and render_kw_only_separator:
2960 # We have a keyword-only parameter to render and we haven't
2961 # rendered an '*args'-like parameter before, so add a '*'
2962 # separator to the parameters list ("foo(arg1, *, arg2)" case)
2963 result.append('*')
2964 # This condition should be only triggered once, so
2965 # reset the flag
2966 render_kw_only_separator = False
2967
2968 result.append(formatted)
2969
Yury Selivanov2393dca2014-01-27 15:07:58 -05002970 if render_pos_only_separator:
2971 # There were only positional-only parameters, hence the
2972 # flag was not reset to 'False'
2973 result.append('/')
2974
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002975 rendered = '({})'.format(', '.join(result))
2976
2977 if self.return_annotation is not _empty:
2978 anno = formatannotation(self.return_annotation)
2979 rendered += ' -> {}'.format(anno)
2980
2981 return rendered
Nick Coghlanf94a16b2013-09-22 22:46:49 +10002982
Yury Selivanovda396452014-03-27 12:09:24 -04002983
Yury Selivanovbcd4fc12015-05-20 14:30:08 -04002984def signature(obj, *, follow_wrapped=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002985 """Get a signature object for the passed callable."""
Yury Selivanovbcd4fc12015-05-20 14:30:08 -04002986 return Signature.from_callable(obj, follow_wrapped=follow_wrapped)
Yury Selivanovda396452014-03-27 12:09:24 -04002987
2988
Nick Coghlanf94a16b2013-09-22 22:46:49 +10002989def _main():
2990 """ Logic for inspecting an object given at command line """
2991 import argparse
2992 import importlib
2993
2994 parser = argparse.ArgumentParser()
2995 parser.add_argument(
2996 'object',
2997 help="The object to be analysed. "
2998 "It supports the 'module:qualname' syntax")
2999 parser.add_argument(
3000 '-d', '--details', action='store_true',
3001 help='Display info about the module rather than its source code')
3002
3003 args = parser.parse_args()
3004
3005 target = args.object
3006 mod_name, has_attrs, attrs = target.partition(":")
3007 try:
3008 obj = module = importlib.import_module(mod_name)
3009 except Exception as exc:
3010 msg = "Failed to import {} ({}: {})".format(mod_name,
3011 type(exc).__name__,
3012 exc)
3013 print(msg, file=sys.stderr)
3014 exit(2)
3015
3016 if has_attrs:
3017 parts = attrs.split(".")
3018 obj = module
3019 for part in parts:
3020 obj = getattr(obj, part)
3021
3022 if module.__name__ in sys.builtin_module_names:
3023 print("Can't get info for builtin modules.", file=sys.stderr)
3024 exit(1)
3025
3026 if args.details:
3027 print('Target: {}'.format(target))
3028 print('Origin: {}'.format(getsourcefile(module)))
3029 print('Cached: {}'.format(module.__cached__))
3030 if obj is module:
3031 print('Loader: {}'.format(repr(module.__loader__)))
3032 if hasattr(module, '__path__'):
3033 print('Submodule search path: {}'.format(module.__path__))
3034 else:
3035 try:
3036 __, lineno = findsource(obj)
3037 except Exception:
3038 pass
3039 else:
3040 print('Line: {}'.format(lineno))
3041
3042 print('\n')
3043 else:
3044 print(getsource(obj))
3045
3046
3047if __name__ == "__main__":
3048 _main()