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:

Config - Collection of configuration options and sub-collections. Particular configuration is then realized as descendant from this class, that defines configuration options in constructor, and customize the validation when required.
Option - Abstract base class for configuration options, where descendants implement handling of particular data type. This module provides implementation for next data types: str, int, float, bool, Decimal, Enum, Flag, UUID, MIME, ZMQAddress, list, dataclass, PyExpr, PyCode and PyCallable. It also provides special options ConfigOption and ConfigListOption.

Additionally, the DirectoryScheme 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.

Tip

You may use get_directory_scheme() function to get the scheme suitable for platform where your application is running.

Tip

If your configurations contain secrets like passwords or access tokens, that would be read from files via configparser, you should consider to use EnvExtendedInterpolation that has support for option values defined via environment variables.

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')

Important

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 pyproject.toml 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.

Constants¶

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

Tip

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

Application Directory Scheme¶

New in version 1.1.0.

Changed in version 1.2.0.

class firebird.base.config.DirectoryScheme(name: str, version: str = None, force_home: bool = False)[source]¶

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:

If environment variable <app_name>_HOME exists, its value is used as HOME directory.
HOME directory is set to current working directory.

Note

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

Parameters:

name (str) –
version (str) –
force_home (bool) –

__init__(name: str, version: str = None, force_home: bool = False)[source]¶

Parameters:

name (str) – Appplication name.
version (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() → bool[source]¶

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.

property config: Path¶: Directory for host-specific system-wide configuration files.

property data: Path¶: Directory for state information / persistent data modified by application as it runs.

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.

property logs: Path¶: Directory for log files.

property run_data: Path¶: Directory for run-time variable data that may not persist over boot.

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.

property tmp: Path¶: Directory for temporary files to be preserved between reboots.

property user_cache: Path¶: Directory for user-specific application cache data.

property user_config: Path¶: Directory for user-specific configuration.

property user_data: Path¶: Directory for User local data.

property user_sync: Path¶: Directory for user data synced accross systems (roaming).

class firebird.base.config.WindowsDirectoryScheme(name: str, version: str = None, force_home: bool = False)[source]¶

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.

Parameters:

name (str) –
version (str) –
force_home (bool) –

__init__(name: str, version: str = None, force_home: bool = False)[source]¶

Parameters:

name (str) – Appplication name.
version (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: str, version: str = None, force_home: bool = False)[source]¶

Bases: DirectoryScheme

Directory scheme that conforms to Linux standards.

Parameters:

name (str) –
version (str) –
force_home (bool) –

__init__(name: str, version: str = None, force_home: bool = False)[source]¶

Parameters:

name (str) – Appplication name.
version (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: str, version: str = None, force_home: bool = False)[source]¶

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.

Parameters:

name (str) –
version (str) –
force_home (bool) –

__init__(name: str, version: str = None, force_home: bool = False)[source]¶

Parameters:

name (str) – Appplication name.
version (str) – Application version.
force_home (bool) –

firebird.base.config.get_directory_scheme(app_name: str, version: str = None, *, force_home: bool = False) → DirectoryScheme[source]¶

Returns directory scheme for current platform.

Parameters:

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

Return type:

DirectoryScheme

Configparser interpolation¶

class firebird.base.config.EnvExtendedInterpolation[source]¶

Bases: ExtendedInterpolation

New in version 1.8.0.

Modified version of configparser.ExtendedInterpolation class that adds special handling for “env” section that returns value of specified environment variable, or empty string if such variable is not defined.

Example:

${env:path} is reference to PATH environment variable.

Config¶

class firebird.base.config.Config(name: str, *, optional: bool = False, description: str = None)[source]¶

Bases: object

Collection of configuration options.

Important

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

Parameters:

name (str) –
optional (bool) –
description (str) –

__init__(name: str, *, optional: bool = False, description: str = None)[source]¶

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 (str) – Optional configuration description. Can span multiple lines.

clear(*, to_default: bool = True) → None[source]¶

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(*, plain: bool = False) → str[source]¶

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

Parameters:: plain (bool) – When True, it outputs only the option values. When False, it includes also option descriptions and other helpful information.
Return type:: str

get_description() → str[source]¶

Configuration description. Can span multiple lines.

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

Return type:: str

load_config(config: ConfigParser, section: str = None) → None[source]¶

Update configuration.

Parameters:

config (ConfigParser) – ConfigParser instance with configuration values.
section (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: ConfigProto) → None[source]¶

Deserialize value from ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message that may contains option values and sub-configs.
Return type:: None

save_proto(proto: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option values and sub-configs should be stored.
Return type:: None

validate() → None[source]¶

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.

property name: str¶: Name associated with Config (default section name).

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

property options: List[Option]¶: List of options defined for this Config instance.

Options¶

class firebird.base.config.Option(name: str, datatype: T, description: str, required: bool = False, default: T = None)[source]¶

Bases: Generic[T], ABC

Generic abstract base class for configuration options.

Parameters:

name (str) –
datatype (T) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, datatype: T, description: str, required: bool = False, default: T = None)[source]¶

Parameters:

name (str) – Option name.
datatype (T) – Option datatype.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (T) – Default option value.

_get_config_lines(plain: bool = False) → List[str][source]¶

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.

Parameters:: plain (bool) – When True, it outputs only the option value. When False, it includes also option description and other helpful information.
Return type:: List[str]

Note

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

abstract clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_config(*, plain: bool = False) → str[source]¶

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

Parameters:: plain (bool) – When True, it outputs only the option value. When False, it includes also option description and other helpful information.
Return type:: str

abstract get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

abstract get_value() → T[source]¶

Returns current option value.

Return type:: T

has_value() → bool[source]¶

Returns True if option value is not None.

Return type:: bool

load_config(config: ConfigParser, section: str) → None[source]¶

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: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

abstract set_as_str(value: str) → None[source]¶

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: T) → None[source]¶

