base
Base class and shared machinery for Drafter configuration sections.
Defines BaseConfiguration, the dataclass all configuration sections inherit
from. It provides the generic pipeline for building a configuration from
dataclass defaults, environment variables, and parsed command line arguments,
plus helpers for merging, copying, and JSON (de)serialization.
FalseType = Literal[False]
module-attribute
Type alias for the literal value False, used in Union[FalseType, str]
annotations where a field is either disabled (False) or holds a string.
BaseConfiguration()
dataclass
Base dataclass for a section of the Drafter system configuration.
Subclasses declare their settings as dataclass fields (whose defaults form
the lowest-precedence layer) and override the hook methods get_key,
parse_env_variables, extend_parser, and parse_args. The
map_from_raw classmethod then assembles an instance by layering values
with the precedence: dataclass defaults < environment variables < parsed
command line arguments.
copy()
Creates a copy of the current configuration instance.
Returns:
| Name | Type | Description |
|---|---|---|
Self |
A new instance of the same class with the same values. |
extend_parser(parser)
staticmethod
Extend argument parser with configuration-specific arguments.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parser
|
An argparse.ArgumentParser instance to extend. |
required |
extract_from_args(potential_args)
Extract configuration values from argument dict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
potential_args
|
dict
|
Dict potentially containing configuration values. |
required |
from_json(data)
classmethod
Construct a configuration instance from a dictionary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
dict
|
Dictionary of field names to values, as produced by |
required |
Returns:
| Type | Description |
|---|---|
|
A new instance of this configuration class. |
get_key()
staticmethod
Return the key identifying this configuration section.
The key names the section in serialized SystemConfiguration
dictionaries (e.g., "bootstrap", "app_server").
Returns:
| Type | Description |
|---|---|
str
|
The unique string key for this configuration section. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
Always, in this base implementation; subclasses must override this method. |
load_from_file(file_path)
Load configuration values from a JSON file.
The file's contents are parsed and returned as-is; nothing is merged into this configuration instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_path
|
str
|
Path to the JSON configuration file. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
The parsed contents of the JSON file as a dictionary. |
map_from_raw(parsed_args, env_vars=None, existing_config=None)
classmethod
Build a configuration instance by layering raw sources in precedence order.
This is the central precedence-defining pipeline for all configuration
sections. The starting point is either a fresh instance (dataclass
defaults) or a copy of existing_config. Environment variables, if
given, are filtered through parse_env_variables and merged on top of
that base. Finally, command line arguments are filtered through
parse_args and merged last, so they win. The resulting precedence is:
defaults (or existing config) < environment variables < command line
arguments. Both merges ignore unknown keys and None values, and
existing_config itself is never mutated.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parsed_args
|
dict[str, Any]
|
Dictionary of parsed command line arguments (e.g.,
|
required |
env_vars
|
dict[str, Any] | None
|
Optional dictionary of environment variables; when omitted or empty, the environment layer is skipped. |
None
|
existing_config
|
Optional configuration instance to use (copied) as the base instead of a default-constructed one. |
None
|
Returns:
| Type | Description |
|---|---|
|
A new configuration instance with all sources merged in. |
merge_in_args(new_args, raise_errors=True)
Merge new arguments into configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
new_args
|
dict
|
Dict of argument names and values. None values are ignored. |
required |
raise_errors
|
Whether to raise on unknown attribute names; when False, unknown names are silently skipped. |
True
|
Raises:
| Type | Description |
|---|---|
AttributeError
|
If an unknown configuration attribute is provided
and |
parse_args(parsed_args)
staticmethod
Parse command line arguments relevant to this configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parsed_args
|
dict
|
A dictionary of parsed command line arguments. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
A dictionary of configuration values extracted from command line arguments. |
parse_env_variables(env_vars)
staticmethod
Parse environment variables relevant to this configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env_vars
|
dict
|
A dictionary of environment variables. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
A dictionary of configuration values extracted from environment variables. |
to_json()
Serialize this configuration to a dictionary.
Returns:
| Type | Description |
|---|---|
dict
|
A dictionary mapping each dataclass field name to its current value. |