Skip to content

bagof.converters.base

Base class for all converters.

Attributes

ConverterRegistry module-attribute 

ConverterRegistry = dict[tx.Hashable, tx.Type['Converter']]

A registry of converters, mapping type hints to converter classes.

register_converter module-attribute 

register_converter = Converter.register

Backward-compatible alias for Converter.register.

get_converter module-attribute 

get_converter = Converter.get

Backward-compatible alias for Converter.get.

get_converter_class module-attribute 

get_converter_class = Converter.get_class

Backward-compatible alias for Converter.get_class.

Classes

Converter 

Converter(hint: Any = UNSET, compose: bool = False)

Bases: MagicHint[TO], Generic[TO, FROM]

Base class for magic converters.

Converters take a value and return a converted version of it. They are registered in a global registry and looked up by type hint.

Note

Failed conversions raise a ConversionError. Its concrete subclasses -- ValueConversionError (also a ValueError) and TypeConversionError (also a TypeError) -- inherit the matching builtin, so callers that already catch ValueError or TypeError still catch conversion failures.

Parameters:

Name Type Description Default
hint Any

The type hint to use for this magic object. If not provided, the default hint for the class is used.

 UNSET
compose bool

Whether to compose this converter with others, when they are found in Annotated metadata.

 False

Methods:

like 
like(__reentrant: tuple = ()) -> Any

Return a type hint describing valid inputs for this converter.

Parameters:

Name Type Description Default
__reentrant tuple

Used internally to avoid infinite recursion.

 ()

Returns:

Type Description
Any

A type hint for valid input values.
__call__ 
__call__(value: FROM) -> TO

Convert the given value.

Parameters:

Name Type Description Default
value FROM

The value to convert.

 required

Returns:

Type Description
TO

The converted value.

Raises:

Type Description
ConversionError

If the value cannot be converted.
error 
error(value: Any, message: str | None = None, **kwargs: Any) -> ConversionError

Return a ConversionError with the given value and message.

type_error 
type_error(value: Any, message: str | None = None) -> TypeConversionError

Return a TypeConversionError with the given value.

value_error 
value_error(value: Any, message: str | None = None) -> ValueConversionError

Return a ValueConversionError with the given value.

register staticmethod 
register(converter: Type[Converter], *hints: Unpack[tuple[Any]], registry: ConverterRegistry = ...) -> Type[Converter]

register(*hints: Unpack[tuple[Any]], registry: ConverterRegistry = ...) -> ClassDecorator

Register a converter class for one or more type hints.

Can be used as a decorator or called directly:

Example

@Converter.register(int)
class ToInt(Converter[int, str]):
    def __call__(self, value: str) -> int:
        return int(value)

Parameters:

Name Type Description Default
*hints Any

One or more type hints to register the converter class for.

 ()
registry ConverterRegistry

The registry to register the converter class in. Defaults to the global registry.

 CONVERTERS
get staticmethod 
get(hint: Any, registry: ConverterRegistry = CONVERTERS, fallback: Type[Converter] | None = None) -> Converter | None

Get the best-matching converter for a given type hint.

Example

>>> from bagof.converters import get_converter
>>> convert = get_converter(list[int])
>>> convert(["1", "2", "3"])
[1, 2, 3]
>>> get_converter(dict[str, int])({"a": "1", "b": "2"})
{'a': 1, 'b': 2}

Parameters:

Name Type Description Default
hint Any

The type hint for which to get a converter.

 required
registry ConverterRegistry

The registry to look up the converter in. Defaults to the global registry.

 CONVERTERS
fallback Optional[Type[Converter]]

The fallback converter class to use if no matching converter is found.

 None

Returns:

Type Description
Optional[Converter]

The best-matching converter for the given type hint, or None if no matching converter is found and no fallback is provided.
get_class staticmethod 
get_class(hint: Any, registry: ConverterRegistry = CONVERTERS, fallback: Type[Converter] | None = None) -> Type[Converter] | None

Get the best-matching converter class for a given type hint.

Parameters:

Name Type Description Default
hint Any

The type hint for which to get a converter.

 required
registry ConverterRegistry

The registry to look up the converter in. Defaults to the global registry.

 CONVERTERS
fallback Optional[Type[Converter]]

The fallback converter class to use if no matching converter is found.

 None

Returns:

Type Description
Optional[Type[Converter]]

The best-matching converter class for the given type hint, or None if no matching converter is found and no fallback is provided.

Functions:

wrap_converter 

wrap_converter(converter: Converter, TO: Any = UNSET, FROM: Any = UNSET) -> Callable

Wrap a converter so that it has the correct input and output annotations.

Parameters:

Name Type Description Default
converter Converter

The converter to wrap.

 required
TO Any

The output type hint. Defaults to converter.hint.

 UNSET
FROM Any

The input type hint. Defaults to converter.like().

 UNSET

Returns:

Type Description
Callable

A callable that wraps converter, annotated with FROM as its parameter type and TO as its return type.