Set new option value.

Parameters:

value (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() → None[source]¶

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.

class firebird.base.config.StrOption(name: str, description: str, *, required: bool = False, default: str = None)[source]¶

Bases: Option[str]

Configuration option with string value.

New in version 1.6.1: Support for verticals to preserve leading whitespace.

Important

Multiline string values could contain significant leading whitespace, but ConfigParser multiline string values have leading whitespace removed. To circumvent this, the StrOption 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 |.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: str = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (str) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → str[source]¶

Returns current option value.

Return type:: str

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: str) → None[source]¶

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

class firebird.base.config.IntOption(name: str, description: str, *, required: bool = False, default: int = None, signed: bool = False)[source]¶

Bases: Option[int]

Configuration option with integer value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –
signed (bool) –

__init__(name: str, description: str, *, required: bool = False, default: int = None, signed: bool = False)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (int) – Default option value.
signed (bool) – When False, the option value cannot be negative.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → int[source]¶

Returns current option value.

Return type:: int

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: int) → None[source]¶

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

class firebird.base.config.FloatOption(name: str, description: str, *, required: bool = False, default: float = None)[source]¶

Bases: Option[float]

Configuration option with float value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: float = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (float) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → float[source]¶

Returns current option value.

Return type:: float

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: float) → None[source]¶

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

class firebird.base.config.DecimalOption(name: str, description: str, *, required: bool = False, default: Decimal = None)[source]¶

Bases: Option[Decimal]

Configuration option with decimal.Decimal value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: Decimal = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (Decimal) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → Decimal[source]¶

Returns current option value.

Return type:: Decimal

load_proto(proto: ConfigProto)[source]¶

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: ConfigProto)[source]¶

Serialize value into ConfigProto message.

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

set_as_str(value: str) → None[source]¶

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: Decimal) → None[source]¶

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

class firebird.base.config.BoolOption(name: str, description: str, *, required: bool = False, default: bool = None)[source]¶

Bases: Option[bool]

Configuration option with boolean value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: bool = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (bool) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → bool[source]¶

Returns current option value.

Return type:: bool

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: bool) → None[source]¶

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

class firebird.base.config.ZMQAddressOption(name: str, description: str, *, required: bool = False, default: ZMQAddress = None)[source]¶

Bases: Option[ZMQAddress]

Configuration option with ZMQAddress value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: ZMQAddress = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (ZMQAddress) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → ZMQAddress[source]¶

