config - Configuration definitions

Overview

Complex applications (and some library modules like logging) could be often parametrized via configuration. This module provides a framework for unified structured configuration that supports:

  • configuration options of various data type, including lists and other complex types

  • validation

  • direct manipulation of configuration values

  • reading from (and writing into) configuration in configparser format

  • exchanging configuration (for example between processes) using Google protobuf messages

Architecture

The framework is based around two classes:

Additionally, the ApplicationDirectoryScheme abstract base class defines set of mostly used application directories. The function get_directory_scheme() could be then used to obtain instance that implements platform-specific standards for file-system location for these directories. Currently, only “Windows”, “Linux” and “MacOS” directory schemes are supported.

Note

You may use platform.system call to determine the scheme name suitable for platform where your application is running.

Usage

First, you need to define your own configuration.

from enum import IntEnum
from firebird.base.config import Config, StrOption, IntOption, ListOption

 class SampleEnum(IntEnum):
     "Enum for testing"
     UNKNOWN    = 0
     READY      = 1
     RUNNING    = 2
     WAITING    = 3
     SUSPENDED  = 4
     FINISHED   = 5
     ABORTED    = 6

class DbConfig(Config):
    "Simple database config"
    def __init__(self, name: str):
        super().__init__(name)
        # options
        self.database: StrOption = StrOption('database', 'Database connection string',
                                             required=True)
        self.user: StrOption = StrOption('user', 'User name', required=True,
                                         default='SYSDBA')
        self.password: StrOption = StrOption('password', 'User password')

class SampleConfig(Config):
    """Sample Config.

Has three options and two sub-configs.
"""
    def __init__(self):
        super().__init__('sample-config')
        # options
        self.opt_str: StrOption = StrOption('opt_str', "Sample string option")
        self.opt_int: IntOption = StrOption('opt_int', "Sample int option")
        self.enum_list: ListOption = ListOption('enum_list', "List of enum values",
                                                item_type=SampleEnum)
        # sub configs
        self.master_db: DbConfig = DbConfig('master-db')
        self.backup_db: DbConfig = DbConfig('backup-db')

Note

Option must be assigned to Config attributes with the same name as option name.

Typically you need only one instance of your configuration class in application.

app_config: SampleConfig = SampleConfig()

Typically, your application is configured using file(s) in configparser format. You may create initial one using Config.get_config() method.

Note

Config.get_config() works with current configuration values. When called on “empty” instance it returns “default” configuration. Option values that match the default are returned as commented out.

>>> print(app_config.get_config())

[sample-config]
;
; Sample Config.
;
; Has three options and two sub-configs.
;

; opt_str
; -------
;
; data type: str
;
; [optional] Sample string option
;
;opt_str = <UNDEFINED>

; opt_int
; -------
;
; data type: str
;
; [optional] Sample int option
;
;opt_int = <UNDEFINED>

; enum_list
; ---------
;
; data type: list
;
; [optional] List of enum values
;
;enum_list = <UNDEFINED>

[master-db]
;
; Simple DB config
;

; database
; --------
;
; data type: str
;
; [REQUIRED] Database connection string
;
;database = <UNDEFINED>

; user
; ----
;
; data type: str
;
; [REQUIRED] User name
;
;user = SYSDBA

; password
; --------
;
; data type: str
;
; [optional] User password
;
;password = <UNDEFINED>

[backup-db]
;
; Simple DB config
;

; database
; --------
;
; data type: str
;
; [REQUIRED] Database connection string
;
;database = <UNDEFINED>

; user
; ----
;
; data type: str
;
; [REQUIRED] User name
;
;user = SYSDBA

; password
; --------
;
; data type: str
;
; [optional] User password
;
;password = <UNDEFINED>

To read the configuration from file, use the ConfigParser and pass it to Config.load_config() method.

Example configuration file:

; myapp.cfg

[DEFAULT]
password = masterkey

[sample-config]
opt_str = Lorem ipsum
enum_list = ready, finished, aborted

[master-db]
database = primary
user = tester
password = lockpick

[backup-db]
database = secondary
from configparser import ConfigParser

cfg = ConfigParser()
cfg.read('myapp.cfg')
app_config.load_config(cfg)

Access to configuration values is through attributes on your Config instance, and their value attribute.

