toml-repo

A TOML-based repository manager for Python applications. Provides precedence-based configuration merging, cross-file imports, and multi-scheme URL support (file://, pkg://, http://). You can have trees of toml (and other data files) with auto resolved links between them.

Features

• Multi-scheme repositories – load TOML configs from local directories (file://), Python package resources (pkg://), or HTTP(S) URLs.
• Precedence-based merging – later-added repos override earlier ones; query across all repos with a single get() call.
• TOML imports – [section.import] tables let you pull nodes from other files or repos, eliminating duplication.
• Configurable config filename – defaults to repo.toml; call set_config_suffix() to use any name (e.g. "myapp.toml").
• Source tracking – every TOML node is monkey-patched with a .source back-pointer to the Repo that loaded it.
• HTTP caching – HTTP repos use requests-cache so previously fetched configs work offline.

Installation

pip install toml-repo

Or with Poetry:

poetry add toml-repo

Quick start

from toml_repo import RepoManager, set_config_suffix

# Optional: change the filename looked up inside repo directories
set_config_suffix("myapp.toml")

manager = RepoManager()
manager.add_repo("file:///path/to/base-config")
manager.add_repo("file:///path/to/user-overrides")

# Last repo wins
value = manager.get("section.key", default="fallback")

Using pkg:// URLs

If your application ships default configs as package data you can load them via importlib resources:

from toml_repo import set_pkg_resource_root

# Tell toml-repo which installed package contains the resources
set_pkg_resource_root("myapp")

manager.add_repo("pkg://defaults")  # reads myapp/defaults/myapp.toml

TOML imports

Inside any TOML file managed by toml-repo you can import nodes from other files to reduce duplication:

[repo]
kind = "recipe"

# Import the "base_stage" table from a library file
[my_stage.import]
file = "library.toml"
node = "base_stage"

Imports support:

• Same-file references (node = "some.path")
• Cross-file references (file = "relative/path.toml")
• Cross-repo references (repo = "file:///other/repo")
• Recursive resolution (imported files can themselves contain imports)

API reference

Module-level configuration

RepoManager

Repo

Development

cd toml-repo
poetry install --with dev
poetry run pytest

License

GPL-3.0 — see LICENSE for details.