Function Signatures¶

Function signatures are represented by the Signature class. Function parameters are represented by the Parameter class.

Signatures can be created through the signature() function or the Signature class’s various from_X methods - Signature.from_callable(), Signature.from_signature().

class introspection.Signature¶

Bases: Signature

An inspect.Signature subclass that represents a function’s parameter signature and return annotation.

Instances of this class are immutable.

Variables

parameters – An OrderedDict of Parameter objects
return_annotation – The annotation for the function’s return value

__init__(parameters=None, return_annotation=inspect.Signature.empty, validate_parameters=True)¶

Parameters

parameters (Union[Iterable[Parameter], Dict[str, Parameter], None], default: None) – A list or dict of Parameter objects
return_annotation (Any, default: inspect.Signature.empty) – The annotation for the function’s return value
validate_parameters (bool, default: True) – Whether to check if the signature is valid

classmethod from_signature(signature, parameter_type=introspection.Parameter)¶

Creates a new Signature instance from an inspect.Signature instance.

Changed in version 1.4: param_type parameter renamed to parameter_type.

Parameters

signature (Signature) – An inspect.Signature instance
parameter_type (type, default: introspection.Parameter) – The class to use for the signature’s parameters

Return type

Signature

Returns

A new Signature instance

classmethod from_callable(callable_, parameter_type=introspection.Parameter, follow_wrapped=True, use_signature_db=True)¶

Returns a matching Signature instance for the given callable_.

Because the signatures of builtin functions often cannot be determined (at least in older python versions), this function contains a database of signatures for builtin functions. These signatures contain much more detail than inspect.signature() would provide - like type annotations and default values of Parameter.missing.

Pass use_signature_db=False if you wish to bypass the signature database.

Changed in version 1.1: Returns more accurate signatures for builtin functions. Also added missing “value” parameter for setattr.

New in version 1.2: Added use_signature_db parameter.

Changed in version 1.2: Signature database updated for python 3.9.

Changed in version 1.4: Signature database updated for python 3.10. param_type parameter renamed to parameter_type.

Parameters

callable_ – A function or any other callable object
parameter_type (Type[Parameter], default: introspection.Parameter) – The class to use for the signature’s parameters
follow_wrapped (bool, default: True) – Whether to unwrap decorated callables
use_signature_db (bool, default: True) – Whether to look up the signature

Return type

Signature

Returns

A corresponding Signature instance

Raises

TypeError – If callable_ isn’t a callable object
ValueError – If the signature can’t be determined (can happen for functions defined in C extensions)

classmethod for_method(class_or_mro, method_name, *, parameter_type=introspection.Parameter)¶

Creates a combined signature for the method in the given class and all parent classes, assuming that all *args and **kwargs are passed to the parent method.

Example:

class A:
    def method(self, foo: int = 3) -> None:
        pass

class B(A):
    def method(self, *args, bar: bool = True, **kwargs):
        return super().method(*args, **kwargs)

print(Signature.for_method(B, 'method'))
# (self, foo: int = 3, *, bar: bool = True) -> None

New in version 1.5.

without_parameters(*params_to_remove)¶

Returns a copy of this signature with some parameters removed.

Parameters can be referenced by the following things:

index
name
kind

Example:

>>> sig = Signature([
...     Parameter('foo'),
...     Parameter('bar'),
...     Parameter('baz'),
... ])
>>> sig.without_parameters(0, 'baz')
<Signature (bar)>

Changed in version 1.5: Parameters can now be referenced by kind.

Parameters: parameters – Names or indices of the parameters to remove
Return type: Signature
Returns: A copy of this signature without the given parameters

property parameter_list: List[Parameter]¶

Returns a list of the signature’s parameters.

Return type: List[Parameter]

property has_return_annotation: bool¶

Returns whether the signature’s return annotation is not Signature.empty.

Return type: bool

property num_required_arguments: int¶

Returns the number of required arguments, i.e. arguments with no default value.

Return type: int

bind(*args, **kwargs)¶

Similar to inspect.Signature.bind(), but returns a introspection.BoundArguments object.

Return type: BoundArguments

bind_partial(*args, **kwargs)¶

Similar to inspect.Signature.bind_partial(), but returns a introspection.BoundArguments object.

Return type: BoundArguments

to_string(implicit_typing=False)¶

Returns a string representation of this signature.

Example:

>>> Signature([
...    Parameter('nums', Parameter.VAR_POSITIONAL, annotation=int)
... ], return_annotation=int).to_string()
'(*nums: int) -> int'

Parameters: implicit_typing (bool, default: False) – If True, the “typing.” prefix will be omitted from types defined in the typing module
Return type: str
Returns: A string representation of this signature, like you would see in python code