>>> app_config.opt_str.value
Lorem ipsum
>>> app_config.opt_int.value
>>> app_config.enum_list.value
[READY, FINISHED, ABORTED]
>>> app_config.master_db.database.value
primary
>>> app_config.master_db.user.value
tester
>>> app_config.master_db.password.value
lockpick
>>> app_config.backup_db.database.value
secondary
>>> app_config.backup_db.user.value
SYSDBA
>>> app_config.backup_db.password.value
masterkey

ConfigProto

You can transfer configuration (state) between instances of your Config classes using Google Protocol Buffer message firebird.base.ConfigProto and methods save_proto() and load_proto().

The protobuf message is defined in /proto/config.proto.

syntax = "proto3";

package firebird.base;

import "google/protobuf/any.proto";

message Value {
  oneof kind {
    string as_string = 2 ;
    bytes  as_bytes  = 3 ;
    bool   as_bool   = 4 ;
    double as_double = 5 ;
    float  as_float  = 6 ;
    sint32 as_sint32 = 7 ;
    sint64 as_sint64 = 8 ;
    uint32 as_uint32 = 9 ;
    uint64 as_uint64 = 10 ;
    google.protobuf.Any as_msg = 11 ;
  }
}

message ConfigProto {
  map<string, Value>  options = 1 ;
  map<string, ConfigProto> configs = 2 ;
}

Note

You can use it directly or via protobuf registry.

# Direct use
from firebird.base.config import ConfigProto
cfg_msg = ConfigProto()

Because the proto file is NOT registered in protobuf registry, you must register it manually. The proto file is listed in setup.cfg under “firebird.base.protobuf” entrypoint, so use load_registered('firebird.base.protobuf') for its registration.

from firebird.base.protobuf import load_registered, create_message
load_registered('firebird.base.protobuf')
cfg_msg = create_message('firebird.base.ConfigProto')

Important

Although Option also provides methods save_proto() and load_proto() to transfer option value in/out ConfigProto message, you should always use methods on Config instance because option’s serialization may relly on Config instance that owns them.

Tip

To address ConfigProto in functions like create_message(), use PROTO_CONFIG constant.

firebird.base.config.PROTO_CONFIG Fully qualified name for `ConfigProto`_ protobuf.

Application Directory Scheme

New in version 1.1.0.

Changed in version 1.2.0.

class firebird.base.config.DirectoryScheme(name, version=None, force_home=False)

Bases: object

Class that provide paths to typically used application directories.

Default scheme uses HOME directory as root for other directories. The HOME is determined as follows:

  1. If environment variable “<app_name>_HOME” exists, its value is used as HOME directory.

  2. HOME directory is set to current working directory.

Note

All paths are set when the instance is created and can be changed later.

__init__(name, version=None, force_home=False)
Parameters
  • name (str) – Appplication name.

  • version (Optional[str]) – Application version.

  • force_home (bool) – When True, general directories (i.e. all except user-specific and TMP) would be always based on HOME directory.

has_home_env()

Returns True if HOME directory is set by “<app_name>_HOME” environment variable.

Return type

bool

property cache: Path

Directory for application cache data.

Such data are locally generated as a result of time-consuming I/O or calculation. The application must be able to regenerate or restore the data. The cached files can be deleted without loss of data.

Return type

Path

property config: Path

Directory for host-specific system-wide configuration files.

Return type

Path

property data: Path

Directory for state information / persistent data modified by application as it runs.

Return type

Path

property home: Path

HOME directory. Initial value is path set by “<app_name>_HOME” environment variable, or to current working directory when variable is not defined.

Important

When new value is assigned, the general directories (i.e. all except user-specific and TMP) are redefined as subdirectories of new home path ONLY when HOME was initially defined using “<app_name>_HOME” environment variable, or instance was created with `force_home`=True.

However, all paths could be still changed individually to any value.

Return type

Path

property logs: Path

Directory for log files.

Return type

Path

property run_data: Path

Directory for run-time variable data that may not persist over boot.

Return type

Path

property srv: Path

Directory for site-specific data served by this system, such as data and scripts for web servers, data offered by FTP servers, and repositories for version control systems etc.

Return type

Path

property tmp: Path

Directory for temporary files to be preserved between reboots.

Return type

Path

property user_cache: Path

Directory for user-specific application cache data.

Return type

Path

property user_config: Path

Directory for user-specific configuration.

Return type

Path

property user_data: Path

Directory for User local data.

Return type

Path

property user_sync: Path

Directory for user data synced accross systems (roaming).

Return type

Path

class firebird.base.config.WindowsDirectoryScheme(name, version=None, force_home=False)

Bases: DirectoryScheme

