PKG-INFO

   1 Metadata-Version: 1.1
   2 Name: funcsigs
   3 Version: 1.0.2
   4 Summary: Python function signatures from PEP362 for Python 2.6, 2.7 and 3.2+
   5 Home-page: http://funcsigs.readthedocs.org
   6 Author: Testing Cabal
   7 Author-email: testing-in-python@lists.idyll.org
   8 License: ASL
   9 Description: .. 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
 363 Platform: UNKNOWN
 364 Classifier: Development Status :: 4 - Beta
 365 Classifier: Intended Audience :: Developers
 366 Classifier: License :: OSI Approved :: Apache Software License
 367 Classifier: Operating System :: OS Independent
 368 Classifier: Programming Language :: Python
 369 Classifier: Programming Language :: Python :: 2
 370 Classifier: Programming Language :: Python :: 2.6
 371 Classifier: Programming Language :: Python :: 2.7
 372 Classifier: Programming Language :: Python :: 3
 373 Classifier: Programming Language :: Python :: 3.3
 374 Classifier: Programming Language :: Python :: 3.4
 375 Classifier: Programming Language :: Python :: 3.5
 376 Classifier: Programming Language :: Python :: Implementation :: CPython
 377 Classifier: Programming Language :: Python :: Implementation :: PyPy
 378 Classifier: Topic :: Software Development :: Libraries :: Python Modules