class introspection.Parameter¶

Bases: Parameter

An inspect.Parameter subclass that represents a function parameter.

Instances of this class are immutable.

This class adds a new special value for the default attribute: Parameter.missing.

Variables

name – The parameter’s name
kind – The parameter’s kind. See inspect.Parameter.kind for details.
default – The parameter’s default value or inspect.Parameter.empty
annotation – The parameter’s type annotation

missing¶

A special class-level marker that can be used to specify that the parameter is optional, but doesn’t have a (known) default value.

This is commonly used by signatures for builtin functions. For example, the signature of the range function can be represented as

>>> Signature([
...     Parameter('start', Parameter.POSITIONAL_ONLY),
...     Parameter('stop', Parameter.POSITIONAL_ONLY, default=Parameter.missing),
...     Parameter('step', Parameter.POSITIONAL_ONLY, default=Parameter.missing),
... ])
<Signature (start[, stop[, step]], /)>

__init__(name=None, kind=inspect.Parameter.POSITIONAL_OR_KEYWORD, default=inspect.Parameter.empty, annotation=inspect.Parameter.empty)¶

Parameters

name (str) – The parameter’s name
kind (Any, default: inspect.Parameter.POSITIONAL_OR_KEYWORD) – The parameter’s kind. See inspect.Parameter.kind for details.
default (Any, default: inspect.Parameter.empty) – The parameter’s default value, or one of the special values inspect.Parameter.empty and Parameter.missing
annotation (Any, default: inspect.Parameter.empty) – The parameter’s type annotation

classmethod from_parameter(parameter)¶

Creates a new Parameter instance from an inspect.Parameter instance.

Parameters: parameter (Parameter) – An inspect.Parameter instance
Return type: Parameter
Returns: A new Parameter instance

property has_annotation: bool¶

Returns whether the parameter’s annotation is not Parameter.empty.

Return type: bool

property is_vararg: bool¶

Returns a boolean indicating whether this parameter accepts a variable number of arguments; i.e. whether the parameter’s kind is inspect.Parameter.VAR_POSITIONAL or inspect.Parameter.VAR_KEYWORD.

Return type: bool

property is_optional: bool¶

Returns a boolean indicating whether this parameter can be omitted or requires an argument.

Returns True if the parameter has a default value or is a vararg.

Return type: bool

to_string(implicit_typing=False)¶

Returns a string representation of this parameter, similar to how parameters are written in function signatures.

Examples:

>>> Parameter('foo', Parameter.VAR_POSITIONAL).to_string()
'*foo'
>>> Parameter('foo', annotation=int, default=3).to_string()
'foo: int = 3'

Parameters: implicit_typing (bool, default: False) – If True, the “typing.” prefix will be omitted from types defined in the typing module
Return type: str
Returns: A string representation of this parameter, like you would see in a function signature

class introspection.BoundArguments¶

Bases: BoundArguments, MutableMapping

Subclass of inspect.BoundArguments with additional features.

New in version 1.4.

classmethod from_bound_arguments(bound_args)¶

Creates a new BoundArguments instance from a inspect.BoundArguments instance.

Parameters: bound_args (BoundArguments) – An inspect.BoundArguments instance
Return type: BoundArguments
Returns: A new BoundArguments instance

get_missing_parameter_names(include_optional_parameters=False)¶

Returns the set of parameter names that were omitted in the call to Signature.bind_partial().

If include_optional_parameters is True, parameters with a default value are included in the output.

*args and **kwargs are never included in the output.

Examples:

>>> signature
(foo, bar, *args, baz=3)
>>> bound_args = signature.bind_partial(1)
>>> bound_args.get_missing_parameter_names()
{'bar'}
>>> bound_args.get_missing_parameter_names(True)
{'bar', 'baz'}

New in version 1.5.

to_varargs(prefer='kwargs')¶

Converts the arguments into an (args, kwargs) tuple.

Example:

>>> signature = Signature.from_callable(lambda a, *b, c: 0)
>>> bound_args = signature.bind(1, c=2)
>>> bound_args.to_varargs(prefer='args')
([1], {'c': 2})
>>> bound_args.to_varargs(prefer='kwargs')
([], {'a': 1, 'c': 2})

Parameters: prefer (Literal[‘args’, ‘kwargs’], default: 'kwargs') – Whether to prefer positional or keyword arguments
Return type: Tuple[list, Dict[str, Any]]
Returns: An (args, kwargs) tuple

introspection.signature(*args, **kwargs)¶: Shorthand for Signature.from_callable().

Function Signatures¶

Table of Contents

Navigation