Directory scheme that conforms to Windows standards.

If HOME is defined using “<app_name>_HOME” environment variable, or force_home parameter is True, only user-specific directories and TMP are set according to platform standars, while general directories remain as defined by base DirectoryScheme.

__init__(name, version=None, force_home=False)
Parameters
  • name (str) – Appplication name.

  • version (Optional[str]) – Application version.

  • force_home (bool) – When True, general directories (i.e. all except user-specific and TMP) would be always based on HOME directory.

class firebird.base.config.LinuxDirectoryScheme(name, version=None, force_home=False)

Bases: DirectoryScheme

Directory scheme that conforms to Linux standards.

If HOME is defined using “<app_name>_HOME” environment variable, or force_home parameter is True, only user-specific directories and TMP are set according to platform standars, while general directories remain as defined by base DirectoryScheme.

__init__(name, version=None, force_home=False)
Parameters
  • name (str) – Appplication name.

  • version (Optional[str]) – Application version.

  • force_home (bool) – When True, general directories (i.e. all except user-specific and TMP) would be always based on HOME directory.

class firebird.base.config.MacOSDirectoryScheme(name, version=None, force_home=False)

Bases: DirectoryScheme

Directory scheme that conforms to MacOS standards.

If HOME is defined using “<app_name>_HOME” environment variable, only user-specific directories and TMP are set according to platform standars, while general directories remain as defined by base DirectoryScheme.

__init__(name, version=None, force_home=False)
Parameters
  • name (str) – Appplication name.

  • version (Optional[str]) – Application version.

firebird.base.config.get_directory_scheme(app_name, version=None, *, force_home=False)

Returns directory scheme for current platform.

Parameters
  • app_name (str) – Application name

  • version (Optional[str]) – Application version string

  • force_home (bool) – When True, the general directies are always set to subdirectories of DirectoryScheme.home directory. When False, these the home is used ONLY when it’s set by “<app_name>_HOME” environment variable.

Return type

DirectoryScheme

Config

Config

class firebird.base.config.Config(name, *, optional=False, description=None)

Bases: object

Collection of configuration options.

Important

Descendants must define individual options and sub configs as instance attributes.

__init__(name, *, optional=False, description=None)
Parameters
  • name (str) – Name associated with Config (default section name).

  • optional (bool) – Whether config is optional (False) or mandatory (True) for configuration file (see load_config() for details).

  • description (Optional[str]) – Optional configuration description. Can span multiple lines.

clear(*, to_default=True)

Clears all owned options and options in owned sub-configs.

Parameters

to_default (bool) – If True, sets the option values to defaults, else to None.

Return type

None

get_config()

Returns string containing text lines suitable for use in configuration file processed with ConfigParser.

Return type

str

get_description()

Configuration description. Can span multiple lines.

Note: If description is not provided on instance creation, class doc string.

Return type

str

load_config(config, section=None)

Update configuration.

Parameters
  • config (ConfigParser) – ConfigParser instance with configuration values.

  • section (Optional[str]) – Name of ConfigParser section that should be used to get new configuration values. If not provided, uses name.

Raises
  • ValueError – When any option value cannot be loadded.

  • KeyError – If section does not exists, and config is not optional or section is not configparser.DEFAULTSECT.

Return type

None

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains option values and sub-configs.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option values and sub-configs should be stored.

Return type

None

validate()
Checks whether:
  • all required options have value other than None.

  • all options are defined as config attribute with the same name as option name

Raises exception when any constraint required by configuration is violated.

Return type

None

property configs: List[Config]

List of sub-Configs defined for this Config instance. It includes all instance attributes of Config type, and Config values of owned ConfigOption and ConfigListOption instances.

Return type

List[Config]

property name: str

Name associated with Config (default section name).

Return type

str

property optional: bool

Whether config is optional (False) or mandatory (True) for configuration file (see load_config() for details).

Return type

bool

property options: List[Option]

List of options defined for this Config instance.

Return type

List[Option]

Options

Option

class firebird.base.config.Option(name, datatype, description, required=False, default=None)

Bases: Generic[T], ABC

Generic abstract base class for configuration options.

__init__(name, datatype, description, required=False, default=None)
Parameters
  • name (str) – Option name.

  • datatype (TypeVar(T)) – Option datatype.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[TypeVar(T)]) – Default option value.

_get_config_lines()

Returns list of strings containing text lines suitable for use in configuration file processed with ConfigParser.

Text lines with configuration start with comment marker ; and end with newline.

