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

TConvertToStr

firebird.base.strconv.TConvertToStr = typing.Callable[[typing.Any], str]

Function that converts typed value to its string representation.

TConvertFromStr

firebird.base.strconv.TConvertFromStr = typing.Callable[[typing.Type, str], typing.Any]

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

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

convert_to_str

firebird.base.strconv.convert_to_str(value)

Converts value to string using registered convertor.

Parameters

value (Any) – Value to be converted.

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.

Return type

str

convert_from_str

firebird.base.strconv.convert_from_str(cls, value)

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

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.

Return type

Any

register_convertor

firebird.base.strconv.register_convertor(cls, *, to_str=<function any2str>, from_str=<function str2any>)

Registers convertor function(s).

Parameters

update_convertor

firebird.base.strconv.update_convertor(cls, *, to_str=None, from_str=None)

Update convertor function(s).

Parameters
Raises

KeyError – If data type has not registered convertor.

register_class

firebird.base.strconv.register_class(cls)

Registers class for name lookup.

Raises

TypeError – When class name is already registered.

Return type

None

has_convertor

firebird.base.strconv.has_convertor(cls)

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.

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.

Return type

bool

get_convertor

firebird.base.strconv.get_convertor(cls)

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.

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.

Return type

Convertor

any2str

firebird.base.strconv.any2str(value)

Converts value to string using str(value).

Return type

str

str2any

firebird.base.strconv.str2any(cls, value)

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

Return type

Any

Dataclasses

Convertor

class firebird.base.strconv.Convertor(cls, to_str, from_str)

Bases: firebird.base.types.Distinct

Data convertor registry entry.

get_key()

Returns instance key.

Return type

Hashable

cls: Type
from_str: Callable[[Type, str], Any]
property full_name

Type name incl. source module

Return type

str

property name

Type name

Return type

str

to_str: Callable[[Any], str]