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:

  1. 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.

  2. 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:

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: Union[Type, str], value: str) Any[source]

Converts value from string to data type using registered convertor.

Parameters
  • cls (Union[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:

  1. If class name is NOT registered via register_class(), it’s not possible to perform lookup for bases classes.

  2. 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
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

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

Update convertor function(s).

Parameters
Raises

KeyError – If data type has not registered convertor.


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

Registers class for name lookup.

Raises

TypeError – When class name is already registered.

Parameters

cls (Type) –

Return type

None


firebird.base.strconv.has_convertor(cls: Union[Type, str]) bool[source]

Returns True if class has a convertor.

Parameters

cls (Union[Type, str]) – Type or type name. The name could be simple class name, or full name that includes the module name.

Return type

bool

Note

When cls is a name:

  1. If class name is NOT registered via register_class(), it’s not possible to perform lookup for bases classes.

  2. 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.


firebird.base.strconv.get_convertor(cls: Union[Type, str]) Convertor[source]

Returns Convertor for data type.

Parameters

cls (Union[Type, str]) – Type or type name. The name could be simple class name, or full name that includes the module name.

Return type

Convertor

Note

When cls is a type name:

  1. If class name is NOT registered via register_class(), it’s not possible to perform lookup for bases classes.

  2. 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 (Union[Type, str]) –

Return type

Convertor


firebird.base.strconv.any2str(value: Any) str[source]

Converts value to string using str(value).

Parameters

value (Any) –

Return type

str


firebird.base.strconv.str2any(cls: Type, value: str) Any[source]

Converts string to data type value using type(value).

Parameters
Return type

Any

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
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]