Function Signatures — Introspection documentation

# 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:

    1. index

    2. name

    3. 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()`.