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`

  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, param_type=<class 'introspection.parameter.Parameter'>)

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

    Parameters

      - signature (inspect.Signature) – An `inspect.Signature` instance

      - param_type (type) – The class to use for the signature’s parameters

    Returns

      A new `Signature` instance

    Return type

      Signature

  classmethod `from_callable`(callable_, param_type=<class 'introspection.parameter.Parameter'>, follow_wrapped=True)

    Returns a matching `Signature` instance for the given `callable_`.

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

    Parameters

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

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

      - follow_wrapped (bool) – Whether to unwrap decorated callables

    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)

    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

      params – 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.

  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`. This value indicates that the parameter is optional, but has no known default value.

  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.

    alias of `_missing`

  `__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 `inspect.Parameter.empty`

      - annotation – The parameter’s type annotation

  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 requires an argument.

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