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

Function Description
set_config_suffix(name) Set the TOML filename for directory repos (default: "repo.toml")
get_config_suffix() Get the current config suffix
set_pkg_resource_root(pkg) Set the Python package for pkg:// URL resolution

RepoManager

Method Description
add_repo(url) Add a repo by URL; returns the Repo instance
get(key, default=None) Get a value with last-repo-wins precedence
get_repo_by_url(url) Find a repo by its URL
get_repo_by_kind(kind) Find the first repo matching a repo.kind value
dump() Log all merged key-value pairs (debug)

Repo

Method Description
get(key, default=None) Get a dot-separated key from this repo's config
set(key, value) Set a dot-separated key in this repo's config
kind() Return the repo.kind value
read(filepath) Read a file relative to the repo root
resolve_path(filepath) Resolve a relative path to an absolute Path
write_config() Write modified config back to disk (file repos only)
add_repo_ref(manager, dir) Add a [[repo-ref]] entry and load it

Development

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

License

GPL-3.0 — see LICENSE for details.

Project links

Data verified by PyPI on Feb 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for geeksville from gravatar.com geeksville

Credits

Author: Kevin Hester

GitHub Statistics

Data verified by PyPI on Feb 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 (GPLv3) (GPL-3.0-only)

Requires

Python >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

toml_repo-0.1.4.tar.gz (25.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

toml_repo-0.1.4-py3-none-any.whl (25.7 kB view details)

Uploaded Python 3

File details

Details for the file toml_repo-0.1.4.tar.gz.

File metadata

  • Download URL: toml_repo-0.1.4.tar.gz
  • Upload date:
  • Size: 25.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for toml_repo-0.1.4.tar.gz
Algorithm Hash digest
SHA256 2cee66542dc95cddc98f5cc0d775ef2ad7a2a8f9377d44c126e054e3d43dd428
MD5 c6ce259df1bdde6d3ffd08a3045d1a26
BLAKE2b-256 c4c2ff276b5d07c96e25679f60b82458a14bfc607b6e1ddbb01fe2dcf7b2b6c6

See more details on using hashes here.

Provenance

The following attestation bundles were made for toml_repo-0.1.4.tar.gz:

Publisher: publish.yml on geeksville/toml-repo

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file toml_repo-0.1.4-py3-none-any.whl.

File metadata

  • Download URL: toml_repo-0.1.4-py3-none-any.whl
  • Upload date:
  • Size: 25.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for toml_repo-0.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 f39b86aaf4cf2cb5bbdddbf7fc35b8072a00b74b954763cace240ad0d86582cb
MD5 910767073a161db6ff49dabdcddaca3a
BLAKE2b-256 02d1b5f7457315395097d27a65ba425f67674f6a025855dabb8c4725a1db2c96

See more details on using hashes here.

Provenance

The following attestation bundles were made for toml_repo-0.1.4-py3-none-any.whl:

Publisher: publish.yml on geeksville/toml-repo

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.4 This release

2 files

0.1.3

2 files

0.1.2

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page