.. module:: firebird.base.config

:synopsis: Configuration definitions

##################################

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.Decimal`, `~enum.Enum`, `~enum.Flag`,

`~uuid.UUID`, `.MIME`, `.ZMQAddress`, `list`, `~dataclasses.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.

.. code-block::

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.

.. code-block::

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.

.. code-block::

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

.. code-block::

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.

.. code-block::

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

`~Config.save_proto()` and `~Config.load_proto()`.

The protobuf message is defined in :file:`/proto/config.proto`.

.. literalinclude:: ../proto/config.proto

:language: proto

:lines: 30-

.. note::

You can use it directly or via `.protobuf` registry.

.. code-block::

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

.. code-block::

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 `~Option.save_proto()` and `~Option.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.

.. seealso:: `.ConfigOption`, `.ConfigListOption`

Constants

=========

.. data:: PROTO_CONFIG

:annotation: Fully qualified name for `ConfigProto`_ protobuf.

.. tip::

To address `ConfigProto`_ in functions like `~firebird.base.protobuf.create_message()`,

use `PROTO_CONFIG` constant.

Application Directory Scheme

============================

.. versionadded:: 1.1.0

.. versionchanged:: 1.2.0

.. autoclass:: DirectoryScheme

.. autoclass:: WindowsDirectoryScheme

.. autoclass:: LinuxDirectoryScheme

.. autoclass:: MacOSDirectoryScheme

.. autofunction:: get_directory_scheme

Configparser interpolation

==========================

.. autoclass:: EnvExtendedInterpolation

Config

======

.. autoclass:: Config

Options

=======

.. autoclass:: Option

.. autoclass:: StrOption

.. autoclass:: IntOption

.. autoclass:: FloatOption

.. autoclass:: DecimalOption

.. autoclass:: BoolOption

.. autoclass:: ZMQAddressOption

.. autoclass:: EnumOption

.. autoclass:: FlagOption

.. autoclass:: UUIDOption

.. autoclass:: MIMEOption

.. autoclass:: ListOption

.. autoclass:: DataclassOption

.. autoclass:: PathOption

.. autoclass:: PyExprOption

.. autoclass:: PyCodeOption

.. autoclass:: PyCallableOption

.. autoclass:: ConfigOption

.. autoclass:: ConfigListOption

Functions

=========

.. autofunction:: has_verticals

.. autofunction:: has_leading_spaces