BoundConfig

BoundConfig manages a TOML config file against one or more TOML defaults files. The current implementation can:

• add missing managed keys and sections with init
• validate managed content without writing with validate
• repair missing or invalid managed content through the Python API with repair

Unknown user keys and sections are preserved during managed operations. Writes go through tomlkit, so comments and ordering survive as well as that adapter allows.

Current Public Surface

• CLI commands: boundconfig init, boundconfig validate
• Python API: boundconfig.BoundConfig, boundconfig.register_validator
• TOML only
• Python 3.10+

repair exists today, but only through the Python API. There is no CLI repair subcommand in the current implementation.

Current Limits

• Defaults files must use top-level TOML sections only.
• Managed nested tables and arrays of tables in defaults files are out of scope.
• Managed inline-table defaults are validated only shallowly for table shape.
• There is no CLI hook for registering custom validators.
• Offset time values are not supported. Use TOML local time values instead.

Install From A Clone

python -m pip install -e .

After installation, the console script is boundconfig. The module entry point also works:

python -m boundconfig --help

Quick Start

The sample set under samples/ is verified against the current test suite. The shortest walkthrough is samples/basic/.

Given a defaults file and a working config:

[service]
enabled = true
retries = 3
mode = { _default_value = "INFO", _allowed_values = ["DEBUG", "INFO"] }
point = { x = 1, y = 2 }

[ui]
theme = "dark"

[service]
enabled = "true"
mode = "DEBUG"
extra = "user"

[custom]
feature = true

Run init to add only missing managed content:

boundconfig init --config ./config.toml --defaults ./defaults.toml --verbose

Run validate to see what is still wrong:

boundconfig validate --config ./config.toml --defaults ./defaults.toml --verbose

Repair invalid managed values through the Python API:

from pathlib import Path

from boundconfig import BoundConfig

bound_config = BoundConfig(
    config_path=Path("config.toml"),
    defaults_paths=(Path("defaults.toml"),),
)

report = bound_config.validate()
repaired_document = bound_config.repair(dry_run=True)

init does not repair existing invalid managed values. repair does.

Guides

• Documentation index: docs/README.md
• Schema declarations: docs/schema-declarations.md
• Schema quick reference: docs/schema-quick-reference.md
• init vs validate vs repair: docs/init-validate-repair.md
• Reserved sections and keys: docs/reserved-sections-and-keys.md
• Example files: samples/README.md
• TOML adapter ADR: docs/architecture/adr-0001-toml-adapter.md

Custom Validators

Custom validators are implemented, but the feature is intentionally narrow. A schema can bind a field to a validator name with _validator, and Python code can register a callable under that name.

[service]
name = { _default_value = "BoundConfig", _validator = "no-spaces" }

from pathlib import Path

from boundconfig import BoundConfig

bound_config = BoundConfig(
    config_path=Path("config.toml"),
    defaults_paths=(Path("defaults.toml"),),
)
bound_config.register_validator(
    "no-spaces",
    lambda value: "must not contain spaces" if " " in value else None,
)

report = bound_config.validate()

There is no CLI flag, plugin system, or import hook for validator registration in the current implementation. If a defaults file uses _validator, the CLI will only work if some wrapper code has already registered that validator in the current Python process.

See samples/custom-validator/ for matching example files.

Notes On CLI Options

The CLI currently exposes the same option set on both subcommands because they share an argument parser:

• --config
• --defaults
• --dry-run
• --verbose
• --suppress-warnings

Only part of that surface matters per command today:

• init uses --dry-run and --verbose. --suppress-warnings is accepted but has no effect.
• validate uses --verbose and --suppress-warnings. --dry-run is accepted but redundant because validate never writes.
• --defaults can be repeated or given multiple paths after one flag.