Metadata-Version: 2.4
Name: batconf
Version: 0.4.0
Summary: Application configuration tool from the BAT project
Project-URL: documentation, https://batconf.readthedocs.io/en/latest/
Project-URL: repository, https://github.com/lundybernard/batconf/
Project-URL: issues, https://github.com/lundybernard/batconf/issues
Project-URL: changelog, https://batconf.readthedocs.io/en/latest/changelog.html
Author-email: Lundy Bernard <lundy.bernard@gmail.com>, Lauren Moore <donotreply@no.com>
License: MIT License
        
        Copyright (c) 2020 Lundy Bernard
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading
Requires-Python: >=3.10
Provides-Extra: toml
Requires-Dist: toml; (python_version <= '3.10') and extra == 'toml'
Provides-Extra: yaml
Requires-Dist: pyyaml; extra == 'yaml'
Description-Content-Type: text/markdown

![Logo](https://github.com/lundybernard/batconf/blob/main/docs/source/_static/batconf-logo.png?raw=true)

# BatConf

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

[![Stable Version](https://img.shields.io/pypi/v/batconf?color=blue)](https://pypi.org/project/batconf/)
[![Downloads](https://img.shields.io/pypi/dm/batconf)](https://pypistats.org/packages/batconf)
[![Build Status](https://github.com/lundybernard/batconf/actions/workflows/tests.yml/badge.svg)](https://github.com/lundybernard/batconf/actions)
[![Documentation Status](https://readthedocs.org/projects/batconf/badge/?version=stable)](https://batconf.readthedocs.io/en/stable/)
[![Python](https://img.shields.io/pypi/pyversions/batconf)](https://pypi.org/pypi/batconf/)
[![Tidelift](https://tidelift.com/badges/package/pypi/batconf)](https://tidelift.com/subscription/pkg/pypi-batconf)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/lundybernard/batconf/badge)](https://securityscorecards.dev/viewer/?uri=github.com/lundybernard/batconf)


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

| Tool | Layered sources | Config object access | Validation | CLI integration |
|---|---|---|---|---|
| **BatConf** | CLI / env / files / dataclass defaults | dot-path + subscript | bring your own (by design) | explicit — your app owns its argparse parser |
| pydantic-settings | env / files / secrets / CLI | typed model attributes | built-in (pydantic) | generated parser |
| environs | env vars only | none (per-value reads) | built-in (marshmallow) | none |
| python-decouple | env / `.ini` / `.env` | none (per-value reads) | `cast` callable only | none |
| Dynaconf | many formats + env profiles | dot-path + subscript | built-in validators | management CLI |
| python-dotenv | `.env` loader only | plain dict | none | none |
| Hydra / OmegaConf | YAML composition + CLI overrides | dot-path + subscript | opt-in structured configs | framework owns `argv` |
| configparser (stdlib) | INI files | subscript (strings) | none | none |

See the full
[comparison guide](https://batconf.readthedocs.io/en/latest/comparison.html)
for details, access-interface ergonomics, and guidance on choosing a tool.

## Professional Support

![Tidelift Logo](docs/source/_static/Tidelift_Logos_RGB_Tidelift_Mark_On-White.png)
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](
https://tidelift.com/subscription/pkg/pypi-batconf?utm_source=pypi-batconf&utm_medium=readme
)

## [Example Configuration](tests/example/)
Check out our [Quick Start Guide](https://batconf.readthedocs.io/en/stable/quickstart.html)

and the example project in [tests/example/](/tests/example)
which includes tests and documentation.

### Quick Example

```python
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
```toml
[project]
dependencies = [
    'batconf',
]
```

Including optional extras, like Yaml:

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


## Migrating to v0.4.0

### Breaking Changes

* `batconf.sources.file.FileConfig` has been removed.
  See the [migration guide](https://batconf.readthedocs.io/en/stable/migration.html)
  for details.

## Architecture Decision Records

Significant design decisions are documented in
[`docs/decisions/`](docs/decisions/). Start with the
[foundational ADRs](docs/decisions/0000-foundational/) 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](https://tidelift.com/security).
Tidelift will coordinate the fix and disclosure.
