BatConf

Configuration Management for Python projects, modules, applications, and microservices.

Compose structured hierarchical configurations from multiple sources. Enable your code to adapt seamlessly to the current context. Allow users in different contexts to use the config source that works best for them.

• Hierarchical priority: CLI > Environment > config file > module defaults
• Provides builtin support for common config sources:
  • CLI args
  • Environment Variables
  • Config File (yaml)
  • Config classes with default values
• Easily extendable, add new sources to serve your needs.
• Set reasonable defaults, and override them as needed.
• Designed for 12-factor applications (config via Environment Variables)
• ConfigSingleton: share a single Configuration instance across your application
• insert_source: dynamically add configuration sources at runtime
• Subscript access: cfg['key'] as an alternative to cfg.key, enabling dynamic lookups like cfg.clients[client_id]

Users can create their own config sources by creating classes that satisfy batconf.source.SourceInterfaceP (or subclass batconf.source.SourceInterface)

The config lookup order is determined by the SourceList instance, which can be adjusted to suit your needs.

Design Principles

• Non-Intrusive Integration: BatConf can be seamlessly incorporated into existing projects with minimal code modifications.
  • imports from batconf can be isolated to a single source file
  • Config classes utilize stdlib dataclasses
• Portability and Modularity: Modules (sub-modules or entire projects) that use batconf configuration should be easy to compose and refactor.
  • modules can be easily plugged in to other modules.
  • modules can be easily factored out (into new projects).

How BatConf Compares

See the full comparison guide for details, access-interface ergonomics, and guidance on choosing a tool.

Professional Support

BatConf participates in the Tidelift open source sustainability program. Organizations can support the ongoing maintenance of BatConf while receiving professional assurances through a Tidelift subscription.

Professionally supported BatConf is now available.

Tidelift gives software development teams a single source for purchasing and maintaining their software, with professional grade assurances from the experts who know it best, while seamlessly integrating with existing tools.

Get supported BatConf with the Tidelift subscription

Example Configuration

Check out our Quick Start Guide

and the example project in tests/example/ which includes tests and documentation.

Quick Example

from dataclasses import dataclass
from batconf import (
    ConfigSingleton,
    insert_source,
    Configuration,
    SourceList,
    EnvSource,
    IniSource,
    NamespaceSource,
    Namespace,
)

@dataclass
class AppConfig:
    host: str = 'localhost'
    port: str = '8080'

def get_config() -> Configuration:
    sources = SourceList([EnvSource(), IniSource('config.ini')])
    return Configuration(sources, AppConfig, path='app')

# A shared singleton — import CFG anywhere in your application
CFG = ConfigSingleton(get_config)

# Attribute access
host = CFG.host

# Subscript access — useful for dynamic keys
key = 'host'
host = CFG[key]

# Add a source at runtime (e.g. after CLI args are parsed)
args = Namespace()
setattr(args, 'app.host', 'example.com')
insert_source(cfg=CFG, source=NamespaceSource(args))

Install Instructions

Install the core package:

pip install .

Install with Yaml support:

pip install .[yaml]

Install with Toml support, for python<=3.10:

pip install .[toml]

Adding BatConf to your project requirements

[project]
dependencies = [
    'batconf',
]

Including optional extras, like Yaml:

[project]
dependencies = [
    'batconf[yaml]',
]

Migrating to v0.4.0

Breaking Changes

• batconf.sources.file.FileConfig has been removed. See the migration guide for details.

Architecture Decision Records

Significant design decisions are documented in docs/decisions/. Start with the foundational ADRs to understand the core philosophy, then read the per-feature groups for decisions made during specific refactors.

Dev Guide

Install dev dependencies (pytest, mypy, etc)

pip install --group=dev -e .

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.