blob: fdb5e2a45a2e06310a2025681e6140a36c76b3c3 [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
Guido van Rossum2e65f892007-02-28 22:03:49 +000020 getfullargspec() - same, with support for Python-3000 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
Yury Selivanov21e83a52014-03-27 11:23:13 -040035import enum
Brett Cannoncb66eb02012-05-11 12:58:42 -040036import importlib.machinery
37import itertools
Christian Heimes7131fd92008-02-19 14:21:46 +000038import linecache
Brett Cannoncb66eb02012-05-11 12:58:42 -040039import os
40import re
41import sys
42import tokenize
Larry Hastings2623c8c2014-02-08 22:15:29 -080043import token
Brett Cannoncb66eb02012-05-11 12:58:42 -040044import types
Brett Cannon2b88fcf2012-06-02 22:28:42 -040045import warnings
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070046import functools
Nick Coghlan2f92e542012-06-23 19:39:55 +100047import builtins
Raymond Hettingera1a992c2005-03-11 06:46:45 +000048from operator import attrgetter
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070049from collections import namedtuple, OrderedDict
Nick Coghlan09c81232010-08-17 10:18:16 +000050
51# Create constants for the compiler flags in Include/code.h
52# We try to get them from dis to avoid duplication, but fall
Ezio Melotti30b9d5d2013-08-17 15:50:46 +030053# back to hardcoding so the dependency is optional
Nick Coghlan09c81232010-08-17 10:18:16 +000054try:
55 from dis import COMPILER_FLAG_NAMES as _flag_names
Brett Cannoncd171c82013-07-04 17:43:24 -040056except ImportError:
Nick Coghlan09c81232010-08-17 10:18:16 +000057 CO_OPTIMIZED, CO_NEWLOCALS = 0x1, 0x2
58 CO_VARARGS, CO_VARKEYWORDS = 0x4, 0x8
59 CO_NESTED, CO_GENERATOR, CO_NOFREE = 0x10, 0x20, 0x40
60else:
61 mod_dict = globals()
62 for k, v in _flag_names.items():
63 mod_dict["CO_" + v] = k
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000064
Christian Heimesbe5b30b2008-03-03 19:18:51 +000065# See Include/object.h
66TPFLAGS_IS_ABSTRACT = 1 << 20
67
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000068# ----------------------------------------------------------- type-checking
69def ismodule(object):
70 """Return true if the object is a module.
71
72 Module objects provide these attributes:
Barry Warsaw28a691b2010-04-17 00:19:56 +000073 __cached__ pathname to byte compiled file
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000074 __doc__ documentation string
75 __file__ filename (missing for built-in modules)"""
Tim Peters28bc59f2001-09-16 08:40:16 +000076 return isinstance(object, types.ModuleType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000077
78def isclass(object):
79 """Return true if the object is a class.
80
81 Class objects provide these attributes:
82 __doc__ documentation string
83 __module__ name of module in which this class was defined"""
Benjamin Petersonc4656002009-01-17 22:41:18 +000084 return isinstance(object, type)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000085
86def ismethod(object):
87 """Return true if the object is an instance method.
88
89 Instance method objects provide these attributes:
90 __doc__ documentation string
91 __name__ name with which this method was defined
Christian Heimesff737952007-11-27 10:40:20 +000092 __func__ function object containing implementation of method
93 __self__ instance to which this method is bound"""
Tim Peters28bc59f2001-09-16 08:40:16 +000094 return isinstance(object, types.MethodType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000095
Tim Peters536d2262001-09-20 05:13:38 +000096def ismethoddescriptor(object):
Tim Petersf1d90b92001-09-20 05:47:55 +000097 """Return true if the object is a method descriptor.
98
99 But not if ismethod() or isclass() or isfunction() are true.
Tim Peters536d2262001-09-20 05:13:38 +0000100
101 This is new in Python 2.2, and, for example, is true of int.__add__.
102 An object passing this test has a __get__ attribute but not a __set__
103 attribute, but beyond that the set of attributes varies. __name__ is
104 usually sensible, and __doc__ often is.
105
Tim Petersf1d90b92001-09-20 05:47:55 +0000106 Methods implemented via descriptors that also pass one of the other
107 tests return false from the ismethoddescriptor() test, simply because
108 the other tests promise more -- you can, e.g., count on having the
Christian Heimesff737952007-11-27 10:40:20 +0000109 __func__ attribute (etc) when an object passes ismethod()."""
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100110 if isclass(object) or ismethod(object) or isfunction(object):
111 # mutual exclusion
112 return False
113 tp = type(object)
114 return hasattr(tp, "__get__") and not hasattr(tp, "__set__")
Tim Peters536d2262001-09-20 05:13:38 +0000115
Martin v. Löwise59e2ba2003-05-03 09:09:02 +0000116def isdatadescriptor(object):
117 """Return true if the object is a data descriptor.
118
119 Data descriptors have both a __get__ and a __set__ attribute. Examples are
120 properties (defined in Python) and getsets and members (defined in C).
121 Typically, data descriptors will also have __name__ and __doc__ attributes
122 (properties, getsets, and members have both of these attributes), but this
123 is not guaranteed."""
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100124 if isclass(object) or ismethod(object) or isfunction(object):
125 # mutual exclusion
126 return False
127 tp = type(object)
128 return hasattr(tp, "__set__") and hasattr(tp, "__get__")
Martin v. Löwise59e2ba2003-05-03 09:09:02 +0000129
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000130if hasattr(types, 'MemberDescriptorType'):
131 # CPython and equivalent
132 def ismemberdescriptor(object):
133 """Return true if the object is a member descriptor.
134
135 Member descriptors are specialized descriptors defined in extension
136 modules."""
137 return isinstance(object, types.MemberDescriptorType)
138else:
139 # Other implementations
140 def ismemberdescriptor(object):
141 """Return true if the object is a member descriptor.
142
143 Member descriptors are specialized descriptors defined in extension
144 modules."""
145 return False
146
147if hasattr(types, 'GetSetDescriptorType'):
148 # CPython and equivalent
149 def isgetsetdescriptor(object):
150 """Return true if the object is a getset descriptor.
151
152 getset descriptors are specialized descriptors defined in extension
153 modules."""
154 return isinstance(object, types.GetSetDescriptorType)
155else:
156 # Other implementations
157 def isgetsetdescriptor(object):
158 """Return true if the object is a getset descriptor.
159
160 getset descriptors are specialized descriptors defined in extension
161 modules."""
162 return False
163
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000164def isfunction(object):
165 """Return true if the object is a user-defined function.
166
167 Function objects provide these attributes:
168 __doc__ documentation string
169 __name__ name with which this function was defined
Neal Norwitz221085d2007-02-25 20:55:47 +0000170 __code__ code object containing compiled function bytecode
171 __defaults__ tuple of any default values for arguments
172 __globals__ global namespace in which this function was defined
173 __annotations__ dict of parameter annotations
174 __kwdefaults__ dict of keyword only parameters with defaults"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000175 return isinstance(object, types.FunctionType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000176
Christian Heimes7131fd92008-02-19 14:21:46 +0000177def isgeneratorfunction(object):
178 """Return true if the object is a user-defined generator function.
179
180 Generator function objects provides same attributes as functions.
181
Alexander Belopolsky977a6842010-08-16 20:17:07 +0000182 See help(isfunction) for attributes listing."""
Georg Brandlb1441c72009-01-03 22:33:39 +0000183 return bool((isfunction(object) or ismethod(object)) and
184 object.__code__.co_flags & CO_GENERATOR)
Christian Heimes7131fd92008-02-19 14:21:46 +0000185
186def isgenerator(object):
187 """Return true if the object is a generator.
188
189 Generator objects provide these attributes:
Ezio Melotti30b9d5d2013-08-17 15:50:46 +0300190 __iter__ defined to support iteration over container
Christian Heimes7131fd92008-02-19 14:21:46 +0000191 close raises a new GeneratorExit exception inside the
192 generator to terminate the iteration
193 gi_code code object
194 gi_frame frame object or possibly None once the generator has
195 been exhausted
196 gi_running set to 1 when generator is executing, 0 otherwise
197 next return the next item from the container
198 send resumes the generator and "sends" a value that becomes
199 the result of the current yield-expression
200 throw used to raise an exception inside the generator"""
201 return isinstance(object, types.GeneratorType)
202
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000203def istraceback(object):
204 """Return true if the object is a traceback.
205
206 Traceback objects provide these attributes:
207 tb_frame frame object at this level
208 tb_lasti index of last attempted instruction in bytecode
209 tb_lineno current line number in Python source code
210 tb_next next inner traceback object (called by this level)"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000211 return isinstance(object, types.TracebackType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000212
213def isframe(object):
214 """Return true if the object is a frame object.
215
216 Frame objects provide these attributes:
217 f_back next outer frame object (this frame's caller)
218 f_builtins built-in namespace seen by this frame
219 f_code code object being executed in this frame
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000220 f_globals global namespace seen by this frame
221 f_lasti index of last attempted instruction in bytecode
222 f_lineno current line number in Python source code
223 f_locals local namespace seen by this frame
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000224 f_trace tracing function for this frame, or None"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000225 return isinstance(object, types.FrameType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000226
227def iscode(object):
228 """Return true if the object is a code object.
229
230 Code objects provide these attributes:
231 co_argcount number of arguments (not including * or ** args)
232 co_code string of raw compiled bytecode
233 co_consts tuple of constants used in the bytecode
234 co_filename name of file in which this code object was created
235 co_firstlineno number of first line in Python source code
236 co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
237 co_lnotab encoded mapping of line numbers to bytecode indices
238 co_name name with which this code object was defined
239 co_names tuple of names of local variables
240 co_nlocals number of local variables
241 co_stacksize virtual machine stack space required
242 co_varnames tuple of names of arguments and local variables"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000243 return isinstance(object, types.CodeType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000244
245def isbuiltin(object):
246 """Return true if the object is a built-in function or method.
247
248 Built-in functions and methods provide these attributes:
249 __doc__ documentation string
250 __name__ original name of this function or method
251 __self__ instance to which a method is bound, or None"""
Tim Peters28bc59f2001-09-16 08:40:16 +0000252 return isinstance(object, types.BuiltinFunctionType)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000253
254def isroutine(object):
255 """Return true if the object is any kind of function or method."""
Tim Peters536d2262001-09-20 05:13:38 +0000256 return (isbuiltin(object)
257 or isfunction(object)
258 or ismethod(object)
259 or ismethoddescriptor(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000260
Christian Heimesbe5b30b2008-03-03 19:18:51 +0000261def isabstract(object):
262 """Return true if the object is an abstract base class (ABC)."""
Benjamin Petersona0dfa822009-11-13 02:25:08 +0000263 return bool(isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT)
Christian Heimesbe5b30b2008-03-03 19:18:51 +0000264
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000265def getmembers(object, predicate=None):
266 """Return all members of an object as (name, value) pairs sorted by name.
267 Optionally, only return members that satisfy a given predicate."""
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100268 if isclass(object):
269 mro = (object,) + getmro(object)
270 else:
271 mro = ()
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000272 results = []
Ethan Furmane03ea372013-09-25 07:14:41 -0700273 processed = set()
274 names = dir(object)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700275 # :dd any DynamicClassAttributes to the list of names if object is a class;
Ethan Furmane03ea372013-09-25 07:14:41 -0700276 # this may result in duplicate entries if, for example, a virtual
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700277 # attribute with the same name as a DynamicClassAttribute exists
Ethan Furmane03ea372013-09-25 07:14:41 -0700278 try:
279 for base in object.__bases__:
280 for k, v in base.__dict__.items():
281 if isinstance(v, types.DynamicClassAttribute):
282 names.append(k)
283 except AttributeError:
284 pass
285 for key in names:
Ethan Furman63c141c2013-10-18 00:27:39 -0700286 # First try to get the value via getattr. Some descriptors don't
287 # like calling their __get__ (see bug #1785), so fall back to
288 # looking in the __dict__.
289 try:
290 value = getattr(object, key)
291 # handle the duplicate key
292 if key in processed:
293 raise AttributeError
294 except AttributeError:
295 for base in mro:
296 if key in base.__dict__:
297 value = base.__dict__[key]
298 break
299 else:
300 # could be a (currently) missing slot member, or a buggy
301 # __dir__; discard and move on
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100302 continue
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000303 if not predicate or predicate(value):
304 results.append((key, value))
Ethan Furmane03ea372013-09-25 07:14:41 -0700305 processed.add(key)
306 results.sort(key=lambda pair: pair[0])
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000307 return results
308
Christian Heimes25bb7832008-01-11 16:17:00 +0000309Attribute = namedtuple('Attribute', 'name kind defining_class object')
310
Tim Peters13b49d32001-09-23 02:00:29 +0000311def classify_class_attrs(cls):
312 """Return list of attribute-descriptor tuples.
313
314 For each name in dir(cls), the return list contains a 4-tuple
315 with these elements:
316
317 0. The name (a string).
318
319 1. The kind of attribute this is, one of these strings:
320 'class method' created via classmethod()
321 'static method' created via staticmethod()
322 'property' created via property()
Ethan Furmane03ea372013-09-25 07:14:41 -0700323 'method' any other flavor of method or descriptor
Tim Peters13b49d32001-09-23 02:00:29 +0000324 'data' not a method
325
326 2. The class which defined this attribute (a class).
327
Ethan Furmane03ea372013-09-25 07:14:41 -0700328 3. The object as obtained by calling getattr; if this fails, or if the
329 resulting object does not live anywhere in the class' mro (including
330 metaclasses) then the object is looked up in the defining class's
331 dict (found by walking the mro).
Ethan Furman668dede2013-09-14 18:53:26 -0700332
333 If one of the items in dir(cls) is stored in the metaclass it will now
334 be discovered and not have None be listed as the class in which it was
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700335 defined. Any items whose home class cannot be discovered are skipped.
Tim Peters13b49d32001-09-23 02:00:29 +0000336 """
337
338 mro = getmro(cls)
Ethan Furman668dede2013-09-14 18:53:26 -0700339 metamro = getmro(type(cls)) # for attributes stored in the metaclass
Ethan Furmane03ea372013-09-25 07:14:41 -0700340 metamro = tuple([cls for cls in metamro if cls not in (type, object)])
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700341 class_bases = (cls,) + mro
342 all_bases = class_bases + metamro
Tim Peters13b49d32001-09-23 02:00:29 +0000343 names = dir(cls)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700344 # :dd any DynamicClassAttributes to the list of names;
Ethan Furmane03ea372013-09-25 07:14:41 -0700345 # this may result in duplicate entries if, for example, a virtual
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700346 # attribute with the same name as a DynamicClassAttribute exists.
Ethan Furman63c141c2013-10-18 00:27:39 -0700347 for base in mro:
Ethan Furmane03ea372013-09-25 07:14:41 -0700348 for k, v in base.__dict__.items():
349 if isinstance(v, types.DynamicClassAttribute):
350 names.append(k)
Tim Peters13b49d32001-09-23 02:00:29 +0000351 result = []
Ethan Furmane03ea372013-09-25 07:14:41 -0700352 processed = set()
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700353
Tim Peters13b49d32001-09-23 02:00:29 +0000354 for name in names:
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100355 # Get the object associated with the name, and where it was defined.
Ethan Furmane03ea372013-09-25 07:14:41 -0700356 # Normal objects will be looked up with both getattr and directly in
357 # its class' dict (in case getattr fails [bug #1785], and also to look
358 # for a docstring).
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700359 # For DynamicClassAttributes on the second pass we only look in the
Ethan Furmane03ea372013-09-25 07:14:41 -0700360 # class's dict.
361 #
Tim Peters13b49d32001-09-23 02:00:29 +0000362 # Getting an obj from the __dict__ sometimes reveals more than
363 # using getattr. Static and class methods are dramatic examples.
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100364 homecls = None
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700365 get_obj = None
366 dict_obj = None
Ethan Furmane03ea372013-09-25 07:14:41 -0700367 if name not in processed:
368 try:
Ethan Furmana8b07072013-10-18 01:22:08 -0700369 if name == '__dict__':
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700370 raise Exception("__dict__ is special, don't want the proxy")
Ethan Furmane03ea372013-09-25 07:14:41 -0700371 get_obj = getattr(cls, name)
372 except Exception as exc:
373 pass
374 else:
Ethan Furmane03ea372013-09-25 07:14:41 -0700375 homecls = getattr(get_obj, "__objclass__", homecls)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700376 if homecls not in class_bases:
Ethan Furmane03ea372013-09-25 07:14:41 -0700377 # if the resulting object does not live somewhere in the
Ethan Furman63c141c2013-10-18 00:27:39 -0700378 # mro, drop it and search the mro manually
Ethan Furmane03ea372013-09-25 07:14:41 -0700379 homecls = None
Ethan Furman63c141c2013-10-18 00:27:39 -0700380 last_cls = None
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700381 # first look in the classes
382 for srch_cls in class_bases:
Ethan Furman63c141c2013-10-18 00:27:39 -0700383 srch_obj = getattr(srch_cls, name, None)
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700384 if srch_obj == get_obj:
Ethan Furman63c141c2013-10-18 00:27:39 -0700385 last_cls = srch_cls
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700386 # then check the metaclasses
387 for srch_cls in metamro:
388 try:
389 srch_obj = srch_cls.__getattr__(cls, name)
390 except AttributeError:
391 continue
392 if srch_obj == get_obj:
393 last_cls = srch_cls
Ethan Furman63c141c2013-10-18 00:27:39 -0700394 if last_cls is not None:
395 homecls = last_cls
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700396 for base in all_bases:
Ethan Furmane03ea372013-09-25 07:14:41 -0700397 if name in base.__dict__:
398 dict_obj = base.__dict__[name]
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700399 if homecls not in metamro:
400 homecls = base
Ethan Furmane03ea372013-09-25 07:14:41 -0700401 break
Ethan Furman63c141c2013-10-18 00:27:39 -0700402 if homecls is None:
403 # unable to locate the attribute anywhere, most likely due to
404 # buggy custom __dir__; discard and move on
405 continue
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700406 obj = get_obj or dict_obj
Ethan Furmane03ea372013-09-25 07:14:41 -0700407 # Classify the object or its descriptor.
Ethan Furman63c141c2013-10-18 00:27:39 -0700408 if isinstance(dict_obj, staticmethod):
Tim Peters13b49d32001-09-23 02:00:29 +0000409 kind = "static method"
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700410 obj = dict_obj
Ethan Furman63c141c2013-10-18 00:27:39 -0700411 elif isinstance(dict_obj, classmethod):
Tim Peters13b49d32001-09-23 02:00:29 +0000412 kind = "class method"
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700413 obj = dict_obj
414 elif isinstance(dict_obj, property):
Tim Peters13b49d32001-09-23 02:00:29 +0000415 kind = "property"
Ethan Furmanb0c84cd2013-10-20 22:37:39 -0700416 obj = dict_obj
Yury Selivanov0860a0b2014-01-31 14:28:44 -0500417 elif isroutine(obj):
Tim Peters13b49d32001-09-23 02:00:29 +0000418 kind = "method"
Antoine Pitrou86a8a9a2011-12-21 09:57:40 +0100419 else:
Ethan Furmane03ea372013-09-25 07:14:41 -0700420 kind = "data"
Christian Heimes25bb7832008-01-11 16:17:00 +0000421 result.append(Attribute(name, kind, homecls, obj))
Ethan Furmane03ea372013-09-25 07:14:41 -0700422 processed.add(name)
Tim Peters13b49d32001-09-23 02:00:29 +0000423 return result
424
Tim Peterse0b2d7a2001-09-22 06:10:55 +0000425# ----------------------------------------------------------- class helpers
Tim Peterse0b2d7a2001-09-22 06:10:55 +0000426
427def getmro(cls):
428 "Return tuple of base classes (including cls) in method resolution order."
Benjamin Petersonb82c8e52010-11-04 00:38:49 +0000429 return cls.__mro__
Tim Peterse0b2d7a2001-09-22 06:10:55 +0000430
Nick Coghlane8c45d62013-07-28 20:00:01 +1000431# -------------------------------------------------------- function helpers
432
433def unwrap(func, *, stop=None):
434 """Get the object wrapped by *func*.
435
436 Follows the chain of :attr:`__wrapped__` attributes returning the last
437 object in the chain.
438
439 *stop* is an optional callback accepting an object in the wrapper chain
440 as its sole argument that allows the unwrapping to be terminated early if
441 the callback returns a true value. If the callback never returns a true
442 value, the last object in the chain is returned as usual. For example,
443 :func:`signature` uses this to stop unwrapping if any object in the
444 chain has a ``__signature__`` attribute defined.
445
446 :exc:`ValueError` is raised if a cycle is encountered.
447
448 """
449 if stop is None:
450 def _is_wrapper(f):
451 return hasattr(f, '__wrapped__')
452 else:
453 def _is_wrapper(f):
454 return hasattr(f, '__wrapped__') and not stop(f)
455 f = func # remember the original func for error reporting
456 memo = {id(f)} # Memoise by id to tolerate non-hashable objects
457 while _is_wrapper(func):
458 func = func.__wrapped__
459 id_func = id(func)
460 if id_func in memo:
461 raise ValueError('wrapper loop when unwrapping {!r}'.format(f))
462 memo.add(id_func)
463 return func
464
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000465# -------------------------------------------------- source code extraction
466def indentsize(line):
467 """Return the indent size, in spaces, at the start of a line of text."""
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000468 expline = line.expandtabs()
469 return len(expline) - len(expline.lstrip())
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000470
471def getdoc(object):
472 """Get the documentation string for an object.
473
474 All tabs are expanded to spaces. To clean up docstrings that are
475 indented to line up with blocks of code, any whitespace than can be
476 uniformly removed from the second line onwards is removed."""
Tim Peters24008312002-03-17 18:56:20 +0000477 try:
478 doc = object.__doc__
479 except AttributeError:
480 return None
Guido van Rossum3172c5d2007-10-16 18:12:55 +0000481 if not isinstance(doc, str):
Tim Peters24008312002-03-17 18:56:20 +0000482 return None
Georg Brandl0c77a822008-06-10 16:37:50 +0000483 return cleandoc(doc)
484
485def cleandoc(doc):
486 """Clean up indentation from docstrings.
487
488 Any whitespace that can be uniformly removed from the second line
489 onwards is removed."""
Tim Peters24008312002-03-17 18:56:20 +0000490 try:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000491 lines = doc.expandtabs().split('\n')
Tim Peters24008312002-03-17 18:56:20 +0000492 except UnicodeError:
493 return None
494 else:
Ka-Ping Yeea59ef7b2002-11-30 03:53:15 +0000495 # Find minimum indentation of any non-blank lines after first line.
Christian Heimesa37d4c62007-12-04 23:02:19 +0000496 margin = sys.maxsize
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000497 for line in lines[1:]:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000498 content = len(line.lstrip())
Ka-Ping Yeea59ef7b2002-11-30 03:53:15 +0000499 if content:
500 indent = len(line) - content
501 margin = min(margin, indent)
502 # Remove indentation.
503 if lines:
504 lines[0] = lines[0].lstrip()
Christian Heimesa37d4c62007-12-04 23:02:19 +0000505 if margin < sys.maxsize:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000506 for i in range(1, len(lines)): lines[i] = lines[i][margin:]
Ka-Ping Yeea59ef7b2002-11-30 03:53:15 +0000507 # Remove any trailing or leading blank lines.
508 while lines and not lines[-1]:
509 lines.pop()
510 while lines and not lines[0]:
511 lines.pop(0)
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000512 return '\n'.join(lines)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000513
514def getfile(object):
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000515 """Work out which source or compiled file an object was defined in."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000516 if ismodule(object):
517 if hasattr(object, '__file__'):
518 return object.__file__
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000519 raise TypeError('{!r} is a built-in module'.format(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000520 if isclass(object):
Yury Selivanov2eed8b72014-01-27 13:24:56 -0500521 if hasattr(object, '__module__'):
522 object = sys.modules.get(object.__module__)
523 if hasattr(object, '__file__'):
524 return object.__file__
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000525 raise TypeError('{!r} is a built-in class'.format(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000526 if ismethod(object):
Christian Heimesff737952007-11-27 10:40:20 +0000527 object = object.__func__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000528 if isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000529 object = object.__code__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000530 if istraceback(object):
531 object = object.tb_frame
532 if isframe(object):
533 object = object.f_code
534 if iscode(object):
535 return object.co_filename
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000536 raise TypeError('{!r} is not a module, class, method, '
537 'function, traceback, frame, or code object'.format(object))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000538
Christian Heimes25bb7832008-01-11 16:17:00 +0000539ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')
540
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000541def getmoduleinfo(path):
542 """Get the module name, suffix, mode, and module type for a given file."""
Brett Cannoncb66eb02012-05-11 12:58:42 -0400543 warnings.warn('inspect.getmoduleinfo() is deprecated', DeprecationWarning,
544 2)
Brett Cannone4f41de2013-06-16 13:13:40 -0400545 with warnings.catch_warnings():
546 warnings.simplefilter('ignore', PendingDeprecationWarning)
547 import imp
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000548 filename = os.path.basename(path)
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000549 suffixes = [(-len(suffix), suffix, mode, mtype)
550 for suffix, mode, mtype in imp.get_suffixes()]
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000551 suffixes.sort() # try longest suffixes first, in case they overlap
552 for neglen, suffix, mode, mtype in suffixes:
553 if filename[neglen:] == suffix:
Christian Heimes25bb7832008-01-11 16:17:00 +0000554 return ModuleInfo(filename[:neglen], suffix, mode, mtype)
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000555
556def getmodulename(path):
557 """Return the module name for a given file, or None."""
Nick Coghlan76e07702012-07-18 23:14:57 +1000558 fname = os.path.basename(path)
559 # Check for paths that look like an actual module file
560 suffixes = [(-len(suffix), suffix)
561 for suffix in importlib.machinery.all_suffixes()]
562 suffixes.sort() # try longest suffixes first, in case they overlap
563 for neglen, suffix in suffixes:
564 if fname.endswith(suffix):
565 return fname[:neglen]
566 return None
Ka-Ping Yee4d6fc7f2001-04-10 11:43:00 +0000567
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000568def getsourcefile(object):
R. David Murraya1b37402010-06-17 02:04:29 +0000569 """Return the filename that can be used to locate an object's source.
570 Return None if no way can be identified to get the source.
571 """
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000572 filename = getfile(object)
Brett Cannoncb66eb02012-05-11 12:58:42 -0400573 all_bytecode_suffixes = importlib.machinery.DEBUG_BYTECODE_SUFFIXES[:]
574 all_bytecode_suffixes += importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES[:]
575 if any(filename.endswith(s) for s in all_bytecode_suffixes):
576 filename = (os.path.splitext(filename)[0] +
577 importlib.machinery.SOURCE_SUFFIXES[0])
578 elif any(filename.endswith(s) for s in
579 importlib.machinery.EXTENSION_SUFFIXES):
580 return None
Thomas Wouters477c8d52006-05-27 19:21:47 +0000581 if os.path.exists(filename):
582 return filename
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000583 # only return a non-existent filename if the module has a PEP 302 loader
Brett Cannon4c14b5d2013-05-04 13:56:58 -0400584 if getattr(getmodule(object, filename), '__loader__', None) is not None:
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000585 return filename
R. David Murraya1b37402010-06-17 02:04:29 +0000586 # or it is in the linecache
587 if filename in linecache.cache:
588 return filename
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000589
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000590def getabsfile(object, _filename=None):
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000591 """Return an absolute path to the source or compiled file for an object.
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000592
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000593 The idea is for each object to have a unique origin, so this routine
594 normalizes the result as much as possible."""
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000595 if _filename is None:
596 _filename = getsourcefile(object) or getfile(object)
597 return os.path.normcase(os.path.abspath(_filename))
Ka-Ping Yeec113c242001-03-02 02:08:53 +0000598
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000599modulesbyfile = {}
Thomas Wouters89f507f2006-12-13 04:49:30 +0000600_filesbymodname = {}
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000601
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000602def getmodule(object, _filename=None):
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000603 """Return the module an object was defined in, or None if not found."""
Ka-Ping Yee202c99b2001-04-13 09:15:08 +0000604 if ismodule(object):
605 return object
Johannes Gijsbers93245262004-09-11 15:53:22 +0000606 if hasattr(object, '__module__'):
Ka-Ping Yee8b58b842001-03-01 13:56:16 +0000607 return sys.modules.get(object.__module__)
Thomas Wouters89f507f2006-12-13 04:49:30 +0000608 # Try the filename to modulename cache
609 if _filename is not None and _filename in modulesbyfile:
610 return sys.modules.get(modulesbyfile[_filename])
611 # Try the cache again with the absolute file name
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000612 try:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000613 file = getabsfile(object, _filename)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000614 except TypeError:
615 return None
Raymond Hettinger54f02222002-06-01 14:18:47 +0000616 if file in modulesbyfile:
Ka-Ping Yeeb38bbbd2003-03-28 16:29:50 +0000617 return sys.modules.get(modulesbyfile[file])
Thomas Wouters89f507f2006-12-13 04:49:30 +0000618 # Update the filename to module name cache and check yet again
619 # Copy sys.modules in order to cope with changes while iterating
Éric Araujoa74f8ef2011-11-29 16:58:53 +0100620 for modname, module in list(sys.modules.items()):
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000621 if ismodule(module) and hasattr(module, '__file__'):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000622 f = module.__file__
623 if f == _filesbymodname.get(modname, None):
624 # Have already mapped this module, so skip it
625 continue
626 _filesbymodname[modname] = f
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000627 f = getabsfile(module)
Thomas Wouters89f507f2006-12-13 04:49:30 +0000628 # Always map to the name the module knows itself by
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000629 modulesbyfile[f] = modulesbyfile[
630 os.path.realpath(f)] = module.__name__
Raymond Hettinger54f02222002-06-01 14:18:47 +0000631 if file in modulesbyfile:
Ka-Ping Yeeb38bbbd2003-03-28 16:29:50 +0000632 return sys.modules.get(modulesbyfile[file])
Thomas Wouters89f507f2006-12-13 04:49:30 +0000633 # Check the main module
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000634 main = sys.modules['__main__']
Brett Cannon4a671fe2003-06-15 22:33:28 +0000635 if not hasattr(object, '__name__'):
636 return None
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000637 if hasattr(main, object.__name__):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000638 mainobject = getattr(main, object.__name__)
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000639 if mainobject is object:
640 return main
Thomas Wouters89f507f2006-12-13 04:49:30 +0000641 # Check builtins
Georg Brandl1a3284e2007-12-02 09:40:06 +0000642 builtin = sys.modules['builtins']
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000643 if hasattr(builtin, object.__name__):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000644 builtinobject = getattr(builtin, object.__name__)
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000645 if builtinobject is object:
646 return builtin
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000647
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000648def findsource(object):
649 """Return the entire source file and starting line number for an object.
650
651 The argument may be a module, class, method, function, traceback, frame,
652 or code object. The source code is returned as a list of all the lines
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200653 in the file and the line number indexes a line in that list. An OSError
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000654 is raised if the source code cannot be retrieved."""
Benjamin Peterson9620cc02011-06-11 15:53:11 -0500655
656 file = getfile(object)
657 sourcefile = getsourcefile(object)
Ezio Melotti1b145922013-03-30 05:17:24 +0200658 if not sourcefile and file[:1] + file[-1:] != '<>':
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200659 raise OSError('source code not available')
Benjamin Peterson9620cc02011-06-11 15:53:11 -0500660 file = sourcefile if sourcefile else file
661
Thomas Wouters89f507f2006-12-13 04:49:30 +0000662 module = getmodule(object, file)
Thomas Wouters477c8d52006-05-27 19:21:47 +0000663 if module:
664 lines = linecache.getlines(file, module.__dict__)
665 else:
666 lines = linecache.getlines(file)
Neil Schemenauerf06f8532002-03-23 23:51:04 +0000667 if not lines:
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200668 raise OSError('could not get source code')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000669
670 if ismodule(object):
671 return lines, 0
672
673 if isclass(object):
674 name = object.__name__
Thomas Wouters89f507f2006-12-13 04:49:30 +0000675 pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
676 # make some effort to find the best matching class definition:
677 # use the one with the least indentation, which is the one
678 # that's most probably not inside a function definition.
679 candidates = []
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000680 for i in range(len(lines)):
Thomas Wouters89f507f2006-12-13 04:49:30 +0000681 match = pat.match(lines[i])
682 if match:
683 # if it's at toplevel, it's already the best one
684 if lines[i][0] == 'c':
685 return lines, i
686 # else add whitespace to candidate list
687 candidates.append((match.group(1), i))
688 if candidates:
689 # this will sort by whitespace, and by line number,
690 # less whitespace first
691 candidates.sort()
692 return lines, candidates[0][1]
Jeremy Hyltonab919022003-06-27 18:41:20 +0000693 else:
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200694 raise OSError('could not find class definition')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000695
696 if ismethod(object):
Christian Heimesff737952007-11-27 10:40:20 +0000697 object = object.__func__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000698 if isfunction(object):
Neal Norwitz221085d2007-02-25 20:55:47 +0000699 object = object.__code__
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000700 if istraceback(object):
701 object = object.tb_frame
702 if isframe(object):
703 object = object.f_code
704 if iscode(object):
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000705 if not hasattr(object, 'co_firstlineno'):
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200706 raise OSError('could not find function definition')
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000707 lnum = object.co_firstlineno - 1
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000708 pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000709 while lnum > 0:
Ka-Ping Yeea6e59712001-03-10 09:31:55 +0000710 if pat.match(lines[lnum]): break
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +0000711 lnum = lnum - 1
712 return lines, lnum
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200713 raise OSError('could not find code object')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000714
715def getcomments(object):
Jeremy Hyltonb4c17c82002-03-28 23:01:56 +0000716 """Get lines of comments immediately preceding an object's source code.
717
718 Returns None when source can't be found.
719 """
720 try:
721 lines, lnum = findsource(object)
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200722 except (OSError, TypeError):
Jeremy Hyltonb4c17c82002-03-28 23:01:56 +0000723 return None
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000724
725 if ismodule(object):
726 # Look for a comment block at the top of the file.
727 start = 0
Ka-Ping Yeeb910efe2001-04-12 13:17:17 +0000728 if lines and lines[0][:2] == '#!': start = 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000729 while start < len(lines) and lines[start].strip() in ('', '#'):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000730 start = start + 1
Ka-Ping Yeeb910efe2001-04-12 13:17:17 +0000731 if start < len(lines) and lines[start][:1] == '#':
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000732 comments = []
733 end = start
734 while end < len(lines) and lines[end][:1] == '#':
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000735 comments.append(lines[end].expandtabs())
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000736 end = end + 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000737 return ''.join(comments)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000738
739 # Look for a preceding block of comments at the same indentation.
740 elif lnum > 0:
741 indent = indentsize(lines[lnum])
742 end = lnum - 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000743 if end >= 0 and lines[end].lstrip()[:1] == '#' and \
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000744 indentsize(lines[end]) == indent:
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000745 comments = [lines[end].expandtabs().lstrip()]
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000746 if end > 0:
747 end = end - 1
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000748 comment = lines[end].expandtabs().lstrip()
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000749 while comment[:1] == '#' and indentsize(lines[end]) == indent:
750 comments[:0] = [comment]
751 end = end - 1
752 if end < 0: break
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000753 comment = lines[end].expandtabs().lstrip()
754 while comments and comments[0].strip() == '#':
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000755 comments[:1] = []
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000756 while comments and comments[-1].strip() == '#':
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000757 comments[-1:] = []
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000758 return ''.join(comments)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000759
Tim Peters4efb6e92001-06-29 23:51:08 +0000760class EndOfBlock(Exception): pass
761
762class BlockFinder:
763 """Provide a tokeneater() method to detect the end of a code block."""
764 def __init__(self):
765 self.indent = 0
Johannes Gijsbersa5855d52005-03-12 16:37:11 +0000766 self.islambda = False
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000767 self.started = False
768 self.passline = False
Armin Rigodd5c0232005-09-25 11:45:45 +0000769 self.last = 1
Tim Peters4efb6e92001-06-29 23:51:08 +0000770
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000771 def tokeneater(self, type, token, srowcol, erowcol, line):
Tim Peters4efb6e92001-06-29 23:51:08 +0000772 if not self.started:
Armin Rigodd5c0232005-09-25 11:45:45 +0000773 # look for the first "def", "class" or "lambda"
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000774 if token in ("def", "class", "lambda"):
Johannes Gijsbersa5855d52005-03-12 16:37:11 +0000775 if token == "lambda":
776 self.islambda = True
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000777 self.started = True
Armin Rigodd5c0232005-09-25 11:45:45 +0000778 self.passline = True # skip to the end of the line
Tim Peters4efb6e92001-06-29 23:51:08 +0000779 elif type == tokenize.NEWLINE:
Armin Rigodd5c0232005-09-25 11:45:45 +0000780 self.passline = False # stop skipping when a NEWLINE is seen
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000781 self.last = srowcol[0]
Armin Rigodd5c0232005-09-25 11:45:45 +0000782 if self.islambda: # lambdas always end at the first NEWLINE
783 raise EndOfBlock
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000784 elif self.passline:
785 pass
Tim Peters4efb6e92001-06-29 23:51:08 +0000786 elif type == tokenize.INDENT:
787 self.indent = self.indent + 1
Johannes Gijsbers1542f342004-12-12 16:46:28 +0000788 self.passline = True
Tim Peters4efb6e92001-06-29 23:51:08 +0000789 elif type == tokenize.DEDENT:
790 self.indent = self.indent - 1
Armin Rigodd5c0232005-09-25 11:45:45 +0000791 # the end of matching indent/dedent pairs end a block
792 # (note that this only works for "def"/"class" blocks,
793 # not e.g. for "if: else:" or "try: finally:" blocks)
794 if self.indent <= 0:
795 raise EndOfBlock
796 elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
797 # any other token on the same indentation level end the previous
798 # block as well, except the pseudo-tokens COMMENT and NL.
799 raise EndOfBlock
Tim Peters4efb6e92001-06-29 23:51:08 +0000800
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000801def getblock(lines):
802 """Extract the block of code at the top of the given list of lines."""
Armin Rigodd5c0232005-09-25 11:45:45 +0000803 blockfinder = BlockFinder()
Tim Peters4efb6e92001-06-29 23:51:08 +0000804 try:
Trent Nelson428de652008-03-18 22:41:35 +0000805 tokens = tokenize.generate_tokens(iter(lines).__next__)
806 for _token in tokens:
807 blockfinder.tokeneater(*_token)
Armin Rigodd5c0232005-09-25 11:45:45 +0000808 except (EndOfBlock, IndentationError):
809 pass
810 return lines[:blockfinder.last]
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000811
812def getsourcelines(object):
813 """Return a list of source lines and starting line number for an object.
814
815 The argument may be a module, class, method, function, traceback, frame,
816 or code object. The source code is returned as a list of the lines
817 corresponding to the object and the line number indicates where in the
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200818 original source file the first line of code was found. An OSError is
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000819 raised if the source code cannot be retrieved."""
820 lines, lnum = findsource(object)
821
822 if ismodule(object): return lines, 0
823 else: return getblock(lines[lnum:]), lnum + 1
824
825def getsource(object):
826 """Return the text of the source code for an object.
827
828 The argument may be a module, class, method, function, traceback, frame,
829 or code object. The source code is returned as a single string. An
Andrew Svetlovf7a17b42012-12-25 16:47:37 +0200830 OSError is raised if the source code cannot be retrieved."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000831 lines, lnum = getsourcelines(object)
Neal Norwitz9d72bb42007-04-17 08:48:32 +0000832 return ''.join(lines)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000833
834# --------------------------------------------------- class tree extraction
835def walktree(classes, children, parent):
836 """Recursive helper function for getclasstree()."""
837 results = []
Raymond Hettingera1a992c2005-03-11 06:46:45 +0000838 classes.sort(key=attrgetter('__module__', '__name__'))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000839 for c in classes:
840 results.append((c, c.__bases__))
Raymond Hettinger54f02222002-06-01 14:18:47 +0000841 if c in children:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000842 results.append(walktree(children[c], children, c))
843 return results
844
Georg Brandl5ce83a02009-06-01 17:23:51 +0000845def getclasstree(classes, unique=False):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000846 """Arrange the given list of classes into a hierarchy of nested lists.
847
848 Where a nested list appears, it contains classes derived from the class
849 whose entry immediately precedes the list. Each entry is a 2-tuple
850 containing a class and a tuple of its base classes. If the 'unique'
851 argument is true, exactly one entry appears in the returned structure
852 for each class in the given list. Otherwise, classes using multiple
853 inheritance and their descendants will appear multiple times."""
854 children = {}
855 roots = []
856 for c in classes:
857 if c.__bases__:
858 for parent in c.__bases__:
Raymond Hettinger54f02222002-06-01 14:18:47 +0000859 if not parent in children:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000860 children[parent] = []
Serhiy Storchaka362c1b52013-09-05 17:14:32 +0300861 if c not in children[parent]:
862 children[parent].append(c)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000863 if unique and parent in classes: break
864 elif c not in roots:
865 roots.append(c)
Raymond Hettingere0d49722002-06-02 18:55:56 +0000866 for parent in children:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000867 if parent not in classes:
868 roots.append(parent)
869 return walktree(roots, children, None)
870
871# ------------------------------------------------ argument list extraction
Christian Heimes25bb7832008-01-11 16:17:00 +0000872Arguments = namedtuple('Arguments', 'args, varargs, varkw')
873
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000874def getargs(co):
875 """Get information about the arguments accepted by a code object.
876
Guido van Rossum2e65f892007-02-28 22:03:49 +0000877 Three things are returned: (args, varargs, varkw), where
Georg Brandlc1c4bf82010-10-15 16:07:41 +0000878 'args' is the list of argument names. Keyword-only arguments are
879 appended. 'varargs' and 'varkw' are the names of the * and **
880 arguments or None."""
Guido van Rossum2e65f892007-02-28 22:03:49 +0000881 args, varargs, kwonlyargs, varkw = _getfullargs(co)
Christian Heimes25bb7832008-01-11 16:17:00 +0000882 return Arguments(args + kwonlyargs, varargs, varkw)
Guido van Rossum2e65f892007-02-28 22:03:49 +0000883
884def _getfullargs(co):
885 """Get information about the arguments accepted by a code object.
886
887 Four things are returned: (args, varargs, kwonlyargs, varkw), where
Georg Brandlc1c4bf82010-10-15 16:07:41 +0000888 'args' and 'kwonlyargs' are lists of argument names, and 'varargs'
889 and 'varkw' are the names of the * and ** arguments or None."""
Jeremy Hylton64967882003-06-27 18:14:39 +0000890
891 if not iscode(co):
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +0000892 raise TypeError('{!r} is not a code object'.format(co))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000893
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000894 nargs = co.co_argcount
895 names = co.co_varnames
Guido van Rossum2e65f892007-02-28 22:03:49 +0000896 nkwargs = co.co_kwonlyargcount
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000897 args = list(names[:nargs])
Guido van Rossum2e65f892007-02-28 22:03:49 +0000898 kwonlyargs = list(names[nargs:nargs+nkwargs])
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000899 step = 0
900
Guido van Rossum2e65f892007-02-28 22:03:49 +0000901 nargs += nkwargs
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000902 varargs = None
903 if co.co_flags & CO_VARARGS:
904 varargs = co.co_varnames[nargs]
905 nargs = nargs + 1
906 varkw = None
907 if co.co_flags & CO_VARKEYWORDS:
908 varkw = co.co_varnames[nargs]
Guido van Rossum2e65f892007-02-28 22:03:49 +0000909 return args, varargs, kwonlyargs, varkw
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000910
Christian Heimes25bb7832008-01-11 16:17:00 +0000911
912ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
913
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000914def getargspec(func):
915 """Get the names and default values of a function's arguments.
916
917 A tuple of four things is returned: (args, varargs, varkw, defaults).
Georg Brandlc1c4bf82010-10-15 16:07:41 +0000918 'args' is a list of the argument names.
Guido van Rossum2e65f892007-02-28 22:03:49 +0000919 'args' will include keyword-only argument names.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +0000920 'varargs' and 'varkw' are the names of the * and ** arguments or None.
Jeremy Hylton64967882003-06-27 18:14:39 +0000921 'defaults' is an n-tuple of the default values of the last n arguments.
Guido van Rossuma8add0e2007-05-14 22:03:55 +0000922
Guido van Rossum2e65f892007-02-28 22:03:49 +0000923 Use the getfullargspec() API for Python-3000 code, as annotations
924 and keyword arguments are supported. getargspec() will raise ValueError
925 if the func has either annotations or keyword arguments.
926 """
927
928 args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \
929 getfullargspec(func)
930 if kwonlyargs or ann:
Collin Winterce36ad82007-08-30 01:19:48 +0000931 raise ValueError("Function has keyword-only arguments or annotations"
932 ", use getfullargspec() API which can support them")
Christian Heimes25bb7832008-01-11 16:17:00 +0000933 return ArgSpec(args, varargs, varkw, defaults)
934
935FullArgSpec = namedtuple('FullArgSpec',
Benjamin Peterson3d4ca742008-11-12 21:39:01 +0000936 'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations')
Guido van Rossum2e65f892007-02-28 22:03:49 +0000937
938def getfullargspec(func):
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500939 """Get the names and default values of a callable object's arguments.
Guido van Rossum2e65f892007-02-28 22:03:49 +0000940
Brett Cannon504d8852007-09-07 02:12:14 +0000941 A tuple of seven things is returned:
942 (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations).
Georg Brandlc1c4bf82010-10-15 16:07:41 +0000943 'args' is a list of the argument names.
Guido van Rossum2e65f892007-02-28 22:03:49 +0000944 'varargs' and 'varkw' are the names of the * and ** arguments or None.
945 'defaults' is an n-tuple of the default values of the last n arguments.
946 'kwonlyargs' is a list of keyword-only argument names.
947 'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults.
948 'annotations' is a dictionary mapping argument names to annotations.
Guido van Rossuma8add0e2007-05-14 22:03:55 +0000949
Guido van Rossum2e65f892007-02-28 22:03:49 +0000950 The first four items in the tuple correspond to getargspec().
Jeremy Hylton64967882003-06-27 18:14:39 +0000951 """
952
Yury Selivanov57d240e2014-02-19 16:27:23 -0500953 try:
954 # Re: `skip_bound_arg=False`
955 #
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500956 # There is a notable difference in behaviour between getfullargspec
957 # and Signature: the former always returns 'self' parameter for bound
958 # methods, whereas the Signature always shows the actual calling
959 # signature of the passed object.
960 #
961 # To simulate this behaviour, we "unbind" bound methods, to trick
962 # inspect.signature to always return their first parameter ("self",
963 # usually)
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500964
Yury Selivanov57d240e2014-02-19 16:27:23 -0500965 # Re: `follow_wrapper_chains=False`
966 #
967 # getfullargspec() historically ignored __wrapped__ attributes,
968 # so we ensure that remains the case in 3.3+
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500969
Yury Selivanov57d240e2014-02-19 16:27:23 -0500970 sig = _signature_internal(func,
971 follow_wrapper_chains=False,
Yury Selivanovda396452014-03-27 12:09:24 -0400972 skip_bound_arg=False,
973 sigcls=Signature)
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500974 except Exception as ex:
975 # Most of the times 'signature' will raise ValueError.
976 # But, it can also raise AttributeError, and, maybe something
977 # else. So to be fully backwards compatible, we catch all
978 # possible exceptions here, and reraise a TypeError.
979 raise TypeError('unsupported callable') from ex
980
981 args = []
982 varargs = None
983 varkw = None
984 kwonlyargs = []
985 defaults = ()
986 annotations = {}
987 defaults = ()
988 kwdefaults = {}
989
990 if sig.return_annotation is not sig.empty:
991 annotations['return'] = sig.return_annotation
992
993 for param in sig.parameters.values():
994 kind = param.kind
995 name = param.name
996
997 if kind is _POSITIONAL_ONLY:
998 args.append(name)
999 elif kind is _POSITIONAL_OR_KEYWORD:
1000 args.append(name)
1001 if param.default is not param.empty:
1002 defaults += (param.default,)
1003 elif kind is _VAR_POSITIONAL:
1004 varargs = name
1005 elif kind is _KEYWORD_ONLY:
1006 kwonlyargs.append(name)
1007 if param.default is not param.empty:
1008 kwdefaults[name] = param.default
1009 elif kind is _VAR_KEYWORD:
1010 varkw = name
1011
1012 if param.annotation is not param.empty:
1013 annotations[name] = param.annotation
1014
1015 if not kwdefaults:
1016 # compatibility with 'func.__kwdefaults__'
1017 kwdefaults = None
1018
1019 if not defaults:
1020 # compatibility with 'func.__defaults__'
1021 defaults = None
1022
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001023 return FullArgSpec(args, varargs, varkw, defaults,
1024 kwonlyargs, kwdefaults, annotations)
1025
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001026
Christian Heimes25bb7832008-01-11 16:17:00 +00001027ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
1028
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001029def getargvalues(frame):
1030 """Get information about arguments passed into a particular frame.
1031
1032 A tuple of four things is returned: (args, varargs, varkw, locals).
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001033 'args' is a list of the argument names.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001034 'varargs' and 'varkw' are the names of the * and ** arguments or None.
1035 'locals' is the locals dictionary of the given frame."""
1036 args, varargs, varkw = getargs(frame.f_code)
Benjamin Peterson1a6e0d02008-10-25 15:49:17 +00001037 return ArgInfo(args, varargs, varkw, frame.f_locals)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001038
Guido van Rossum2e65f892007-02-28 22:03:49 +00001039def formatannotation(annotation, base_module=None):
1040 if isinstance(annotation, type):
Georg Brandl1a3284e2007-12-02 09:40:06 +00001041 if annotation.__module__ in ('builtins', base_module):
Guido van Rossum2e65f892007-02-28 22:03:49 +00001042 return annotation.__name__
1043 return annotation.__module__+'.'+annotation.__name__
1044 return repr(annotation)
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001045
Guido van Rossum2e65f892007-02-28 22:03:49 +00001046def formatannotationrelativeto(object):
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001047 module = getattr(object, '__module__', None)
1048 def _formatannotation(annotation):
1049 return formatannotation(annotation, module)
1050 return _formatannotation
Guido van Rossum2e65f892007-02-28 22:03:49 +00001051
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001052def formatargspec(args, varargs=None, varkw=None, defaults=None,
Guido van Rossum2e65f892007-02-28 22:03:49 +00001053 kwonlyargs=(), kwonlydefaults={}, annotations={},
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001054 formatarg=str,
1055 formatvarargs=lambda name: '*' + name,
1056 formatvarkw=lambda name: '**' + name,
1057 formatvalue=lambda value: '=' + repr(value),
Guido van Rossum2e65f892007-02-28 22:03:49 +00001058 formatreturns=lambda text: ' -> ' + text,
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001059 formatannotation=formatannotation):
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001060 """Format an argument spec from the values returned by getargspec
Guido van Rossum2e65f892007-02-28 22:03:49 +00001061 or getfullargspec.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001062
Guido van Rossum2e65f892007-02-28 22:03:49 +00001063 The first seven arguments are (args, varargs, varkw, defaults,
1064 kwonlyargs, kwonlydefaults, annotations). The other five arguments
1065 are the corresponding optional formatting functions that are called to
1066 turn names and values into strings. The last argument is an optional
1067 function to format the sequence of arguments."""
1068 def formatargandannotation(arg):
1069 result = formatarg(arg)
1070 if arg in annotations:
1071 result += ': ' + formatannotation(annotations[arg])
1072 return result
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001073 specs = []
1074 if defaults:
1075 firstdefault = len(args) - len(defaults)
Benjamin Petersonb58dda72009-01-18 22:27:04 +00001076 for i, arg in enumerate(args):
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001077 spec = formatargandannotation(arg)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001078 if defaults and i >= firstdefault:
1079 spec = spec + formatvalue(defaults[i - firstdefault])
1080 specs.append(spec)
Raymond Hettinger936654b2002-06-01 03:06:31 +00001081 if varargs is not None:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001082 specs.append(formatvarargs(formatargandannotation(varargs)))
1083 else:
1084 if kwonlyargs:
1085 specs.append('*')
1086 if kwonlyargs:
1087 for kwonlyarg in kwonlyargs:
1088 spec = formatargandannotation(kwonlyarg)
Benjamin Peterson9953a8d2009-01-17 04:15:01 +00001089 if kwonlydefaults and kwonlyarg in kwonlydefaults:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001090 spec += formatvalue(kwonlydefaults[kwonlyarg])
1091 specs.append(spec)
Raymond Hettinger936654b2002-06-01 03:06:31 +00001092 if varkw is not None:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001093 specs.append(formatvarkw(formatargandannotation(varkw)))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001094 result = '(' + ', '.join(specs) + ')'
Guido van Rossum2e65f892007-02-28 22:03:49 +00001095 if 'return' in annotations:
1096 result += formatreturns(formatannotation(annotations['return']))
1097 return result
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001098
1099def formatargvalues(args, varargs, varkw, locals,
1100 formatarg=str,
1101 formatvarargs=lambda name: '*' + name,
1102 formatvarkw=lambda name: '**' + name,
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001103 formatvalue=lambda value: '=' + repr(value)):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001104 """Format an argument spec from the 4 values returned by getargvalues.
1105
1106 The first four arguments are (args, varargs, varkw, locals). The
1107 next four arguments are the corresponding optional formatting functions
1108 that are called to turn names and values into strings. The ninth
1109 argument is an optional function to format the sequence of arguments."""
1110 def convert(name, locals=locals,
1111 formatarg=formatarg, formatvalue=formatvalue):
1112 return formatarg(name) + formatvalue(locals[name])
1113 specs = []
1114 for i in range(len(args)):
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001115 specs.append(convert(args[i]))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001116 if varargs:
1117 specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
1118 if varkw:
1119 specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001120 return '(' + ', '.join(specs) + ')'
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001121
Benjamin Petersone109c702011-06-24 09:37:26 -05001122def _missing_arguments(f_name, argnames, pos, values):
1123 names = [repr(name) for name in argnames if name not in values]
1124 missing = len(names)
1125 if missing == 1:
1126 s = names[0]
1127 elif missing == 2:
1128 s = "{} and {}".format(*names)
1129 else:
1130 tail = ", {} and {}".format(names[-2:])
1131 del names[-2:]
1132 s = ", ".join(names) + tail
1133 raise TypeError("%s() missing %i required %s argument%s: %s" %
1134 (f_name, missing,
1135 "positional" if pos else "keyword-only",
1136 "" if missing == 1 else "s", s))
1137
1138def _too_many(f_name, args, kwonly, varargs, defcount, given, values):
Benjamin Petersonb204a422011-06-05 22:04:07 -05001139 atleast = len(args) - defcount
Benjamin Petersonb204a422011-06-05 22:04:07 -05001140 kwonly_given = len([arg for arg in kwonly if arg in values])
1141 if varargs:
1142 plural = atleast != 1
1143 sig = "at least %d" % (atleast,)
1144 elif defcount:
1145 plural = True
1146 sig = "from %d to %d" % (atleast, len(args))
1147 else:
1148 plural = len(args) != 1
1149 sig = str(len(args))
1150 kwonly_sig = ""
1151 if kwonly_given:
1152 msg = " positional argument%s (and %d keyword-only argument%s)"
1153 kwonly_sig = (msg % ("s" if given != 1 else "", kwonly_given,
1154 "s" if kwonly_given != 1 else ""))
1155 raise TypeError("%s() takes %s positional argument%s but %d%s %s given" %
1156 (f_name, sig, "s" if plural else "", given, kwonly_sig,
1157 "was" if given == 1 and not kwonly_given else "were"))
1158
Benjamin Peterson3e6ab172014-01-02 12:24:08 -06001159def getcallargs(*func_and_positional, **named):
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001160 """Get the mapping of arguments to values.
1161
1162 A dict is returned, with keys the function argument names (including the
1163 names of the * and ** arguments, if any), and values the respective bound
1164 values from 'positional' and 'named'."""
Benjamin Peterson3e6ab172014-01-02 12:24:08 -06001165 func = func_and_positional[0]
1166 positional = func_and_positional[1:]
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001167 spec = getfullargspec(func)
1168 args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = spec
1169 f_name = func.__name__
1170 arg2value = {}
1171
Benjamin Petersonb204a422011-06-05 22:04:07 -05001172
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001173 if ismethod(func) and func.__self__ is not None:
1174 # implicit 'self' (or 'cls' for classmethods) argument
1175 positional = (func.__self__,) + positional
1176 num_pos = len(positional)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001177 num_args = len(args)
1178 num_defaults = len(defaults) if defaults else 0
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001179
Benjamin Petersonb204a422011-06-05 22:04:07 -05001180 n = min(num_pos, num_args)
1181 for i in range(n):
1182 arg2value[args[i]] = positional[i]
1183 if varargs:
1184 arg2value[varargs] = tuple(positional[n:])
1185 possible_kwargs = set(args + kwonlyargs)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001186 if varkw:
Benjamin Petersonb204a422011-06-05 22:04:07 -05001187 arg2value[varkw] = {}
1188 for kw, value in named.items():
1189 if kw not in possible_kwargs:
1190 if not varkw:
1191 raise TypeError("%s() got an unexpected keyword argument %r" %
1192 (f_name, kw))
1193 arg2value[varkw][kw] = value
1194 continue
1195 if kw in arg2value:
1196 raise TypeError("%s() got multiple values for argument %r" %
1197 (f_name, kw))
1198 arg2value[kw] = value
1199 if num_pos > num_args and not varargs:
Benjamin Petersone109c702011-06-24 09:37:26 -05001200 _too_many(f_name, args, kwonlyargs, varargs, num_defaults,
1201 num_pos, arg2value)
Benjamin Petersonb204a422011-06-05 22:04:07 -05001202 if num_pos < num_args:
Benjamin Petersone109c702011-06-24 09:37:26 -05001203 req = args[:num_args - num_defaults]
1204 for arg in req:
Benjamin Petersonb204a422011-06-05 22:04:07 -05001205 if arg not in arg2value:
Benjamin Petersone109c702011-06-24 09:37:26 -05001206 _missing_arguments(f_name, req, True, arg2value)
Benjamin Petersonb204a422011-06-05 22:04:07 -05001207 for i, arg in enumerate(args[num_args - num_defaults:]):
1208 if arg not in arg2value:
1209 arg2value[arg] = defaults[i]
Benjamin Petersone109c702011-06-24 09:37:26 -05001210 missing = 0
Benjamin Petersonb204a422011-06-05 22:04:07 -05001211 for kwarg in kwonlyargs:
1212 if kwarg not in arg2value:
Yury Selivanov875df202014-03-27 18:23:03 -04001213 if kwonlydefaults and kwarg in kwonlydefaults:
Benjamin Petersone109c702011-06-24 09:37:26 -05001214 arg2value[kwarg] = kwonlydefaults[kwarg]
1215 else:
1216 missing += 1
1217 if missing:
1218 _missing_arguments(f_name, kwonlyargs, False, arg2value)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001219 return arg2value
1220
Nick Coghlan2f92e542012-06-23 19:39:55 +10001221ClosureVars = namedtuple('ClosureVars', 'nonlocals globals builtins unbound')
1222
1223def getclosurevars(func):
1224 """
1225 Get the mapping of free variables to their current values.
1226
Meador Inge8fda3592012-07-19 21:33:21 -05001227 Returns a named tuple of dicts mapping the current nonlocal, global
Nick Coghlan2f92e542012-06-23 19:39:55 +10001228 and builtin references as seen by the body of the function. A final
1229 set of unbound names that could not be resolved is also provided.
1230 """
1231
1232 if ismethod(func):
1233 func = func.__func__
1234
1235 if not isfunction(func):
1236 raise TypeError("'{!r}' is not a Python function".format(func))
1237
1238 code = func.__code__
1239 # Nonlocal references are named in co_freevars and resolved
1240 # by looking them up in __closure__ by positional index
1241 if func.__closure__ is None:
1242 nonlocal_vars = {}
1243 else:
1244 nonlocal_vars = {
1245 var : cell.cell_contents
1246 for var, cell in zip(code.co_freevars, func.__closure__)
1247 }
1248
1249 # Global and builtin references are named in co_names and resolved
1250 # by looking them up in __globals__ or __builtins__
1251 global_ns = func.__globals__
1252 builtin_ns = global_ns.get("__builtins__", builtins.__dict__)
1253 if ismodule(builtin_ns):
1254 builtin_ns = builtin_ns.__dict__
1255 global_vars = {}
1256 builtin_vars = {}
1257 unbound_names = set()
1258 for name in code.co_names:
1259 if name in ("None", "True", "False"):
1260 # Because these used to be builtins instead of keywords, they
1261 # may still show up as name references. We ignore them.
1262 continue
1263 try:
1264 global_vars[name] = global_ns[name]
1265 except KeyError:
1266 try:
1267 builtin_vars[name] = builtin_ns[name]
1268 except KeyError:
1269 unbound_names.add(name)
1270
1271 return ClosureVars(nonlocal_vars, global_vars,
1272 builtin_vars, unbound_names)
1273
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001274# -------------------------------------------------- stack frame extraction
Christian Heimes25bb7832008-01-11 16:17:00 +00001275
1276Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
1277
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001278def getframeinfo(frame, context=1):
1279 """Get information about a frame or traceback object.
1280
1281 A tuple of five things is returned: the filename, the line number of
1282 the current line, the function name, a list of lines of context from
1283 the source code, and the index of the current line within that list.
1284 The optional second argument specifies the number of lines of context
1285 to return, which are centered around the current line."""
1286 if istraceback(frame):
Andrew M. Kuchlingba8b6bc2004-06-05 14:11:59 +00001287 lineno = frame.tb_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001288 frame = frame.tb_frame
Andrew M. Kuchlingba8b6bc2004-06-05 14:11:59 +00001289 else:
1290 lineno = frame.f_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001291 if not isframe(frame):
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001292 raise TypeError('{!r} is not a frame or traceback object'.format(frame))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001293
Neil Schemenauerf06f8532002-03-23 23:51:04 +00001294 filename = getsourcefile(frame) or getfile(frame)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001295 if context > 0:
Guido van Rossum54e54c62001-09-04 19:14:14 +00001296 start = lineno - 1 - context//2
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001297 try:
1298 lines, lnum = findsource(frame)
Andrew Svetlovf7a17b42012-12-25 16:47:37 +02001299 except OSError:
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +00001300 lines = index = None
1301 else:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001302 start = max(start, 1)
Raymond Hettingera0501712004-06-15 11:22:53 +00001303 start = max(0, min(start, len(lines) - context))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001304 lines = lines[start:start+context]
Ka-Ping Yee59ade082001-03-01 03:55:35 +00001305 index = lineno - 1 - start
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001306 else:
1307 lines = index = None
1308
Christian Heimes25bb7832008-01-11 16:17:00 +00001309 return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
Ka-Ping Yee59ade082001-03-01 03:55:35 +00001310
1311def getlineno(frame):
1312 """Get the line number from a frame object, allowing for optimization."""
Michael W. Hudsondd32a912002-08-15 14:59:02 +00001313 # FrameType.f_lineno is now a descriptor that grovels co_lnotab
1314 return frame.f_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001315
1316def getouterframes(frame, context=1):
1317 """Get a list of records for a frame and all higher (calling) frames.
1318
1319 Each record contains a frame object, filename, line number, function
1320 name, a list of lines of context, and index within the context."""
1321 framelist = []
1322 while frame:
1323 framelist.append((frame,) + getframeinfo(frame, context))
1324 frame = frame.f_back
1325 return framelist
1326
1327def getinnerframes(tb, context=1):
1328 """Get a list of records for a traceback's frame and all lower frames.
1329
1330 Each record contains a frame object, filename, line number, function
1331 name, a list of lines of context, and index within the context."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001332 framelist = []
1333 while tb:
1334 framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
1335 tb = tb.tb_next
1336 return framelist
1337
Benjamin Peterson42ac4752010-08-09 13:05:35 +00001338def currentframe():
Benjamin Petersona3a3fc62010-08-09 15:49:56 +00001339 """Return the frame of the caller or None if this is not possible."""
Benjamin Peterson42ac4752010-08-09 13:05:35 +00001340 return sys._getframe(1) if hasattr(sys, "_getframe") else None
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001341
1342def stack(context=1):
1343 """Return a list of records for the stack above the caller's frame."""
Jeremy Hyltonab919022003-06-27 18:41:20 +00001344 return getouterframes(sys._getframe(1), context)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001345
1346def trace(context=1):
Tim Peters85ba6732001-02-28 08:26:44 +00001347 """Return a list of records for the stack below the current exception."""
Fred Draked451ec12002-04-26 02:29:55 +00001348 return getinnerframes(sys.exc_info()[2], context)
Michael Foord95fc51d2010-11-20 15:07:30 +00001349
1350
1351# ------------------------------------------------ static version of getattr
1352
1353_sentinel = object()
1354
Michael Foorde5162652010-11-20 16:40:44 +00001355def _static_getmro(klass):
1356 return type.__dict__['__mro__'].__get__(klass)
1357
Michael Foord95fc51d2010-11-20 15:07:30 +00001358def _check_instance(obj, attr):
1359 instance_dict = {}
1360 try:
1361 instance_dict = object.__getattribute__(obj, "__dict__")
1362 except AttributeError:
1363 pass
Michael Foorddcebe0f2011-03-15 19:20:44 -04001364 return dict.get(instance_dict, attr, _sentinel)
Michael Foord95fc51d2010-11-20 15:07:30 +00001365
1366
1367def _check_class(klass, attr):
Michael Foorde5162652010-11-20 16:40:44 +00001368 for entry in _static_getmro(klass):
Michael Foorda51623b2011-12-18 22:01:40 +00001369 if _shadowed_dict(type(entry)) is _sentinel:
Michael Foorddcebe0f2011-03-15 19:20:44 -04001370 try:
1371 return entry.__dict__[attr]
1372 except KeyError:
1373 pass
Michael Foord95fc51d2010-11-20 15:07:30 +00001374 return _sentinel
1375
Michael Foord35184ed2010-11-20 16:58:30 +00001376def _is_type(obj):
1377 try:
1378 _static_getmro(obj)
1379 except TypeError:
1380 return False
1381 return True
1382
Michael Foorddcebe0f2011-03-15 19:20:44 -04001383def _shadowed_dict(klass):
1384 dict_attr = type.__dict__["__dict__"]
1385 for entry in _static_getmro(klass):
1386 try:
1387 class_dict = dict_attr.__get__(entry)["__dict__"]
1388 except KeyError:
1389 pass
1390 else:
1391 if not (type(class_dict) is types.GetSetDescriptorType and
1392 class_dict.__name__ == "__dict__" and
1393 class_dict.__objclass__ is entry):
Michael Foorda51623b2011-12-18 22:01:40 +00001394 return class_dict
1395 return _sentinel
Michael Foord95fc51d2010-11-20 15:07:30 +00001396
1397def getattr_static(obj, attr, default=_sentinel):
1398 """Retrieve attributes without triggering dynamic lookup via the
1399 descriptor protocol, __getattr__ or __getattribute__.
1400
1401 Note: this function may not be able to retrieve all attributes
1402 that getattr can fetch (like dynamically created attributes)
1403 and may find attributes that getattr can't (like descriptors
1404 that raise AttributeError). It can also return descriptor objects
1405 instead of instance members in some cases. See the
1406 documentation for details.
1407 """
1408 instance_result = _sentinel
Michael Foord35184ed2010-11-20 16:58:30 +00001409 if not _is_type(obj):
Michael Foordcc7ebb82010-11-20 16:20:16 +00001410 klass = type(obj)
Michael Foorda51623b2011-12-18 22:01:40 +00001411 dict_attr = _shadowed_dict(klass)
1412 if (dict_attr is _sentinel or
1413 type(dict_attr) is types.MemberDescriptorType):
Michael Foorddcebe0f2011-03-15 19:20:44 -04001414 instance_result = _check_instance(obj, attr)
Michael Foord95fc51d2010-11-20 15:07:30 +00001415 else:
1416 klass = obj
1417
1418 klass_result = _check_class(klass, attr)
1419
1420 if instance_result is not _sentinel and klass_result is not _sentinel:
1421 if (_check_class(type(klass_result), '__get__') is not _sentinel and
1422 _check_class(type(klass_result), '__set__') is not _sentinel):
1423 return klass_result
1424
1425 if instance_result is not _sentinel:
1426 return instance_result
1427 if klass_result is not _sentinel:
1428 return klass_result
1429
1430 if obj is klass:
1431 # for types we check the metaclass too
Michael Foorde5162652010-11-20 16:40:44 +00001432 for entry in _static_getmro(type(klass)):
Michael Foord3ba95f82011-12-22 01:13:37 +00001433 if _shadowed_dict(type(entry)) is _sentinel:
1434 try:
1435 return entry.__dict__[attr]
1436 except KeyError:
1437 pass
Michael Foord95fc51d2010-11-20 15:07:30 +00001438 if default is not _sentinel:
1439 return default
1440 raise AttributeError(attr)
Nick Coghlane0f04652010-11-21 03:44:04 +00001441
1442
Nick Coghlan04e2e3f2012-06-23 19:52:05 +10001443# ------------------------------------------------ generator introspection
1444
Nick Coghlan7921b9f2010-11-30 06:36:04 +00001445GEN_CREATED = 'GEN_CREATED'
1446GEN_RUNNING = 'GEN_RUNNING'
1447GEN_SUSPENDED = 'GEN_SUSPENDED'
1448GEN_CLOSED = 'GEN_CLOSED'
Nick Coghlane0f04652010-11-21 03:44:04 +00001449
1450def getgeneratorstate(generator):
1451 """Get current state of a generator-iterator.
1452
1453 Possible states are:
1454 GEN_CREATED: Waiting to start execution.
1455 GEN_RUNNING: Currently being executed by the interpreter.
1456 GEN_SUSPENDED: Currently suspended at a yield expression.
1457 GEN_CLOSED: Execution has completed.
1458 """
1459 if generator.gi_running:
1460 return GEN_RUNNING
1461 if generator.gi_frame is None:
1462 return GEN_CLOSED
1463 if generator.gi_frame.f_lasti == -1:
1464 return GEN_CREATED
1465 return GEN_SUSPENDED
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001466
1467
Nick Coghlan04e2e3f2012-06-23 19:52:05 +10001468def getgeneratorlocals(generator):
1469 """
1470 Get the mapping of generator local variables to their current values.
1471
1472 A dict is returned, with the keys the local variable names and values the
1473 bound values."""
1474
1475 if not isgenerator(generator):
1476 raise TypeError("'{!r}' is not a Python generator".format(generator))
1477
1478 frame = getattr(generator, "gi_frame", None)
1479 if frame is not None:
1480 return generator.gi_frame.f_locals
1481 else:
1482 return {}
1483
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001484###############################################################################
1485### Function Signature Object (PEP 362)
1486###############################################################################
1487
1488
1489_WrapperDescriptor = type(type.__call__)
1490_MethodWrapper = type(all.__call__)
Larry Hastings5c661892014-01-24 06:17:25 -08001491_ClassMethodWrapper = type(int.__dict__['from_bytes'])
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001492
1493_NonUserDefinedCallables = (_WrapperDescriptor,
1494 _MethodWrapper,
Larry Hastings5c661892014-01-24 06:17:25 -08001495 _ClassMethodWrapper,
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001496 types.BuiltinFunctionType)
1497
1498
Yury Selivanov421f0c72014-01-29 12:05:40 -05001499def _signature_get_user_defined_method(cls, method_name):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001500 try:
1501 meth = getattr(cls, method_name)
1502 except AttributeError:
1503 return
1504 else:
1505 if not isinstance(meth, _NonUserDefinedCallables):
1506 # Once '__signature__' will be added to 'C'-level
1507 # callables, this check won't be necessary
1508 return meth
1509
1510
Yury Selivanov62560fb2014-01-28 12:26:24 -05001511def _signature_get_partial(wrapped_sig, partial, extra_args=()):
1512 # Internal helper to calculate how 'wrapped_sig' signature will
1513 # look like after applying a 'functools.partial' object (or alike)
1514 # on it.
1515
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001516 new_params = OrderedDict(wrapped_sig.parameters.items())
1517
1518 partial_args = partial.args or ()
1519 partial_keywords = partial.keywords or {}
1520
1521 if extra_args:
1522 partial_args = extra_args + partial_args
1523
1524 try:
1525 ba = wrapped_sig.bind_partial(*partial_args, **partial_keywords)
1526 except TypeError as ex:
1527 msg = 'partial object {!r} has incorrect arguments'.format(partial)
1528 raise ValueError(msg) from ex
1529
1530 for arg_name, arg_value in ba.arguments.items():
1531 param = new_params[arg_name]
1532 if arg_name in partial_keywords:
1533 # We set a new default value, because the following code
1534 # is correct:
1535 #
1536 # >>> def foo(a): print(a)
1537 # >>> print(partial(partial(foo, a=10), a=20)())
1538 # 20
1539 # >>> print(partial(partial(foo, a=10), a=20)(a=30))
1540 # 30
1541 #
1542 # So, with 'partial' objects, passing a keyword argument is
1543 # like setting a new default value for the corresponding
1544 # parameter
1545 #
1546 # We also mark this parameter with '_partial_kwarg'
1547 # flag. Later, in '_bind', the 'default' value of this
1548 # parameter will be added to 'kwargs', to simulate
1549 # the 'functools.partial' real call.
1550 new_params[arg_name] = param.replace(default=arg_value,
1551 _partial_kwarg=True)
1552
1553 elif (param.kind not in (_VAR_KEYWORD, _VAR_POSITIONAL) and
1554 not param._partial_kwarg):
1555 new_params.pop(arg_name)
1556
1557 return wrapped_sig.replace(parameters=new_params.values())
1558
1559
Yury Selivanov62560fb2014-01-28 12:26:24 -05001560def _signature_bound_method(sig):
1561 # Internal helper to transform signatures for unbound
1562 # functions to bound methods
1563
1564 params = tuple(sig.parameters.values())
1565
1566 if not params or params[0].kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
1567 raise ValueError('invalid method signature')
1568
1569 kind = params[0].kind
1570 if kind in (_POSITIONAL_OR_KEYWORD, _POSITIONAL_ONLY):
1571 # Drop first parameter:
1572 # '(p1, p2[, ...])' -> '(p2[, ...])'
1573 params = params[1:]
1574 else:
1575 if kind is not _VAR_POSITIONAL:
1576 # Unless we add a new parameter type we never
1577 # get here
1578 raise ValueError('invalid argument type')
1579 # It's a var-positional parameter.
1580 # Do nothing. '(*args[, ...])' -> '(*args[, ...])'
1581
1582 return sig.replace(parameters=params)
1583
1584
Yury Selivanovb77511d2014-01-29 10:46:14 -05001585def _signature_is_builtin(obj):
1586 # Internal helper to test if `obj` is a callable that might
1587 # support Argument Clinic's __text_signature__ protocol.
Yury Selivanov1d241832014-02-02 12:51:20 -05001588 return (isbuiltin(obj) or
Yury Selivanovb77511d2014-01-29 10:46:14 -05001589 ismethoddescriptor(obj) or
Yury Selivanov1d241832014-02-02 12:51:20 -05001590 isinstance(obj, _NonUserDefinedCallables) or
Yury Selivanovb77511d2014-01-29 10:46:14 -05001591 # Can't test 'isinstance(type)' here, as it would
1592 # also be True for regular python classes
1593 obj in (type, object))
1594
1595
Yury Selivanov63da7c72014-01-31 14:48:37 -05001596def _signature_is_functionlike(obj):
1597 # Internal helper to test if `obj` is a duck type of FunctionType.
1598 # A good example of such objects are functions compiled with
1599 # Cython, which have all attributes that a pure Python function
1600 # would have, but have their code statically compiled.
1601
1602 if not callable(obj) or isclass(obj):
1603 # All function-like objects are obviously callables,
1604 # and not classes.
1605 return False
1606
1607 name = getattr(obj, '__name__', None)
1608 code = getattr(obj, '__code__', None)
1609 defaults = getattr(obj, '__defaults__', _void) # Important to use _void ...
1610 kwdefaults = getattr(obj, '__kwdefaults__', _void) # ... and not None here
1611 annotations = getattr(obj, '__annotations__', None)
1612
1613 return (isinstance(code, types.CodeType) and
1614 isinstance(name, str) and
1615 (defaults is None or isinstance(defaults, tuple)) and
1616 (kwdefaults is None or isinstance(kwdefaults, dict)) and
1617 isinstance(annotations, dict))
1618
1619
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001620def _signature_get_bound_param(spec):
1621 # Internal helper to get first parameter name from a
1622 # __text_signature__ of a builtin method, which should
1623 # be in the following format: '($param1, ...)'.
1624 # Assumptions are that the first argument won't have
1625 # a default value or an annotation.
1626
1627 assert spec.startswith('($')
1628
1629 pos = spec.find(',')
1630 if pos == -1:
1631 pos = spec.find(')')
1632
1633 cpos = spec.find(':')
1634 assert cpos == -1 or cpos > pos
1635
1636 cpos = spec.find('=')
1637 assert cpos == -1 or cpos > pos
1638
1639 return spec[2:pos]
1640
1641
Larry Hastings2623c8c2014-02-08 22:15:29 -08001642def _signature_strip_non_python_syntax(signature):
1643 """
1644 Takes a signature in Argument Clinic's extended signature format.
1645 Returns a tuple of three things:
1646 * that signature re-rendered in standard Python syntax,
1647 * the index of the "self" parameter (generally 0), or None if
1648 the function does not have a "self" parameter, and
1649 * the index of the last "positional only" parameter,
1650 or None if the signature has no positional-only parameters.
1651 """
1652
1653 if not signature:
1654 return signature, None, None
1655
1656 self_parameter = None
1657 last_positional_only = None
1658
1659 lines = [l.encode('ascii') for l in signature.split('\n')]
1660 generator = iter(lines).__next__
1661 token_stream = tokenize.tokenize(generator)
1662
1663 delayed_comma = False
1664 skip_next_comma = False
1665 text = []
1666 add = text.append
1667
1668 current_parameter = 0
1669 OP = token.OP
1670 ERRORTOKEN = token.ERRORTOKEN
1671
1672 # token stream always starts with ENCODING token, skip it
1673 t = next(token_stream)
1674 assert t.type == tokenize.ENCODING
1675
1676 for t in token_stream:
1677 type, string = t.type, t.string
1678
1679 if type == OP:
1680 if string == ',':
1681 if skip_next_comma:
1682 skip_next_comma = False
1683 else:
1684 assert not delayed_comma
1685 delayed_comma = True
1686 current_parameter += 1
1687 continue
1688
1689 if string == '/':
1690 assert not skip_next_comma
1691 assert last_positional_only is None
1692 skip_next_comma = True
1693 last_positional_only = current_parameter - 1
1694 continue
1695
1696 if (type == ERRORTOKEN) and (string == '$'):
1697 assert self_parameter is None
1698 self_parameter = current_parameter
1699 continue
1700
1701 if delayed_comma:
1702 delayed_comma = False
1703 if not ((type == OP) and (string == ')')):
1704 add(', ')
1705 add(string)
1706 if (string == ','):
1707 add(' ')
1708 clean_signature = ''.join(text)
1709 return clean_signature, self_parameter, last_positional_only
1710
1711
Yury Selivanov57d240e2014-02-19 16:27:23 -05001712def _signature_fromstr(cls, obj, s, skip_bound_arg=True):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001713 # Internal helper to parse content of '__text_signature__'
1714 # and return a Signature based on it
1715 Parameter = cls._parameter_cls
1716
Larry Hastings2623c8c2014-02-08 22:15:29 -08001717 clean_signature, self_parameter, last_positional_only = \
1718 _signature_strip_non_python_syntax(s)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001719
Larry Hastings2623c8c2014-02-08 22:15:29 -08001720 program = "def foo" + clean_signature + ": pass"
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001721
1722 try:
Larry Hastings2623c8c2014-02-08 22:15:29 -08001723 module = ast.parse(program)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001724 except SyntaxError:
1725 module = None
1726
1727 if not isinstance(module, ast.Module):
1728 raise ValueError("{!r} builtin has invalid signature".format(obj))
1729
1730 f = module.body[0]
1731
1732 parameters = []
1733 empty = Parameter.empty
1734 invalid = object()
1735
1736 module = None
1737 module_dict = {}
1738 module_name = getattr(obj, '__module__', None)
1739 if module_name:
1740 module = sys.modules.get(module_name, None)
1741 if module:
1742 module_dict = module.__dict__
1743 sys_module_dict = sys.modules
1744
1745 def parse_name(node):
1746 assert isinstance(node, ast.arg)
1747 if node.annotation != None:
1748 raise ValueError("Annotations are not currently supported")
1749 return node.arg
1750
1751 def wrap_value(s):
1752 try:
1753 value = eval(s, module_dict)
1754 except NameError:
1755 try:
1756 value = eval(s, sys_module_dict)
1757 except NameError:
1758 raise RuntimeError()
1759
1760 if isinstance(value, str):
1761 return ast.Str(value)
1762 if isinstance(value, (int, float)):
1763 return ast.Num(value)
1764 if isinstance(value, bytes):
1765 return ast.Bytes(value)
1766 if value in (True, False, None):
1767 return ast.NameConstant(value)
1768 raise RuntimeError()
1769
1770 class RewriteSymbolics(ast.NodeTransformer):
1771 def visit_Attribute(self, node):
1772 a = []
1773 n = node
1774 while isinstance(n, ast.Attribute):
1775 a.append(n.attr)
1776 n = n.value
1777 if not isinstance(n, ast.Name):
1778 raise RuntimeError()
1779 a.append(n.id)
1780 value = ".".join(reversed(a))
1781 return wrap_value(value)
1782
1783 def visit_Name(self, node):
1784 if not isinstance(node.ctx, ast.Load):
1785 raise ValueError()
1786 return wrap_value(node.id)
1787
1788 def p(name_node, default_node, default=empty):
1789 name = parse_name(name_node)
1790 if name is invalid:
1791 return None
1792 if default_node and default_node is not _empty:
1793 try:
1794 default_node = RewriteSymbolics().visit(default_node)
1795 o = ast.literal_eval(default_node)
1796 except ValueError:
1797 o = invalid
1798 if o is invalid:
1799 return None
1800 default = o if o is not invalid else default
1801 parameters.append(Parameter(name, kind, default=default, annotation=empty))
1802
1803 # non-keyword-only parameters
1804 args = reversed(f.args.args)
1805 defaults = reversed(f.args.defaults)
1806 iter = itertools.zip_longest(args, defaults, fillvalue=None)
Larry Hastings2623c8c2014-02-08 22:15:29 -08001807 if last_positional_only is not None:
1808 kind = Parameter.POSITIONAL_ONLY
1809 else:
1810 kind = Parameter.POSITIONAL_OR_KEYWORD
1811 for i, (name, default) in enumerate(reversed(list(iter))):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001812 p(name, default)
Larry Hastings2623c8c2014-02-08 22:15:29 -08001813 if i == last_positional_only:
1814 kind = Parameter.POSITIONAL_OR_KEYWORD
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001815
1816 # *args
1817 if f.args.vararg:
1818 kind = Parameter.VAR_POSITIONAL
1819 p(f.args.vararg, empty)
1820
1821 # keyword-only arguments
1822 kind = Parameter.KEYWORD_ONLY
1823 for name, default in zip(f.args.kwonlyargs, f.args.kw_defaults):
1824 p(name, default)
1825
1826 # **kwargs
1827 if f.args.kwarg:
1828 kind = Parameter.VAR_KEYWORD
1829 p(f.args.kwarg, empty)
1830
Larry Hastings2623c8c2014-02-08 22:15:29 -08001831 if self_parameter is not None:
Yury Selivanov8c185ee2014-02-21 01:32:42 -05001832 # Possibly strip the bound argument:
1833 # - We *always* strip first bound argument if
1834 # it is a module.
1835 # - We don't strip first bound argument if
1836 # skip_bound_arg is False.
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001837 assert parameters
Yury Selivanov8c185ee2014-02-21 01:32:42 -05001838 _self = getattr(obj, '__self__', None)
1839 self_isbound = _self is not None
1840 self_ismodule = ismodule(_self)
1841 if self_isbound and (self_ismodule or skip_bound_arg):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001842 parameters.pop(0)
1843 else:
1844 # for builtins, self parameter is always positional-only!
1845 p = parameters[0].replace(kind=Parameter.POSITIONAL_ONLY)
1846 parameters[0] = p
1847
1848 return cls(parameters, return_annotation=cls.empty)
1849
1850
Yury Selivanov57d240e2014-02-19 16:27:23 -05001851def _signature_from_builtin(cls, func, skip_bound_arg=True):
1852 # Internal helper function to get signature for
1853 # builtin callables
1854 if not _signature_is_builtin(func):
1855 raise TypeError("{!r} is not a Python builtin "
1856 "function".format(func))
1857
1858 s = getattr(func, "__text_signature__", None)
1859 if not s:
1860 raise ValueError("no signature found for builtin {!r}".format(func))
1861
1862 return _signature_fromstr(cls, func, s, skip_bound_arg)
1863
1864
Yury Selivanovda396452014-03-27 12:09:24 -04001865def _signature_internal(obj, *,
1866 follow_wrapper_chains=True,
1867 skip_bound_arg=True,
1868 sigcls):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001869
1870 if not callable(obj):
1871 raise TypeError('{!r} is not a callable object'.format(obj))
1872
1873 if isinstance(obj, types.MethodType):
1874 # In this case we skip the first parameter of the underlying
1875 # function (usually `self` or `cls`).
Yury Selivanovda396452014-03-27 12:09:24 -04001876 sig = _signature_internal(
1877 obj.__func__,
1878 follow_wrapper_chains=follow_wrapper_chains,
1879 skip_bound_arg=skip_bound_arg,
1880 sigcls=sigcls)
1881
Yury Selivanov57d240e2014-02-19 16:27:23 -05001882 if skip_bound_arg:
1883 return _signature_bound_method(sig)
1884 else:
1885 return sig
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001886
Nick Coghlane8c45d62013-07-28 20:00:01 +10001887 # Was this function wrapped by a decorator?
Yury Selivanov57d240e2014-02-19 16:27:23 -05001888 if follow_wrapper_chains:
1889 obj = unwrap(obj, stop=(lambda f: hasattr(f, "__signature__")))
Nick Coghlane8c45d62013-07-28 20:00:01 +10001890
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001891 try:
1892 sig = obj.__signature__
1893 except AttributeError:
1894 pass
1895 else:
1896 if sig is not None:
1897 return sig
1898
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001899 try:
1900 partialmethod = obj._partialmethod
1901 except AttributeError:
1902 pass
1903 else:
Yury Selivanov0486f812014-01-29 12:18:59 -05001904 if isinstance(partialmethod, functools.partialmethod):
1905 # Unbound partialmethod (see functools.partialmethod)
1906 # This means, that we need to calculate the signature
1907 # as if it's a regular partial object, but taking into
1908 # account that the first positional argument
1909 # (usually `self`, or `cls`) will not be passed
1910 # automatically (as for boundmethods)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001911
Yury Selivanovda396452014-03-27 12:09:24 -04001912 wrapped_sig = _signature_internal(
1913 partialmethod.func,
1914 follow_wrapper_chains=follow_wrapper_chains,
1915 skip_bound_arg=skip_bound_arg,
1916 sigcls=sigcls)
1917
Yury Selivanov0486f812014-01-29 12:18:59 -05001918 sig = _signature_get_partial(wrapped_sig, partialmethod, (None,))
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001919
Yury Selivanov0486f812014-01-29 12:18:59 -05001920 first_wrapped_param = tuple(wrapped_sig.parameters.values())[0]
1921 new_params = (first_wrapped_param,) + tuple(sig.parameters.values())
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001922
Yury Selivanov0486f812014-01-29 12:18:59 -05001923 return sig.replace(parameters=new_params)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001924
Yury Selivanov63da7c72014-01-31 14:48:37 -05001925 if isfunction(obj) or _signature_is_functionlike(obj):
1926 # If it's a pure Python function, or an object that is duck type
1927 # of a Python function (Cython functions, for instance), then:
Yury Selivanovda396452014-03-27 12:09:24 -04001928 return sigcls.from_function(obj)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001929
Yury Selivanova773de02014-02-21 18:30:53 -05001930 if _signature_is_builtin(obj):
Yury Selivanovda396452014-03-27 12:09:24 -04001931 return _signature_from_builtin(sigcls, obj,
Yury Selivanova773de02014-02-21 18:30:53 -05001932 skip_bound_arg=skip_bound_arg)
1933
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001934 if isinstance(obj, functools.partial):
Yury Selivanovda396452014-03-27 12:09:24 -04001935 wrapped_sig = _signature_internal(
1936 obj.func,
1937 follow_wrapper_chains=follow_wrapper_chains,
1938 skip_bound_arg=skip_bound_arg,
1939 sigcls=sigcls)
Yury Selivanov62560fb2014-01-28 12:26:24 -05001940 return _signature_get_partial(wrapped_sig, obj)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001941
1942 sig = None
1943 if isinstance(obj, type):
1944 # obj is a class or a metaclass
1945
1946 # First, let's see if it has an overloaded __call__ defined
1947 # in its metaclass
Yury Selivanov421f0c72014-01-29 12:05:40 -05001948 call = _signature_get_user_defined_method(type(obj), '__call__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001949 if call is not None:
Yury Selivanovda396452014-03-27 12:09:24 -04001950 sig = _signature_internal(
1951 call,
1952 follow_wrapper_chains=follow_wrapper_chains,
1953 skip_bound_arg=skip_bound_arg,
1954 sigcls=sigcls)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001955 else:
1956 # Now we check if the 'obj' class has a '__new__' method
Yury Selivanov421f0c72014-01-29 12:05:40 -05001957 new = _signature_get_user_defined_method(obj, '__new__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001958 if new is not None:
Yury Selivanovda396452014-03-27 12:09:24 -04001959 sig = _signature_internal(
1960 new,
1961 follow_wrapper_chains=follow_wrapper_chains,
1962 skip_bound_arg=skip_bound_arg,
1963 sigcls=sigcls)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001964 else:
1965 # Finally, we should have at least __init__ implemented
Yury Selivanov421f0c72014-01-29 12:05:40 -05001966 init = _signature_get_user_defined_method(obj, '__init__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001967 if init is not None:
Yury Selivanovda396452014-03-27 12:09:24 -04001968 sig = _signature_internal(
1969 init,
1970 follow_wrapper_chains=follow_wrapper_chains,
1971 skip_bound_arg=skip_bound_arg,
1972 sigcls=sigcls)
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05001973
1974 if sig is None:
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001975 # At this point we know, that `obj` is a class, with no user-
1976 # defined '__init__', '__new__', or class-level '__call__'
1977
Larry Hastings2623c8c2014-02-08 22:15:29 -08001978 for base in obj.__mro__[:-1]:
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001979 # Since '__text_signature__' is implemented as a
1980 # descriptor that extracts text signature from the
1981 # class docstring, if 'obj' is derived from a builtin
1982 # class, its own '__text_signature__' may be 'None'.
Larry Hastings2623c8c2014-02-08 22:15:29 -08001983 # Therefore, we go through the MRO (except the last
1984 # class in there, which is 'object') to find the first
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001985 # class with non-empty text signature.
1986 try:
1987 text_sig = base.__text_signature__
1988 except AttributeError:
1989 pass
1990 else:
1991 if text_sig:
1992 # If 'obj' class has a __text_signature__ attribute:
1993 # return a signature based on it
Yury Selivanovda396452014-03-27 12:09:24 -04001994 return _signature_fromstr(sigcls, obj, text_sig)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001995
1996 # No '__text_signature__' was found for the 'obj' class.
1997 # Last option is to check if its '__init__' is
1998 # object.__init__ or type.__init__.
Larry Hastings2623c8c2014-02-08 22:15:29 -08001999 if type not in obj.__mro__:
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002000 # We have a class (not metaclass), but no user-defined
2001 # __init__ or __new__ for it
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002002 if obj.__init__ is object.__init__:
2003 # Return a signature of 'object' builtin.
2004 return signature(object)
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002005
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002006 elif not isinstance(obj, _NonUserDefinedCallables):
2007 # An object with __call__
2008 # We also check that the 'obj' is not an instance of
2009 # _WrapperDescriptor or _MethodWrapper to avoid
2010 # infinite recursion (and even potential segfault)
Yury Selivanov421f0c72014-01-29 12:05:40 -05002011 call = _signature_get_user_defined_method(type(obj), '__call__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002012 if call is not None:
Larry Hastings2623c8c2014-02-08 22:15:29 -08002013 try:
Yury Selivanovda396452014-03-27 12:09:24 -04002014 sig = _signature_internal(
2015 call,
2016 follow_wrapper_chains=follow_wrapper_chains,
2017 skip_bound_arg=skip_bound_arg,
2018 sigcls=sigcls)
Larry Hastings2623c8c2014-02-08 22:15:29 -08002019 except ValueError as ex:
2020 msg = 'no signature found for {!r}'.format(obj)
2021 raise ValueError(msg) from ex
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002022
2023 if sig is not None:
2024 # For classes and objects we skip the first parameter of their
2025 # __call__, __new__, or __init__ methods
Yury Selivanov57d240e2014-02-19 16:27:23 -05002026 if skip_bound_arg:
2027 return _signature_bound_method(sig)
2028 else:
2029 return sig
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002030
2031 if isinstance(obj, types.BuiltinFunctionType):
2032 # Raise a nicer error message for builtins
2033 msg = 'no signature found for builtin function {!r}'.format(obj)
2034 raise ValueError(msg)
2035
2036 raise ValueError('callable {!r} is not supported by signature'.format(obj))
2037
2038
2039class _void:
2040 '''A private marker - used in Parameter & Signature'''
2041
2042
2043class _empty:
2044 pass
2045
2046
Yury Selivanov21e83a52014-03-27 11:23:13 -04002047class _ParameterKind(enum.IntEnum):
2048 POSITIONAL_ONLY = 0
2049 POSITIONAL_OR_KEYWORD = 1
2050 VAR_POSITIONAL = 2
2051 KEYWORD_ONLY = 3
2052 VAR_KEYWORD = 4
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002053
2054 def __str__(self):
Yury Selivanov21e83a52014-03-27 11:23:13 -04002055 return self._name_
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002056
2057
Yury Selivanov21e83a52014-03-27 11:23:13 -04002058_POSITIONAL_ONLY = _ParameterKind.POSITIONAL_ONLY
2059_POSITIONAL_OR_KEYWORD = _ParameterKind.POSITIONAL_OR_KEYWORD
2060_VAR_POSITIONAL = _ParameterKind.VAR_POSITIONAL
2061_KEYWORD_ONLY = _ParameterKind.KEYWORD_ONLY
2062_VAR_KEYWORD = _ParameterKind.VAR_KEYWORD
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002063
2064
2065class Parameter:
2066 '''Represents a parameter in a function signature.
2067
2068 Has the following public attributes:
2069
2070 * name : str
2071 The name of the parameter as a string.
2072 * default : object
2073 The default value for the parameter if specified. If the
Yury Selivanov8757ead2014-01-28 16:39:25 -05002074 parameter has no default value, this attribute is set to
2075 `Parameter.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002076 * annotation
2077 The annotation for the parameter if specified. If the
Yury Selivanov8757ead2014-01-28 16:39:25 -05002078 parameter has no annotation, this attribute is set to
2079 `Parameter.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002080 * kind : str
2081 Describes how argument values are bound to the parameter.
2082 Possible values: `Parameter.POSITIONAL_ONLY`,
2083 `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
2084 `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
2085 '''
2086
2087 __slots__ = ('_name', '_kind', '_default', '_annotation', '_partial_kwarg')
2088
2089 POSITIONAL_ONLY = _POSITIONAL_ONLY
2090 POSITIONAL_OR_KEYWORD = _POSITIONAL_OR_KEYWORD
2091 VAR_POSITIONAL = _VAR_POSITIONAL
2092 KEYWORD_ONLY = _KEYWORD_ONLY
2093 VAR_KEYWORD = _VAR_KEYWORD
2094
2095 empty = _empty
2096
2097 def __init__(self, name, kind, *, default=_empty, annotation=_empty,
2098 _partial_kwarg=False):
2099
2100 if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
2101 _VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
2102 raise ValueError("invalid value for 'Parameter.kind' attribute")
2103 self._kind = kind
2104
2105 if default is not _empty:
2106 if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
2107 msg = '{} parameters cannot have default values'.format(kind)
2108 raise ValueError(msg)
2109 self._default = default
2110 self._annotation = annotation
2111
Yury Selivanov2393dca2014-01-27 15:07:58 -05002112 if name is _empty:
2113 raise ValueError('name is a required attribute for Parameter')
2114
2115 if not isinstance(name, str):
2116 raise TypeError("name must be a str, not a {!r}".format(name))
2117
2118 if not name.isidentifier():
2119 raise ValueError('{!r} is not a valid parameter name'.format(name))
2120
2121 self._name = name
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002122
2123 self._partial_kwarg = _partial_kwarg
2124
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002125 def __reduce__(self):
2126 return (type(self),
2127 (self._name, self._kind),
2128 {'_partial_kwarg': self._partial_kwarg,
2129 '_default': self._default,
2130 '_annotation': self._annotation})
2131
2132 def __setstate__(self, state):
2133 self._partial_kwarg = state['_partial_kwarg']
2134 self._default = state['_default']
2135 self._annotation = state['_annotation']
2136
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002137 @property
2138 def name(self):
2139 return self._name
2140
2141 @property
2142 def default(self):
2143 return self._default
2144
2145 @property
2146 def annotation(self):
2147 return self._annotation
2148
2149 @property
2150 def kind(self):
2151 return self._kind
2152
2153 def replace(self, *, name=_void, kind=_void, annotation=_void,
2154 default=_void, _partial_kwarg=_void):
2155 '''Creates a customized copy of the Parameter.'''
2156
2157 if name is _void:
2158 name = self._name
2159
2160 if kind is _void:
2161 kind = self._kind
2162
2163 if annotation is _void:
2164 annotation = self._annotation
2165
2166 if default is _void:
2167 default = self._default
2168
2169 if _partial_kwarg is _void:
2170 _partial_kwarg = self._partial_kwarg
2171
2172 return type(self)(name, kind, default=default, annotation=annotation,
2173 _partial_kwarg=_partial_kwarg)
2174
2175 def __str__(self):
2176 kind = self.kind
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002177 formatted = self._name
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002178
2179 # Add annotation and default value
2180 if self._annotation is not _empty:
2181 formatted = '{}:{}'.format(formatted,
2182 formatannotation(self._annotation))
2183
2184 if self._default is not _empty:
2185 formatted = '{}={}'.format(formatted, repr(self._default))
2186
2187 if kind == _VAR_POSITIONAL:
2188 formatted = '*' + formatted
2189 elif kind == _VAR_KEYWORD:
2190 formatted = '**' + formatted
2191
2192 return formatted
2193
2194 def __repr__(self):
Yury Selivanov374375d2014-03-27 12:41:53 -04002195 return '<{} at {:#x} "{}">'.format(self.__class__.__name__,
2196 id(self), self)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002197
2198 def __eq__(self, other):
Yury Selivanov0ba5f0d2014-01-31 15:30:30 -05002199 # NB: We deliberately do not compare '_partial_kwarg' attributes
2200 # here. Imagine we have a following situation:
2201 #
2202 # def foo(a, b=1): pass
2203 # def bar(a, b): pass
2204 # bar2 = functools.partial(bar, b=1)
2205 #
2206 # For the above scenario, signatures for `foo` and `bar2` should
2207 # be equal. '_partial_kwarg' attribute is an internal flag, to
2208 # distinguish between keyword parameters with defaults and
2209 # keyword parameters which got their defaults from functools.partial
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002210 return (issubclass(other.__class__, Parameter) and
2211 self._name == other._name and
2212 self._kind == other._kind and
2213 self._default == other._default and
2214 self._annotation == other._annotation)
2215
2216 def __ne__(self, other):
2217 return not self.__eq__(other)
2218
2219
2220class BoundArguments:
2221 '''Result of `Signature.bind` call. Holds the mapping of arguments
2222 to the function's parameters.
2223
2224 Has the following public attributes:
2225
2226 * arguments : OrderedDict
2227 An ordered mutable mapping of parameters' names to arguments' values.
2228 Does not contain arguments' default values.
2229 * signature : Signature
2230 The Signature object that created this instance.
2231 * args : tuple
2232 Tuple of positional arguments values.
2233 * kwargs : dict
2234 Dict of keyword arguments values.
2235 '''
2236
2237 def __init__(self, signature, arguments):
2238 self.arguments = arguments
2239 self._signature = signature
2240
2241 @property
2242 def signature(self):
2243 return self._signature
2244
2245 @property
2246 def args(self):
2247 args = []
2248 for param_name, param in self._signature.parameters.items():
2249 if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
2250 param._partial_kwarg):
2251 # Keyword arguments mapped by 'functools.partial'
2252 # (Parameter._partial_kwarg is True) are mapped
2253 # in 'BoundArguments.kwargs', along with VAR_KEYWORD &
2254 # KEYWORD_ONLY
2255 break
2256
2257 try:
2258 arg = self.arguments[param_name]
2259 except KeyError:
2260 # We're done here. Other arguments
2261 # will be mapped in 'BoundArguments.kwargs'
2262 break
2263 else:
2264 if param.kind == _VAR_POSITIONAL:
2265 # *args
2266 args.extend(arg)
2267 else:
2268 # plain argument
2269 args.append(arg)
2270
2271 return tuple(args)
2272
2273 @property
2274 def kwargs(self):
2275 kwargs = {}
2276 kwargs_started = False
2277 for param_name, param in self._signature.parameters.items():
2278 if not kwargs_started:
2279 if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
2280 param._partial_kwarg):
2281 kwargs_started = True
2282 else:
2283 if param_name not in self.arguments:
2284 kwargs_started = True
2285 continue
2286
2287 if not kwargs_started:
2288 continue
2289
2290 try:
2291 arg = self.arguments[param_name]
2292 except KeyError:
2293 pass
2294 else:
2295 if param.kind == _VAR_KEYWORD:
2296 # **kwargs
2297 kwargs.update(arg)
2298 else:
2299 # plain keyword argument
2300 kwargs[param_name] = arg
2301
2302 return kwargs
2303
2304 def __eq__(self, other):
2305 return (issubclass(other.__class__, BoundArguments) and
2306 self.signature == other.signature and
2307 self.arguments == other.arguments)
2308
2309 def __ne__(self, other):
2310 return not self.__eq__(other)
2311
2312
2313class Signature:
2314 '''A Signature object represents the overall signature of a function.
2315 It stores a Parameter object for each parameter accepted by the
2316 function, as well as information specific to the function itself.
2317
2318 A Signature object has the following public attributes and methods:
2319
2320 * parameters : OrderedDict
2321 An ordered mapping of parameters' names to the corresponding
2322 Parameter objects (keyword-only arguments are in the same order
2323 as listed in `code.co_varnames`).
2324 * return_annotation : object
2325 The annotation for the return type of the function if specified.
2326 If the function has no annotation for its return type, this
Yury Selivanov8757ead2014-01-28 16:39:25 -05002327 attribute is set to `Signature.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002328 * bind(*args, **kwargs) -> BoundArguments
2329 Creates a mapping from positional and keyword arguments to
2330 parameters.
2331 * bind_partial(*args, **kwargs) -> BoundArguments
2332 Creates a partial mapping from positional and keyword arguments
2333 to parameters (simulating 'functools.partial' behavior.)
2334 '''
2335
2336 __slots__ = ('_return_annotation', '_parameters')
2337
2338 _parameter_cls = Parameter
2339 _bound_arguments_cls = BoundArguments
2340
2341 empty = _empty
2342
2343 def __init__(self, parameters=None, *, return_annotation=_empty,
2344 __validate_parameters__=True):
2345 '''Constructs Signature from the given list of Parameter
2346 objects and 'return_annotation'. All arguments are optional.
2347 '''
2348
2349 if parameters is None:
2350 params = OrderedDict()
2351 else:
2352 if __validate_parameters__:
2353 params = OrderedDict()
2354 top_kind = _POSITIONAL_ONLY
Yury Selivanov07a9e452014-01-29 10:58:16 -05002355 kind_defaults = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002356
2357 for idx, param in enumerate(parameters):
2358 kind = param.kind
Yury Selivanov2393dca2014-01-27 15:07:58 -05002359 name = param.name
2360
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002361 if kind < top_kind:
2362 msg = 'wrong parameter order: {} before {}'
Yury Selivanov2393dca2014-01-27 15:07:58 -05002363 msg = msg.format(top_kind, kind)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002364 raise ValueError(msg)
Yury Selivanov07a9e452014-01-29 10:58:16 -05002365 elif kind > top_kind:
2366 kind_defaults = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002367 top_kind = kind
2368
Yury Selivanov07a9e452014-01-29 10:58:16 -05002369 if (kind in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD) and
2370 not param._partial_kwarg):
2371 # If we have a positional-only or positional-or-keyword
2372 # parameter, that does not have its default value set
2373 # by 'functools.partial' or other "partial" signature:
2374 if param.default is _empty:
2375 if kind_defaults:
2376 # No default for this parameter, but the
2377 # previous parameter of the same kind had
2378 # a default
2379 msg = 'non-default argument follows default ' \
2380 'argument'
2381 raise ValueError(msg)
2382 else:
2383 # There is a default for this parameter.
2384 kind_defaults = True
2385
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002386 if name in params:
2387 msg = 'duplicate parameter name: {!r}'.format(name)
2388 raise ValueError(msg)
Yury Selivanov2393dca2014-01-27 15:07:58 -05002389
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002390 params[name] = param
2391 else:
2392 params = OrderedDict(((param.name, param)
2393 for param in parameters))
2394
2395 self._parameters = types.MappingProxyType(params)
2396 self._return_annotation = return_annotation
2397
2398 @classmethod
2399 def from_function(cls, func):
2400 '''Constructs Signature for the given python function'''
2401
Yury Selivanov5334bcd2014-01-31 15:21:51 -05002402 is_duck_function = False
2403 if not isfunction(func):
2404 if _signature_is_functionlike(func):
2405 is_duck_function = True
2406 else:
2407 # If it's not a pure Python function, and not a duck type
2408 # of pure function:
2409 raise TypeError('{!r} is not a Python function'.format(func))
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002410
2411 Parameter = cls._parameter_cls
2412
2413 # Parameter information.
2414 func_code = func.__code__
2415 pos_count = func_code.co_argcount
2416 arg_names = func_code.co_varnames
2417 positional = tuple(arg_names[:pos_count])
2418 keyword_only_count = func_code.co_kwonlyargcount
2419 keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
2420 annotations = func.__annotations__
2421 defaults = func.__defaults__
2422 kwdefaults = func.__kwdefaults__
2423
2424 if defaults:
2425 pos_default_count = len(defaults)
2426 else:
2427 pos_default_count = 0
2428
2429 parameters = []
2430
2431 # Non-keyword-only parameters w/o defaults.
2432 non_default_count = pos_count - pos_default_count
2433 for name in positional[:non_default_count]:
2434 annotation = annotations.get(name, _empty)
2435 parameters.append(Parameter(name, annotation=annotation,
2436 kind=_POSITIONAL_OR_KEYWORD))
2437
2438 # ... w/ defaults.
2439 for offset, name in enumerate(positional[non_default_count:]):
2440 annotation = annotations.get(name, _empty)
2441 parameters.append(Parameter(name, annotation=annotation,
2442 kind=_POSITIONAL_OR_KEYWORD,
2443 default=defaults[offset]))
2444
2445 # *args
Yury Selivanov89ca85c2014-01-29 16:50:40 -05002446 if func_code.co_flags & CO_VARARGS:
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002447 name = arg_names[pos_count + keyword_only_count]
2448 annotation = annotations.get(name, _empty)
2449 parameters.append(Parameter(name, annotation=annotation,
2450 kind=_VAR_POSITIONAL))
2451
2452 # Keyword-only parameters.
2453 for name in keyword_only:
2454 default = _empty
2455 if kwdefaults is not None:
2456 default = kwdefaults.get(name, _empty)
2457
2458 annotation = annotations.get(name, _empty)
2459 parameters.append(Parameter(name, annotation=annotation,
2460 kind=_KEYWORD_ONLY,
2461 default=default))
2462 # **kwargs
Yury Selivanov89ca85c2014-01-29 16:50:40 -05002463 if func_code.co_flags & CO_VARKEYWORDS:
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002464 index = pos_count + keyword_only_count
Yury Selivanov89ca85c2014-01-29 16:50:40 -05002465 if func_code.co_flags & CO_VARARGS:
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002466 index += 1
2467
2468 name = arg_names[index]
2469 annotation = annotations.get(name, _empty)
2470 parameters.append(Parameter(name, annotation=annotation,
2471 kind=_VAR_KEYWORD))
2472
Yury Selivanov5334bcd2014-01-31 15:21:51 -05002473 # Is 'func' is a pure Python function - don't validate the
2474 # parameters list (for correct order and defaults), it should be OK.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002475 return cls(parameters,
2476 return_annotation=annotations.get('return', _empty),
Yury Selivanov5334bcd2014-01-31 15:21:51 -05002477 __validate_parameters__=is_duck_function)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002478
Larry Hastings44e2eaa2013-11-23 15:37:55 -08002479 @classmethod
2480 def from_builtin(cls, func):
Yury Selivanov57d240e2014-02-19 16:27:23 -05002481 return _signature_from_builtin(cls, func)
Larry Hastings44e2eaa2013-11-23 15:37:55 -08002482
Yury Selivanovda396452014-03-27 12:09:24 -04002483 @classmethod
2484 def from_callable(cls, obj):
2485 return _signature_internal(obj, sigcls=cls)
2486
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002487 @property
2488 def parameters(self):
2489 return self._parameters
2490
2491 @property
2492 def return_annotation(self):
2493 return self._return_annotation
2494
2495 def replace(self, *, parameters=_void, return_annotation=_void):
2496 '''Creates a customized copy of the Signature.
2497 Pass 'parameters' and/or 'return_annotation' arguments
2498 to override them in the new copy.
2499 '''
2500
2501 if parameters is _void:
2502 parameters = self.parameters.values()
2503
2504 if return_annotation is _void:
2505 return_annotation = self._return_annotation
2506
2507 return type(self)(parameters,
2508 return_annotation=return_annotation)
2509
2510 def __eq__(self, other):
2511 if (not issubclass(type(other), Signature) or
2512 self.return_annotation != other.return_annotation or
2513 len(self.parameters) != len(other.parameters)):
2514 return False
2515
2516 other_positions = {param: idx
2517 for idx, param in enumerate(other.parameters.keys())}
2518
2519 for idx, (param_name, param) in enumerate(self.parameters.items()):
2520 if param.kind == _KEYWORD_ONLY:
2521 try:
2522 other_param = other.parameters[param_name]
2523 except KeyError:
2524 return False
2525 else:
2526 if param != other_param:
2527 return False
2528 else:
2529 try:
2530 other_idx = other_positions[param_name]
2531 except KeyError:
2532 return False
2533 else:
2534 if (idx != other_idx or
2535 param != other.parameters[param_name]):
2536 return False
2537
2538 return True
2539
2540 def __ne__(self, other):
2541 return not self.__eq__(other)
2542
2543 def _bind(self, args, kwargs, *, partial=False):
2544 '''Private method. Don't use directly.'''
2545
2546 arguments = OrderedDict()
2547
2548 parameters = iter(self.parameters.values())
2549 parameters_ex = ()
2550 arg_vals = iter(args)
2551
2552 if partial:
2553 # Support for binding arguments to 'functools.partial' objects.
2554 # See 'functools.partial' case in 'signature()' implementation
2555 # for details.
2556 for param_name, param in self.parameters.items():
2557 if (param._partial_kwarg and param_name not in kwargs):
2558 # Simulating 'functools.partial' behavior
2559 kwargs[param_name] = param.default
2560
2561 while True:
2562 # Let's iterate through the positional arguments and corresponding
2563 # parameters
2564 try:
2565 arg_val = next(arg_vals)
2566 except StopIteration:
2567 # No more positional arguments
2568 try:
2569 param = next(parameters)
2570 except StopIteration:
2571 # No more parameters. That's it. Just need to check that
2572 # we have no `kwargs` after this while loop
2573 break
2574 else:
2575 if param.kind == _VAR_POSITIONAL:
2576 # That's OK, just empty *args. Let's start parsing
2577 # kwargs
2578 break
2579 elif param.name in kwargs:
2580 if param.kind == _POSITIONAL_ONLY:
2581 msg = '{arg!r} parameter is positional only, ' \
2582 'but was passed as a keyword'
2583 msg = msg.format(arg=param.name)
2584 raise TypeError(msg) from None
2585 parameters_ex = (param,)
2586 break
2587 elif (param.kind == _VAR_KEYWORD or
2588 param.default is not _empty):
2589 # That's fine too - we have a default value for this
2590 # parameter. So, lets start parsing `kwargs`, starting
2591 # with the current parameter
2592 parameters_ex = (param,)
2593 break
2594 else:
Yury Selivanov38b0d5a2014-01-28 17:27:39 -05002595 # No default, not VAR_KEYWORD, not VAR_POSITIONAL,
2596 # not in `kwargs`
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002597 if partial:
2598 parameters_ex = (param,)
2599 break
2600 else:
2601 msg = '{arg!r} parameter lacking default value'
2602 msg = msg.format(arg=param.name)
2603 raise TypeError(msg) from None
2604 else:
2605 # We have a positional argument to process
2606 try:
2607 param = next(parameters)
2608 except StopIteration:
2609 raise TypeError('too many positional arguments') from None
2610 else:
2611 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
2612 # Looks like we have no parameter for this positional
2613 # argument
2614 raise TypeError('too many positional arguments')
2615
2616 if param.kind == _VAR_POSITIONAL:
2617 # We have an '*args'-like argument, let's fill it with
2618 # all positional arguments we have left and move on to
2619 # the next phase
2620 values = [arg_val]
2621 values.extend(arg_vals)
2622 arguments[param.name] = tuple(values)
2623 break
2624
2625 if param.name in kwargs:
2626 raise TypeError('multiple values for argument '
2627 '{arg!r}'.format(arg=param.name))
2628
2629 arguments[param.name] = arg_val
2630
2631 # Now, we iterate through the remaining parameters to process
2632 # keyword arguments
2633 kwargs_param = None
2634 for param in itertools.chain(parameters_ex, parameters):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002635 if param.kind == _VAR_KEYWORD:
2636 # Memorize that we have a '**kwargs'-like parameter
2637 kwargs_param = param
2638 continue
2639
Yury Selivanov38b0d5a2014-01-28 17:27:39 -05002640 if param.kind == _VAR_POSITIONAL:
2641 # Named arguments don't refer to '*args'-like parameters.
2642 # We only arrive here if the positional arguments ended
2643 # before reaching the last parameter before *args.
2644 continue
2645
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002646 param_name = param.name
2647 try:
2648 arg_val = kwargs.pop(param_name)
2649 except KeyError:
2650 # We have no value for this parameter. It's fine though,
2651 # if it has a default value, or it is an '*args'-like
2652 # parameter, left alone by the processing of positional
2653 # arguments.
2654 if (not partial and param.kind != _VAR_POSITIONAL and
2655 param.default is _empty):
2656 raise TypeError('{arg!r} parameter lacking default value'. \
2657 format(arg=param_name)) from None
2658
2659 else:
Yury Selivanov9b9ac952014-01-28 20:54:28 -05002660 if param.kind == _POSITIONAL_ONLY:
2661 # This should never happen in case of a properly built
2662 # Signature object (but let's have this check here
2663 # to ensure correct behaviour just in case)
2664 raise TypeError('{arg!r} parameter is positional only, '
2665 'but was passed as a keyword'. \
2666 format(arg=param.name))
2667
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002668 arguments[param_name] = arg_val
2669
2670 if kwargs:
2671 if kwargs_param is not None:
2672 # Process our '**kwargs'-like parameter
2673 arguments[kwargs_param.name] = kwargs
2674 else:
2675 raise TypeError('too many keyword arguments')
2676
2677 return self._bound_arguments_cls(self, arguments)
2678
Yury Selivanovc45873e2014-01-29 12:10:27 -05002679 def bind(*args, **kwargs):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002680 '''Get a BoundArguments object, that maps the passed `args`
2681 and `kwargs` to the function's signature. Raises `TypeError`
2682 if the passed arguments can not be bound.
2683 '''
Yury Selivanovc45873e2014-01-29 12:10:27 -05002684 return args[0]._bind(args[1:], kwargs)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002685
Yury Selivanovc45873e2014-01-29 12:10:27 -05002686 def bind_partial(*args, **kwargs):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002687 '''Get a BoundArguments object, that partially maps the
2688 passed `args` and `kwargs` to the function's signature.
2689 Raises `TypeError` if the passed arguments can not be bound.
2690 '''
Yury Selivanovc45873e2014-01-29 12:10:27 -05002691 return args[0]._bind(args[1:], kwargs, partial=True)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002692
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002693 def __reduce__(self):
2694 return (type(self),
2695 (tuple(self._parameters.values()),),
2696 {'_return_annotation': self._return_annotation})
2697
2698 def __setstate__(self, state):
2699 self._return_annotation = state['_return_annotation']
2700
Yury Selivanov374375d2014-03-27 12:41:53 -04002701 def __repr__(self):
2702 return '<{} at {:#x} "{}">'.format(self.__class__.__name__,
2703 id(self), self)
2704
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002705 def __str__(self):
2706 result = []
Yury Selivanov2393dca2014-01-27 15:07:58 -05002707 render_pos_only_separator = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002708 render_kw_only_separator = True
Yury Selivanov2393dca2014-01-27 15:07:58 -05002709 for param in self.parameters.values():
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002710 formatted = str(param)
2711
2712 kind = param.kind
Yury Selivanov2393dca2014-01-27 15:07:58 -05002713
2714 if kind == _POSITIONAL_ONLY:
2715 render_pos_only_separator = True
2716 elif render_pos_only_separator:
2717 # It's not a positional-only parameter, and the flag
2718 # is set to 'True' (there were pos-only params before.)
2719 result.append('/')
2720 render_pos_only_separator = False
2721
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002722 if kind == _VAR_POSITIONAL:
2723 # OK, we have an '*args'-like parameter, so we won't need
2724 # a '*' to separate keyword-only arguments
2725 render_kw_only_separator = False
2726 elif kind == _KEYWORD_ONLY and render_kw_only_separator:
2727 # We have a keyword-only parameter to render and we haven't
2728 # rendered an '*args'-like parameter before, so add a '*'
2729 # separator to the parameters list ("foo(arg1, *, arg2)" case)
2730 result.append('*')
2731 # This condition should be only triggered once, so
2732 # reset the flag
2733 render_kw_only_separator = False
2734
2735 result.append(formatted)
2736
Yury Selivanov2393dca2014-01-27 15:07:58 -05002737 if render_pos_only_separator:
2738 # There were only positional-only parameters, hence the
2739 # flag was not reset to 'False'
2740 result.append('/')
2741
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002742 rendered = '({})'.format(', '.join(result))
2743
2744 if self.return_annotation is not _empty:
2745 anno = formatannotation(self.return_annotation)
2746 rendered += ' -> {}'.format(anno)
2747
2748 return rendered
Nick Coghlanf94a16b2013-09-22 22:46:49 +10002749
Yury Selivanovda396452014-03-27 12:09:24 -04002750
2751def signature(obj):
2752 '''Get a signature object for the passed callable.'''
2753 return Signature.from_callable(obj)
2754
2755
Nick Coghlanf94a16b2013-09-22 22:46:49 +10002756def _main():
2757 """ Logic for inspecting an object given at command line """
2758 import argparse
2759 import importlib
2760
2761 parser = argparse.ArgumentParser()
2762 parser.add_argument(
2763 'object',
2764 help="The object to be analysed. "
2765 "It supports the 'module:qualname' syntax")
2766 parser.add_argument(
2767 '-d', '--details', action='store_true',
2768 help='Display info about the module rather than its source code')
2769
2770 args = parser.parse_args()
2771
2772 target = args.object
2773 mod_name, has_attrs, attrs = target.partition(":")
2774 try:
2775 obj = module = importlib.import_module(mod_name)
2776 except Exception as exc:
2777 msg = "Failed to import {} ({}: {})".format(mod_name,
2778 type(exc).__name__,
2779 exc)
2780 print(msg, file=sys.stderr)
2781 exit(2)
2782
2783 if has_attrs:
2784 parts = attrs.split(".")
2785 obj = module
2786 for part in parts:
2787 obj = getattr(obj, part)
2788
2789 if module.__name__ in sys.builtin_module_names:
2790 print("Can't get info for builtin modules.", file=sys.stderr)
2791 exit(1)
2792
2793 if args.details:
2794 print('Target: {}'.format(target))
2795 print('Origin: {}'.format(getsourcefile(module)))
2796 print('Cached: {}'.format(module.__cached__))
2797 if obj is module:
2798 print('Loader: {}'.format(repr(module.__loader__)))
2799 if hasattr(module, '__path__'):
2800 print('Submodule search path: {}'.format(module.__path__))
2801 else:
2802 try:
2803 __, lineno = findsource(obj)
2804 except Exception:
2805 pass
2806 else:
2807 print('Line: {}'.format(lineno))
2808
2809 print('\n')
2810 else:
2811 print(getsource(obj))
2812
2813
2814if __name__ == "__main__":
2815 _main()