batconf package

Subpackages

Submodules

batconf.lib module

class batconf.lib.ConfigSingleton(get_config_fn)

Bases: object

Lazy singleton proxy for a Configuration instance.

Wraps a get_config_fn factory and creates the underlying Configuration on first attribute access, then caches it for subsequent accesses. Importing the same ConfigSingleton instance in multiple modules shares a single configuration object across the application.

Parameters

get_config_fnCallable[[], Configuration]

Callable that returns a Configuration instance. Use functools.partial() to pre-fill any arguments.

Examples

>>> CFG = ConfigSingleton(get_config_fn=get_config)
>>> CFG.some_option
'value'

Using a partially applied config factory:

>>> from functools import partial
>>> CFG = ConfigSingleton(
...     get_config_fn=partial(get_config, config_env='prod')
... )
type get_config_fn:

Callable

param get_config_fn:

batconf.lib.insert_source(cfg, source, index=0)

Insert a configuration source into the configuration’s source list.

Configuration sources are queried in order, with lower indices taking precedence. By default, new sources are inserted at index 0 (highest priority).

Return type:

None

Parameters

cfgConfiguration or ConfigSingleton

Configuration object or singleton to modify.

sourceSourceInterfaceP

Configuration source to insert (e.g., CLI args, environment variables, config file).

indexint, default=0

Position to insert the source at (0 = highest priority).

Examples

Insert CLI arguments as the highest priority source:

>>> from batconf import NamespaceSource
>>> from argparse import Namespace
>>> args = Namespace()
>>> setattr(args, 'project.key', 'value')
>>> insert_source(cfg=CFG, source=NamespaceSource(namespace=args))

Insert a lower priority source:

>>> insert_source(cfg=CFG, source=env_source, index=2)

See Also

Configuration : Main configuration manager class. SourceList : Container that manages configuration sources. ConfigSingleton : Singleton proxy for global configuration.

type cfg:

_HasConfigSources

param cfg:

type source:

SourceInterfaceP

param source:

type index:

int

param index:

batconf.manager module

class batconf.manager.Configuration(source_list, config_class, path=None)

Bases: object

Resolves configuration values from an ordered SourceList.

Values are looked up by walking the config_class dataclass schema to determine the dotted path, then querying each source in the SourceList in priority order until a value is found.

Configuration hierarchy (highest to lowest priority):

  1. Command-line arguments — passed in via a NamespaceSource

  2. Environment variables — via EnvSource

  3. Config file — via IniSource, TomlSource, etc.

  4. Dataclass defaults — values declared on the config schema

Parameters

source_listSourceListP

Ordered collection of configuration sources to query.

config_classConfigP

Dataclass whose fields define the configuration schema.

pathstr or None, default=None

Dotted namespace path for this configuration node. Defaults to the module of config_class when not provided.

Examples

>>> cfg = Configuration(
...     source_list=SourceList(sources=[EnvSource(), IniSource(file_path='config.ini')]),
...     config_class=AppConfigSchema,
... )
>>> cfg.database.host
'localhost'
type source_list:

SourceListP

param source_list:

type config_class:

ConfigP | Any

param config_class:

type path:

str | None

param path:

batconf.source module

class batconf.source.SourceInterface(*args, **kwargs)

Bases: SourceInterfaceP

abstractmethod get(key, path=None)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

class batconf.source.SourceList(sources)

Bases: object

An ordered list of configuration sources.

Sources are queried in order; the first non-None value returned wins. None entries in the constructor sequence are silently filtered out, making it easy to conditionally include sources.

Parameters

sourcesSequence[SourceInterfaceP | None]

Ordered sequence of configuration sources. Earlier entries take precedence over later ones.

Examples

>>> source_list = SourceList(sources=[NamespaceSource(args), EnvSource(), IniSource(file_path='config.ini')])
type sources:

Sequence[SourceInterfaceP | None]

param sources:

get(key, path=None)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

insert_source(source, index=0)
Parameters:
Return type:

None

batconf.types module

Protocol types and type aliases for use in type annotations.

Import from here when you need to annotate parameters that accept batconf objects, rather than importing implementation classes directly.

Examples

>>> from batconf.types import ConfigP, SourceInterfaceP
>>> def get_config(config_class: ConfigP, source: SourceInterfaceP) -> Configuration:
...     ...
class batconf.types.ConfigP(*args, **kwargs)

Bases: Protocol

class batconf.types.FieldP(*args, **kwargs)

Bases: Protocol

default: str
name: str
type: ConfigP | Type[str]
class batconf.types.FileSourceP(file_path, file_format='environments', config_env=None, missing_file_option='warn')

