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