vinegar.transform

Sub modules

`ip_address`	Transformations for both IPv4 and IPv6 addresses.
`ipv4_address`	Transformations for IPv4 addresses.
`ipv6_address`	Transformations for IPv6 addresses.
`mac_address`	Transformations for MAC addresses.
`misc`	Miscellaneous transformations.
`passlib`	Transformations for encrypting passwords.
`string`	String transformations.

Module API

Base package for transformation functions.

Transformation functions are functions that help with transforming a value, possibly building a chain.

For a list of the supported functions, please refer to the various sub-modules that provide the actual functions. The functions from these modules can be called directly.

The apply_transformation function in this module helps with calling transformation functions that are not known at the time of writing the code. For example, code might allow a user to choose the transformation function at runtime.

The apply_transformation_chain function can be used when a user can specify a whole chain of transformations that shall be applied one after the other. If that chain is going to be used repeatedly, it might be more efficient to use get_transformation_chain once and use the returned function repeatedly.

vinegar.transform.apply_transformation(name: str, *args, **kwargs) → Any

Transform a value using the specified transformation.

The name of the transformation function that shall be used is specified in the form module_name.function_name, where module_name is the name of one of the modules in the vinegar.transform package and function_name is the name of the transformation function in that module.

Typically, transformation functions take the value to be transformed as their first positional argument.

Example:

apply_transformation('string.to_upper', 'abc')

Parameters:

name – name of the transformation that shall be applied.
args – positional arguments. This arguments are simply passed on to the transformation function.
kwargs – keyword arguments. This arguments are simply passed on to the transformation function.

Returns:

value returned by the transformation function.

vinegar.transform.apply_transformation_chain(chain: Sequence[str | Mapping[str, Any]], value: Any) → Any

Apply a chain of transformations to a value.

Each of the functions in the chain in the chain is applied to the input value in sequence.

The chain argument is a list of transformation specifications. Each specification is either a str simply specifying the name of the transformation function, or it is a dict with a single entry, where the key is the name of the transformation function and the value is the configuration for that function.

The name of the transformation function is parsed according to the same as for the apply_transformation function.

The configuration for a function can be a dict, a list or another value. If it is a dict, the items in it are passed to the function as keyword arguments. If it is a list, the items in it are passed to the function as positional arguments (after the value argument). In all other cases, the configuration is passed as a single positional argument after the value argument.

Example:

# The following three calls all result in the output "ABC.def":
chain = [
    'string.to_upper',
    {'string.add_suffix': '.def'}]
apply_transformation_chain(chain, 'abc')
chain = [
    {'string.to_upper': []},
    {'string.add_suffix': ['.def']}]
apply_transformation_chain(chain, 'abc')
chain = [
    {'string.to_upper': {}},
    {'string.add_suffix': {'suffix': '.def'}}]
apply_transformation_chain(chain, 'abc')

Parameters:

chain – list describing the transformation chain. Please refer to the function description for details.
value – value that shall be transformed. This is the input to the first function in the transformation chain.

Returns:

transformed value. This is the return value of the last function in the transformation chain.

vinegar.transform.get_transformation_chain(chain: Sequence[str | Mapping[str, Any]]) → Callable

Return a function representing the specified transformation chain.

Each of the functions in the chain in the chain is applied to the input value to the returned function in sequence.

The chain argument is a list of transformation specifications. Each specification is either a str simply specifying the name of the transformation function, or it is a dict with a single entry, where the key is the name of the transformation function and the value is the configuration for that function.

The name of the transformation functions is parsed according to the same rules as for the apply_transformation function.

The configuration for a function can be a dict, a list or another value. If it is a dict, the items in it are passed to the function as keyword arguments. If it is a list, the items in it are passed to the function as positional arguments (after the value argument). In all other cases, the configuration is passed as a single positional argument after the value argument.

Example:

# The following three calls all result in the output "ABC.def":
chain = [
    'string.to_upper',
    {'string.add_suffix': '.def'}]
func = get_transformation_chain(chain)
func('abc')
chain = [
    {'string.to_upper': []},
    {'string.add_suffix': ['.def']}]
func = get_transformation_chain(chain)
func('abc')
chain = [
    {'string.to_upper': {}},
    {'string.add_suffix': {'suffix': '.def'}}]
func = get_transformation_chain(chain)
func('abc')

Parameters:: chain – list describing the transformation chain. Please refer to the function description for details.
Returns:: transformed value. This is the return value of the last function in the transformation chain.

vinegar.transform.get_transformation_function(name: str) → Callable

Return a transformation by name.

The name of the transformation function that shall be used is specified in the form module_name.function_name, where module_name is the name of one of the modules in the vinegar.transform package and function_name is the name of the transformation function in that module.

If the specified module cannot be found, a ModuleNotFoundError is raised. If the module is found, but the transformation function does not exist, an AttributeError is raised. If an object by the specified name exists, but it is not a Callable, a TypeError is raised.

Parameters:: name – name of the transformation that shall be returned.
Returns:: transformation function for the specified name.