# config - Configuration definitions

## Overview

## `firebird.base.config`

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 types (int, str, bool, list, Enum, Path, etc.).
- Nested configuration structures (`Config` containing other `Config` instances).
- Type checking and validation for option values.
- Default values and marking options as required.
- Reading from (and writing to) configuration files in `configparser` format, with extended interpolation support (including environment variables via `${env:VAR}`).
- Serialization/deserialization using Google protobuf messages (`ConfigProto`).
- Platform-specific application directory schemes (`DirectoryScheme`).

> [!NOTE]
>
> **Example**
>
> ```python
> from firebird.base.config import Config, StrOption, IntOption, load_config
> from configparser import ConfigParser
> import io
>
> class ServerConfig(Config):
>     '''Configuration for a server application.'''
>     def __init__(self):
>         super().__init__('server') # Section name in config file
>         self.host = StrOption('host', 'Server hostname or IP address', default='localhost')
>         self.port = IntOption('port', 'Server port number', required=True, default=8080)
>
> # Instantiate
> my_config = ServerConfig()
>
> # Load from a string (simulating a file)
> config_string = '''
> [server]
> host = 192.168.1.100
> port = 9000
> '''
> parser = ConfigParser()
> parser.read_string(config_string)
> my_config.load_config(parser)
>
> # Access values
> print(f"Host: {my_config.host.value}") # Output: Host: 192.168.1.100
> print(f"Port: {my_config.port.value}") # Output: Port: 9000
>
> # Get config file representation
> print(my_config.get_config())
> ```

### 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, pathlib.Path, MIME, ZMQAddress, list, dataclasses.dataclass, PyExpr, PyCode and PyCallable. It also provides special options ConfigOption and ConfigListOption.

Use `ConfigOption` for one nested `Config` object whose section name is stored in an option. Use `ConfigListOption` for a list of nested `Config` objects: its option value contains their section names, separated by commas or by lines. When loading an INI file, `Config` loads the options from those referenced sections as well.

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.

```python
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 = IntOption('opt_int', "Sample int option")
        self.enum_list: ListOption = ListOption('enum_list', SampleEnum, "List of enum values")
        # 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.

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

```ini
>>> print(app_config.get_config())

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

; Sample string option
; Type: str
;opt_str = <UNDEFINED>

; Sample int option
; Type: int
;opt_int = <UNDEFINED>

; List of enum values
; Type: list [SampleEnum]
;enum_list = <UNDEFINED>

[master-db]
;
; Simple database config

; REQUIRED option.
; Database connection string
; Type: str
;database = <UNDEFINED>

; REQUIRED option.
; User name
; Type: str
;user = SYSDBA

; User password
; Type: str
;password = <UNDEFINED>

[backup-db]
;
; Simple database config

; REQUIRED option.
; Database connection string
; Type: str
;database = <UNDEFINED>

; REQUIRED option.
; User name
; Type: str
;user = SYSDBA

; User password
; Type: str
;password = <UNDEFINED>
```

To read the configuration from file, use the configparser.ConfigParser and pass it to Config.load\_config() method.

Example configuration file:

```ini
; 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
```

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

```python
>>> 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 `/proto/config.proto`.

```proto
syntax = "proto3";

package firebird.base;

import "google/protobuf/any.proto";
import "google/protobuf/struct.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 firebird.base.protobuf registry.
>
> ```python
> # 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.
>
> ```python
> 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 `Config.save_proto()` and `Config.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.
>
> See Also: ConfigOption, ConfigListOption

## Constants

## `firebird.base.config.PROTO_CONFIG`

> [!TIP]
>
> To address `ConfigProto` in functions like `firebird.base.protobuf.create_message()`, use `PROTO_CONFIG` constant.

## Application Directory Scheme

## `firebird.base.config.DirectoryScheme`

Class that provide paths to typically used application directories.

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

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

> [!NOTE]
>
> All paths are set when the instance is created and can be changed later.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Appplication name. | *required* |
| `version` | `str \| None` | Application version. | `None` |
| `force_home` | `bool` | When True, general directories (i.e. all except user-specific and TMP) would be always based on HOME directory. | `False` |