Note

This function is intended for internal use. To get string describing current configuration that is suitable for configuration files, use get_config method.

Return type

List[str]

abstract clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

abstract get_as_str()

Returns value as string.

Return type

str

get_config()

Returns string containing text lines suitable for use in configuration file processed with ConfigParser.

Return type

str

abstract get_formatted()

Returns value formatted for use in config file.

Return type

str

abstract get_value()

Returns current option value.

Return type

TypeVar(T)

has_value()

Returns True if option value is not None.

Return type

bool

load_config(config, section)

Update option value from ConfigParser instance.

Parameters
  • config (ConfigParser) – ConfigParser instance.

  • section (str) – Name of ConfigParser section that should be used to get new option value.

Raises
  • ValueError – When option value cannot be loadded.

  • KeyError – If section does not exists, and it’s not configparser.DEFAULTSECT.

Return type

None

abstract load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

abstract save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

abstract set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

abstract set_value(value)

Set new option value.

Parameters

value (TypeVar(T)) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

validate()

Validates option state.

Raises

Error – When required option does not have a value.

Return type

None

datatype: T

Option datatype.

default: T

Default option value.

description: str

Option description. Can span multiple lines.

name: str

Option name.

required: bool

True if option must have a value.

StrOption

class firebird.base.config.StrOption(name, description, *, required=False, default=None)

Bases: Option[str]

Configuration option with string value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[str]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

str

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (str) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: str

Current option value

Return type

str

IntOption

class firebird.base.config.IntOption(name, description, *, required=False, default=None, signed=False)

Bases: Option[int]

Configuration option with integer value.

__init__(name, description, *, required=False, default=None, signed=False)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[int]) – Default option value.

  • signed (bool) – When False, the option value cannot be negative.

clear(to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

int

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (int) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: int

Current option value

Return type

int

FloatOption

class firebird.base.config.FloatOption(name, description, *, required=False, default=None)

Bases: Option[float]

Configuration option with float value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[float]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

float

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (float) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: float

Current option value

Return type

float

DecimalOption

class firebird.base.config.DecimalOption(name, description, *, required=False, default=None)

Bases: Option[Decimal]

Configuration option with decimal.Decimal value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[Decimal]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

Decimal

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (Decimal) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: Decimal

Current option value

Return type

Decimal

BoolOption

class firebird.base.config.BoolOption(name, description, *, required=False, default=None)

Bases: Option[bool]

Configuration option with boolean value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[bool]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

bool

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (bool) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: bool

Current option value

Return type

bool

ZMQAddressOption

class firebird.base.config.ZMQAddressOption(name, description, *, required=False, default=None)

Bases: Option[ZMQAddress]

Configuration option with ZMQAddress value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[ZMQAddress]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

ZMQAddress

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (ZMQAddress) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: ZMQAddress

Current option value

Return type

ZMQAddress

EnumOption

class firebird.base.config.EnumOption(name, enum_class, description, *, required=False, default=None, allowed=None)

Bases: Option[Enum]

Configuration option with enum value.

__init__(name, enum_class, description, *, required=False, default=None, allowed=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[Enum]) – Default option value.

  • allowed (Optional[List]) – List of allowed Enum members. When not defined, all members of enum type are allowed.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

Enum

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (Enum) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

allowed: Sequence

List of allowed enum values.

property value: Enum

Current option value

Return type

Enum

FlagOption

class firebird.base.config.FlagOption(name, flag_class, description, *, required=False, default=None, allowed=None)

Bases: Option[Flag]

Configuration option with flag value.

__init__(name, flag_class, description, *, required=False, default=None, allowed=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[Flag]) – Default option value.

  • allowed (Optional[List]) – List of allowed Flag members. When not defined, all members of flag type are allowed.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

Flag

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (Flag) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

allowed: Sequence

List of allowed flag values.

property value: Flag

Current option value

Return type

Flag

UUIDOption

class firebird.base.config.UUIDOption(name, description, *, required=False, default=None)

Bases: Option[UUID]

Configuration option with UUID value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[UUID]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

UUID

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (UUID) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: UUID

Current option value

Return type

UUID

MIMEOption

class firebird.base.config.MIMEOption(name, description, *, required=False, default=None)

Bases: Option[MIME]

Configuration option with MIME type specification value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[MIME]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

MIME

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (MIME) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: MIME

Current option value

Return type

MIME

ListOption

class firebird.base.config.ListOption(name, item_type, description, *, required=False, default=None, separator=None)

Bases: Option[List]

Configuration option with list of values.

Important

When option is read from ConfigParser, empty values are ignored.

__init__(name, item_type, description, *, required=False, default=None, separator=None)
Parameters
  • name (str) – Option name.

  • item_type (Union[Type, Sequence[Type]]) – Datatype of list items. It could be a type or sequence of types. If multiple types are provided, each value in config file must have format: type_name:value_as_str.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[List]) – Default option value.

  • separator (Optional[str]) – String that separates list item values when options value is read from ConfigParser. It’s possible to use a line break as separator. If separator is None [default] and the value contains line breaks, it uses the line break as separator, otherwise it uses comma as separator.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

