Migration Guide

v0.4.0

FileConfig Removed

batconf.sources.file.FileConfig has been removed. Replace it with IniSource or YamlSource as appropriate.

New Public API

The following names are now importable directly from batconf:

Configuration
SourceList
ConfigSingleton
insert_source()
NamespaceSource, Namespace
EnvSource
IniSource
TomlSource
YamlSource (requires batconf[yaml])

Old submodule imports still work but the top-level names are now preferred:

# old
from batconf.sources.argparse import NamespaceConfig, Namespace
from batconf.sources.env import EnvConfig
from batconf.sources.ini import IniConfig

# new
from batconf import NamespaceSource, Namespace, EnvSource, IniSource

ConfigSingleton

A new ConfigSingleton class provides a shared, lazily-initialised configuration instance that can be imported anywhere in your application. See the get_config function section of the quickstart for usage.

insert_source

insert_source() allows a configuration source to be added to a running Configuration or ConfigSingleton at runtime. This is the recommended pattern for injecting CLI args after argument parsing.

Subscript Access

Configuration now supports subscript notation, so cfg['key'] is equivalent to cfg.key. This enables dynamic lookups such as cfg.clients[client_id].

v0.2.0

Yaml Optional Extra

pyyaml is no longer a default dependency of BatConf. It is now available as an optional extra.

If you wish to keep using Yaml format for your configuration, you should update your dependencies in your pyproject.toml

old pyproject.toml

dependencies = [
    "batconf[yaml]>=0.2",
]

Projects which require yaml for BatConf and for project code should make both dependencies explicit:

pyproject.toml

dependencies = [
    "batconf[yaml]>=0.2",
    "pyyaml=*",
]

TOML Optional Extra for Python<3.11

Python provides stdlib support for Toml in version 3.11+ (via tomllib). BatConf provides an optional extra [toml] for Python 3.10 and earlier.

pyproject.toml

dependencies = [
    "batconf[toml]>=0.2",
]

If your project needs to support multiple versions of python, both <= 3.10 and >= 3.11, you can do so, only including the toml dependency when required, like so:

pyproject.toml

dependencies = [
    "batconf=*",
    "batconf[toml]>=0.2; python_version <= '3.10'",
]

FreeForm Configuration Schemas

Previous versions of BatConf inferred the structure of the configuration schema from the structure of your module’s namespace. That behavior is deprecated, but it still works for now.

Going forward, we recommend defining your Configuration Schema in conf.py or in its own module.

conf.py example Schema

# Import MyClient, which provides a 'Config' dataclass.
# Import a configuration schema from a submodule in your project.
from .submodule import MyClient, SubmoduleConfigSchema


@dataclass
class ClientConfigurationsSchema:
    """
    .. versionchanged:: 0.2
       Added support for multiple configurations from single Schema.
    """
    clientA: MyClient.Config
    clientB: MyClient.Config
    doc: str = "Configurations for multiple clients"


@dataclass
class ProjectConfigSchema:
    # Configuration subsection for a specific submodule
    submodule: SubmoduleConfigSchema
    clients: ClientConfigurationsSchema
    # Schemas can be reused
    moreclients: ClientConfigurationsSchema
    doc: str = "Root Configuration Schema for your project"

This approach gives us much more flexibility to organize our configurations to suit our projects.