strconv - Data conversion from/to string¶

Overview¶

While Python types typically support conversion to string via builtin str() function (and custom __str__ methods), there is no symetric operation that converts string created by str() back to typed value. This module provides support for such symetric conversion from/to string for any data type.

Note

Symetric string conversion is used by config module, notably by ListOption and DataclassOption. You can extend the range of data types supported by these options by registering convertors for required data types.

Architecture¶

Module maintains a global registry of convertors associated with a data type. These convertor functions may support conversion for multiple data types, and must have signatures:

# Conversion to string

def value2str(value: Any) -> str:
    ...

# Conversion from string

def str2value(cls: Type, value: str) -> Any:
    ...

Convertors should raise ValueError when conversion fails.

Convertors must be registered using register_convertor() function, or reassigned using update_convertor().

There are two methods for use of registered convertors:

By using functions convert_to_str() and convert_from_str(). These functions use convertor that is registered for particular data type. If there is no such convertor, they use first convertor registered for any base class. The lookup is performed in Method Resolution Order.

This method is preferred when you will work with various data types.
Using get_convertor() function to obtain registry entry with convertors.

This method is preferred when you will work with single data type repeatedly.

Important

The convertor registry lookup could be done either for a class, or class name.

Lookup for a class is first performed for specified class. If there is no such entry, all bases classes in Method Resolution Order are used for lookup, and the first entry found is returned.

Lookup for a class name could be performed only for a specified class. Because some types could be converted using convertors registered for their base class, such lookup will not find the required convertor entry. To circumvent this issue, it’s necessary to register a class for name lookup using register_class() function. The registry lookup uses this class registry to use the actual type instead type name.

Registered data types¶

Module registers convertor functions for next data types:

str
int
float
complex
bool. Uses TRUE_STR and FALSE_STR list for conversion from string (the case is NOT significant). Conversion to string always uses first item in these lists.
Decimal
UUID
MIME
ZMQAddress
Enum and Flag. Supports conversion for all descendants of Enum, IntEnum, Flag and IntFlag.

Tip

Functions any2str() and str2any() could be used to register conversion for data types that support symetric conversion via __str__() method and class constructor (__init__() must accept one positional argument that could be a string and all other arguments must be keyword arguments with default values).

Types for annotations¶

firebird.base.strconv.TConvertToStr¶

Function that converts typed value to its string representation.

alias of Callable[[Any], str]

firebird.base.strconv.TConvertFromStr¶

Function that converts string representation of typed value to typed value.

alias of Callable[[Type, str], Any]

Globals¶

firebird.base.strconv.TRUE_STR = ['yes', 'true', 'on', 'y', '1']¶: Valid string literals for True value.

firebird.base.strconv.FALSE_STR = ['no', 'false', 'off', 'n', '0']¶: Valid string literals for False value.

Functions¶

firebird.base.strconv.convert_to_str(value: Any) → str[source]¶

Converts value to string using registered convertor.

Parameters:: value (Any) – Value to be converted.
Return type:: str

If there is no convertor for value’s class, uses MRO to locate alternative convertor.

Raises:: TypeError – If there is no convertor for value’s class or any from its bases classes.
Parameters:: value (Any) –
Return type:: str

firebird.base.strconv.convert_from_str(cls: Type | str, value: str) → Any[source]¶

Converts value from string to data type using registered convertor.

Parameters:

cls (Type | str) – Type or type name. The name could be simple class name, or full name that includes the module name.
value (str) – String value to be converted

Return type:

Any

Note

When cls is a type name:

If class name is NOT registered via register_class(), it’s not possible to perform lookup for bases classes.
If simple class name is provided and multiple classes of the same name but from different modules have registered convertors, the first one found is used. If you want to avoid this situation, use full names.

Raises:

TypeError – If there is no convertor for cls or any from its bases classes.

Parameters:

cls (Type | str) –
value (str) –

Return type:

Any

firebird.base.strconv.register_convertor(cls: ~typing.Type, *, to_str: ~typing.Callable[[~typing.Any], str] = <function any2str>, from_str: ~typing.Callable[[~typing.Type, str], ~typing.Any] = <function str2any>)[source]¶

Registers convertor function(s).

Parameters:

cls (Type) – Class or class name
to_str (Callable[[Any], str]) – Function that converts cls value to str
from_str (Callable[[Type, str], Any]) – Function that converts str to value of cls data type

firebird.base.strconv.update_convertor(cls: Type | str, *, to_str: Callable[[Any], str] = None, from_str: Callable[[Type, str], Any] = None)[source]¶

Update convertor function(s).

Parameters:

cls (Type | str) – Class or class name
to_str (Callable[[Any], str]) – Function that converts cls value to str
from_str (Callable[[Type, str], Any]) – Function that converts str to value of cls data type

Raises:

KeyError – If data type has not registered convertor.

firebird.base.strconv.register_class(cls: Type) → None[source]¶

Registers class for name lookup.

Dataclasses¶

class firebird.base.strconv.Convertor(cls: Type, to_str: Callable[[Any], str], from_str: Callable[[Type, str], Any])[source]¶

Bases: Distinct

Data convertor registry entry.

Parameters:

cls (Type) –
to_str (Callable[[Any], str]) –
from_str (Callable[[Type, str], Any]) –

get_key() → Hashable[source]¶

Returns instance key.

Return type:: Hashable

cls: Type¶

from_str: Callable[[Type, str], Any]¶

property full_name: str¶: Type name including source module.

property name: str¶: Type name.

to_str: Callable[[Any], str]¶