List

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (List) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

item_types: Sequence[Type]

Datatypes of list items. If there is more than one type, each value in config file must have format: type_name:value_as_str.

separator: Optional[str]

String that separates list item values when options value is read from ConfigParser. Default separator is None. It’s possible to use a line break as separator. If separator is None and the value contains line breaks, it uses the line break as separator, otherwise it uses comma as separator.

property value: List

Current option value

Return type

List

DataclassOption

class firebird.base.config.DataclassOption(name, dataclass, description, *, required=False, default=None, separator=None, fields=None)

Bases: Option[Any]

Configuration option with a dataclass value.

The ConfigParser format for this option is a list of values, where each list items defines value for dataclass field in field_name:value_as_str format. The configuration must contain values for all fields for the dataclass that does not have default value.

Important

This option uses type annotation for dataclass to determine the actual data type for conversion from string. It means that:

  1. If type annotation contains “typing” types, it’s necessary to specify “real” types for all dataclass fields using the fields argument.

  2. All used data types must have string convertors registered in strconv module.

Important

When option is read from ConfigParser, empty values are ignored.

__init__(name, dataclass, description, *, required=False, default=None, separator=None, fields=None)
Parameters
  • name (str) – Option name.

  • dataclass (Type) – Dataclass type.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[Any]) – Default option value.

  • separator (Optional[str]) – String that separates dataclass field values when options value is read from ConfigParser. It’s possible to use a line break as separator. If separator is None [default] and the value contains line breaks, it uses the line break as separator, otherwise it uses comma as separator.

  • fields (Optional[Dict[str, Type]]) – Dictionary that maps dataclass field names to data types.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

Any

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (Any) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

dataclass: Type

Dataclass type.

separator: Optional[str]

String that separates dataclass field values when options value is read from ConfigParser. Default separator is None. It’s possible to use a line break as separator. If separator is None and the value contains line breaks, it uses the line break as separator, otherwise it uses comma as separator.

property value: Any

Current option value

Return type

Any

PathOption

class firebird.base.config.PathOption(name, description, *, required=False, default=None)

Bases: Option[str]

Configuration option with pathlib.Path value.

