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