> [!NOTE]
>
> **Example**
>
> ```python
> scheme = get_directory_scheme("MyApp", "1.0")
> config_path = scheme.config / "settings.ini"
> log_file = scheme.logs / "app.log"
> user_cache_dir = scheme.user_cache
> print(f"Config dir: {scheme.config}")
> print(f"User cache: {user_cache_dir}")
> ```

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

### `config: Path`

Directory for host-specific system-wide configuration files.

### `data: Path`

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

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

### `logs: Path`

Directory for log files.

### `run_data: Path`

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

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

### `tmp: Path`

Directory for temporary files to be preserved between reboots.

### `user_cache: Path`

Directory for user-specific application cache data.

### `user_config: Path`

Directory for user-specific configuration.

### `user_data: Path`

Directory for User local data.

### `user_sync: Path`

Directory for user data synced accross systems (roaming).

### `has_home_env() -> bool`

Returns True if HOME directory is set by "\_HOME" environment variable.

## `firebird.base.config.WindowsDirectoryScheme`

Bases: `DirectoryScheme`

Directory scheme conforming to Windows standards (e.g., `APPDATA`, `PROGRAMDATA`).

If HOME is defined using "\_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 | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Appplication name. | *required* |
| `version` | `str \| None` | Application version. | `None` |
| `force_home` | `bool` | When True, general directories (i.e. all except user-specific and TMP) would be always based on HOME directory. | `False` |

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

### `config: Path`

Directory for host-specific system-wide configuration files.

### `data: Path`

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

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

### `logs: Path`

Directory for log files.

### `run_data: Path`

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

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

### `tmp: Path`

Directory for temporary files to be preserved between reboots.

### `user_cache: Path`

Directory for user-specific application cache data.

### `user_config: Path`

Directory for user-specific configuration.

### `user_data: Path`

Directory for User local data.

### `user_sync: Path`

Directory for user data synced accross systems (roaming).

### `has_home_env() -> bool`

Returns True if HOME directory is set by "\_HOME" environment variable.

## `firebird.base.config.LinuxDirectoryScheme`

Bases: `DirectoryScheme`

Directory scheme that conforms to Linux standards.

If HOME is defined using "\_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 | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Appplication name. | *required* |
| `version` | `str \| None` | Application version. | `None` |
| `force_home` | `bool` | When True, general directories (i.e. all except user-specific and TMP) would be always based on HOME directory. | `False` |

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

### `config: Path`

Directory for host-specific system-wide configuration files.

### `data: Path`

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

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

### `logs: Path`

Directory for log files.

### `run_data: Path`

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

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

### `tmp: Path`

Directory for temporary files to be preserved between reboots.

### `user_cache: Path`

Directory for user-specific application cache data.

### `user_config: Path`

Directory for user-specific configuration.

### `user_data: Path`

Directory for User local data.

### `user_sync: Path`

Directory for user data synced accross systems (roaming).

### `has_home_env() -> bool`

Returns True if HOME directory is set by "\_HOME" environment variable.

## `firebird.base.config.MacOSDirectoryScheme`

Bases: `DirectoryScheme`

Directory scheme that conforms to MacOS standards.

If HOME is defined using "\_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 | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Appplication name. | *required* |
| `version` | `str \| None` | Application version. | `None` |

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

### `config: Path`

Directory for host-specific system-wide configuration files.

### `data: Path`

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

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

### `logs: Path`

Directory for log files.

### `run_data: Path`

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

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

### `tmp: Path`

Directory for temporary files to be preserved between reboots.

### `user_cache: Path`

Directory for user-specific application cache data.

### `user_config: Path`

Directory for user-specific configuration.

### `user_data: Path`

Directory for User local data.

### `user_sync: Path`

Directory for user data synced accross systems (roaming).

### `has_home_env() -> bool`

Returns True if HOME directory is set by "\_HOME" environment variable.

## `firebird.base.config.get_directory_scheme(app_name: str, version: str | None = None, *, force_home: bool = False) -> DirectoryScheme`

