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
ofParameter
objectsreturn_annotation – The annotation for the function’s return value
-
__init__
()¶ - Parameters
parameters – A list or dict of
Parameter
objectsreturn_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 aninspect.Signature
instance.Deprecated since version 1.2: The
param_type
parameter. Useparameter_type
instead.- Parameters
signature (inspect.Signature) – An
inspect.Signature
instanceparameter_type (type) – The class to use for the signature’s parameters
- Returns
A new
Signature
instance- Return type
-
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 givencallable_
.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 ofParameter.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. Useparameter_type
instead.- Parameters
- Returns
A corresponding
Signature
instance- Raises
TypeError – If
callable_
isn’t a callable objectValueError – If the signature can’t be determined (can happen for functions defined in C extensions)
- Return type
-
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
-
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 thetyping
module- Returns
A string representation of this signature, like you would see in python code
- Return type
-
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
name (str) – The parameter’s name
kind – The parameter’s kind. See
inspect.Parameter.kind
for details.default – The parameter’s default value, or one of the special values
inspect.Parameter.empty
andParameter.missing
annotation – The parameter’s type annotation
-
classmethod
from_parameter
(parameter)¶ Creates a new
Parameter
instance from aninspect.Parameter
instance.- Parameters
parameter (inspect.Parameter) – An
inspect.Parameter
instance- Returns
A new
Parameter
instance- Return type
-
property
has_annotation
¶ Returns whether the parameter’s
annotation
is notParameter.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
orinspect.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 thetyping
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()
.