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:

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.

class firebird.base.config.ConfigProto

Bases: google.protobuf.pyext._message.CMessage, google.protobuf.message.Message

class ConfigsEntry

Bases: google.protobuf.pyext._message.CMessage, google.protobuf.message.Message

DESCRIPTOR = <google.protobuf.pyext._message.MessageDescriptor object>
key

Field firebird.base.ConfigProto.ConfigsEntry.key

value

Field firebird.base.ConfigProto.ConfigsEntry.value

class OptionsEntry

Bases: google.protobuf.pyext._message.CMessage, google.protobuf.message.Message

DESCRIPTOR = <google.protobuf.pyext._message.MessageDescriptor object>
key

Field firebird.base.ConfigProto.OptionsEntry.key

value

Field firebird.base.ConfigProto.OptionsEntry.value

DESCRIPTOR = <google.protobuf.pyext._message.MessageDescriptor object>
configs

Field firebird.base.ConfigProto.configs

options

Field firebird.base.ConfigProto.options

Config

Config

class firebird.base.config.Config(name)

Bases: object

Collection of configuration options.

Parameters

name (str) – Name associated with Config (default section name).

Important

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

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.

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

Return type

str

get_description()

Configuration description. Can span multiple lines.

Note: Default implementation returns 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.

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

Name associated with Config (default section name).

Return type

str

property options

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: typing.Generic, abc.ABC

Generic abstract base class for configuration options.

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 (Optional[~T]) – Default option value.

name

Option name.

Type

str

datatype

Option datatype.

Type

type

description

Option description. Can span multiple lines.

Type

str

required

True if option must have a value.

Type

bool

default

Default option value.

Type

instance of [T]

_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()

Return value as string.

Return type

str

get_config()

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

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

Return type

str

abstract get_formatted()

Return value formatted for use in config file.

Return type

str

abstract get_value()

Return current option value

Return type

~T

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 the argument is not a valid option value.

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 (~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

StrOption

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

Bases: firebird.base.config.Option

Configuration option with string value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

str

IntOption

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

Bases: firebird.base.config.Option

Configuration option with integer value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

int

FloatOption

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

Bases: firebird.base.config.Option

Configuration option with float value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

float

DecimalOption

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

Bases: firebird.base.config.Option

Configuration option with decimal.Decimal value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

Decimal

BoolOption

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

Bases: firebird.base.config.Option

Configuration option with boolean value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

bool

ZMQAddressOption

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

Bases: firebird.base.config.Option

Configuration option with ZMQAddress value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

ZMQAddress

EnumOption

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

Bases: firebird.base.config.Option

Configuration option with enum value.

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.

allowed

List of allowed enum values.

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

Return value as string.

Return type

str

get_config()

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

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

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

property value

Return current option value

Return type

Enum

UUIDOption

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

Bases: firebird.base.config.Option

Configuration option with UUID value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

UUID

MIMEOption

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

Bases: firebird.base.config.Option

Configuration option with MIME type specification value.

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

MIME

ListOption

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

Bases: firebird.base.config.Option

Configuration option with list of values.

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.

item_types

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

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.

Important

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

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

property value

Return current option value

Return type

List

DataclassOption

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

Bases: firebird.base.config.Option

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.

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.

dataclass

Dataclass type.

separator

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.

Important

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

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

property value

Return current option value

Return type

Any

PyExprOption

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

Bases: firebird.base.config.Option

String configuration option with Python expression value.

Parameters
  • name (str) – Option name.

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

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

  • default (Optional[PyExpr]) – 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()

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

PyExpr

PyCodeOption

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

Bases: firebird.base.config.Option

String configuration option with Python code value.

Parameters
  • name (str) – Option name.

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

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

  • default (Optional[PyCode]) – Default option 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()

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

PyCode

PyCallableOption

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

Bases: firebird.base.config.Option

String configuration option with Python callable value.

Parameters
  • name (str) – Option name.

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

  • signature (Signature) – Callable signature.

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

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

signature

Callable signature.

Type

inspect.Signature

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

Return current option value

Return type

PyCallable

ConfigOption

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

Bases: firebird.base.config.Option

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) – 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()

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

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.

Parameters

value (str) – New Config.name value.

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

Return current option value.

Return type

Config

ConfigListOption

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

Bases: firebird.base.config.Option

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.

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.

item_type

Datatype of list items.

separator

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.

Important

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

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

Return value as string.

Return type

str

get_formatted()

Return value formatted for use in config file.

Return type

str

get_value()

Return 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

property value

Return current option value

Return type

List

Functions

create_config

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

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

Return type

Config