__init__(name, description, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • required (bool) – True if option must have a value.

  • default (Optional[Path]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

Path

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (Path) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: Path

Current option value

Return type

Path

PyExprOption

class firebird.base.config.PyExprOption(name, description, *, required=False, default=None)

Bases: Option[PyExpr]

String configuration option with Python expression value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

PyExpr

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (PyExpr) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: PyExpr

Current option value

Return type

PyExpr

PyCodeOption

class firebird.base.config.PyCodeOption(name, description, *, required=False, default=None)

Bases: Option[PyCode]

String configuration option with Python code value.

Important

Python code must be properly indented, but ConfigParser multiline string values have leading whitespace removed. To circumvent this, the PyCodeOption supports assignment of text values where lines start with | character. This character is removed, along with any number of subsequent whitespace characters that are between | and first non-whitespace character on first line starting with |.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

PyCode

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (PyCode) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

property value: PyCode

Current option value

Return type

PyCode

PyCallableOption

class firebird.base.config.PyCallableOption(name, description, signature, *, required=False, default=None)

Bases: Option[PyCallable]

String configuration option with Python callable value.

Important

Python code must be properly indented, but ConfigParser multiline string values have leading whitespace removed. To circumvent this, the PyCodeOption supports assignment of text values where lines start with | character. This character is removed, along with any number of subsequent whitespace characters that are between | and first non-whitespace character on first line starting with |.

__init__(name, description, signature, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • signature (Union[Signature, Callable]) – Callable signature or callable.

  • required (bool) – True if option must have a value.

  • default (Optional[PyCallable]) – Default option value.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

PyCallable

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (PyCallable) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the callable has wrong signature.

Return type

None

property value: PyCallable

Current option value

Return type

PyCallable

ConfigOption

class firebird.base.config.ConfigOption(name, description, config, *, required=False, default=None)

Bases: Option[str]

Configuration option with Config value.

Important

This option is intended for sub-configs that should have configurable name (i.e. the section name that holds sub-config values). To create sub-configs with fixed section names, simply assign them to instance attributes of Config instance that owns them (preferably in constructor).

While the value attribute for this option is an instance of any class inherited from Config, in other ways it behaves like StrOption that loads/saves only name of its Config value (i.e. the section name). The actual I/O for sub-config’s options is delegated to Config instance that owns this option.

The “empty” value for this option is not None (because the Config instance always exists), but an empty string for Config.name attribute.

__init__(name, description, config, *, required=False, default=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • config (Config) – Option’s value.

  • required (bool) – True if option must have a value.

  • default (Optional[str]) – Default Config.name value.

clear(*, to_default=True)

Clears the option value.

Note

This method calls clear(to_default).

Parameters

to_default (bool) – If True, sets the Config.name to default value, else to empty string.

Return type

None

get_as_str()

Return value as string.

Important

Because the actual value is a Config instance, the returned string is the section name used to store Config options.

Return type

str

get_formatted()

Return value formatted for use in config file.

The string contains section name that will be used to store the Config values.

Return type

str

get_value()

Returns current option value.

Return type

Config

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New Config.name value.

Important

Because the actual value is a Config instance, the string must contain the Config.name value (which is the section name used to store Config options). Beware that multiple Config instances with the same (section) name may cause collision when configuration is written to protobuf message or configuration file.

Return type

None

set_value(value)

Set new option value.

This option type does not support direct assignment of Config value. Because this method is also used to assign default value (which is a Config.name), it accepts None or string argument that is interpreted as new Config name. None value is translated to empty string.

Parameters

value (str) – New Config name.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When None or empty string is passed and option value is required.

Return type

None

validate()

Validates option state.

Raises

Error – When required option does not have a value.

Return type

None

property value: Config

Current option value

Return type

Config

ConfigListOption

class firebird.base.config.ConfigListOption(name, description, item_type, *, required=False, separator=None)

Bases: Option[List]

Configuration option with list of Config values.

Important

This option is intended for configurable set of sub-configs of fixed type.

While the value attribute for this option is a list of instances of single class inherited from Config, in other ways it behaves like ListOption with str items that loads/saves only names of its Config items (i.e. the section names). The actual I/O for sub-config options is delegated to Config instance that owns this option.

Important

When option is read from ConfigParser, empty values are ignored.

__init__(name, description, item_type, *, required=False, separator=None)
Parameters
  • name (str) – Option name.

  • description (str) – Option description. Can span multiple lines.

  • item_type (Type[Config]) – Datatype of list items. Must be subclass of Config.

  • required (bool) – True if option must have a value.

  • separator (Optional[str]) – String that separates values when options value is read from ConfigParser. It’s possible to use a line break as separator. If separator is None [default] and the value contains line breaks, it uses the line break as separator, otherwise it uses comma as separator.

clear(*, to_default=True)

Clears the option value.

Parameters

to_default (bool) – If True, sets the option value to default value, else to None.

Return type

None

get_as_str()

Returns value as string.

Return type

str

get_formatted()

Returns value formatted for use in config file.

Return type

str

get_value()

Returns current option value.

Return type

List

load_proto(proto)

Deserialize value from ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message that may contains options value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

save_proto(proto)

Serialize value into ConfigProto message.

Parameters

proto (ConfigProto) – Protobuf message where option value should be stored.

Return type

None

set_as_str(value)

Set new option value from string.

Parameters

value (str) – New option value.

Raises

ValueError – When the argument is not a valid option value.

Return type

None

set_value(value)

Set new option value.

Parameters

value (List) – New option value.

Raises
  • TypeError – When the new value is of the wrong type.

  • ValueError – When the argument is not a valid option value.

Return type

None

item_type: Type[Config]

Datatype of list items.

separator: Optional[str]

String that separates values when options value is read from ConfigParser. Default separator is None. It’s possible to use a line break as separator. If separator is None and the value contains line breaks, it uses the line break as separator, otherwise it uses comma as separator.

property value: List

Current option value

Return type

List

Functions

create_config

firebird.base.config.create_config(_cls, name)

Return newly created Config instance. Intended to be used with functools.partial.

Return type

Config