Returns directory scheme for current platform.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `app_name` | `str` | Application name | *required* |
| `version` | `str \| None` | Application version string | `None` |
| `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 "\_HOME" environment variable. | `False` |

## Configparser interpolation

## `firebird.base.config.EnvExtendedInterpolation`

Bases: `ExtendedInterpolation`

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.

> [!NOTE]
>
> **Example**
>
> ```text
> ${env:path} is reference to PATH environment variable.
> ```

## Config

## `firebird.base.config.Config`

Collection of configuration options, potentially nested.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Name associated with Config (default section name). | *required* |
| `optional` | `bool` | Whether config is optional (True) or mandatory (False) for configuration file (see `load_config()` for details). | `False` |
| `description` | `str \| None` | Optional configuration description. Can span multiple lines. | `None` |

> [!IMPORTANT]
>
> Descendants must define individual options and sub configs as instance attributes.
>
> Attributes defined as instances of `Option` subclasses represent individual configuration settings. Attributes defined as instances of `Config` subclasses represent nested configuration sections with fixed names. Attributes defined as `ConfigOption` or `ConfigListOption` allow for referring to nested sections whose names (section headers) are themselves configurable.

### `configs: list[Config]`

List of nested `Config` instances associated with this instance.

Includes:

- `Config` instances directly assigned as attributes.
- The `Config` instance held by any `ConfigOption` attribute.
- All `Config` instances within the list held by any `ConfigListOption` attribute.

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

### `options: list[Option]`

List of `Option` instances directly defined as attributes of this `Config` instance.

### `clear(*, to_default: bool = True) -> None`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option values to defaults, else to None. | `True` |

### `get_config(*, plain: bool = False) -> str`

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

> [!IMPORTANT]
>
> When config is optional and the name is an empty string, it returns empty string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option values. When False, it includes also option descriptions and other helpful information. | `False` |

### `get_description() -> str`

Configuration description. Can span multiple lines.

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

### `load_config(config: ConfigParser, section: str | None = None) -> None`

Update configuration values from a `ConfigParser` instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | `ConfigParser` instance containing configuration values. | *required* |
| `section` | `str \| None` | Name of the `ConfigParser` section corresponding to this `Config` instance. If `None`, uses `self.name`. | `None` |

**Behavior**

- Reads values for directly owned `Option` instances from the specified `section`.
- Recursively calls `load_config` on directly owned `Config` instances using their respective `name` attribute as the section name.
- Recursively calls `load_config` on `Config` instances referenced by owned `ConfigOption` and `ConfigListOption` values, using the section names stored within those options.

Raises:

| Type | Description |
| --- | --- |
| `Error` | If `section` does not exist in `config` and `self.optional` is `False` (unless `section` is `DEFAULTSECT`). Also wraps underlying ValueError or KeyError from option parsing. |
| `KeyError` | Propagated if an invalid section name is used for a nested config. |
| `ValueError` | Propagated if an option string cannot be parsed correctly. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains option values and sub-configs. | *required* |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option values and sub-configs should be stored. | *required* |

### `validate() -> None`

Recursively validates all directly owned options and sub-configs.

**Checks whether**

- all required options have a non-`None` value.
- required `ConfigOption` values have a non-empty section name.
- required `ConfigListOption` values have a non-empty list.
- all options are defined as instance attributes with the same name as `option.name`.
- calls `validate()` on all nested `Config` instances (direct attributes, values of `ConfigOption`, and items in `ConfigListOption`).

Raises:

| Type | Description |
| --- | --- |
| `Error` | When any validation constraint is violated. |

## Options

## `firebird.base.config.Option`

Bases: `Generic[T]`, `ABC`

Generic abstract base class for configuration options.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `datatype` | `type[T]` | Option datatype. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `T \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> T | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contain this option's value under `proto.options[self.name]`. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | If the protobuf field type is incompatible with the option. |
| `ValueError` | If the deserialized value content is invalid for the option. |

### `save_proto(proto: ConfigProto) -> None`

Serialize the current value into `ConfigProto` message.

The value is stored in `proto.options[self.name]` using an appropriate protobuf field type (e.g., `as_string`, `as_sint64`). If the current value is `None`, nothing is saved for this option.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where the option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: T | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `T \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is not of the expected `datatype`. |
| `ValueError` | When the `value` content is invalid for the specific option type (e.g., disallowed enum member, negative for unsigned int). |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.StrOption`

Bases: `Option[str]`