Bases: SourceInterfaceP, Protocol

Protocol for file-backed configuration sources.

Defines the standard constructor and query interface that all file-based configuration sources must satisfy.

Parameters

file_pathstr

Path to the configuration file.

file_format{‘environments’, ‘sections’, ‘flat’}, default=’environments’

File layout. 'environments' reads a per-environment subtree selected by config_env; 'sections' uses top-level sections as namespaces; 'flat' reads from a single top-level mapping.

config_envstr or None, default=None

Active configuration environment. When None, the default defined inside the file is used.

missing_file_option{‘warn’, ‘ignore’, ‘error’}, default=’warn’

Behaviour when the specified file does not exist.

type file_path:

str

param file_path:

type file_format:

Literal['flat', 'sections', 'environments']

param file_format:

type config_env:

str | None

param config_env:

type missing_file_option:

Literal['ignore', 'warn', 'error']

param missing_file_option:

class batconf.types.SourceInterfaceP(*args, **kwargs)

Bases: Protocol

get(key, path)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

class batconf.types.SourceListP(*args, **kwargs)

Bases: SourceInterfaceP, Protocol

insert_source(source, index=0)
Parameters:
Return type:

None

Module contents

batconf — layered configuration for Python applications.

Public API

Configuration

The main configuration manager. Resolves values from an ordered SourceList against a dataclass-based config schema.

ConfigSingleton

Lazy, singleton-style proxy around a Configuration instance, suitable for use as a module-level global.

SourceList

Ordered collection of configuration sources.

insert_source

Helper to insert a new source into an existing configuration at runtime.

Sources

NamespaceSource

Reads from an argparse.Namespace object using fully-qualified dotted key paths (e.g. project.host).

EnvSource

Reads from environment variables.

IniSource

Reads from INI files.

TomlSource

Reads from TOML files.

YamlSource

Reads from YAML files.

Type annotations

See batconf.types for Protocol types used in type hints.

class batconf.ConfigSingleton(get_config_fn)

Bases: object

Lazy singleton proxy for a Configuration instance.

Wraps a get_config_fn factory and creates the underlying Configuration on first attribute access, then caches it for subsequent accesses. Importing the same ConfigSingleton instance in multiple modules shares a single configuration object across the application.

Parameters

get_config_fnCallable[[], Configuration]

Callable that returns a Configuration instance. Use functools.partial() to pre-fill any arguments.

Examples

>>> CFG = ConfigSingleton(get_config_fn=get_config)
>>> CFG.some_option
'value'

Using a partially applied config factory:

>>> from functools import partial
>>> CFG = ConfigSingleton(
...     get_config_fn=partial(get_config, config_env='prod')
... )
type get_config_fn:

Callable

param get_config_fn:

class batconf.Configuration(source_list, config_class, path=None)

Bases: object

Resolves configuration values from an ordered SourceList.

Values are looked up by walking the config_class dataclass schema to determine the dotted path, then querying each source in the SourceList in priority order until a value is found.

Configuration hierarchy (highest to lowest priority):

  1. Command-line arguments — passed in via a NamespaceSource

  2. Environment variables — via EnvSource

  3. Config file — via IniSource, TomlSource, etc.

  4. Dataclass defaults — values declared on the config schema

Parameters

source_listSourceListP

Ordered collection of configuration sources to query.

config_classConfigP

Dataclass whose fields define the configuration schema.

pathstr or None, default=None

Dotted namespace path for this configuration node. Defaults to the module of config_class when not provided.

Examples

>>> cfg = Configuration(
...     source_list=SourceList(sources=[EnvSource(), IniSource(file_path='config.ini')]),
...     config_class=AppConfigSchema,
... )
>>> cfg.database.host
'localhost'
type source_list:

SourceListP

param source_list:

type config_class:

ConfigP | Any

param config_class:

type path:

str | None

param path:

batconf.EnvSource

alias of EnvConfig

class batconf.IniSource(file_path, file_format='environments', config_env=None, missing_file_option='warn')

Bases: FileSourceP

Configuration source backed by an INI file.

Parameters

file_pathstr

Path to the INI configuration file.

file_format{‘environments’, ‘sections’, ‘flat’}, default=’environments’

INI file layout. 'environments' expects top-level sections named after environments; 'sections' uses sections as config namespaces; 'flat' reads all keys from a single [root] section.

config_envstr or None, default=read from file

Active configuration environment. When not provided, the value of batconf.default_env in the INI file is used.

missing_file_option{‘warn’, ‘ignore’, ‘error’}, default=’warn’

Behaviour when the specified file is missing.

Examples

