API Reference

forge works by decorating a callable using forge.sign() with parameters of forge.arg(), forge.kwarg(), forge.kwargs, and .

Note

When this documentation speaks about “forge parameters” it means those parameters that are defined using forge.arg() and friends in the forge.sign() decorator.

What follows is the API explanation, if you’d like a more hands-on introduction, have a look at Basic Usage.

Parameter

Classes

class forge.FParameter(kind, name=None, interface_name=None, default=<empty>, factory=<empty>, type=<empty>, converter=None, validator=None, bound=False, contextual=False, metadata=None)

An immutable representation of a signature parameter that encompasses its public name, its interface name, transformations to be applied, and associated meta-data that defines its behavior in a signature.

Note

This class doesn’t need to be invoked directly. Use one of the constructor methods instead:

• pos() for positional-only FParameter
• pok() or arg() for positional-or-keyword FParameter
• vpo() for var-positional FParameter
• kwo() or kwarg() for keyword-only FParameter
• vkw() for var-keyword FParameter

Parameters:

• kind – the parameter kind, which detemrines the position of the parameter in a callable signature.
• name – the public name of the parameter. For example, in f(x) -> g(y), name is x.
• interface_name – the name of mapped-to the parameter. For example, in f(x) -> g(y), interface_name is y.
• default – the default value for the parameter. Cannot be supplied alongside a factory argument. For example, to achieve f(x=3), specify :code`default=3`.
• factory – a function that generates a default for the parameter Cannot be supplied alongside a default argument. For example, to achieve f(x=<Factory now>), specify factory=default.now (notice: without parentheses).
• type – the type annotation of the parameter. For example, to achieve f(x: int), type is int.
• converter – a callable or iterable of callables that receive a ctx argument, a name argument and a value argument for transforming inputs.
• validator – a callable that receives a ctx argument, a name argument and a value argument for validating inputs.
• bound – whether the parameter is visible in the signature (requires default or factory if True)
• contextual – whether the parameter will be passed to converter and validator callables as the context (only the first parameter in a FSignature can be contextual)
• metadata – optional, extra meta-data that describes the parameter

POSITIONAL_ONLY

For more information about this parameter kind constant, refer to positional-only.

POSITIONAL_OR_KEYWORD

For more information about this parameter kind constant, refer to positional-or-keyword.

VAR_POSTIIONAL

For more information about this parameter kind constant, refer to var-positional.

KEYWORD_ONLY

For more information about this parameter kind constant, refer to keyword-only.

VAR_KEYWORD

For more information about this parameter kind constant, refer to var-keyword.

Constructors

forge.pos(name=None, interface_name=None, *, default=<empty>, factory=<empty>, type=<empty>, converter=None, validator=None, bound=False, metadata=None)

A factory method for creating positional-only FParameter instances.

Parameters:

• name – see FParameter.name
• interface_name – see FParameter.interface_name
• default – see FParameter.default
• factory – see FParameter.factory
• type – see FParameter.type
• converter – see FParameter.converter
• validator – see FParameter.validator
• bound – see FParameter.bound
• metadata – see FParameter.metadata

Return type:

FParameter

forge.pok(name=None, interface_name=None, *, default=<empty>, factory=<empty>, type=<empty>, converter=None, validator=None, bound=False, metadata=None)

A factory method for creating positional-or-keyword FParameter instances.

Parameters:

• name – see FParameter.name
• interface_name – see FParameter.interface_name
• default – see FParameter.default
• factory – see FParameter.factory
• type – see FParameter.type
• converter – see FParameter.converter
• validator – see FParameter.validator
• bound – see FParameter.bound
• metadata – see FParameter.metadata

Return type:

FParameter

forge.arg()

a convenience for forge.pok()

forge.ctx(name=None, interface_name=None, *, type=<empty>, metadata=None)

A factory method for creating positional-or-keyword FParameter instances that are contextual (this value is passed to other FParameter`s ``converter` and validator functions.)

Parameters:

• name – see FParameter.name
• interface_name – see FParameter.interface_name
• type – see FParameter.type
• metadata – see FParameter.metadata

Return type:

FParameter

forge.vpo(name, *, converter=None, validator=None, metadata=None)

A factory method for creating var-positional FParameter instances.

Parameters:

• name – see FParameter.name
• converter – see FParameter.converter
• validator – see FParameter.validator
• metadata – see FParameter.metadata

Return type:

FParameter

forge.kwo(name=None, interface_name=None, *, default=<empty>, factory=<empty>, type=<empty>, converter=None, validator=None, bound=False, metadata=None)

A factory method for creating keyword-only FParameter instances.

Parameters:

• name – see FParameter.name
• interface_name – see FParameter.interface_name
• default – see FParameter.default
• factory – see FParameter.factory
• type – see FParameter.type
• converter – see FParameter.converter
• validator – see FParameter.validator
• bound – see FParameter.bound
• metadata – see FParameter.metadata

Return type:

FParameter

forge.kwarg()

a convenience for forge.kwo()

forge.vkw(name, *, converter=None, validator=None, metadata=None)

A factory method for creating var-keyword FParameter instances.

Parameters:

• name – see FParameter.name
• converter – see FParameter.converter
• validator – see FParameter.validator
• metadata – see FParameter.metadata

Return type:

FParameter

forge.args(name: Union[str, NoneType] = None, *, converter: Union[typing.Callable[[typing.Any, str, typing.Any], typing.Any], typing.Iterable[typing.Callable[[typing.Any, str, typing.Any], typing.Any]], NoneType] = None, validator: Union[typing.Callable[[typing.Any, str, typing.Any], typing.Any], typing.Iterable[typing.Callable[[typing.Any, str, typing.Any], typing.Any]], NoneType] = None, metadata: Union[typing.Mapping, NoneType] = None) → VarPositional

A convenience class that generates an iterable consisting of one FParameter of parameter kind var-positional.

Instances can be used as either *args or *args().

Typical usage:

>>> import forge
>>> fsig = forge.FSignature(*forge.args)
>>> print(fsig)
<FSignature (*args)>

>>> import forge
>>> fsig = forge.FSignature(*forge.args(name='vars'))
>>> print(fsig)
<FSignature (*vars)>

While name can be supplied (by default it’s args), interface_name is unavailable. This is because when FSignature maps parameters, the mapping between var-positional parameters is 1:1, so the interface name for var-positional is auto-discovered.

Implements collections.abc.Iterable, with provided: __iter__. Inherits method: __next__.

Parameters:

• name – see FParameter.name
• converter – see FParameter.converter
• validator – see FParameter.validator
• metadata – see FParameter.metadata

forge.kwargs(name: Union[str, NoneType] = None, *, converter: Union[typing.Callable[[typing.Any, str, typing.Any], typing.Any], typing.Iterable[typing.Callable[[typing.Any, str, typing.Any], typing.Any]], NoneType] = None, validator: Union[typing.Callable[[typing.Any, str, typing.Any], typing.Any], typing.Iterable[typing.Callable[[typing.Any, str, typing.Any], typing.Any]], NoneType] = None, metadata: Union[typing.Mapping, NoneType] = None) → VarKeyword

A convenience class that generates an iterable consisting of a mapping of name to a FParameter of parameter kind var-keyword.

Instances can be used as either **kwargs or **kwargs().

Typical usage:

>>> import forge
>>> fsig = forge.FSignature(**forge.kwargs)
>>> print(fsig)
<FSignature (**kwargs)>

>>> import forge
>>> fsig = forge.FSignature(**forge.kwargs(name='items'))
>>> print(fsig)
<FSignature (**items)>

While name can be supplied (by default it’s kwargs), interface_name is unavailable. This is because when FSignature maps parameters, the mapping between var-keyword parameters is 1:1, so the interface name for var-keyword is auto-discovered.

Implements collections.abc.Mapping, with provided: __getitem__, __iter__ and __len__. Inherits methods: __contains__, keys, items, values, get, __eq__ and __ne__.

Parameters:

• name – see FParameter.name
• converter – see FParameter.converter
• validator – see FParameter.validator
• metadata – see FParameter.metadata

Helpers

forge.self

a convenience for forge.ctx('self').

forge.cls

a convenience for forge.ctx('cls').

Signature

Classes

class forge.FSignature(*fparameters, **named_fparameters)