Configuration option with string value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `str \| None` | Default option value. | `None` |

> [!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 `|`.

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> str | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: str | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.IntOption`

Bases: `Option[int]`

Configuration option with integer value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `int \| None` | Default option value. | `None` |
| `signed` | `bool` | When False, the option value cannot be negative. | `False` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> int | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: int | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `int \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.FloatOption`

Bases: `Option[float]`

Configuration option with float value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `float \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> float | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: float | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `float \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.DecimalOption`

Bases: `Option[Decimal]`

Configuration option with decimal.Decimal value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `Decimal \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> Decimal | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto)`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto)`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: Decimal | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `Decimal \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.BoolOption`

Bases: `Option[bool]`

Configuration option with boolean value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `bool \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> bool | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: bool | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `bool \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.ZMQAddressOption`

Bases: `Option[ZMQAddress]`

Configuration option with firebird.base.types.ZMQAddress value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `ZMQAddress` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> ZMQAddress | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: ZMQAddress | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `ZMQAddress \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.EnumOption`

Bases: `Option[E]`, `Generic[E]`

Configuration option with enum value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `E \| None` | Default option value. | `None` |
| `allowed` | `list \| None` | List of allowed Enum members. When not defined, all members of enum type are allowed. | `None` |

### `allowed: Sequence[E]`

List of allowed enum values.

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> E | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: E | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `E \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.FlagOption`

Bases: `Option[F]`, `Generic[F]`

Configuration option with flag value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `F \| None` | Default option value. | `None` |
| `allowed` | `list \| None` | List of allowed Flag members. When not defined, all members of flag type are allowed. | `None` |

### `allowed: Sequence[F]`

List of allowed flag values.

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> F | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: F | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `F \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.UUIDOption`

Bases: `Option[UUID]`

