PKG-INFO 17 KB

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