Returns current option value.

Return type:: ZMQAddress

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: ZMQAddress) → None[source]¶

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

class firebird.base.config.EnumOption(name: str, enum_class: Enum, description: str, *, required: bool = False, default: Enum = None, allowed: List = None)[source]¶

Bases: Option[Enum]

Configuration option with enum value.

Parameters:

name (str) –
enum_class (Enum) –
description (str) –
required (bool) –
default (T) –
allowed (List) –

__init__(name: str, enum_class: Enum, description: str, *, required: bool = False, default: Enum = None, allowed: List = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (Enum) – Default option value.
allowed (List) – List of allowed Enum members. When not defined, all members of enum type are allowed.
enum_class (Enum) –

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → Enum[source]¶

Returns current option value.

Return type:: Enum

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: Enum) → None[source]¶

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

class firebird.base.config.FlagOption(name: str, flag_class: Flag, description: str, *, required: bool = False, default: Flag = None, allowed: List = None)[source]¶

Bases: Option[Flag]

Configuration option with flag value.

Parameters:

name (str) –
flag_class (Flag) –
description (str) –
required (bool) –
default (T) –
allowed (List) –

__init__(name: str, flag_class: Flag, description: str, *, required: bool = False, default: Flag = None, allowed: List = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (Flag) – Default option value.
allowed (List) – List of allowed Flag members. When not defined, all members of flag type are allowed.
flag_class (Flag) –

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → Flag[source]¶

Returns current option value.

Return type:: Flag

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: Flag) → None[source]¶

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

class firebird.base.config.UUIDOption(name: str, description: str, *, required: bool = False, default: UUID = None)[source]¶

Bases: Option[UUID]

Configuration option with UUID value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: UUID = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (UUID) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → UUID[source]¶

Returns current option value.

Return type:: UUID

load_proto(proto: ConfigProto) → None[source]¶

Deserialize value from ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message that may contains options value.
Return type:: None

save_proto(proto: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: UUID) → None[source]¶

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

class firebird.base.config.MIMEOption(name: str, description: str, *, required: bool = False, default: MIME = None)[source]¶

Bases: Option[MIME]

Configuration option with MIME type specification value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: MIME = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (MIME) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → MIME[source]¶

Returns current option value.

Return type:: MIME

load_proto(proto: ConfigProto) → None[source]¶

Deserialize value from ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message that may contains options value.
Return type:: None

save_proto(proto: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: MIME) → None[source]¶

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

class firebird.base.config.ListOption(name: str, item_type: Type | Sequence[Type], description: str, *, required: bool = False, default: List = None, separator: str = None)[source]¶

Bases: Option[List]

Configuration option with list of values.

Important

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

Parameters:

name (str) –
item_type (Union[Type, Sequence[Type]]) –
description (str) –
required (bool) –
default (T) –
separator (str) –

__init__(name: str, item_type: Type | Sequence[Type], description: str, *, required: bool = False, default: List = None, separator: str = None)[source]¶

Parameters:

name (str) – Option name.
item_type (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 (List) – Default option value.
separator (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: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → List[source]¶

Returns current option value.

Return type:: List

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: List) → None[source]¶

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: str | None¶: 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

class firebird.base.config.DataclassOption(name: str, dataclass: Type, description: str, *, required: bool = False, default: Any = None, separator: str = None, fields: Dict[str, Type] = None)[source]¶

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:

If type annotation contains “typing” types, it’s necessary to specify “real” types for all dataclass fields using the fields argument.
All used data types must have string convertors registered in strconv module.

Important

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

Parameters:

name (str) –
dataclass (Type) –
description (str) –
required (bool) –
default (T) –
separator (str) –
fields (Dict[str, Type]) –

__init__(name: str, dataclass: Type, description: str, *, required: bool = False, default: Any = None, separator: str = None, fields: Dict[str, Type] = None)[source]¶

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 (Any) – Default option value.
separator (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 (Dict[str, Type]) – Dictionary that maps dataclass field names to data types.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → Any[source]¶

Returns current option value.

Return type:: Any

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: Any) → None[source]¶

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: str | None¶: 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

class firebird.base.config.PathOption(name: str, description: str, *, required: bool = False, default: Path = None)[source]¶

Bases: Option[str]

Configuration option with pathlib.Path value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

__init__(name: str, description: str, *, required: bool = False, default: Path = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
required (bool) – True if option must have a value.
default (Path) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → Path[source]¶

Returns current option value.

Return type:: Path

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: Path) → None[source]¶

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

class firebird.base.config.PyExprOption(name: str, description: str, *, required: bool = False, default: PyExpr = None)[source]¶

Bases: Option[PyExpr]

String configuration option with Python expression value.

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → PyExpr[source]¶

Returns current option value.

Return type:: PyExpr

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: PyExpr) → None[source]¶

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

