diff options
Diffstat (limited to 'third_party/python/funcsigs/docs/index.rst')
| -rw-r--r-- | third_party/python/funcsigs/docs/index.rst | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/third_party/python/funcsigs/docs/index.rst b/third_party/python/funcsigs/docs/index.rst new file mode 100644 index 0000000000..5fbca27e6e --- /dev/null +++ b/third_party/python/funcsigs/docs/index.rst @@ -0,0 +1,353 @@ +.. funcsigs documentation master file, created by + sphinx-quickstart on Fri Apr 20 20:27:52 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Introducing funcsigs +==================== + +The Funcsigs Package +-------------------- + +``funcsigs`` is a backport of the `PEP 362`_ function signature features from +Python 3.3's `inspect`_ module. The backport is compatible with Python 2.6, 2.7 +as well as 3.3 and up. 3.2 was supported by version 0.4, but with setuptools and +pip no longer supporting 3.2, we cannot make any statement about 3.2 +compatibility. + +Compatibility +````````````` + +The ``funcsigs`` backport has been tested against: + +* CPython 2.6 +* CPython 2.7 +* CPython 3.3 +* CPython 3.4 +* CPython 3.5 +* CPython nightlies +* PyPy and PyPy3(currently failing CI) + +Continuous integration testing is provided by `Travis CI`_. + +Under Python 2.x there is a compatibility issue when a function is assigned to +the ``__wrapped__`` property of a class after it has been constructed. +Similiarily there under PyPy directly passing the ``__call__`` method of a +builtin is also a compatibility issues. Otherwise the functionality is +believed to be uniform between both Python2 and Python3. + +Issues +`````` + +Source code for ``funcsigs`` is hosted on `GitHub`_. Any bug reports or feature +requests can be made using GitHub's `issues system`_. |build_status| |coverage| + +Example +------- + +To obtain a `Signature` object, pass the target function to the +``funcsigs.signature`` function. + +.. code-block:: python + + >>> from funcsigs import signature + >>> def foo(a, b=None, *args, **kwargs): + ... pass + ... + >>> sig = signature(foo) + >>> sig + <funcsigs.Signature object at 0x...> + >>> sig.parameters + OrderedDict([('a', <Parameter at 0x... 'a'>), ('b', <Parameter at 0x... 'b'>), ('args', <Parameter at 0x... 'args'>), ('kwargs', <Parameter at 0x... 'kwargs'>)]) + >>> sig.return_annotation + <class 'funcsigs._empty'> + +Introspecting callables with the Signature object +------------------------------------------------- + +.. note:: + + This section of documentation is a direct reproduction of the Python + standard library documentation for the inspect module. + +The Signature object represents the call signature of a callable object and its +return annotation. To retrieve a Signature object, use the :func:`signature` +function. + +.. function:: signature(callable) + + Return a :class:`Signature` object for the given ``callable``:: + + >>> from funcsigs import signature + >>> def foo(a, *, b:int, **kwargs): + ... pass + + >>> sig = signature(foo) + + >>> str(sig) + '(a, *, b:int, **kwargs)' + + >>> str(sig.parameters['b']) + 'b:int' + + >>> sig.parameters['b'].annotation + <class 'int'> + + Accepts a wide range of python callables, from plain functions and classes to + :func:`functools.partial` objects. + + .. note:: + + Some callables may not be introspectable in certain implementations of + Python. For example, in CPython, built-in functions defined in C provide + no metadata about their arguments. + + +.. class:: Signature + + A Signature object represents the call signature of a function and its return + annotation. For each parameter accepted by the function it stores a + :class:`Parameter` object in its :attr:`parameters` collection. + + Signature objects are *immutable*. Use :meth:`Signature.replace` to make a + modified copy. + + .. attribute:: Signature.empty + + A special class-level marker to specify absence of a return annotation. + + .. attribute:: Signature.parameters + + An ordered mapping of parameters' names to the corresponding + :class:`Parameter` objects. + + .. attribute:: Signature.return_annotation + + The "return" annotation for the callable. If the callable has no "return" + annotation, this attribute is set to :attr:`Signature.empty`. + + .. method:: Signature.bind(*args, **kwargs) + + Create a mapping from positional and keyword arguments to parameters. + Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match the + signature, or raises a :exc:`TypeError`. + + .. method:: Signature.bind_partial(*args, **kwargs) + + Works the same way as :meth:`Signature.bind`, but allows the omission of + some required arguments (mimics :func:`functools.partial` behavior.) + Returns :class:`BoundArguments`, or raises a :exc:`TypeError` if the + passed arguments do not match the signature. + + .. method:: Signature.replace(*[, parameters][, return_annotation]) + + Create a new Signature instance based on the instance replace was invoked + on. It is possible to pass different ``parameters`` and/or + ``return_annotation`` to override the corresponding properties of the base + signature. To remove return_annotation from the copied Signature, pass in + :attr:`Signature.empty`. + + :: + + >>> def test(a, b): + ... pass + >>> sig = signature(test) + >>> new_sig = sig.replace(return_annotation="new return anno") + >>> str(new_sig) + "(a, b) -> 'new return anno'" + + +.. class:: Parameter + + Parameter objects are *immutable*. Instead of modifying a Parameter object, + you can use :meth:`Parameter.replace` to create a modified copy. + + .. attribute:: Parameter.empty + + A special class-level marker to specify absence of default values and + annotations. + + .. attribute:: Parameter.name + + The name of the parameter as a string. Must be a valid python identifier + name (with the exception of ``POSITIONAL_ONLY`` parameters, which can have + it set to ``None``). + + .. attribute:: Parameter.default + + The default value for the parameter. If the parameter has no default + value, this attribute is set to :attr:`Parameter.empty`. + + .. attribute:: Parameter.annotation + + The annotation for the parameter. If the parameter has no annotation, + this attribute is set to :attr:`Parameter.empty`. + + .. attribute:: Parameter.kind + + Describes how argument values are bound to the parameter. Possible values + (accessible via :class:`Parameter`, like ``Parameter.KEYWORD_ONLY``): + + +------------------------+----------------------------------------------+ + | Name | Meaning | + +========================+==============================================+ + | *POSITIONAL_ONLY* | Value must be supplied as a positional | + | | argument. | + | | | + | | Python has no explicit syntax for defining | + | | positional-only parameters, but many built-in| + | | and extension module functions (especially | + | | those that accept only one or two parameters)| + | | accept them. | + +------------------------+----------------------------------------------+ + | *POSITIONAL_OR_KEYWORD*| Value may be supplied as either a keyword or | + | | positional argument (this is the standard | + | | binding behaviour for functions implemented | + | | in Python.) | + +------------------------+----------------------------------------------+ + | *VAR_POSITIONAL* | A tuple of positional arguments that aren't | + | | bound to any other parameter. This | + | | corresponds to a ``*args`` parameter in a | + | | Python function definition. | + +------------------------+----------------------------------------------+ + | *KEYWORD_ONLY* | Value must be supplied as a keyword argument.| + | | Keyword only parameters are those which | + | | appear after a ``*`` or ``*args`` entry in a | + | | Python function definition. | + +------------------------+----------------------------------------------+ + | *VAR_KEYWORD* | A dict of keyword arguments that aren't bound| + | | to any other parameter. This corresponds to a| + | | ``**kwargs`` parameter in a Python function | + | | definition. | + +------------------------+----------------------------------------------+ + + Example: print all keyword-only arguments without default values:: + + >>> def foo(a, b, *, c, d=10): + ... pass + + >>> sig = signature(foo) + >>> for param in sig.parameters.values(): + ... if (param.kind == param.KEYWORD_ONLY and + ... param.default is param.empty): + ... print('Parameter:', param) + Parameter: c + + .. method:: Parameter.replace(*[, name][, kind][, default][, annotation]) + + Create a new Parameter instance based on the instance replaced was invoked + on. To override a :class:`Parameter` attribute, pass the corresponding + argument. To remove a default value or/and an annotation from a + Parameter, pass :attr:`Parameter.empty`. + + :: + + >>> from funcsigs import Parameter + >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42) + >>> str(param) + 'foo=42' + + >>> str(param.replace()) # Will create a shallow copy of 'param' + 'foo=42' + + >>> str(param.replace(default=Parameter.empty, annotation='spam')) + "foo:'spam'" + + +.. class:: BoundArguments + + Result of a :meth:`Signature.bind` or :meth:`Signature.bind_partial` call. + Holds the mapping of arguments to the function's parameters. + + .. attribute:: BoundArguments.arguments + + An ordered, mutable mapping (:class:`collections.OrderedDict`) of + parameters' names to arguments' values. Contains only explicitly bound + arguments. Changes in :attr:`arguments` will reflect in :attr:`args` and + :attr:`kwargs`. + + Should be used in conjunction with :attr:`Signature.parameters` for any + argument processing purposes. + + .. note:: + + Arguments for which :meth:`Signature.bind` or + :meth:`Signature.bind_partial` relied on a default value are skipped. + However, if needed, it is easy to include them. + + :: + + >>> def foo(a, b=10): + ... pass + + >>> sig = signature(foo) + >>> ba = sig.bind(5) + + >>> ba.args, ba.kwargs + ((5,), {}) + + >>> for param in sig.parameters.values(): + ... if param.name not in ba.arguments: + ... ba.arguments[param.name] = param.default + + >>> ba.args, ba.kwargs + ((5, 10), {}) + + + .. attribute:: BoundArguments.args + + A tuple of positional arguments values. Dynamically computed from the + :attr:`arguments` attribute. + + .. attribute:: BoundArguments.kwargs + + A dict of keyword arguments values. Dynamically computed from the + :attr:`arguments` attribute. + + The :attr:`args` and :attr:`kwargs` properties can be used to invoke + functions:: + + def test(a, *, b): + ... + + sig = signature(test) + ba = sig.bind(10, b=20) + test(*ba.args, **ba.kwargs) + + +.. seealso:: + + :pep:`362` - Function Signature Object. + The detailed specification, implementation details and examples. + +Copyright +--------- + +*funcsigs* is a derived work of CPython under the terms of the `PSF License +Agreement`_. The original CPython inspect module, its unit tests and +documentation are the copyright of the Python Software Foundation. The derived +work is distributed under the `Apache License Version 2.0`_. + +.. _PSF License Agreement: http://docs.python.org/3/license.html#terms-and-conditions-for-accessing-or-otherwise-using-python +.. _Apache License Version 2.0: http://opensource.org/licenses/Apache-2.0 +.. _GitHub: https://github.com/testing-cabal/funcsigs +.. _PSF License Agreement: http://docs.python.org/3/license.html#terms-and-conditions-for-accessing-or-otherwise-using-python +.. _Travis CI: http://travis-ci.org/ +.. _Read The Docs: http://funcsigs.readthedocs.org/ +.. _PEP 362: http://www.python.org/dev/peps/pep-0362/ +.. _inspect: http://docs.python.org/3/library/inspect.html#introspecting-callables-with-the-signature-object +.. _issues system: https://github.com/testing-cabal/funcsigs/issues + +.. |build_status| image:: https://secure.travis-ci.org/aliles/funcsigs.png?branch=master + :target: http://travis-ci.org/#!/aliles/funcsigs + :alt: Current build status + +.. |coverage| image:: https://coveralls.io/repos/aliles/funcsigs/badge.png?branch=master + :target: https://coveralls.io/r/aliles/funcsigs?branch=master + :alt: Coverage status + +.. |pypi_version| image:: https://pypip.in/v/funcsigs/badge.png + :target: https://crate.io/packages/funcsigs/ + :alt: Latest PyPI version + + |