blob: 819bb8de2d5b1f1255166c2089f101e6c1198454 [file] [log] [blame]
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001"""Get useful information from live Python objects.
2
3This module encapsulates the interface provided by the internal special
Neal Norwitz221085d2007-02-25 20:55:47 +00004attributes (co_*, im_*, tb_*, etc.) in a friendlier fashion.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00005It also provides some help for examining source code and class layout.
6
7Here are some of the useful functions provided by this module:
8
Christian Heimes7131fd92008-02-19 14:21:46 +00009 ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
10 isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
11 isroutine() - check object types
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000012 getmembers() - get members of an object that satisfy a given condition
13
14 getfile(), getsourcefile(), getsource() - find an object's source code
15 getdoc(), getcomments() - get documentation on an object
16 getmodule() - determine the module that an object came from
17 getclasstree() - arrange classes so as to represent their hierarchy
18
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +000019 getargspec(), getargvalues(), getcallargs() - get info about function arguments
Yury Selivanov0cf3ed62014-04-01 10:17:08 -040020 getfullargspec() - same, with support for Python 3 features
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000021 formatargspec(), formatargvalues() - format an argument spec
22 getouterframes(), getinnerframes() - get info about frames
23 currentframe() - get the current stack frame
24 stack(), trace() - get info about frames on the stack or in a traceback
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070025
26 signature() - get a Signature object for the callable
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000027"""
28
29# This module is in the public domain. No warranties.
30
Larry Hastings7c7cbfc2012-06-22 15:19:35 -070031__author__ = ('Ka-Ping Yee <ping@lfw.org>',
32 'Yury Selivanov <yselivanov@sprymix.com>')
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +000033
Larry Hastings44e2eaa2013-11-23 15:37:55 -080034import ast
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
Guido van Rossume82881c2014-07-15 12:29:11 -0700917 A tuple of four things is returned: (args, varargs, keywords, defaults).
918 'args' is a list of the argument names, including keyword-only argument names.
919 'varargs' and 'keywords' are the names of the * and ** arguments or None.
Jeremy Hylton64967882003-06-27 18:14:39 +0000920 'defaults' is an n-tuple of the default values of the last n arguments.
Guido van Rossuma8add0e2007-05-14 22:03:55 +0000921
Yury Selivanov0cf3ed62014-04-01 10:17:08 -0400922 Use the getfullargspec() API for Python 3 code, as annotations
Guido van Rossum2e65f892007-02-28 22:03:49 +0000923 and keyword arguments are supported. getargspec() will raise ValueError
924 if the func has either annotations or keyword arguments.
925 """
926
927 args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \
928 getfullargspec(func)
929 if kwonlyargs or ann:
Collin Winterce36ad82007-08-30 01:19:48 +0000930 raise ValueError("Function has keyword-only arguments or annotations"
931 ", use getfullargspec() API which can support them")
Christian Heimes25bb7832008-01-11 16:17:00 +0000932 return ArgSpec(args, varargs, varkw, defaults)
933
934FullArgSpec = namedtuple('FullArgSpec',
Benjamin Peterson3d4ca742008-11-12 21:39:01 +0000935 'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations')
Guido van Rossum2e65f892007-02-28 22:03:49 +0000936
937def getfullargspec(func):
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500938 """Get the names and default values of a callable object's arguments.
Guido van Rossum2e65f892007-02-28 22:03:49 +0000939
Brett Cannon504d8852007-09-07 02:12:14 +0000940 A tuple of seven things is returned:
941 (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations).
Georg Brandlc1c4bf82010-10-15 16:07:41 +0000942 'args' is a list of the argument names.
Guido van Rossum2e65f892007-02-28 22:03:49 +0000943 'varargs' and 'varkw' are the names of the * and ** arguments or None.
944 'defaults' is an n-tuple of the default values of the last n arguments.
945 'kwonlyargs' is a list of keyword-only argument names.
946 'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults.
947 'annotations' is a dictionary mapping argument names to annotations.
Guido van Rossuma8add0e2007-05-14 22:03:55 +0000948
Guido van Rossum2e65f892007-02-28 22:03:49 +0000949 The first four items in the tuple correspond to getargspec().
Jeremy Hylton64967882003-06-27 18:14:39 +0000950 """
951
Yury Selivanov57d240e2014-02-19 16:27:23 -0500952 try:
953 # Re: `skip_bound_arg=False`
954 #
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500955 # There is a notable difference in behaviour between getfullargspec
956 # and Signature: the former always returns 'self' parameter for bound
957 # methods, whereas the Signature always shows the actual calling
958 # signature of the passed object.
959 #
960 # To simulate this behaviour, we "unbind" bound methods, to trick
961 # inspect.signature to always return their first parameter ("self",
962 # usually)
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500963
Yury Selivanov57d240e2014-02-19 16:27:23 -0500964 # Re: `follow_wrapper_chains=False`
965 #
966 # getfullargspec() historically ignored __wrapped__ attributes,
967 # so we ensure that remains the case in 3.3+
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500968
Yury Selivanov5a23bd02014-03-29 13:47:11 -0400969 sig = _signature_from_callable(func,
970 follow_wrapper_chains=False,
971 skip_bound_arg=False,
972 sigcls=Signature)
Yury Selivanovd82eddc2014-01-29 11:24:39 -0500973 except Exception as ex:
974 # Most of the times 'signature' will raise ValueError.
975 # But, it can also raise AttributeError, and, maybe something
976 # else. So to be fully backwards compatible, we catch all
977 # possible exceptions here, and reraise a TypeError.
978 raise TypeError('unsupported callable') from ex
979
980 args = []
981 varargs = None
982 varkw = None
983 kwonlyargs = []
984 defaults = ()
985 annotations = {}
986 defaults = ()
987 kwdefaults = {}
988
989 if sig.return_annotation is not sig.empty:
990 annotations['return'] = sig.return_annotation
991
992 for param in sig.parameters.values():
993 kind = param.kind
994 name = param.name
995
996 if kind is _POSITIONAL_ONLY:
997 args.append(name)
998 elif kind is _POSITIONAL_OR_KEYWORD:
999 args.append(name)
1000 if param.default is not param.empty:
1001 defaults += (param.default,)
1002 elif kind is _VAR_POSITIONAL:
1003 varargs = name
1004 elif kind is _KEYWORD_ONLY:
1005 kwonlyargs.append(name)
1006 if param.default is not param.empty:
1007 kwdefaults[name] = param.default
1008 elif kind is _VAR_KEYWORD:
1009 varkw = name
1010
1011 if param.annotation is not param.empty:
1012 annotations[name] = param.annotation
1013
1014 if not kwdefaults:
1015 # compatibility with 'func.__kwdefaults__'
1016 kwdefaults = None
1017
1018 if not defaults:
1019 # compatibility with 'func.__defaults__'
1020 defaults = None
1021
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001022 return FullArgSpec(args, varargs, varkw, defaults,
1023 kwonlyargs, kwdefaults, annotations)
1024
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001025
Christian Heimes25bb7832008-01-11 16:17:00 +00001026ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
1027
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001028def getargvalues(frame):
1029 """Get information about arguments passed into a particular frame.
1030
1031 A tuple of four things is returned: (args, varargs, varkw, locals).
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001032 'args' is a list of the argument names.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001033 'varargs' and 'varkw' are the names of the * and ** arguments or None.
1034 'locals' is the locals dictionary of the given frame."""
1035 args, varargs, varkw = getargs(frame.f_code)
Benjamin Peterson1a6e0d02008-10-25 15:49:17 +00001036 return ArgInfo(args, varargs, varkw, frame.f_locals)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001037
Guido van Rossum2e65f892007-02-28 22:03:49 +00001038def formatannotation(annotation, base_module=None):
1039 if isinstance(annotation, type):
Georg Brandl1a3284e2007-12-02 09:40:06 +00001040 if annotation.__module__ in ('builtins', base_module):
Serhiy Storchaka521e5862014-07-22 15:00:37 +03001041 return annotation.__qualname__
1042 return annotation.__module__+'.'+annotation.__qualname__
Guido van Rossum2e65f892007-02-28 22:03:49 +00001043 return repr(annotation)
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001044
Guido van Rossum2e65f892007-02-28 22:03:49 +00001045def formatannotationrelativeto(object):
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001046 module = getattr(object, '__module__', None)
1047 def _formatannotation(annotation):
1048 return formatannotation(annotation, module)
1049 return _formatannotation
Guido van Rossum2e65f892007-02-28 22:03:49 +00001050
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001051def formatargspec(args, varargs=None, varkw=None, defaults=None,
Guido van Rossum2e65f892007-02-28 22:03:49 +00001052 kwonlyargs=(), kwonlydefaults={}, annotations={},
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001053 formatarg=str,
1054 formatvarargs=lambda name: '*' + name,
1055 formatvarkw=lambda name: '**' + name,
1056 formatvalue=lambda value: '=' + repr(value),
Guido van Rossum2e65f892007-02-28 22:03:49 +00001057 formatreturns=lambda text: ' -> ' + text,
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001058 formatannotation=formatannotation):
Guido van Rossuma8add0e2007-05-14 22:03:55 +00001059 """Format an argument spec from the values returned by getargspec
Guido van Rossum2e65f892007-02-28 22:03:49 +00001060 or getfullargspec.
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001061
Guido van Rossum2e65f892007-02-28 22:03:49 +00001062 The first seven arguments are (args, varargs, varkw, defaults,
1063 kwonlyargs, kwonlydefaults, annotations). The other five arguments
1064 are the corresponding optional formatting functions that are called to
1065 turn names and values into strings. The last argument is an optional
1066 function to format the sequence of arguments."""
1067 def formatargandannotation(arg):
1068 result = formatarg(arg)
1069 if arg in annotations:
1070 result += ': ' + formatannotation(annotations[arg])
1071 return result
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001072 specs = []
1073 if defaults:
1074 firstdefault = len(args) - len(defaults)
Benjamin Petersonb58dda72009-01-18 22:27:04 +00001075 for i, arg in enumerate(args):
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001076 spec = formatargandannotation(arg)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001077 if defaults and i >= firstdefault:
1078 spec = spec + formatvalue(defaults[i - firstdefault])
1079 specs.append(spec)
Raymond Hettinger936654b2002-06-01 03:06:31 +00001080 if varargs is not None:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001081 specs.append(formatvarargs(formatargandannotation(varargs)))
1082 else:
1083 if kwonlyargs:
1084 specs.append('*')
1085 if kwonlyargs:
1086 for kwonlyarg in kwonlyargs:
1087 spec = formatargandannotation(kwonlyarg)
Benjamin Peterson9953a8d2009-01-17 04:15:01 +00001088 if kwonlydefaults and kwonlyarg in kwonlydefaults:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001089 spec += formatvalue(kwonlydefaults[kwonlyarg])
1090 specs.append(spec)
Raymond Hettinger936654b2002-06-01 03:06:31 +00001091 if varkw is not None:
Guido van Rossum2e65f892007-02-28 22:03:49 +00001092 specs.append(formatvarkw(formatargandannotation(varkw)))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001093 result = '(' + ', '.join(specs) + ')'
Guido van Rossum2e65f892007-02-28 22:03:49 +00001094 if 'return' in annotations:
1095 result += formatreturns(formatannotation(annotations['return']))
1096 return result
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001097
1098def formatargvalues(args, varargs, varkw, locals,
1099 formatarg=str,
1100 formatvarargs=lambda name: '*' + name,
1101 formatvarkw=lambda name: '**' + name,
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001102 formatvalue=lambda value: '=' + repr(value)):
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001103 """Format an argument spec from the 4 values returned by getargvalues.
1104
1105 The first four arguments are (args, varargs, varkw, locals). The
1106 next four arguments are the corresponding optional formatting functions
1107 that are called to turn names and values into strings. The ninth
1108 argument is an optional function to format the sequence of arguments."""
1109 def convert(name, locals=locals,
1110 formatarg=formatarg, formatvalue=formatvalue):
1111 return formatarg(name) + formatvalue(locals[name])
1112 specs = []
1113 for i in range(len(args)):
Georg Brandlc1c4bf82010-10-15 16:07:41 +00001114 specs.append(convert(args[i]))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001115 if varargs:
1116 specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
1117 if varkw:
1118 specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
Neal Norwitz9d72bb42007-04-17 08:48:32 +00001119 return '(' + ', '.join(specs) + ')'
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001120
Benjamin Petersone109c702011-06-24 09:37:26 -05001121def _missing_arguments(f_name, argnames, pos, values):
1122 names = [repr(name) for name in argnames if name not in values]
1123 missing = len(names)
1124 if missing == 1:
1125 s = names[0]
1126 elif missing == 2:
1127 s = "{} and {}".format(*names)
1128 else:
Yury Selivanovdccfa132014-03-27 18:42:52 -04001129 tail = ", {} and {}".format(*names[-2:])
Benjamin Petersone109c702011-06-24 09:37:26 -05001130 del names[-2:]
1131 s = ", ".join(names) + tail
1132 raise TypeError("%s() missing %i required %s argument%s: %s" %
1133 (f_name, missing,
1134 "positional" if pos else "keyword-only",
1135 "" if missing == 1 else "s", s))
1136
1137def _too_many(f_name, args, kwonly, varargs, defcount, given, values):
Benjamin Petersonb204a422011-06-05 22:04:07 -05001138 atleast = len(args) - defcount
Benjamin Petersonb204a422011-06-05 22:04:07 -05001139 kwonly_given = len([arg for arg in kwonly if arg in values])
1140 if varargs:
1141 plural = atleast != 1
1142 sig = "at least %d" % (atleast,)
1143 elif defcount:
1144 plural = True
1145 sig = "from %d to %d" % (atleast, len(args))
1146 else:
1147 plural = len(args) != 1
1148 sig = str(len(args))
1149 kwonly_sig = ""
1150 if kwonly_given:
1151 msg = " positional argument%s (and %d keyword-only argument%s)"
1152 kwonly_sig = (msg % ("s" if given != 1 else "", kwonly_given,
1153 "s" if kwonly_given != 1 else ""))
1154 raise TypeError("%s() takes %s positional argument%s but %d%s %s given" %
1155 (f_name, sig, "s" if plural else "", given, kwonly_sig,
1156 "was" if given == 1 and not kwonly_given else "were"))
1157
Benjamin Peterson3e6ab172014-01-02 12:24:08 -06001158def getcallargs(*func_and_positional, **named):
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001159 """Get the mapping of arguments to values.
1160
1161 A dict is returned, with keys the function argument names (including the
1162 names of the * and ** arguments, if any), and values the respective bound
1163 values from 'positional' and 'named'."""
Benjamin Peterson3e6ab172014-01-02 12:24:08 -06001164 func = func_and_positional[0]
1165 positional = func_and_positional[1:]
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001166 spec = getfullargspec(func)
1167 args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = spec
1168 f_name = func.__name__
1169 arg2value = {}
1170
Benjamin Petersonb204a422011-06-05 22:04:07 -05001171
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001172 if ismethod(func) and func.__self__ is not None:
1173 # implicit 'self' (or 'cls' for classmethods) argument
1174 positional = (func.__self__,) + positional
1175 num_pos = len(positional)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001176 num_args = len(args)
1177 num_defaults = len(defaults) if defaults else 0
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001178
Benjamin Petersonb204a422011-06-05 22:04:07 -05001179 n = min(num_pos, num_args)
1180 for i in range(n):
1181 arg2value[args[i]] = positional[i]
1182 if varargs:
1183 arg2value[varargs] = tuple(positional[n:])
1184 possible_kwargs = set(args + kwonlyargs)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001185 if varkw:
Benjamin Petersonb204a422011-06-05 22:04:07 -05001186 arg2value[varkw] = {}
1187 for kw, value in named.items():
1188 if kw not in possible_kwargs:
1189 if not varkw:
1190 raise TypeError("%s() got an unexpected keyword argument %r" %
1191 (f_name, kw))
1192 arg2value[varkw][kw] = value
1193 continue
1194 if kw in arg2value:
1195 raise TypeError("%s() got multiple values for argument %r" %
1196 (f_name, kw))
1197 arg2value[kw] = value
1198 if num_pos > num_args and not varargs:
Benjamin Petersone109c702011-06-24 09:37:26 -05001199 _too_many(f_name, args, kwonlyargs, varargs, num_defaults,
1200 num_pos, arg2value)
Benjamin Petersonb204a422011-06-05 22:04:07 -05001201 if num_pos < num_args:
Benjamin Petersone109c702011-06-24 09:37:26 -05001202 req = args[:num_args - num_defaults]
1203 for arg in req:
Benjamin Petersonb204a422011-06-05 22:04:07 -05001204 if arg not in arg2value:
Benjamin Petersone109c702011-06-24 09:37:26 -05001205 _missing_arguments(f_name, req, True, arg2value)
Benjamin Petersonb204a422011-06-05 22:04:07 -05001206 for i, arg in enumerate(args[num_args - num_defaults:]):
1207 if arg not in arg2value:
1208 arg2value[arg] = defaults[i]
Benjamin Petersone109c702011-06-24 09:37:26 -05001209 missing = 0
Benjamin Petersonb204a422011-06-05 22:04:07 -05001210 for kwarg in kwonlyargs:
1211 if kwarg not in arg2value:
Yury Selivanov875df202014-03-27 18:23:03 -04001212 if kwonlydefaults and kwarg in kwonlydefaults:
Benjamin Petersone109c702011-06-24 09:37:26 -05001213 arg2value[kwarg] = kwonlydefaults[kwarg]
1214 else:
1215 missing += 1
1216 if missing:
1217 _missing_arguments(f_name, kwonlyargs, False, arg2value)
Benjamin Peterson25cd7eb2010-03-30 18:42:32 +00001218 return arg2value
1219
Nick Coghlan2f92e542012-06-23 19:39:55 +10001220ClosureVars = namedtuple('ClosureVars', 'nonlocals globals builtins unbound')
1221
1222def getclosurevars(func):
1223 """
1224 Get the mapping of free variables to their current values.
1225
Meador Inge8fda3592012-07-19 21:33:21 -05001226 Returns a named tuple of dicts mapping the current nonlocal, global
Nick Coghlan2f92e542012-06-23 19:39:55 +10001227 and builtin references as seen by the body of the function. A final
1228 set of unbound names that could not be resolved is also provided.
1229 """
1230
1231 if ismethod(func):
1232 func = func.__func__
1233
1234 if not isfunction(func):
1235 raise TypeError("'{!r}' is not a Python function".format(func))
1236
1237 code = func.__code__
1238 # Nonlocal references are named in co_freevars and resolved
1239 # by looking them up in __closure__ by positional index
1240 if func.__closure__ is None:
1241 nonlocal_vars = {}
1242 else:
1243 nonlocal_vars = {
1244 var : cell.cell_contents
1245 for var, cell in zip(code.co_freevars, func.__closure__)
1246 }
1247
1248 # Global and builtin references are named in co_names and resolved
1249 # by looking them up in __globals__ or __builtins__
1250 global_ns = func.__globals__
1251 builtin_ns = global_ns.get("__builtins__", builtins.__dict__)
1252 if ismodule(builtin_ns):
1253 builtin_ns = builtin_ns.__dict__
1254 global_vars = {}
1255 builtin_vars = {}
1256 unbound_names = set()
1257 for name in code.co_names:
1258 if name in ("None", "True", "False"):
1259 # Because these used to be builtins instead of keywords, they
1260 # may still show up as name references. We ignore them.
1261 continue
1262 try:
1263 global_vars[name] = global_ns[name]
1264 except KeyError:
1265 try:
1266 builtin_vars[name] = builtin_ns[name]
1267 except KeyError:
1268 unbound_names.add(name)
1269
1270 return ClosureVars(nonlocal_vars, global_vars,
1271 builtin_vars, unbound_names)
1272
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001273# -------------------------------------------------- stack frame extraction
Christian Heimes25bb7832008-01-11 16:17:00 +00001274
1275Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
1276
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001277def getframeinfo(frame, context=1):
1278 """Get information about a frame or traceback object.
1279
1280 A tuple of five things is returned: the filename, the line number of
1281 the current line, the function name, a list of lines of context from
1282 the source code, and the index of the current line within that list.
1283 The optional second argument specifies the number of lines of context
1284 to return, which are centered around the current line."""
1285 if istraceback(frame):
Andrew M. Kuchlingba8b6bc2004-06-05 14:11:59 +00001286 lineno = frame.tb_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001287 frame = frame.tb_frame
Andrew M. Kuchlingba8b6bc2004-06-05 14:11:59 +00001288 else:
1289 lineno = frame.f_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001290 if not isframe(frame):
Benjamin Peterson4ac9ce42009-10-04 14:49:41 +00001291 raise TypeError('{!r} is not a frame or traceback object'.format(frame))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001292
Neil Schemenauerf06f8532002-03-23 23:51:04 +00001293 filename = getsourcefile(frame) or getfile(frame)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001294 if context > 0:
Guido van Rossum54e54c62001-09-04 19:14:14 +00001295 start = lineno - 1 - context//2
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001296 try:
1297 lines, lnum = findsource(frame)
Andrew Svetlovf7a17b42012-12-25 16:47:37 +02001298 except OSError:
Ka-Ping Yee4eb0c002001-03-02 05:50:34 +00001299 lines = index = None
1300 else:
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001301 start = max(start, 1)
Raymond Hettingera0501712004-06-15 11:22:53 +00001302 start = max(0, min(start, len(lines) - context))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001303 lines = lines[start:start+context]
Ka-Ping Yee59ade082001-03-01 03:55:35 +00001304 index = lineno - 1 - start
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001305 else:
1306 lines = index = None
1307
Christian Heimes25bb7832008-01-11 16:17:00 +00001308 return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
Ka-Ping Yee59ade082001-03-01 03:55:35 +00001309
1310def getlineno(frame):
1311 """Get the line number from a frame object, allowing for optimization."""
Michael W. Hudsondd32a912002-08-15 14:59:02 +00001312 # FrameType.f_lineno is now a descriptor that grovels co_lnotab
1313 return frame.f_lineno
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001314
Antoine Pitroucdcafb72014-08-24 10:50:28 -04001315FrameInfo = namedtuple('FrameInfo', ('frame',) + Traceback._fields)
1316
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001317def getouterframes(frame, context=1):
1318 """Get a list of records for a frame and all higher (calling) frames.
1319
1320 Each record contains a frame object, filename, line number, function
1321 name, a list of lines of context, and index within the context."""
1322 framelist = []
1323 while frame:
Antoine Pitroucdcafb72014-08-24 10:50:28 -04001324 frameinfo = (frame,) + getframeinfo(frame, context)
1325 framelist.append(FrameInfo(*frameinfo))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001326 frame = frame.f_back
1327 return framelist
1328
1329def getinnerframes(tb, context=1):
1330 """Get a list of records for a traceback's frame and all lower frames.
1331
1332 Each record contains a frame object, filename, line number, function
1333 name, a list of lines of context, and index within the context."""
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001334 framelist = []
1335 while tb:
Antoine Pitroucdcafb72014-08-24 10:50:28 -04001336 frameinfo = (tb.tb_frame,) + getframeinfo(tb, context)
1337 framelist.append(FrameInfo(*frameinfo))
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001338 tb = tb.tb_next
1339 return framelist
1340
Benjamin Peterson42ac4752010-08-09 13:05:35 +00001341def currentframe():
Benjamin Petersona3a3fc62010-08-09 15:49:56 +00001342 """Return the frame of the caller or None if this is not possible."""
Benjamin Peterson42ac4752010-08-09 13:05:35 +00001343 return sys._getframe(1) if hasattr(sys, "_getframe") else None
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001344
1345def stack(context=1):
1346 """Return a list of records for the stack above the caller's frame."""
Jeremy Hyltonab919022003-06-27 18:41:20 +00001347 return getouterframes(sys._getframe(1), context)
Ka-Ping Yee6397c7c2001-02-27 14:43:21 +00001348
1349def trace(context=1):
Tim Peters85ba6732001-02-28 08:26:44 +00001350 """Return a list of records for the stack below the current exception."""
Fred Draked451ec12002-04-26 02:29:55 +00001351 return getinnerframes(sys.exc_info()[2], context)
Michael Foord95fc51d2010-11-20 15:07:30 +00001352
1353
1354# ------------------------------------------------ static version of getattr
1355
1356_sentinel = object()
1357
Michael Foorde5162652010-11-20 16:40:44 +00001358def _static_getmro(klass):
1359 return type.__dict__['__mro__'].__get__(klass)
1360
Michael Foord95fc51d2010-11-20 15:07:30 +00001361def _check_instance(obj, attr):
1362 instance_dict = {}
1363 try:
1364 instance_dict = object.__getattribute__(obj, "__dict__")
1365 except AttributeError:
1366 pass
Michael Foorddcebe0f2011-03-15 19:20:44 -04001367 return dict.get(instance_dict, attr, _sentinel)
Michael Foord95fc51d2010-11-20 15:07:30 +00001368
1369
1370def _check_class(klass, attr):
Michael Foorde5162652010-11-20 16:40:44 +00001371 for entry in _static_getmro(klass):
Michael Foorda51623b2011-12-18 22:01:40 +00001372 if _shadowed_dict(type(entry)) is _sentinel:
Michael Foorddcebe0f2011-03-15 19:20:44 -04001373 try:
1374 return entry.__dict__[attr]
1375 except KeyError:
1376 pass
Michael Foord95fc51d2010-11-20 15:07:30 +00001377 return _sentinel
1378
Michael Foord35184ed2010-11-20 16:58:30 +00001379def _is_type(obj):
1380 try:
1381 _static_getmro(obj)
1382 except TypeError:
1383 return False
1384 return True
1385
Michael Foorddcebe0f2011-03-15 19:20:44 -04001386def _shadowed_dict(klass):
1387 dict_attr = type.__dict__["__dict__"]
1388 for entry in _static_getmro(klass):
1389 try:
1390 class_dict = dict_attr.__get__(entry)["__dict__"]
1391 except KeyError:
1392 pass
1393 else:
1394 if not (type(class_dict) is types.GetSetDescriptorType and
1395 class_dict.__name__ == "__dict__" and
1396 class_dict.__objclass__ is entry):
Michael Foorda51623b2011-12-18 22:01:40 +00001397 return class_dict
1398 return _sentinel
Michael Foord95fc51d2010-11-20 15:07:30 +00001399
1400def getattr_static(obj, attr, default=_sentinel):
1401 """Retrieve attributes without triggering dynamic lookup via the
1402 descriptor protocol, __getattr__ or __getattribute__.
1403
1404 Note: this function may not be able to retrieve all attributes
1405 that getattr can fetch (like dynamically created attributes)
1406 and may find attributes that getattr can't (like descriptors
1407 that raise AttributeError). It can also return descriptor objects
1408 instead of instance members in some cases. See the
1409 documentation for details.
1410 """
1411 instance_result = _sentinel
Michael Foord35184ed2010-11-20 16:58:30 +00001412 if not _is_type(obj):
Michael Foordcc7ebb82010-11-20 16:20:16 +00001413 klass = type(obj)
Michael Foorda51623b2011-12-18 22:01:40 +00001414 dict_attr = _shadowed_dict(klass)
1415 if (dict_attr is _sentinel or
1416 type(dict_attr) is types.MemberDescriptorType):
Michael Foorddcebe0f2011-03-15 19:20:44 -04001417 instance_result = _check_instance(obj, attr)
Michael Foord95fc51d2010-11-20 15:07:30 +00001418 else:
1419 klass = obj
1420
1421 klass_result = _check_class(klass, attr)
1422
1423 if instance_result is not _sentinel and klass_result is not _sentinel:
1424 if (_check_class(type(klass_result), '__get__') is not _sentinel and
1425 _check_class(type(klass_result), '__set__') is not _sentinel):
1426 return klass_result
1427
1428 if instance_result is not _sentinel:
1429 return instance_result
1430 if klass_result is not _sentinel:
1431 return klass_result
1432
1433 if obj is klass:
1434 # for types we check the metaclass too
Michael Foorde5162652010-11-20 16:40:44 +00001435 for entry in _static_getmro(type(klass)):
Michael Foord3ba95f82011-12-22 01:13:37 +00001436 if _shadowed_dict(type(entry)) is _sentinel:
1437 try:
1438 return entry.__dict__[attr]
1439 except KeyError:
1440 pass
Michael Foord95fc51d2010-11-20 15:07:30 +00001441 if default is not _sentinel:
1442 return default
1443 raise AttributeError(attr)
Nick Coghlane0f04652010-11-21 03:44:04 +00001444
1445
Nick Coghlan04e2e3f2012-06-23 19:52:05 +10001446# ------------------------------------------------ generator introspection
1447
Nick Coghlan7921b9f2010-11-30 06:36:04 +00001448GEN_CREATED = 'GEN_CREATED'
1449GEN_RUNNING = 'GEN_RUNNING'
1450GEN_SUSPENDED = 'GEN_SUSPENDED'
1451GEN_CLOSED = 'GEN_CLOSED'
Nick Coghlane0f04652010-11-21 03:44:04 +00001452
1453def getgeneratorstate(generator):
1454 """Get current state of a generator-iterator.
1455
1456 Possible states are:
1457 GEN_CREATED: Waiting to start execution.
1458 GEN_RUNNING: Currently being executed by the interpreter.
1459 GEN_SUSPENDED: Currently suspended at a yield expression.
1460 GEN_CLOSED: Execution has completed.
1461 """
1462 if generator.gi_running:
1463 return GEN_RUNNING
1464 if generator.gi_frame is None:
1465 return GEN_CLOSED
1466 if generator.gi_frame.f_lasti == -1:
1467 return GEN_CREATED
1468 return GEN_SUSPENDED
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001469
1470
Nick Coghlan04e2e3f2012-06-23 19:52:05 +10001471def getgeneratorlocals(generator):
1472 """
1473 Get the mapping of generator local variables to their current values.
1474
1475 A dict is returned, with the keys the local variable names and values the
1476 bound values."""
1477
1478 if not isgenerator(generator):
1479 raise TypeError("'{!r}' is not a Python generator".format(generator))
1480
1481 frame = getattr(generator, "gi_frame", None)
1482 if frame is not None:
1483 return generator.gi_frame.f_locals
1484 else:
1485 return {}
1486
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001487###############################################################################
1488### Function Signature Object (PEP 362)
1489###############################################################################
1490
1491
1492_WrapperDescriptor = type(type.__call__)
1493_MethodWrapper = type(all.__call__)
Larry Hastings5c661892014-01-24 06:17:25 -08001494_ClassMethodWrapper = type(int.__dict__['from_bytes'])
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001495
1496_NonUserDefinedCallables = (_WrapperDescriptor,
1497 _MethodWrapper,
Larry Hastings5c661892014-01-24 06:17:25 -08001498 _ClassMethodWrapper,
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001499 types.BuiltinFunctionType)
1500
1501
Yury Selivanov421f0c72014-01-29 12:05:40 -05001502def _signature_get_user_defined_method(cls, method_name):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001503 """Private helper. Checks if ``cls`` has an attribute
1504 named ``method_name`` and returns it only if it is a
1505 pure python function.
1506 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001507 try:
1508 meth = getattr(cls, method_name)
1509 except AttributeError:
1510 return
1511 else:
1512 if not isinstance(meth, _NonUserDefinedCallables):
1513 # Once '__signature__' will be added to 'C'-level
1514 # callables, this check won't be necessary
1515 return meth
1516
1517
Yury Selivanov62560fb2014-01-28 12:26:24 -05001518def _signature_get_partial(wrapped_sig, partial, extra_args=()):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001519 """Private helper to calculate how 'wrapped_sig' signature will
1520 look like after applying a 'functools.partial' object (or alike)
1521 on it.
1522 """
Yury Selivanov62560fb2014-01-28 12:26:24 -05001523
Yury Selivanov3f73ca22014-04-08 11:30:45 -04001524 old_params = wrapped_sig.parameters
1525 new_params = OrderedDict(old_params.items())
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001526
1527 partial_args = partial.args or ()
1528 partial_keywords = partial.keywords or {}
1529
1530 if extra_args:
1531 partial_args = extra_args + partial_args
1532
1533 try:
1534 ba = wrapped_sig.bind_partial(*partial_args, **partial_keywords)
1535 except TypeError as ex:
1536 msg = 'partial object {!r} has incorrect arguments'.format(partial)
1537 raise ValueError(msg) from ex
1538
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001539
Yury Selivanov3f73ca22014-04-08 11:30:45 -04001540 transform_to_kwonly = False
1541 for param_name, param in old_params.items():
1542 try:
1543 arg_value = ba.arguments[param_name]
1544 except KeyError:
1545 pass
1546 else:
1547 if param.kind is _POSITIONAL_ONLY:
1548 # If positional-only parameter is bound by partial,
1549 # it effectively disappears from the signature
1550 new_params.pop(param_name)
1551 continue
1552
1553 if param.kind is _POSITIONAL_OR_KEYWORD:
1554 if param_name in partial_keywords:
1555 # This means that this parameter, and all parameters
1556 # after it should be keyword-only (and var-positional
1557 # should be removed). Here's why. Consider the following
1558 # function:
1559 # foo(a, b, *args, c):
1560 # pass
1561 #
1562 # "partial(foo, a='spam')" will have the following
1563 # signature: "(*, a='spam', b, c)". Because attempting
1564 # to call that partial with "(10, 20)" arguments will
1565 # raise a TypeError, saying that "a" argument received
1566 # multiple values.
1567 transform_to_kwonly = True
1568 # Set the new default value
1569 new_params[param_name] = param.replace(default=arg_value)
1570 else:
1571 # was passed as a positional argument
1572 new_params.pop(param.name)
1573 continue
1574
1575 if param.kind is _KEYWORD_ONLY:
1576 # Set the new default value
1577 new_params[param_name] = param.replace(default=arg_value)
1578
1579 if transform_to_kwonly:
1580 assert param.kind is not _POSITIONAL_ONLY
1581
1582 if param.kind is _POSITIONAL_OR_KEYWORD:
1583 new_param = new_params[param_name].replace(kind=_KEYWORD_ONLY)
1584 new_params[param_name] = new_param
1585 new_params.move_to_end(param_name)
1586 elif param.kind in (_KEYWORD_ONLY, _VAR_KEYWORD):
1587 new_params.move_to_end(param_name)
1588 elif param.kind is _VAR_POSITIONAL:
1589 new_params.pop(param.name)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001590
1591 return wrapped_sig.replace(parameters=new_params.values())
1592
1593
Yury Selivanov62560fb2014-01-28 12:26:24 -05001594def _signature_bound_method(sig):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001595 """Private helper to transform signatures for unbound
1596 functions to bound methods.
1597 """
Yury Selivanov62560fb2014-01-28 12:26:24 -05001598
1599 params = tuple(sig.parameters.values())
1600
1601 if not params or params[0].kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
1602 raise ValueError('invalid method signature')
1603
1604 kind = params[0].kind
1605 if kind in (_POSITIONAL_OR_KEYWORD, _POSITIONAL_ONLY):
1606 # Drop first parameter:
1607 # '(p1, p2[, ...])' -> '(p2[, ...])'
1608 params = params[1:]
1609 else:
1610 if kind is not _VAR_POSITIONAL:
1611 # Unless we add a new parameter type we never
1612 # get here
1613 raise ValueError('invalid argument type')
1614 # It's a var-positional parameter.
1615 # Do nothing. '(*args[, ...])' -> '(*args[, ...])'
1616
1617 return sig.replace(parameters=params)
1618
1619
Yury Selivanovb77511d2014-01-29 10:46:14 -05001620def _signature_is_builtin(obj):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001621 """Private helper to test if `obj` is a callable that might
1622 support Argument Clinic's __text_signature__ protocol.
1623 """
Yury Selivanov1d241832014-02-02 12:51:20 -05001624 return (isbuiltin(obj) or
Yury Selivanovb77511d2014-01-29 10:46:14 -05001625 ismethoddescriptor(obj) or
Yury Selivanov1d241832014-02-02 12:51:20 -05001626 isinstance(obj, _NonUserDefinedCallables) or
Yury Selivanovb77511d2014-01-29 10:46:14 -05001627 # Can't test 'isinstance(type)' here, as it would
1628 # also be True for regular python classes
1629 obj in (type, object))
1630
1631
Yury Selivanov63da7c72014-01-31 14:48:37 -05001632def _signature_is_functionlike(obj):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001633 """Private helper to test if `obj` is a duck type of FunctionType.
1634 A good example of such objects are functions compiled with
1635 Cython, which have all attributes that a pure Python function
1636 would have, but have their code statically compiled.
1637 """
Yury Selivanov63da7c72014-01-31 14:48:37 -05001638
1639 if not callable(obj) or isclass(obj):
1640 # All function-like objects are obviously callables,
1641 # and not classes.
1642 return False
1643
1644 name = getattr(obj, '__name__', None)
1645 code = getattr(obj, '__code__', None)
1646 defaults = getattr(obj, '__defaults__', _void) # Important to use _void ...
1647 kwdefaults = getattr(obj, '__kwdefaults__', _void) # ... and not None here
1648 annotations = getattr(obj, '__annotations__', None)
1649
1650 return (isinstance(code, types.CodeType) and
1651 isinstance(name, str) and
1652 (defaults is None or isinstance(defaults, tuple)) and
1653 (kwdefaults is None or isinstance(kwdefaults, dict)) and
1654 isinstance(annotations, dict))
1655
1656
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001657def _signature_get_bound_param(spec):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001658 """ Private helper to get first parameter name from a
1659 __text_signature__ of a builtin method, which should
1660 be in the following format: '($param1, ...)'.
1661 Assumptions are that the first argument won't have
1662 a default value or an annotation.
1663 """
Yury Selivanovd82eddc2014-01-29 11:24:39 -05001664
1665 assert spec.startswith('($')
1666
1667 pos = spec.find(',')
1668 if pos == -1:
1669 pos = spec.find(')')
1670
1671 cpos = spec.find(':')
1672 assert cpos == -1 or cpos > pos
1673
1674 cpos = spec.find('=')
1675 assert cpos == -1 or cpos > pos
1676
1677 return spec[2:pos]
1678
1679
Larry Hastings2623c8c2014-02-08 22:15:29 -08001680def _signature_strip_non_python_syntax(signature):
1681 """
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001682 Private helper function. Takes a signature in Argument Clinic's
1683 extended signature format.
1684
Larry Hastings2623c8c2014-02-08 22:15:29 -08001685 Returns a tuple of three things:
1686 * that signature re-rendered in standard Python syntax,
1687 * the index of the "self" parameter (generally 0), or None if
1688 the function does not have a "self" parameter, and
1689 * the index of the last "positional only" parameter,
1690 or None if the signature has no positional-only parameters.
1691 """
1692
1693 if not signature:
1694 return signature, None, None
1695
1696 self_parameter = None
1697 last_positional_only = None
1698
1699 lines = [l.encode('ascii') for l in signature.split('\n')]
1700 generator = iter(lines).__next__
1701 token_stream = tokenize.tokenize(generator)
1702
1703 delayed_comma = False
1704 skip_next_comma = False
1705 text = []
1706 add = text.append
1707
1708 current_parameter = 0
1709 OP = token.OP
1710 ERRORTOKEN = token.ERRORTOKEN
1711
1712 # token stream always starts with ENCODING token, skip it
1713 t = next(token_stream)
1714 assert t.type == tokenize.ENCODING
1715
1716 for t in token_stream:
1717 type, string = t.type, t.string
1718
1719 if type == OP:
1720 if string == ',':
1721 if skip_next_comma:
1722 skip_next_comma = False
1723 else:
1724 assert not delayed_comma
1725 delayed_comma = True
1726 current_parameter += 1
1727 continue
1728
1729 if string == '/':
1730 assert not skip_next_comma
1731 assert last_positional_only is None
1732 skip_next_comma = True
1733 last_positional_only = current_parameter - 1
1734 continue
1735
1736 if (type == ERRORTOKEN) and (string == '$'):
1737 assert self_parameter is None
1738 self_parameter = current_parameter
1739 continue
1740
1741 if delayed_comma:
1742 delayed_comma = False
1743 if not ((type == OP) and (string == ')')):
1744 add(', ')
1745 add(string)
1746 if (string == ','):
1747 add(' ')
1748 clean_signature = ''.join(text)
1749 return clean_signature, self_parameter, last_positional_only
1750
1751
Yury Selivanov57d240e2014-02-19 16:27:23 -05001752def _signature_fromstr(cls, obj, s, skip_bound_arg=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001753 """Private helper to parse content of '__text_signature__'
1754 and return a Signature based on it.
1755 """
1756
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001757 Parameter = cls._parameter_cls
1758
Larry Hastings2623c8c2014-02-08 22:15:29 -08001759 clean_signature, self_parameter, last_positional_only = \
1760 _signature_strip_non_python_syntax(s)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001761
Larry Hastings2623c8c2014-02-08 22:15:29 -08001762 program = "def foo" + clean_signature + ": pass"
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001763
1764 try:
Larry Hastings2623c8c2014-02-08 22:15:29 -08001765 module = ast.parse(program)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001766 except SyntaxError:
1767 module = None
1768
1769 if not isinstance(module, ast.Module):
1770 raise ValueError("{!r} builtin has invalid signature".format(obj))
1771
1772 f = module.body[0]
1773
1774 parameters = []
1775 empty = Parameter.empty
1776 invalid = object()
1777
1778 module = None
1779 module_dict = {}
1780 module_name = getattr(obj, '__module__', None)
1781 if module_name:
1782 module = sys.modules.get(module_name, None)
1783 if module:
1784 module_dict = module.__dict__
1785 sys_module_dict = sys.modules
1786
1787 def parse_name(node):
1788 assert isinstance(node, ast.arg)
1789 if node.annotation != None:
1790 raise ValueError("Annotations are not currently supported")
1791 return node.arg
1792
1793 def wrap_value(s):
1794 try:
1795 value = eval(s, module_dict)
1796 except NameError:
1797 try:
1798 value = eval(s, sys_module_dict)
1799 except NameError:
1800 raise RuntimeError()
1801
1802 if isinstance(value, str):
1803 return ast.Str(value)
1804 if isinstance(value, (int, float)):
1805 return ast.Num(value)
1806 if isinstance(value, bytes):
1807 return ast.Bytes(value)
1808 if value in (True, False, None):
1809 return ast.NameConstant(value)
1810 raise RuntimeError()
1811
1812 class RewriteSymbolics(ast.NodeTransformer):
1813 def visit_Attribute(self, node):
1814 a = []
1815 n = node
1816 while isinstance(n, ast.Attribute):
1817 a.append(n.attr)
1818 n = n.value
1819 if not isinstance(n, ast.Name):
1820 raise RuntimeError()
1821 a.append(n.id)
1822 value = ".".join(reversed(a))
1823 return wrap_value(value)
1824
1825 def visit_Name(self, node):
1826 if not isinstance(node.ctx, ast.Load):
1827 raise ValueError()
1828 return wrap_value(node.id)
1829
1830 def p(name_node, default_node, default=empty):
1831 name = parse_name(name_node)
1832 if name is invalid:
1833 return None
1834 if default_node and default_node is not _empty:
1835 try:
1836 default_node = RewriteSymbolics().visit(default_node)
1837 o = ast.literal_eval(default_node)
1838 except ValueError:
1839 o = invalid
1840 if o is invalid:
1841 return None
1842 default = o if o is not invalid else default
1843 parameters.append(Parameter(name, kind, default=default, annotation=empty))
1844
1845 # non-keyword-only parameters
1846 args = reversed(f.args.args)
1847 defaults = reversed(f.args.defaults)
1848 iter = itertools.zip_longest(args, defaults, fillvalue=None)
Larry Hastings2623c8c2014-02-08 22:15:29 -08001849 if last_positional_only is not None:
1850 kind = Parameter.POSITIONAL_ONLY
1851 else:
1852 kind = Parameter.POSITIONAL_OR_KEYWORD
1853 for i, (name, default) in enumerate(reversed(list(iter))):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001854 p(name, default)
Larry Hastings2623c8c2014-02-08 22:15:29 -08001855 if i == last_positional_only:
1856 kind = Parameter.POSITIONAL_OR_KEYWORD
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001857
1858 # *args
1859 if f.args.vararg:
1860 kind = Parameter.VAR_POSITIONAL
1861 p(f.args.vararg, empty)
1862
1863 # keyword-only arguments
1864 kind = Parameter.KEYWORD_ONLY
1865 for name, default in zip(f.args.kwonlyargs, f.args.kw_defaults):
1866 p(name, default)
1867
1868 # **kwargs
1869 if f.args.kwarg:
1870 kind = Parameter.VAR_KEYWORD
1871 p(f.args.kwarg, empty)
1872
Larry Hastings2623c8c2014-02-08 22:15:29 -08001873 if self_parameter is not None:
Yury Selivanov8c185ee2014-02-21 01:32:42 -05001874 # Possibly strip the bound argument:
1875 # - We *always* strip first bound argument if
1876 # it is a module.
1877 # - We don't strip first bound argument if
1878 # skip_bound_arg is False.
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001879 assert parameters
Yury Selivanov8c185ee2014-02-21 01:32:42 -05001880 _self = getattr(obj, '__self__', None)
1881 self_isbound = _self is not None
1882 self_ismodule = ismodule(_self)
1883 if self_isbound and (self_ismodule or skip_bound_arg):
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05001884 parameters.pop(0)
1885 else:
1886 # for builtins, self parameter is always positional-only!
1887 p = parameters[0].replace(kind=Parameter.POSITIONAL_ONLY)
1888 parameters[0] = p
1889
1890 return cls(parameters, return_annotation=cls.empty)
1891
1892
Yury Selivanov57d240e2014-02-19 16:27:23 -05001893def _signature_from_builtin(cls, func, skip_bound_arg=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001894 """Private helper function to get signature for
1895 builtin callables.
1896 """
1897
Yury Selivanov57d240e2014-02-19 16:27:23 -05001898 if not _signature_is_builtin(func):
1899 raise TypeError("{!r} is not a Python builtin "
1900 "function".format(func))
1901
1902 s = getattr(func, "__text_signature__", None)
1903 if not s:
1904 raise ValueError("no signature found for builtin {!r}".format(func))
1905
1906 return _signature_fromstr(cls, func, s, skip_bound_arg)
1907
1908
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001909def _signature_from_callable(obj, *,
1910 follow_wrapper_chains=True,
1911 skip_bound_arg=True,
1912 sigcls):
1913
1914 """Private helper function to get signature for arbitrary
1915 callable objects.
1916 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001917
1918 if not callable(obj):
1919 raise TypeError('{!r} is not a callable object'.format(obj))
1920
1921 if isinstance(obj, types.MethodType):
1922 # In this case we skip the first parameter of the underlying
1923 # function (usually `self` or `cls`).
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001924 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04001925 obj.__func__,
1926 follow_wrapper_chains=follow_wrapper_chains,
1927 skip_bound_arg=skip_bound_arg,
1928 sigcls=sigcls)
1929
Yury Selivanov57d240e2014-02-19 16:27:23 -05001930 if skip_bound_arg:
1931 return _signature_bound_method(sig)
1932 else:
1933 return sig
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001934
Nick Coghlane8c45d62013-07-28 20:00:01 +10001935 # Was this function wrapped by a decorator?
Yury Selivanov57d240e2014-02-19 16:27:23 -05001936 if follow_wrapper_chains:
1937 obj = unwrap(obj, stop=(lambda f: hasattr(f, "__signature__")))
Nick Coghlane8c45d62013-07-28 20:00:01 +10001938
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001939 try:
1940 sig = obj.__signature__
1941 except AttributeError:
1942 pass
1943 else:
1944 if sig is not None:
Yury Selivanov42407ab2014-06-23 10:23:50 -07001945 if not isinstance(sig, Signature):
1946 raise TypeError(
1947 'unexpected object {!r} in __signature__ '
1948 'attribute'.format(sig))
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001949 return sig
1950
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001951 try:
1952 partialmethod = obj._partialmethod
1953 except AttributeError:
1954 pass
1955 else:
Yury Selivanov0486f812014-01-29 12:18:59 -05001956 if isinstance(partialmethod, functools.partialmethod):
1957 # Unbound partialmethod (see functools.partialmethod)
1958 # This means, that we need to calculate the signature
1959 # as if it's a regular partial object, but taking into
1960 # account that the first positional argument
1961 # (usually `self`, or `cls`) will not be passed
1962 # automatically (as for boundmethods)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001963
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001964 wrapped_sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04001965 partialmethod.func,
1966 follow_wrapper_chains=follow_wrapper_chains,
1967 skip_bound_arg=skip_bound_arg,
1968 sigcls=sigcls)
1969
Yury Selivanov0486f812014-01-29 12:18:59 -05001970 sig = _signature_get_partial(wrapped_sig, partialmethod, (None,))
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001971
Yury Selivanov0486f812014-01-29 12:18:59 -05001972 first_wrapped_param = tuple(wrapped_sig.parameters.values())[0]
1973 new_params = (first_wrapped_param,) + tuple(sig.parameters.values())
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001974
Yury Selivanov0486f812014-01-29 12:18:59 -05001975 return sig.replace(parameters=new_params)
Yury Selivanovda5fe4f2014-01-27 17:28:37 -05001976
Yury Selivanov63da7c72014-01-31 14:48:37 -05001977 if isfunction(obj) or _signature_is_functionlike(obj):
1978 # If it's a pure Python function, or an object that is duck type
1979 # of a Python function (Cython functions, for instance), then:
Yury Selivanovda396452014-03-27 12:09:24 -04001980 return sigcls.from_function(obj)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001981
Yury Selivanova773de02014-02-21 18:30:53 -05001982 if _signature_is_builtin(obj):
Yury Selivanovda396452014-03-27 12:09:24 -04001983 return _signature_from_builtin(sigcls, obj,
Yury Selivanova773de02014-02-21 18:30:53 -05001984 skip_bound_arg=skip_bound_arg)
1985
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001986 if isinstance(obj, functools.partial):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04001987 wrapped_sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04001988 obj.func,
1989 follow_wrapper_chains=follow_wrapper_chains,
1990 skip_bound_arg=skip_bound_arg,
1991 sigcls=sigcls)
Yury Selivanov62560fb2014-01-28 12:26:24 -05001992 return _signature_get_partial(wrapped_sig, obj)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07001993
1994 sig = None
1995 if isinstance(obj, type):
1996 # obj is a class or a metaclass
1997
1998 # First, let's see if it has an overloaded __call__ defined
1999 # in its metaclass
Yury Selivanov421f0c72014-01-29 12:05:40 -05002000 call = _signature_get_user_defined_method(type(obj), '__call__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002001 if call is not None:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002002 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002003 call,
2004 follow_wrapper_chains=follow_wrapper_chains,
2005 skip_bound_arg=skip_bound_arg,
2006 sigcls=sigcls)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002007 else:
2008 # Now we check if the 'obj' class has a '__new__' method
Yury Selivanov421f0c72014-01-29 12:05:40 -05002009 new = _signature_get_user_defined_method(obj, '__new__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002010 if new is not None:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002011 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002012 new,
2013 follow_wrapper_chains=follow_wrapper_chains,
2014 skip_bound_arg=skip_bound_arg,
2015 sigcls=sigcls)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002016 else:
2017 # Finally, we should have at least __init__ implemented
Yury Selivanov421f0c72014-01-29 12:05:40 -05002018 init = _signature_get_user_defined_method(obj, '__init__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002019 if init is not None:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002020 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002021 init,
2022 follow_wrapper_chains=follow_wrapper_chains,
2023 skip_bound_arg=skip_bound_arg,
2024 sigcls=sigcls)
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002025
2026 if sig is None:
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002027 # At this point we know, that `obj` is a class, with no user-
2028 # defined '__init__', '__new__', or class-level '__call__'
2029
Larry Hastings2623c8c2014-02-08 22:15:29 -08002030 for base in obj.__mro__[:-1]:
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002031 # Since '__text_signature__' is implemented as a
2032 # descriptor that extracts text signature from the
2033 # class docstring, if 'obj' is derived from a builtin
2034 # class, its own '__text_signature__' may be 'None'.
Larry Hastings2623c8c2014-02-08 22:15:29 -08002035 # Therefore, we go through the MRO (except the last
2036 # class in there, which is 'object') to find the first
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002037 # class with non-empty text signature.
2038 try:
2039 text_sig = base.__text_signature__
2040 except AttributeError:
2041 pass
2042 else:
2043 if text_sig:
2044 # If 'obj' class has a __text_signature__ attribute:
2045 # return a signature based on it
Yury Selivanovda396452014-03-27 12:09:24 -04002046 return _signature_fromstr(sigcls, obj, text_sig)
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002047
2048 # No '__text_signature__' was found for the 'obj' class.
2049 # Last option is to check if its '__init__' is
2050 # object.__init__ or type.__init__.
Larry Hastings2623c8c2014-02-08 22:15:29 -08002051 if type not in obj.__mro__:
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002052 # We have a class (not metaclass), but no user-defined
2053 # __init__ or __new__ for it
Yury Selivanov7d2bfed2014-02-03 02:46:07 -05002054 if obj.__init__ is object.__init__:
2055 # Return a signature of 'object' builtin.
2056 return signature(object)
Yury Selivanove7dcc5e2014-01-27 19:29:45 -05002057
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002058 elif not isinstance(obj, _NonUserDefinedCallables):
2059 # An object with __call__
2060 # We also check that the 'obj' is not an instance of
2061 # _WrapperDescriptor or _MethodWrapper to avoid
2062 # infinite recursion (and even potential segfault)
Yury Selivanov421f0c72014-01-29 12:05:40 -05002063 call = _signature_get_user_defined_method(type(obj), '__call__')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002064 if call is not None:
Larry Hastings2623c8c2014-02-08 22:15:29 -08002065 try:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002066 sig = _signature_from_callable(
Yury Selivanovda396452014-03-27 12:09:24 -04002067 call,
2068 follow_wrapper_chains=follow_wrapper_chains,
2069 skip_bound_arg=skip_bound_arg,
2070 sigcls=sigcls)
Larry Hastings2623c8c2014-02-08 22:15:29 -08002071 except ValueError as ex:
2072 msg = 'no signature found for {!r}'.format(obj)
2073 raise ValueError(msg) from ex
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002074
2075 if sig is not None:
2076 # For classes and objects we skip the first parameter of their
2077 # __call__, __new__, or __init__ methods
Yury Selivanov57d240e2014-02-19 16:27:23 -05002078 if skip_bound_arg:
2079 return _signature_bound_method(sig)
2080 else:
2081 return sig
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002082
2083 if isinstance(obj, types.BuiltinFunctionType):
2084 # Raise a nicer error message for builtins
2085 msg = 'no signature found for builtin function {!r}'.format(obj)
2086 raise ValueError(msg)
2087
2088 raise ValueError('callable {!r} is not supported by signature'.format(obj))
2089
2090
2091class _void:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002092 """A private marker - used in Parameter & Signature."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002093
2094
2095class _empty:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002096 """Marker object for Signature.empty and Parameter.empty."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002097
2098
Yury Selivanov21e83a52014-03-27 11:23:13 -04002099class _ParameterKind(enum.IntEnum):
2100 POSITIONAL_ONLY = 0
2101 POSITIONAL_OR_KEYWORD = 1
2102 VAR_POSITIONAL = 2
2103 KEYWORD_ONLY = 3
2104 VAR_KEYWORD = 4
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002105
2106 def __str__(self):
Yury Selivanov21e83a52014-03-27 11:23:13 -04002107 return self._name_
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002108
2109
Yury Selivanov21e83a52014-03-27 11:23:13 -04002110_POSITIONAL_ONLY = _ParameterKind.POSITIONAL_ONLY
2111_POSITIONAL_OR_KEYWORD = _ParameterKind.POSITIONAL_OR_KEYWORD
2112_VAR_POSITIONAL = _ParameterKind.VAR_POSITIONAL
2113_KEYWORD_ONLY = _ParameterKind.KEYWORD_ONLY
2114_VAR_KEYWORD = _ParameterKind.VAR_KEYWORD
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002115
2116
2117class Parameter:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002118 """Represents a parameter in a function signature.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002119
2120 Has the following public attributes:
2121
2122 * name : str
2123 The name of the parameter as a string.
2124 * default : object
2125 The default value for the parameter if specified. If the
Yury Selivanov8757ead2014-01-28 16:39:25 -05002126 parameter has no default value, this attribute is set to
2127 `Parameter.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002128 * annotation
2129 The annotation for the parameter if specified. If the
Yury Selivanov8757ead2014-01-28 16:39:25 -05002130 parameter has no annotation, this attribute is set to
2131 `Parameter.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002132 * kind : str
2133 Describes how argument values are bound to the parameter.
2134 Possible values: `Parameter.POSITIONAL_ONLY`,
2135 `Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
2136 `Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002137 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002138
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002139 __slots__ = ('_name', '_kind', '_default', '_annotation')
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002140
2141 POSITIONAL_ONLY = _POSITIONAL_ONLY
2142 POSITIONAL_OR_KEYWORD = _POSITIONAL_OR_KEYWORD
2143 VAR_POSITIONAL = _VAR_POSITIONAL
2144 KEYWORD_ONLY = _KEYWORD_ONLY
2145 VAR_KEYWORD = _VAR_KEYWORD
2146
2147 empty = _empty
2148
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002149 def __init__(self, name, kind, *, default=_empty, annotation=_empty):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002150
2151 if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
2152 _VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
2153 raise ValueError("invalid value for 'Parameter.kind' attribute")
2154 self._kind = kind
2155
2156 if default is not _empty:
2157 if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
2158 msg = '{} parameters cannot have default values'.format(kind)
2159 raise ValueError(msg)
2160 self._default = default
2161 self._annotation = annotation
2162
Yury Selivanov2393dca2014-01-27 15:07:58 -05002163 if name is _empty:
2164 raise ValueError('name is a required attribute for Parameter')
2165
2166 if not isinstance(name, str):
2167 raise TypeError("name must be a str, not a {!r}".format(name))
2168
2169 if not name.isidentifier():
2170 raise ValueError('{!r} is not a valid parameter name'.format(name))
2171
2172 self._name = name
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002173
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002174 def __reduce__(self):
2175 return (type(self),
2176 (self._name, self._kind),
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002177 {'_default': self._default,
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002178 '_annotation': self._annotation})
2179
2180 def __setstate__(self, state):
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002181 self._default = state['_default']
2182 self._annotation = state['_annotation']
2183
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002184 @property
2185 def name(self):
2186 return self._name
2187
2188 @property
2189 def default(self):
2190 return self._default
2191
2192 @property
2193 def annotation(self):
2194 return self._annotation
2195
2196 @property
2197 def kind(self):
2198 return self._kind
2199
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002200 def replace(self, *, name=_void, kind=_void,
2201 annotation=_void, default=_void):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002202 """Creates a customized copy of the Parameter."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002203
2204 if name is _void:
2205 name = self._name
2206
2207 if kind is _void:
2208 kind = self._kind
2209
2210 if annotation is _void:
2211 annotation = self._annotation
2212
2213 if default is _void:
2214 default = self._default
2215
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002216 return type(self)(name, kind, default=default, annotation=annotation)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002217
2218 def __str__(self):
2219 kind = self.kind
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002220 formatted = self._name
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002221
2222 # Add annotation and default value
2223 if self._annotation is not _empty:
2224 formatted = '{}:{}'.format(formatted,
2225 formatannotation(self._annotation))
2226
2227 if self._default is not _empty:
2228 formatted = '{}={}'.format(formatted, repr(self._default))
2229
2230 if kind == _VAR_POSITIONAL:
2231 formatted = '*' + formatted
2232 elif kind == _VAR_KEYWORD:
2233 formatted = '**' + formatted
2234
2235 return formatted
2236
2237 def __repr__(self):
Yury Selivanov374375d2014-03-27 12:41:53 -04002238 return '<{} at {:#x} "{}">'.format(self.__class__.__name__,
2239 id(self), self)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002240
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002241 def __hash__(self):
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002242 return hash((self.name, self.kind, self.annotation, self.default))
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002243
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002244 def __eq__(self, other):
2245 return (issubclass(other.__class__, Parameter) and
2246 self._name == other._name and
2247 self._kind == other._kind and
2248 self._default == other._default and
2249 self._annotation == other._annotation)
2250
2251 def __ne__(self, other):
2252 return not self.__eq__(other)
2253
2254
2255class BoundArguments:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002256 """Result of `Signature.bind` call. Holds the mapping of arguments
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002257 to the function's parameters.
2258
2259 Has the following public attributes:
2260
2261 * arguments : OrderedDict
2262 An ordered mutable mapping of parameters' names to arguments' values.
2263 Does not contain arguments' default values.
2264 * signature : Signature
2265 The Signature object that created this instance.
2266 * args : tuple
2267 Tuple of positional arguments values.
2268 * kwargs : dict
2269 Dict of keyword arguments values.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002270 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002271
2272 def __init__(self, signature, arguments):
2273 self.arguments = arguments
2274 self._signature = signature
2275
2276 @property
2277 def signature(self):
2278 return self._signature
2279
2280 @property
2281 def args(self):
2282 args = []
2283 for param_name, param in self._signature.parameters.items():
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002284 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002285 break
2286
2287 try:
2288 arg = self.arguments[param_name]
2289 except KeyError:
2290 # We're done here. Other arguments
2291 # will be mapped in 'BoundArguments.kwargs'
2292 break
2293 else:
2294 if param.kind == _VAR_POSITIONAL:
2295 # *args
2296 args.extend(arg)
2297 else:
2298 # plain argument
2299 args.append(arg)
2300
2301 return tuple(args)
2302
2303 @property
2304 def kwargs(self):
2305 kwargs = {}
2306 kwargs_started = False
2307 for param_name, param in self._signature.parameters.items():
2308 if not kwargs_started:
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002309 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002310 kwargs_started = True
2311 else:
2312 if param_name not in self.arguments:
2313 kwargs_started = True
2314 continue
2315
2316 if not kwargs_started:
2317 continue
2318
2319 try:
2320 arg = self.arguments[param_name]
2321 except KeyError:
2322 pass
2323 else:
2324 if param.kind == _VAR_KEYWORD:
2325 # **kwargs
2326 kwargs.update(arg)
2327 else:
2328 # plain keyword argument
2329 kwargs[param_name] = arg
2330
2331 return kwargs
2332
2333 def __eq__(self, other):
2334 return (issubclass(other.__class__, BoundArguments) and
2335 self.signature == other.signature and
2336 self.arguments == other.arguments)
2337
2338 def __ne__(self, other):
2339 return not self.__eq__(other)
2340
2341
2342class Signature:
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002343 """A Signature object represents the overall signature of a function.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002344 It stores a Parameter object for each parameter accepted by the
2345 function, as well as information specific to the function itself.
2346
2347 A Signature object has the following public attributes and methods:
2348
2349 * parameters : OrderedDict
2350 An ordered mapping of parameters' names to the corresponding
2351 Parameter objects (keyword-only arguments are in the same order
2352 as listed in `code.co_varnames`).
2353 * return_annotation : object
2354 The annotation for the return type of the function if specified.
2355 If the function has no annotation for its return type, this
Yury Selivanov8757ead2014-01-28 16:39:25 -05002356 attribute is set to `Signature.empty`.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002357 * bind(*args, **kwargs) -> BoundArguments
2358 Creates a mapping from positional and keyword arguments to
2359 parameters.
2360 * bind_partial(*args, **kwargs) -> BoundArguments
2361 Creates a partial mapping from positional and keyword arguments
2362 to parameters (simulating 'functools.partial' behavior.)
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002363 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002364
2365 __slots__ = ('_return_annotation', '_parameters')
2366
2367 _parameter_cls = Parameter
2368 _bound_arguments_cls = BoundArguments
2369
2370 empty = _empty
2371
2372 def __init__(self, parameters=None, *, return_annotation=_empty,
2373 __validate_parameters__=True):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002374 """Constructs Signature from the given list of Parameter
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002375 objects and 'return_annotation'. All arguments are optional.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002376 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002377
2378 if parameters is None:
2379 params = OrderedDict()
2380 else:
2381 if __validate_parameters__:
2382 params = OrderedDict()
2383 top_kind = _POSITIONAL_ONLY
Yury Selivanov07a9e452014-01-29 10:58:16 -05002384 kind_defaults = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002385
2386 for idx, param in enumerate(parameters):
2387 kind = param.kind
Yury Selivanov2393dca2014-01-27 15:07:58 -05002388 name = param.name
2389
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002390 if kind < top_kind:
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002391 msg = 'wrong parameter order: {!r} before {!r}'
Yury Selivanov2393dca2014-01-27 15:07:58 -05002392 msg = msg.format(top_kind, kind)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002393 raise ValueError(msg)
Yury Selivanov07a9e452014-01-29 10:58:16 -05002394 elif kind > top_kind:
2395 kind_defaults = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002396 top_kind = kind
2397
Yury Selivanov3f73ca22014-04-08 11:30:45 -04002398 if kind in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD):
Yury Selivanov07a9e452014-01-29 10:58:16 -05002399 if param.default is _empty:
2400 if kind_defaults:
2401 # No default for this parameter, but the
2402 # previous parameter of the same kind had
2403 # a default
2404 msg = 'non-default argument follows default ' \
2405 'argument'
2406 raise ValueError(msg)
2407 else:
2408 # There is a default for this parameter.
2409 kind_defaults = True
2410
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002411 if name in params:
2412 msg = 'duplicate parameter name: {!r}'.format(name)
2413 raise ValueError(msg)
Yury Selivanov2393dca2014-01-27 15:07:58 -05002414
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002415 params[name] = param
2416 else:
2417 params = OrderedDict(((param.name, param)
2418 for param in parameters))
2419
2420 self._parameters = types.MappingProxyType(params)
2421 self._return_annotation = return_annotation
2422
2423 @classmethod
2424 def from_function(cls, func):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002425 """Constructs Signature for the given python function."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002426
Yury Selivanov5334bcd2014-01-31 15:21:51 -05002427 is_duck_function = False
2428 if not isfunction(func):
2429 if _signature_is_functionlike(func):
2430 is_duck_function = True
2431 else:
2432 # If it's not a pure Python function, and not a duck type
2433 # of pure function:
2434 raise TypeError('{!r} is not a Python function'.format(func))
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002435
2436 Parameter = cls._parameter_cls
2437
2438 # Parameter information.
2439 func_code = func.__code__
2440 pos_count = func_code.co_argcount
2441 arg_names = func_code.co_varnames
2442 positional = tuple(arg_names[:pos_count])
2443 keyword_only_count = func_code.co_kwonlyargcount
2444 keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
2445 annotations = func.__annotations__
2446 defaults = func.__defaults__
2447 kwdefaults = func.__kwdefaults__
2448
2449 if defaults:
2450 pos_default_count = len(defaults)
2451 else:
2452 pos_default_count = 0
2453
2454 parameters = []
2455
2456 # Non-keyword-only parameters w/o defaults.
2457 non_default_count = pos_count - pos_default_count
2458 for name in positional[:non_default_count]:
2459 annotation = annotations.get(name, _empty)
2460 parameters.append(Parameter(name, annotation=annotation,
2461 kind=_POSITIONAL_OR_KEYWORD))
2462
2463 # ... w/ defaults.
2464 for offset, name in enumerate(positional[non_default_count:]):
2465 annotation = annotations.get(name, _empty)
2466 parameters.append(Parameter(name, annotation=annotation,
2467 kind=_POSITIONAL_OR_KEYWORD,
2468 default=defaults[offset]))
2469
2470 # *args
Yury Selivanov89ca85c2014-01-29 16:50:40 -05002471 if func_code.co_flags & CO_VARARGS:
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002472 name = arg_names[pos_count + keyword_only_count]
2473 annotation = annotations.get(name, _empty)
2474 parameters.append(Parameter(name, annotation=annotation,
2475 kind=_VAR_POSITIONAL))
2476
2477 # Keyword-only parameters.
2478 for name in keyword_only:
2479 default = _empty
2480 if kwdefaults is not None:
2481 default = kwdefaults.get(name, _empty)
2482
2483 annotation = annotations.get(name, _empty)
2484 parameters.append(Parameter(name, annotation=annotation,
2485 kind=_KEYWORD_ONLY,
2486 default=default))
2487 # **kwargs
Yury Selivanov89ca85c2014-01-29 16:50:40 -05002488 if func_code.co_flags & CO_VARKEYWORDS:
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002489 index = pos_count + keyword_only_count
Yury Selivanov89ca85c2014-01-29 16:50:40 -05002490 if func_code.co_flags & CO_VARARGS:
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002491 index += 1
2492
2493 name = arg_names[index]
2494 annotation = annotations.get(name, _empty)
2495 parameters.append(Parameter(name, annotation=annotation,
2496 kind=_VAR_KEYWORD))
2497
Yury Selivanov5334bcd2014-01-31 15:21:51 -05002498 # Is 'func' is a pure Python function - don't validate the
2499 # parameters list (for correct order and defaults), it should be OK.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002500 return cls(parameters,
2501 return_annotation=annotations.get('return', _empty),
Yury Selivanov5334bcd2014-01-31 15:21:51 -05002502 __validate_parameters__=is_duck_function)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002503
Larry Hastings44e2eaa2013-11-23 15:37:55 -08002504 @classmethod
2505 def from_builtin(cls, func):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002506 """Constructs Signature for the given builtin function."""
Yury Selivanov57d240e2014-02-19 16:27:23 -05002507 return _signature_from_builtin(cls, func)
Larry Hastings44e2eaa2013-11-23 15:37:55 -08002508
Yury Selivanovda396452014-03-27 12:09:24 -04002509 @classmethod
2510 def from_callable(cls, obj):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002511 """Constructs Signature for the given callable object."""
2512 return _signature_from_callable(obj, sigcls=cls)
Yury Selivanovda396452014-03-27 12:09:24 -04002513
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002514 @property
2515 def parameters(self):
2516 return self._parameters
2517
2518 @property
2519 def return_annotation(self):
2520 return self._return_annotation
2521
2522 def replace(self, *, parameters=_void, return_annotation=_void):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002523 """Creates a customized copy of the Signature.
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002524 Pass 'parameters' and/or 'return_annotation' arguments
2525 to override them in the new copy.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002526 """
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002527
2528 if parameters is _void:
2529 parameters = self.parameters.values()
2530
2531 if return_annotation is _void:
2532 return_annotation = self._return_annotation
2533
2534 return type(self)(parameters,
2535 return_annotation=return_annotation)
2536
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002537 def _hash_basis(self):
2538 params = tuple(param for param in self.parameters.values()
2539 if param.kind != _KEYWORD_ONLY)
2540
2541 kwo_params = {param.name: param for param in self.parameters.values()
2542 if param.kind == _KEYWORD_ONLY}
2543
2544 return params, kwo_params, self.return_annotation
2545
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002546 def __hash__(self):
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002547 params, kwo_params, return_annotation = self._hash_basis()
2548 kwo_params = frozenset(kwo_params.values())
2549 return hash((params, kwo_params, return_annotation))
Yury Selivanov67ae50e2014-04-08 11:46:50 -04002550
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002551 def __eq__(self, other):
Yury Selivanov08d4a4f2014-09-12 15:48:02 -04002552 return (isinstance(other, Signature) and
2553 self._hash_basis() == other._hash_basis())
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002554
2555 def __ne__(self, other):
2556 return not self.__eq__(other)
2557
2558 def _bind(self, args, kwargs, *, partial=False):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002559 """Private method. Don't use directly."""
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002560
2561 arguments = OrderedDict()
2562
2563 parameters = iter(self.parameters.values())
2564 parameters_ex = ()
2565 arg_vals = iter(args)
2566
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002567 while True:
2568 # Let's iterate through the positional arguments and corresponding
2569 # parameters
2570 try:
2571 arg_val = next(arg_vals)
2572 except StopIteration:
2573 # No more positional arguments
2574 try:
2575 param = next(parameters)
2576 except StopIteration:
2577 # No more parameters. That's it. Just need to check that
2578 # we have no `kwargs` after this while loop
2579 break
2580 else:
2581 if param.kind == _VAR_POSITIONAL:
2582 # That's OK, just empty *args. Let's start parsing
2583 # kwargs
2584 break
2585 elif param.name in kwargs:
2586 if param.kind == _POSITIONAL_ONLY:
2587 msg = '{arg!r} parameter is positional only, ' \
2588 'but was passed as a keyword'
2589 msg = msg.format(arg=param.name)
2590 raise TypeError(msg) from None
2591 parameters_ex = (param,)
2592 break
2593 elif (param.kind == _VAR_KEYWORD or
2594 param.default is not _empty):
2595 # That's fine too - we have a default value for this
2596 # parameter. So, lets start parsing `kwargs`, starting
2597 # with the current parameter
2598 parameters_ex = (param,)
2599 break
2600 else:
Yury Selivanov38b0d5a2014-01-28 17:27:39 -05002601 # No default, not VAR_KEYWORD, not VAR_POSITIONAL,
2602 # not in `kwargs`
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002603 if partial:
2604 parameters_ex = (param,)
2605 break
2606 else:
2607 msg = '{arg!r} parameter lacking default value'
2608 msg = msg.format(arg=param.name)
2609 raise TypeError(msg) from None
2610 else:
2611 # We have a positional argument to process
2612 try:
2613 param = next(parameters)
2614 except StopIteration:
2615 raise TypeError('too many positional arguments') from None
2616 else:
2617 if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
2618 # Looks like we have no parameter for this positional
2619 # argument
2620 raise TypeError('too many positional arguments')
2621
2622 if param.kind == _VAR_POSITIONAL:
2623 # We have an '*args'-like argument, let's fill it with
2624 # all positional arguments we have left and move on to
2625 # the next phase
2626 values = [arg_val]
2627 values.extend(arg_vals)
2628 arguments[param.name] = tuple(values)
2629 break
2630
2631 if param.name in kwargs:
2632 raise TypeError('multiple values for argument '
2633 '{arg!r}'.format(arg=param.name))
2634
2635 arguments[param.name] = arg_val
2636
2637 # Now, we iterate through the remaining parameters to process
2638 # keyword arguments
2639 kwargs_param = None
2640 for param in itertools.chain(parameters_ex, parameters):
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002641 if param.kind == _VAR_KEYWORD:
2642 # Memorize that we have a '**kwargs'-like parameter
2643 kwargs_param = param
2644 continue
2645
Yury Selivanov38b0d5a2014-01-28 17:27:39 -05002646 if param.kind == _VAR_POSITIONAL:
2647 # Named arguments don't refer to '*args'-like parameters.
2648 # We only arrive here if the positional arguments ended
2649 # before reaching the last parameter before *args.
2650 continue
2651
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002652 param_name = param.name
2653 try:
2654 arg_val = kwargs.pop(param_name)
2655 except KeyError:
2656 # We have no value for this parameter. It's fine though,
2657 # if it has a default value, or it is an '*args'-like
2658 # parameter, left alone by the processing of positional
2659 # arguments.
2660 if (not partial and param.kind != _VAR_POSITIONAL and
2661 param.default is _empty):
2662 raise TypeError('{arg!r} parameter lacking default value'. \
2663 format(arg=param_name)) from None
2664
2665 else:
Yury Selivanov9b9ac952014-01-28 20:54:28 -05002666 if param.kind == _POSITIONAL_ONLY:
2667 # This should never happen in case of a properly built
2668 # Signature object (but let's have this check here
2669 # to ensure correct behaviour just in case)
2670 raise TypeError('{arg!r} parameter is positional only, '
2671 'but was passed as a keyword'. \
2672 format(arg=param.name))
2673
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002674 arguments[param_name] = arg_val
2675
2676 if kwargs:
2677 if kwargs_param is not None:
2678 # Process our '**kwargs'-like parameter
2679 arguments[kwargs_param.name] = kwargs
2680 else:
2681 raise TypeError('too many keyword arguments')
2682
2683 return self._bound_arguments_cls(self, arguments)
2684
Yury Selivanovc45873e2014-01-29 12:10:27 -05002685 def bind(*args, **kwargs):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002686 """Get a BoundArguments object, that maps the passed `args`
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002687 and `kwargs` to the function's signature. Raises `TypeError`
2688 if the passed arguments can not be bound.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002689 """
Yury Selivanovc45873e2014-01-29 12:10:27 -05002690 return args[0]._bind(args[1:], kwargs)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002691
Yury Selivanovc45873e2014-01-29 12:10:27 -05002692 def bind_partial(*args, **kwargs):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002693 """Get a BoundArguments object, that partially maps the
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002694 passed `args` and `kwargs` to the function's signature.
2695 Raises `TypeError` if the passed arguments can not be bound.
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002696 """
Yury Selivanovc45873e2014-01-29 12:10:27 -05002697 return args[0]._bind(args[1:], kwargs, partial=True)
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002698
Yury Selivanova5d63dd2014-03-27 11:31:43 -04002699 def __reduce__(self):
2700 return (type(self),
2701 (tuple(self._parameters.values()),),
2702 {'_return_annotation': self._return_annotation})
2703
2704 def __setstate__(self, state):
2705 self._return_annotation = state['_return_annotation']
2706
Yury Selivanov374375d2014-03-27 12:41:53 -04002707 def __repr__(self):
2708 return '<{} at {:#x} "{}">'.format(self.__class__.__name__,
2709 id(self), self)
2710
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002711 def __str__(self):
2712 result = []
Yury Selivanov2393dca2014-01-27 15:07:58 -05002713 render_pos_only_separator = False
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002714 render_kw_only_separator = True
Yury Selivanov2393dca2014-01-27 15:07:58 -05002715 for param in self.parameters.values():
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002716 formatted = str(param)
2717
2718 kind = param.kind
Yury Selivanov2393dca2014-01-27 15:07:58 -05002719
2720 if kind == _POSITIONAL_ONLY:
2721 render_pos_only_separator = True
2722 elif render_pos_only_separator:
2723 # It's not a positional-only parameter, and the flag
2724 # is set to 'True' (there were pos-only params before.)
2725 result.append('/')
2726 render_pos_only_separator = False
2727
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002728 if kind == _VAR_POSITIONAL:
2729 # OK, we have an '*args'-like parameter, so we won't need
2730 # a '*' to separate keyword-only arguments
2731 render_kw_only_separator = False
2732 elif kind == _KEYWORD_ONLY and render_kw_only_separator:
2733 # We have a keyword-only parameter to render and we haven't
2734 # rendered an '*args'-like parameter before, so add a '*'
2735 # separator to the parameters list ("foo(arg1, *, arg2)" case)
2736 result.append('*')
2737 # This condition should be only triggered once, so
2738 # reset the flag
2739 render_kw_only_separator = False
2740
2741 result.append(formatted)
2742
Yury Selivanov2393dca2014-01-27 15:07:58 -05002743 if render_pos_only_separator:
2744 # There were only positional-only parameters, hence the
2745 # flag was not reset to 'False'
2746 result.append('/')
2747
Larry Hastings7c7cbfc2012-06-22 15:19:35 -07002748 rendered = '({})'.format(', '.join(result))
2749
2750 if self.return_annotation is not _empty:
2751 anno = formatannotation(self.return_annotation)
2752 rendered += ' -> {}'.format(anno)
2753
2754 return rendered
Nick Coghlanf94a16b2013-09-22 22:46:49 +10002755
Yury Selivanovda396452014-03-27 12:09:24 -04002756
2757def signature(obj):
Yury Selivanov5a23bd02014-03-29 13:47:11 -04002758 """Get a signature object for the passed callable."""
Yury Selivanovda396452014-03-27 12:09:24 -04002759 return Signature.from_callable(obj)
2760
2761
Nick Coghlanf94a16b2013-09-22 22:46:49 +10002762def _main():
2763 """ Logic for inspecting an object given at command line """
2764 import argparse
2765 import importlib
2766
2767 parser = argparse.ArgumentParser()
2768 parser.add_argument(
2769 'object',
2770 help="The object to be analysed. "
2771 "It supports the 'module:qualname' syntax")
2772 parser.add_argument(
2773 '-d', '--details', action='store_true',
2774 help='Display info about the module rather than its source code')
2775
2776 args = parser.parse_args()
2777
2778 target = args.object
2779 mod_name, has_attrs, attrs = target.partition(":")
2780 try:
2781 obj = module = importlib.import_module(mod_name)
2782 except Exception as exc:
2783 msg = "Failed to import {} ({}: {})".format(mod_name,
2784 type(exc).__name__,
2785 exc)
2786 print(msg, file=sys.stderr)
2787 exit(2)
2788
2789 if has_attrs:
2790 parts = attrs.split(".")
2791 obj = module
2792 for part in parts:
2793 obj = getattr(obj, part)
2794
2795 if module.__name__ in sys.builtin_module_names:
2796 print("Can't get info for builtin modules.", file=sys.stderr)
2797 exit(1)
2798
2799 if args.details:
2800 print('Target: {}'.format(target))
2801 print('Origin: {}'.format(getsourcefile(module)))
2802 print('Cached: {}'.format(module.__cached__))
2803 if obj is module:
2804 print('Loader: {}'.format(repr(module.__loader__)))
2805 if hasattr(module, '__path__'):
2806 print('Submodule search path: {}'.format(module.__path__))
2807 else:
2808 try:
2809 __, lineno = findsource(obj)
2810 except Exception:
2811 pass
2812 else:
2813 print('Line: {}'.format(lineno))
2814
2815 print('\n')
2816 else:
2817 print(getsource(obj))
2818
2819
2820if __name__ == "__main__":
2821 _main()