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

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

  • parameters – A list or dict of Parameter objects

  • return_annotation – The annotation for the function’s return value

classmethod from_signature(signature, parameter_type=introspection.Parameter, *, param_type=None)

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

Deprecated since version 1.2: The param_type parameter. Use parameter_type instead.

Parameters
Returns

A new Signature instance

Return type

Signature

classmethod from_callable(callable_, parameter_type=introspection.Parameter, follow_wrapped=True, use_signature_db=True, *, param_type=None)

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.

Deprecated since version 1.2: The param_type parameter. Use parameter_type instead.

Parameters

  • callable_ (Callable) – A function or any other callable object

  • parameter_type (Type[Parameter]) – The class to use for the signature’s parameters

  • follow_wrapped (bool) – Whether to unwrap decorated callables

  • use_signature_db (bool) – Whether to look up the 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)

Return type

Signature

without_parameters(*params_to_remove)

Returns a copy of this signature with some parameters removed.

Parameters can be referenced by their name or index.

Example:

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

parameters – Names or indices of the parameters to remove

Returns

A copy of this signature without the given parameters

Return type

Signature

property param_list

Returns a list of the signature’s parameters.

Deprecated since version 1.2: Use parameter_list instead.

property parameter_list

Returns a list of the signature’s parameters.

property has_return_annotation

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

property num_required_arguments

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

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 – If True, the “typing.” prefix will be omitted from types defined in the typing module

Returns

A string representation of this signature, like you would see in python code

Return type

str

class introspection.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__()
Parameters
classmethod from_parameter(parameter)

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

Parameters

parameter (inspect.Parameter) – An inspect.Parameter instance

Returns

A new Parameter instance

Return type

Parameter

property has_annotation

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

property is_vararg

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.

property is_optional

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.

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 – If True, the “typing.” prefix will be omitted from types defined in the typing module

Returns

A string representation of this parameter, like you would see in a function signature

introspection.signature(*args, **kwargs)

Shorthand for Signature.from_callable().