class firebird.base.config.PyCodeOption(name: str, description: str, *, required: bool = False, default: PyCode = None)[source]¶

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

Parameters:

name (str) –
description (str) –
required (bool) –
default (T) –

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → PyCode[source]¶

Returns current option value.

Return type:: PyCode

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: PyCode) → None[source]¶

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

class firebird.base.config.PyCallableOption(name: str, description: str, signature: Signature | Callable, *, required: bool = False, default: PyCallable = None)[source]¶

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

Parameters:

name (str) –
description (str) –
signature (Union[Signature, Callable]) –
required (bool) –
default (T) –

__init__(name: str, description: str, signature: Signature | Callable, *, required: bool = False, default: PyCallable = None)[source]¶

Parameters:

name (str) – Option name.
description (str) – Option description. Can span multiple lines.
signature (Signature | Callable) – Callable signature or callable.
required (bool) – True if option must have a value.
default (PyCallable) – Default option value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → PyCallable[source]¶

Returns current option value.

Return type:: PyCallable

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: PyCallable) → None[source]¶

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

class firebird.base.config.ConfigOption(name: str, description: str, config: Config, *, required: bool = False, default: str = None)[source]¶

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.

Parameters:

name (str) –
description (str) –
config (Config) –
required (bool) –
default (T) –

__init__(name: str, description: str, config: Config, *, required: bool = False, default: str = None)[source]¶

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 (str) – Default Config.name value.

clear(*, to_default: bool = True) → None[source]¶

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() → str[source]¶

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() → str[source]¶

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() → Config[source]¶

Returns current option value.

Return type:: Config

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

Set new option value from string.

Parameters:: value (str) – New Config.name value.
Return type:: None

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.

set_value(value: str) → None[source]¶

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() → None[source]¶

Validates option state.

Raises:: Error – When required option does not have a value.
Return type:: None

property value: Config¶: Current option value

class firebird.base.config.ConfigListOption(name: str, description: str, item_type: Type[Config], *, required: bool = False, separator: str = None)[source]¶

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.

Parameters:

name (str) –
description (str) –
item_type (Type[Config]) –
required (bool) –
separator (str) –

__init__(name: str, description: str, item_type: Type[Config], *, required: bool = False, separator: str = None)[source]¶

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 (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: bool = True) → None[source]¶

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() → str[source]¶

Returns value as string.

Return type:: str

get_formatted() → str[source]¶

Returns value formatted for use in config file.

Return type:: str

get_value() → List[source]¶

Returns current option value.

Return type:: List

load_proto(proto: ConfigProto) → None[source]¶

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: ConfigProto) → None[source]¶

Serialize value into ConfigProto message.

Parameters:: proto (ConfigProto) – Protobuf message where option value should be stored.
Return type:: None

set_as_str(value: str) → None[source]¶

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: List) → None[source]¶

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: str | None¶: 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

Functions¶

firebird.base.config.has_verticals(value: str) → bool[source]¶

Returns True if lines in multiline string contains leading ‘|’ character.

Parameters:: value (str) –
Return type:: bool

firebird.base.config.has_leading_spaces(value: str) → bool[source]¶

Returns True if any line in multiline string starts with space(s).

Parameters:: value (str) –
Return type:: bool

firebird.base.config.create_config(_cls: Type[Config], name: str) → Config[source]¶

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

Deprecated since version 1.6: Will be removed in version 2.0

Parameters:

_cls (Type[Config]) –
name (str) –

Return type:

Config