1.. funcsigs documentation master file, created by 2 sphinx-quickstart on Fri Apr 20 20:27:52 2012. 3 You can adapt this file completely to your liking, but it should at least 4 contain the root `toctree` directive. 5 6Introducing funcsigs 7==================== 8 9The Funcsigs Package 10-------------------- 11 12*funcsigs* is a backport of the `PEP 362`_ function signature features from 13Python 3.3's `inspect`_ module. The backport is compatible with Python 2.6, 2.7 14as well as 3.2 and up. 15 16.. _PEP 362: http://www.python.org/dev/peps/pep-0362/ 17.. _inspect: http://docs.python.org/3/library/inspect.html#introspecting-callables-with-the-signature-object 18 19Compatability 20````````````` 21 22The *funcsigs* backport has been tested against: 23 24* CPython 2.6 25* CPython 2.7 26* CPython 3.2 27* PyPy 1.9 28 29Continuous integration testing is provided by `Travis CI`_. 30 31Under Python 2.x there is a compatability issue when a function is assigned to 32the ``__wrapped__`` property of a class after it has been constructed. 33Similiarily there under PyPy directly passing the ``__call__`` method of a 34builtin is also a compatability issues. Otherwise the functionality is 35believed to be uniform between both Python2 and Python3. 36 37.. _Travis CI: http://travis-ci.org/ 38 39Issues 40`````` 41 42Source code for *funcsigs* is hosted on `GitHub`_. Any bug reports or feature 43requests can be made using GitHub's `issues system`_. 44 45.. _GitHub: https://github.com/aliles/funcsigs 46.. _issues system: https://github.com/alies/funcsigs/issues 47 48Introspecting callables with the Signature object 49------------------------------------------------- 50 51.. note:: 52 53 This section of documentation is a direct repoduction of the Python 54 standard library documentation for the inspect module. 55 56The Signature object represents the call signature of a callable object and its 57return annotation. To retrieve a Signature object, use the :func:`signature` 58function. 59 60.. function:: signature(callable) 61 62 Return a :class:`Signature` object for the given ``callable``:: 63 64 >>> from inspect import signature 65 >>> def foo(a, *, b:int, **kwargs): 66 ... pass 67 68 >>> sig = signature(foo) 69 70 >>> str(sig) 71 '(a, *, b:int, **kwargs)' 72 73 >>> str(sig.parameters['b']) 74 'b:int' 75 76 >>> sig.parameters['b'].annotation 77 <class 'int'> 78 79 Accepts a wide range of python callables, from plain functions and classes to 80 :func:`functools.partial` objects. 81 82 .. note:: 83 84 Some callables may not be introspectable in certain implementations of 85 Python. For example, in CPython, built-in functions defined in C provide 86 no metadata about their arguments. 87 88 89.. class:: Signature 90 91 A Signature object represents the call signature of a function and its return 92 annotation. For each parameter accepted by the function it stores a 93 :class:`Parameter` object in its :attr:`parameters` collection. 94 95 Signature objects are *immutable*. Use :meth:`Signature.replace` to make a 96 modified copy. 97 98 .. attribute:: Signature.empty 99 100 A special class-level marker to specify absence of a return annotation. 101 102 .. attribute:: Signature.parameters 103 104 An ordered mapping of parameters' names to the corresponding 105 :class:`Parameter` objects. 106 107 .. attribute:: Signature.return_annotation 108 109 The "return" annotation for the callable. If the callable has no "return" 110 annotation, this attribute is set to :attr:`Signature.empty`. 111 112 .. method:: Signature.bind(*args, **kwargs) 113 114 Create a mapping from positional and keyword arguments to parameters. 115 Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match the 116 signature, or raises a :exc:`TypeError`. 117 118 .. method:: Signature.bind_partial(*args, **kwargs) 119 120 Works the same way as :meth:`Signature.bind`, but allows the omission of 121 some required arguments (mimics :func:`functools.partial` behavior.) 122 Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the 123 passed arguments do not match the signature. 124 125 .. method:: Signature.replace(*[, parameters][, return_annotation]) 126 127 Create a new Signature instance based on the instance replace was invoked 128 on. It is possible to pass different ``parameters`` and/or 129 ``return_annotation`` to override the corresponding properties of the base 130 signature. To remove return_annotation from the copied Signature, pass in 131 :attr:`Signature.empty`. 132 133 :: 134 135 >>> def test(a, b): 136 ... pass 137 >>> sig = signature(test) 138 >>> new_sig = sig.replace(return_annotation="new return anno") 139 >>> str(new_sig) 140 "(a, b) -> 'new return anno'" 141 142 143.. class:: Parameter 144 145 Parameter objects are *immutable*. Instead of modifying a Parameter object, 146 you can use :meth:`Parameter.replace` to create a modified copy. 147 148 .. attribute:: Parameter.empty 149 150 A special class-level marker to specify absence of default values and 151 annotations. 152 153 .. attribute:: Parameter.name 154 155 The name of the parameter as a string. Must be a valid python identifier 156 name (with the exception of ``POSITIONAL_ONLY`` parameters, which can have 157 it set to ``None``). 158 159 .. attribute:: Parameter.default 160 161 The default value for the parameter. If the parameter has no default 162 value, this attribute is set to :attr:`Parameter.empty`. 163 164 .. attribute:: Parameter.annotation 165 166 The annotation for the parameter. If the parameter has no annotation, 167 this attribute is set to :attr:`Parameter.empty`. 168 169 .. attribute:: Parameter.kind 170 171 Describes how argument values are bound to the parameter. Possible values 172 (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``): 173 174 +------------------------+----------------------------------------------+ 175 | Name | Meaning | 176 +========================+==============================================+ 177 | *POSITIONAL_ONLY* | Value must be supplied as a positional | 178 | | argument. | 179 | | | 180 | | Python has no explicit syntax for defining | 181 | | positional-only parameters, but many built-in| 182 | | and extension module functions (especially | 183 | | those that accept only one or two parameters)| 184 | | accept them. | 185 +------------------------+----------------------------------------------+ 186 | *POSITIONAL_OR_KEYWORD*| Value may be supplied as either a keyword or | 187 | | positional argument (this is the standard | 188 | | binding behaviour for functions implemented | 189 | | in Python.) | 190 +------------------------+----------------------------------------------+ 191 | *VAR_POSITIONAL* | A tuple of positional arguments that aren't | 192 | | bound to any other parameter. This | 193 | | corresponds to a ``*args`` parameter in a | 194 | | Python function definition. | 195 +------------------------+----------------------------------------------+ 196 | *KEYWORD_ONLY* | Value must be supplied as a keyword argument.| 197 | | Keyword only parameters are those which | 198 | | appear after a ``*`` or ``*args`` entry in a | 199 | | Python function definition. | 200 +------------------------+----------------------------------------------+ 201 | *VAR_KEYWORD* | A dict of keyword arguments that aren't bound| 202 | | to any other parameter. This corresponds to a| 203 | | ``**kwargs`` parameter in a Python function | 204 | | definition. | 205 +------------------------+----------------------------------------------+ 206 207 Example: print all keyword-only arguments without default values:: 208 209 >>> def foo(a, b, *, c, d=10): 210 ... pass 211 212 >>> sig = signature(foo) 213 >>> for param in sig.parameters.values(): 214 ... if (param.kind == param.KEYWORD_ONLY and 215 ... param.default is param.empty): 216 ... print('Parameter:', param) 217 Parameter: c 218 219 .. method:: Parameter.replace(*[, name][, kind][, default][, annotation]) 220 221 Create a new Parameter instance based on the instance replaced was invoked 222 on. To override a :class:`Parameter` attribute, pass the corresponding 223 argument. To remove a default value or/and an annotation from a 224 Parameter, pass :attr:`Parameter.empty`. 225 226 :: 227 228 >>> from inspect import Parameter 229 >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42) 230 >>> str(param) 231 'foo=42' 232 233 >>> str(param.replace()) # Will create a shallow copy of 'param' 234 'foo=42' 235 236 >>> str(param.replace(default=Parameter.empty, annotation='spam')) 237 "foo:'spam'" 238 239 240.. class:: BoundArguments 241 242 Result of a :meth:`Signature.bind` or :meth:`Signature.bind_partial` call. 243 Holds the mapping of arguments to the function's parameters. 244 245 .. attribute:: BoundArguments.arguments 246 247 An ordered, mutable mapping (:class:`collections.OrderedDict`) of 248 parameters' names to arguments' values. Contains only explicitly bound 249 arguments. Changes in :attr:`arguments` will reflect in :attr:`args` and 250 :attr:`kwargs`. 251 252 Should be used in conjunction with :attr:`Signature.parameters` for any 253 argument processing purposes. 254 255 .. note:: 256 257 Arguments for which :meth:`Signature.bind` or 258 :meth:`Signature.bind_partial` relied on a default value are skipped. 259 However, if needed, it is easy to include them. 260 261 :: 262 263 >>> def foo(a, b=10): 264 ... pass 265 266 >>> sig = signature(foo) 267 >>> ba = sig.bind(5) 268 269 >>> ba.args, ba.kwargs 270 ((5,), {}) 271 272 >>> for param in sig.parameters.values(): 273 ... if param.name not in ba.arguments: 274 ... ba.arguments[param.name] = param.default 275 276 >>> ba.args, ba.kwargs 277 ((5, 10), {}) 278 279 280 .. attribute:: BoundArguments.args 281 282 A tuple of positional arguments values. Dynamically computed from the 283 :attr:`arguments` attribute. 284 285 .. attribute:: BoundArguments.kwargs 286 287 A dict of keyword arguments values. Dynamically computed from the 288 :attr:`arguments` attribute. 289 290 The :attr:`args` and :attr:`kwargs` properties can be used to invoke 291 functions:: 292 293 def test(a, *, b): 294 ... 295 296 sig = signature(test) 297 ba = sig.bind(10, b=20) 298 test(*ba.args, **ba.kwargs) 299 300 301.. seealso:: 302 303 :pep:`362` - Function Signature Object. 304 The detailed specification, implementation details and examples. 305 306Copyright 307--------- 308 309*funcsigs* is a derived work of CPython under the terms of the `PSF License 310Agreement`_. The original CPython inspect module, its unit tests and 311documentation are the copyright of the Python Software Foundation. The derived 312work is distributed under the `Apache License Version 2.0`_. 313 314.. _PSF License Agreement: http://docs.python.org/3/license.html#terms-and-conditions-for-accessing-or-otherwise-using-python 315.. _Apache License Version 2.0: http://opensource.org/licenses/Apache-2.0 316