Configuration option with uuid.UUID value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `UUID \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> UUID | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: UUID | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `UUID \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.MIMEOption`

Bases: `Option[MIME]`

Configuration option with firebird.base.types.MIME type specification value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `MIME` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> MIME | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: MIME | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `MIME \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.ListOption`

Bases: `Option[list]`

Configuration option with list of values.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `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`. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `list \| None` | Default option value. | `None` |
| `separator` | `str \| None` | 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. | `None` |

> [!IMPORTANT]
>
> When option is read from `ConfigParser`, empty values are ignored.

### `datatype: type[T]`

Option datatype.

### `default: T`

Default option value.

### `description: str`

Option description. Can span multiple lines.

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

### `name: str`

Option name.

### `required: bool`

True if option must have a value.

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

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> list | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: list | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `list \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.DataclassOption`

Bases: `Option[Any]`

Configuration option holding an instance of a Python dataclass.

Parses configuration from a string representation where each field of the dataclass is defined on its own line or separated by a defined `separator`. The format for each field within the string is `field_name: value_as_str`.

Relies on the firebird.base.strconv module to convert the `value_as_str` part for each field into the appropriate Python type based on the dataclass's type hints or the explicitly provided `fields` mapping.

> [!IMPORTANT]
>
> - Ensure type hints in the dataclass are concrete types (or provide the `fields` mapping) and that `strconv` has registered convertors for all field types used.
> - When read from `ConfigParser`, empty field definitions in the value string might be ignored or cause errors depending on parsing.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `dataclass` | `type` | The dataclass type this option holds an instance of. | *required* |
| `description` | `str` | Option description. | *required* |
| `required` | `bool` | If True, the option must have a value (cannot be None). | `False` |
| `default` | `Any \| None` | Default instance of the dataclass. | `None` |
| `separator` | `str \| None` | String separating `field:value` pairs in the config file string. Handles line breaks automatically if `None`. See class docs. | `None` |
| `fields` | `dict[str, type] \| None` | Optional override mapping field names to types. Useful if type hints are complex or need overriding. If None, uses `get_type_hints`. | `None` |

> [!NOTE]
>
> **Example**
>
> ```python
> from dataclasses import dataclass, field
> from firebird.base.config import Config, DataclassOption
> from firebird.base.strconv import register_convertor # If custom types needed
> from configparser import ConfigParser
> import io
>
> @dataclass
> class DBInfo:
>     host: str
>     user: str
>     port: int = 5432 # Field with default
>     ssl_mode: bool = field(default=False)
>
> class AppSettings(Config):
>     def __init__(self):
>         super().__init__('app')
>         self.database = DataclassOption('database', DBInfo,
>                                        'Database connection details')
> ```
>
> ```ini
> # --- Configuration File Content ---
> config_data = '''
> [app]
> database =
>     host: db.example.com
>     user: app_user
>     port: 15432
> '''
> # Note: ssl_mode uses its default (False) as it's not specified.
> ```
>
> ```python
> # --- Loading ---
> app_config = AppSettings()
> parser = ConfigParser()
> parser.read_string(config_data)
> app_config.load_config(parser)
>
> # --- Accessing ---
> db_info = app_config.database.value
> print(f"Is DBInfo instance: {isinstance(db_info, DBInfo)}") # Output: True
> print(f"DB Host: {db_info.host}")       # Output: db.example.com
> print(f"DB Port: {db_info.port}")       # Output: 15432 (overrode default)
> print(f"DB User: {db_info.user}")       # Output: app_user
> print(f"DB SSL: {db_info.ssl_mode}")    # Output: False (used default)
>
> # --- Getting Config String ---
> # print(app_config.get_config()) would regenerate the structure
> ```

### `dataclass: type`

Dataclass type.

### `datatype: type[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.

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

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns the string representation of the current dataclass value.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> Any`

Returns the current dataclass instance (or None).

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize dataclass from `proto.options[self.name].as_string`.

### `save_proto(proto: ConfigProto) -> None`

Serialize dataclass into `proto.options[self.name].as_string`.

### `set_as_str(value: str) -> None`

Creates and sets the dataclass instance from its string representation.

Parses the `value` string expecting `field_name: value_as_str` items, separated according to the `separator` logic. Uses `strconv` to convert each `value_as_str` to the required field type. Finally, instantiates the dataclass using the parsed field values.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | String containing the dataclass representation. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | If the string format is invalid, a field name is unknown, a value cannot be converted by `strconv`, or the resulting dictionary of values cannot instantiate the dataclass (e.g., missing required fields without defaults). |
| `TypeError` | If `strconv` conversion fails with a type error. |

### `set_value(value: Any) -> None`

Sets the option value to the provided dataclass instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `Any` | An instance of the option's `dataclass` type, or `None`. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | If `value` is not None and not an instance of the expected `dataclass`. |
| `ValueError` | If `value` is None and the option is required. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.PathOption`

Bases: `Option[str]`

Configuration option with pathlib.Path value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `Path \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> Path | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: Path | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `Path \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.PyExprOption`

Bases: `Option[PyExpr]`

String configuration option with Python expression value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `PyExpr \| None` | Default option value. | `None` |

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> PyExpr | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: PyExpr | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `PyExpr \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.PyCodeOption`

Bases: `Option[PyCode]`

String configuration option with Python code value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `PyCode \| None` | Default option value. | `None` |

> [!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 `|`.

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> PyCode | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: PyCode | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `PyCode \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.PyCallableOption`

Bases: `Option[PyCallable]`

String configuration option with Python callable value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `signature` | `Signature \| Callable \| str` | Callable signature, callable or string with callable signature (function header). | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `PyCallable \| None` | Default option value. | `None` |

> [!IMPORTANT]
>
> Python code must be properly indented, but `ConfigParser` multiline string values have leading whitespace removed. To circumvent this, the `PyCallableOption` 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 `|`.

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the option value to default value, else to None. | `True` |

### `get_as_str() -> str`

Returns value as string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns value formatted for use in config file.

### `get_value() -> PyCallable | None`

Returns current option value.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize value from `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message that may contains options value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the argument is not a valid option value. |

### `save_proto(proto: ConfigProto) -> None`

Serialize value into `ConfigProto` message.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `proto` | `ConfigProto` | Protobuf message where option value should be stored. | *required* |

### `set_as_str(value: str) -> None`

Set new option value from string.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When the argument is not a valid option value. |

### `set_value(value: PyCallable | None) -> None`

Set new option value.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `PyCallable \| None` | New option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | When the new value is of the wrong type. |
| `ValueError` | When the callable has wrong signature. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.ConfigOption`

Bases: `Option[str]`

Option whose 'value' is a Config instance, but stores/parses its section name.

This allows having nested configuration sections where the section *name* itself is configurable. The actual `Config` object must be passed during initialization. The `value` property returns this `Config` object, while methods like `set_as_str`, `get_as_str`, `get_formatted`, `load_proto`, `save_proto` operate on the `Config` object's **name** (the section name).

Loading/saving the *contents* of the referenced `Config` object is handled by the parent `Config`'s `load_config`/`save_proto` methods.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `config` | `Config` | Option's value. | *required* |
| `required` | `bool` | True if option must have a value. | `False` |
| `default` | `str \| None` | Default `Config.name` value. | `None` |

> [!IMPORTANT]
>
> Assigning directly to the `value` property is not supported like other options; use `set_as_str` or assign to the `Config` object's `.name` attribute indirectly if needed (though typically done via `load_config`).

> [!NOTE]
>
> The "empty" value for this option is not `None` (because the `Config` instance always exists), but an empty string for `Config.name` attribute.

### `datatype: type[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.

### `clear(*, to_default: bool = True) -> None`

Clears the option value.

> [!NOTE]
>
> This method calls `Config.clear(to_default)`.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | If True, sets the `Config.name` to default value, else to empty string. | `True` |

### `get_as_str() -> str`

Returns the current section name of the associated `Config` instance.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Return value formatted for use in config file.

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

### `get_value() -> Config`

Returns the associated `Config` instance itself.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize section name from `proto.options[self.name].as_string`.

### `save_proto(proto: ConfigProto) -> None`

Serialize section name into `proto.options[self.name].as_string`.

### `set_as_str(value: str) -> None`

Sets the section name for the associated `Config` instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | The new section name (string). | *required* |

### `set_value(value: str | None) -> None`

Sets the section name (indirectly). **Does not accept a Config object.**

This method primarily handles setting the default section name during init. Setting the name post-init is typically done via `load_config` or `set_as_str`. Passing `None` sets the name to empty string (if not required).

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str \| None` | The new section name (string) or None. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | If `value` is None or empty string and the option is required. |

### `validate() -> None`

Validates option state.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required option does not have a value. |

## `firebird.base.config.ConfigListOption`

Bases: `Option[list]`

Option holding a list of Config instances, parsing/storing their section names.

This option manages a list of `Config` objects, all of the **same** specified `item_type`. However, in configuration files (`ConfigParser`) and Protobuf messages, it stores and parses a *list of strings*, where each string is the section name corresponding to one of the `Config` instances in the list.

Loading/saving the *contents* (options) of each referenced `Config` section is handled by the parent `Config`'s `load_config`/`save_proto` methods when they iterate through the main configuration structure. This option itself only deals with the list of *names* that identify which sections belong here.

When `set_as_str` or `load_config` processes the string list of names, it creates new instances of `item_type` (the specified `Config` subclass) for each name found.

> [!IMPORTANT]
>
> When read from `ConfigParser`, empty values in the list of names are ignored.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `name` | `str` | Option name identifying where the **list of section names** is stored. | *required* |
| `item_type` | `type[Config]` | The specific `Config` subclass for items in the list. All items will be instances of this type. | *required* |
| `description` | `str` | Option description. Can span multiple lines. | *required* |
| `required` | `bool` | If True, the list of section names cannot be empty. | `False` |
| `separator` | `str \| None` | String separating section names in the config file value. Handles line breaks automatically if `None`. See class docs. | `None` |

> [!NOTE]
>
> **Example**
>
> ```python
> from firebird.base.config import Config, StrOption, ConfigListOption
> from configparser import ConfigParser
> import io
>
> class WorkerConfig(Config):
>     '''Configuration for a worker process.'''
>     def __init__(self, name: str):
>         super().__init__(name)
>         self.task_type = StrOption('task_type', 'Type of task', default='generic')
>
> class MainAppConfig(Config):
>     '''Main application configuration.'''
>     def __init__(self):
>         super().__init__('main_app')
>         self.workers = ConfigListOption('workers', WorkerConfig,
>                                         'List of worker configurations (section names)')
> ```
>
> ```ini
> # --- Configuration File Content ---
> config_data = '''
> [main_app]
> workers = worker_alpha, worker_beta  ; List of section names
>
> [worker_alpha]
> task_type = processing
>
> [worker_beta]
> task_type = reporting
> '''
> ```
>
> ```python
> # --- Loading ---
> app_config = MainAppConfig()
> parser = ConfigParser()
> parser.read_string(config_data)
> app_config.load_config(parser) # Loads 'workers' list and worker sections
>
> # --- Accessing ---
> print(f"Worker section names: {app_config.workers.get_as_str()}")
> # Output: Worker section names: worker_alpha, worker_beta
>
> worker_list = app_config.workers.value
> print(f"Number of workers: {len(worker_list)}") # Output: 2
> print(f"First worker name: {worker_list[0].name}") # Output: worker_alpha
> print(f"First worker task: {worker_list[0].task_type.value}") # Output: processing
> print(f"Second worker task: {worker_list[1].task_type.value}") # Output: reporting
>
> # --- Getting Config String ---
> # print(app_config.get_config()) would regenerate the structure
> ```

### `datatype: type[T]`

Option datatype.

### `default: T`

Default option value.

### `description: str`

Option description. Can span multiple lines.

### `item_type: type[Config]`

Datatype of list items.

### `name: str`

Option name.

### `required: bool`

True if option must have a value.

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

### `clear(*, to_default: bool = True) -> None`

Clears the list of `Config` instances.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `to_default` | `bool` | This parameter is ignored as there's no default list content. The list is simply emptied. | `True` |

### `get_as_str() -> str`

Returns the list of contained section names as a separator-joined string.

### `get_config(*, plain: bool = False) -> str`

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

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `plain` | `bool` | When True, it outputs only the option value. When False, it includes also option description and other helpful information. | `False` |

### `get_formatted() -> str`

Returns the list of section names formatted for use in a config file.

### `get_value() -> list`

Returns the current list of `Config` instances.

### `has_value() -> bool`

Returns True if option value is not None.

### `load_config(config: ConfigParser, section: str) -> None`

Update option value from configparser.ConfigParser instance.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `config` | `ConfigParser` | ConfigParser instance. | *required* |
| `section` | `str` | Name of ConfigParser section that should be used to get new option value. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | When option value cannot be loadded. |
| `KeyError` | If section does not exists, and it's not `configparser.DEFAULTSECT`. |

### `load_proto(proto: ConfigProto) -> None`

Deserialize list of section names from `proto.options[self.name].as_string`.

### `save_proto(proto: ConfigProto) -> None`

Serialize list of section names into `proto.options[self.name].as_string`.

### `set_as_str(value: str) -> None`

Populates the list with new `Config` instances based on section names in string.

Parses the input string `value` (using the defined `separator` logic) to get a list of section names. For each non-empty name, creates a new instance of `self.item_type` with that name and adds it to the internal list, replacing any previous list content.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `str` | String containing separator-defined list of section names. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `ValueError` | If the string parsing encounters issues (though typically just results in fewer items if format is odd). |

### `set_value(value: list | None) -> None`

Sets the list of `Config` instances.

Replaces the current list with the provided one. Ensures all items in the new list are of the correct `item_type`. Passing `None` clears the list.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `value` | `list \| None` | A new list of `Config` instances (must be of `self.item_type`), or `None`. | *required* |

Raises:

| Type | Description |
| --- | --- |
| `TypeError` | If `value` is not a list or contains items of the wrong type. |
| `ValueError` | If `value` is None or empty and the option is required. |

### `validate() -> None`

Validates the option state.

Checks if the list is non-empty if required. Calls `validate()` on each `Config` instance currently in the list.

Raises:

| Type | Description |
| --- | --- |
| `Error` | When required and the list is empty, or if any contained `Config` instance fails its own validation. |

## Functions

## `firebird.base.config.has_verticals(value: str) -> bool`

Returns True if lines in multiline string contains leading `'|'` character. Used to detect if special vertical bar indentation was used.

## `firebird.base.config.has_leading_spaces(value: str) -> bool`

Returns True if any line in multiline string starts with space(s). Used to determine if vertical bar notation is needed for preservation.