>>> src = IniSource(file_path='config.ini', config_env='dev')
type file_path:

str

param file_path:

type file_format:

Literal['flat', 'sections', 'environments']

param file_format:

type config_env:

str | None

param config_env:

type missing_file_option:

Literal['ignore', 'warn', 'error']

param missing_file_option:

get(key, path=None)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

class batconf.Namespace(**kwargs)

Bases: _AttributeHolder

Simple object for storing attributes.

Implements equality by attribute names and values, and provides a simple string representation.

batconf.NamespaceSource

alias of NamespaceConfig

class batconf.SourceList(sources)

Bases: object

An ordered list of configuration sources.

Sources are queried in order; the first non-None value returned wins. None entries in the constructor sequence are silently filtered out, making it easy to conditionally include sources.

Parameters

sourcesSequence[SourceInterfaceP | None]

Ordered sequence of configuration sources. Earlier entries take precedence over later ones.

Examples

>>> source_list = SourceList(sources=[NamespaceSource(args), EnvSource(), IniSource(file_path='config.ini')])
type sources:

Sequence[SourceInterfaceP | None]

param sources:

get(key, path=None)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

insert_source(source, index=0)
Parameters:
Return type:

None

class batconf.TomlSource(file_path, file_format='environments', config_env=None, missing_file_option='warn')

Bases: FileSourceP

Configuration source backed by a TOML file.

Parameters

file_pathstr

Path to the TOML configuration file.

file_format{‘environments’, ‘sections’, ‘flat’}, default=’environments’

TOML file layout. 'environments' expects a [batconf] table with a default_env key and per-environment top-level tables; 'sections' uses tables as config namespaces; 'flat' reads all keys from the top-level table.

config_envstr or None, default=read from file

Active configuration environment. When not provided, the value of batconf.default_env in the TOML file is used.

missing_file_option{‘warn’, ‘ignore’, ‘error’}, default=’warn’

Behaviour when the specified file is missing.

Examples

>>> src = TomlSource(file_path='config.toml', config_env='dev')
type file_path:

str

param file_path:

type file_format:

Literal['flat', 'sections', 'environments']

param file_format:

type config_env:

str | None

param config_env:

type missing_file_option:

Literal['ignore', 'warn', 'error']

param missing_file_option:

get(key, path=None)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

keys()
Return type:

list[str]

class batconf.YamlSource(file_path, file_format='environments', config_env=None, missing_file_option='warn')

Bases: FileSourceP

Configuration source backed by a YAML file.

Parameters

file_pathstr

Path to the YAML configuration file.

file_format{‘environments’, ‘sections’, ‘flat’}, default=’environments’

YAML file layout. 'environments' expects a batconf mapping with a default_env key and per-environment top-level mappings; 'sections' uses top-level keys as config namespaces; 'flat' reads all keys from the top level.

config_envstr or None, default=read from file

Active configuration environment. When not provided, the value of batconf.default_env in the YAML file is used.

missing_file_option{‘warn’, ‘ignore’, ‘error’}, default=’warn’

Behaviour when the specified file is missing.

Examples

>>> src = YamlSource(file_path='config.yaml', config_env='dev')
type file_path:

str

param file_path:

type file_format:

Literal['flat', 'sections', 'environments']

param file_format:

type config_env:

str | None

param config_env:

type missing_file_option:

Literal['ignore', 'warn', 'error']

param missing_file_option:

get(key, path=None)
Parameters:

  • key (str)

  • path (str | None)

Return type:

str | None

keys()
batconf.insert_source(cfg, source, index=0)

Insert a configuration source into the configuration’s source list.

Configuration sources are queried in order, with lower indices taking precedence. By default, new sources are inserted at index 0 (highest priority).

Return type:

None

Parameters

cfgConfiguration or ConfigSingleton

Configuration object or singleton to modify.

sourceSourceInterfaceP

Configuration source to insert (e.g., CLI args, environment variables, config file).

indexint, default=0

Position to insert the source at (0 = highest priority).

Examples

Insert CLI arguments as the highest priority source:

>>> from batconf import NamespaceSource
>>> from argparse import Namespace
>>> args = Namespace()
>>> setattr(args, 'project.key', 'value')
>>> insert_source(cfg=CFG, source=NamespaceSource(namespace=args))

Insert a lower priority source:

>>> insert_source(cfg=CFG, source=env_source, index=2)

See Also

Configuration : Main configuration manager class. SourceList : Container that manages configuration sources. ConfigSingleton : Singleton proxy for global configuration.

type cfg:

_HasConfigSources

param cfg:

type source:

SourceInterfaceP

param source:

type index:

int

param index: