sigtools
documentation¶
sigtools
is a Python package that improves on introspection tools available
for determining function signatures. This is useful for libraries or tooling
that want to know how a function can be called: Documentation generators, IDEs,
and tools that adapt themselves to functions they are given.
sigtools
also provides a backport of Python 3’s keyword-only parameters and
function annotations.
Keyword-only parameters¶
sigtools
provides two decorators to emulate keyword-only parameters:
-
sigtools.modifiers.
autokwoargs
(func=None, *, exceptions=())[source] Converts all parameters with default values to keyword-only parameters:
from sigtools.modifiers import autokwoargs @autokwoargs def func(arg, opt1=False, opt2=False, *rest): print(arg, rest, opt1, opt2) func(1, 2, 3) # 1 (2, 3) False False func(1, 2, opt2=True) # -> 1 (2,) False True
In the example above, the
opt1
andopt2
parameters are ‘skipped’ by positional arguments and can only be set using named arguments (opt2=True
).If you wish to prevent parameters that have a default from becoming keyword-only, you can use the
exceptions=
parameter:@autokwoargs(exceptions=['arg2']) def func(arg1, arg2=42, opt1=False, opt2=False): print(arg1, arg2, opt1, opt2) func(1, 2, opt1=False) # 1 2 False False
If you wish to pick individual parameters to convert, use
sigtools.modifiers.kwoargs
. This module also allows you to add function
annotations using the annotate
decorator.
Improved signature reporting¶
Python 3.3’s inspect
module introduces signature objects,
which represent how a function can be called. Their textual representation
roughly matches the parameter list part of a function definition:
import inspect
def func(abc, *args, **kwargs):
...
print(inspect.signature(func))
# (abc, *args, **kwargs)
-
sigtools.
signature
(obj, auto=True, args=(), kwargs={})¶ Improved version of
inspect.signature
. Takes into account decorators fromsigtools.specifiers
if present or tries to determine a full signature automatically.
For instance, consider this example of a decorator being defined and applied:
import inspect
from sigtools import specifiers
def decorator(param):
def _decorate(wrapped):
def _wrapper(*args, **kwargs):
wrapped(param, *args, **kwargs)
return _wrapper
return _decorate
@decorator('eggs')
def func(ham, spam):
return ham, spam
print(inspect.signature(func))
# (*args, **kwargs)
print(specifiers.signature(func))
# (spam)
Where inspect.signature
simply sees (*args, **kwargs)
from _wrapper
,
sigtools.signature
returns the correct signature for the *args,
**kwargs
portion of wrapped(param, *args, **params)
.
Improved signatures in sphinx.ext.autodoc
documentation¶
Sphinx, the documentation tool, comes with an
extension, sphinx.ext.autodoc
, which lets you source some of your
documentation from your code and its docstrings. sigtools.sphinxext
, if
activated, automatically improves signatures like explained above.
To activate it, add 'sigtools.sphinxext'
to the extensions
list in your
Sphinx’s conf.py
:
extensions = [
'sphinx.ext.autodoc', ...
'sigtools.sphinxext']
If you want to use the automatic signature gathering while ignoring the docstring
in order to supply your own explanations, you can use this directive instead of
autofunction
:
-
.. autosignature::
object
¶ Documents a Python object while ignoring the source docstring.
sigtools.specifiers.signature
is used to retrieve the object’s call signature
Reference¶
- API Reference
sigtools.modifiers
: Modify the effective signature of the decorated callablesigtools.specifiers
: Decorators to enhance a callable’s signaturesigtools.wrappers
: Combine multiple functionssigtools.signatures
: Signature object manipulationsigtools.support
: Utilities for use in interactive sessions and unit testssigtools.sphinxext
: Extension to make Sphinx use signature objects
- Picking the appropriate arguments for
forwards
- Picking the appropriate
forwards_to_*
decorator *args
and**kwargs
are forwarded directly if present- Passing positional arguments to the wrapped function
- Passing named arguments to from the wrapper
- When the outer function uses
*args
or**kwargs
but doesn’t forward them to the inner function - When the outer function passes an arbitrary
*args
or**kwargs
to the inner function - Summary
- Picking the appropriate
- Limitations of automatic signature discovery
- Building signature-inspecting tools with sigtools
Installing¶
You can install sigtools
using pip. If in an activated virtualenv, type:
pip install sigtools
If you wish to do a user-wide install:
pip install --user sigtools