An immutable representation of a callable signature composed of forge.FParameter instances.`

Unliked inspect.Signature, FSignature does not provide or manage return type annotations. That is the work of returns() and / or Mapper.

Note

This class doesn’t usually need to be invoked directly. Use one of the constructor methods instead:

• sign() to wrap a callable with a FSignature.
• resign() to revise a wrapped callable’s FSignature.
• from_callable() to generate a FSignature from any Python callable.
• from_signature() to generate a FSignature from a inspect.Signature.

Implements collections.abc.Mapping, with provided: __getitem__, __iter__ and __len__. Inherits methods: __contains__, keys, items, values, get, __eq__ and __ne__.

Parameters:

• fparameters – forge.FParameter instances passed as arguments
• named_fparameters – forge.FParameter instances passed as as keyword arguments.

class forge.Mapper(fsignature, callable)

An immutable data structure that provides the recipe for mapping an FSignature to an underlying callable.

Parameters:

• fsignature – an instance of FSignature that provides the public and private interface.
• callable – a callable that ultimately receives the arguments provided to public FSignature interface.

Variables:

• callable – see Mapper.callable
• fsignature – see Mapper.fsignature
• parameter_map – a types.MappingProxy that exposes the strategy of how to map from the Mapper.fsignature to the Mapper.callable
• private_signature – a cached copy of Mapper.callable’s inspect.Signature
• public_signature – a cached copy of Mapper.fsignature’s manifest as a inspect.Signature

Functions

forge.resign(*fparameters, **named_fparameters)

Takes instances of FParameter and returns a revision factory that alters already-forged signatures.

Parameters:

• fparameters – see FSignature.fparameters
• named_fparameters – see FSignature.named_fparameters

Return type:

Callable[…, Any]

Returns:

a revision factory that takes a callable and updates it so that it has a signature as defined by the resign.fparameters and resign.named_fparameters

forge.returns(type=<empty>)

Produces a factory that updates callables’ signatures to reflect a new return-type annotation

Parameters:type – the return-type for the factory Return type:Callable[[Callable[…, Any]], Any] Returns:a factory that takes a callable and updates it to reflect the return-type as provided to returns.type

forge.sign(*fparameters, **named_fparameters)

Takes instances of FParameter and returns a wrapping factory to generate forged signatures.

Parameters:

• fparameters – see FSignature.fparameters
• named_fparameters – see FSignature.named_fparameters

Return type:

Callable[…, Any]

Returns:

a revision factory that takes a callable and updates it so that it has a signature as defined by the resign.fparameters and resign.named_fparameters

Config

forge.get_run_validators()

Check whether validators are enabled. :rtype: bool :return: whether or not validators are run.

forge.set_run_validators(run)

Set whether or not validators are enabled. :type run: bool :param _sphinx_paramlinks_forge.set_run_validators.run: whether the validators are run

Return type:None

Marker

class forge.void

A simple MarkerMeta class useful for denoting that no input was suplied.

Usage:

def proxy(a, b, extra=void):
    if extra is not void:
        return proxied(a, b)
    return proxied(a, b, c=extra)

Utils

forge.getparam(callable, name, default=<empty>)

Gets a parameter object (either a :class.`inspect.Parmater` or a FParameter) by name from its respective inspect.Signature or FSignature

Parameters:

• callable – the callable whose signature will be inspected
• name – the name of the parameter to retrieve from the getparam.callable signature
• default – a default value to return if getparam.name is not found in the signature of getparam.callable.

Raises:

TypeError – if getparam.name not found

Return type:

Parameter

Returns:

the inspect.Parameter or FParameter object with getparam.name from getparam.callable, or getparam.default if not found.

forge.hasparam(callable, name)

Checks (by name) whether a parameter is taken by a callable.

Parameters:

• callable – a callable whose signature will be inspected
• name – the name of the paramter to identify in the hasparam.callable signature

Return type:

bool

Returns:

True if hasparam.callable has hasparam.name in its signature.

forge.get_return_type(callable)

A convenience for retrieving the return-type annotation from a callable

Parameters:callable – a callable whose return-type annotation is retrieved Return type:Any Returns:the return-type annotation from get_return_type.callable

forge.set_return_type(callable, type)

Set the return-type annotation on a callable.

Parameters:

• callable – a callable whose return-type annotation will be set
• type – the annotation to set for set_return_type.callable

Return type:

None

forge.stringify_callable(callable)

Build a string representation of a callable, including the callable’s :attr:__name__, its inspect.Parameter`s and its ``return type`

usage:

>>> stringify_callable(stringify_callable)
'stringify_callable(callable: Callable) -> str'

Parameters:callable – a Python callable to build a string representation of Return type:str Returns:the string representation of the function