Converters are one of the core aspects of konfi. Converters make it possible to provide full type-safety to templates.

You can add new converters by using the konfi.register_converter decorator or simply passing the converter argument to konfi.field. Since last registered converters are used first, you can overwrite a built-in converter by registering a new converter for the same type (Regardless of complex or not). The old converter(s) will be used as a fallback if the new one raises an exception.

Converters should be stable i.e. if a value already has the correct type, the converter should return the same value (not necessarily the same value by identity, but by equality).

Builtin converters



None (NoneType)

Always returns None.


Returns the value directly.

Implemented by calling the type with the value.


If the value is already iterable, it is returned directly, unless it is a string. Everything else is wrapped in a list and returned.

Implemented by converting to an Iterable first and then passing the result to the type.


If the value is already a Mapping it’s returned directly. If the value is a Sequence it is converted to a dict by using the index as the key and the item as the value. All other value types raise a conversion error.

dict (Dict)

Implemented by converting to a Mapping and then passing the result to the type.

Union[T1, T2]

Returns value directly if it’s already in the union, otherwise returns the first successful conversion result of trying each type from left to right.

Tuple[T1, T2]

For n-tuples (tuples with a limited amount of items) each item is converted to the corresponding type. This requires that the lengths of the tuples are equal.

Variadic tuples (tuples with an unspecified amount of items) are handled by converting each item to the value type.


Works for all subtypes like List[T], Set[T] and so on. Implemented by gathering the items converted to T in a list and then converting that to the container type.

Mapping[K, V]

Works analogous to Iterable[T].


Exists mainly for templates in containers like List[MyTemplate] or Dict[str, MyTemplate]. It’s not used for nested templates and custom sources shouldn’t use it, because it requires the value to be complete.


Tries to find the appropriate member in the following order:

  1. Perfect name match

  2. Perfect value match

  3. First case-insensitive match on either name or value