toml-repo 0.1.2__py3-none-any.whl

toml_repo-0.1.2.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: toml-repo
+Version: 0.1.2
+Summary: A TOML-based repository manager with precedence-based configuration merging, imports, and multi-scheme URL support.
+License: GPL-3.0-only
+License-File: LICENSE
+Author: Kevin Hester
+Author-email: kevinh@geeksville.com
+Requires-Python: >=3.12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: multidict (>=6.7.0,<7.0.0)
+Requires-Dist: requests-cache (>=1.2.1,<2.0.0)
+Requires-Dist: tomlkit (>=0.13.3,<0.14.0)
+Project-URL: Homepage, https://github.com/geeksville/toml-repo
+Project-URL: Repository, https://github.com/geeksville/toml-repo
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+pip install toml-repo
+```
+
+Or with Poetry:
+
+```bash
+poetry add toml-repo
+```
+
+## Quick start
+
+```python
+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:
+
+```python
+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:
+
+```toml
+[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
+
+```bash
+cd toml-repo
+poetry install --with dev
+poetry run pytest
+```
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE) for details.
+

toml_repo-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+toml_repo/__init__.py,sha256=AIfyf5qCM3oowEkO5lT9mCJ5vRnFS-UXsBM5-SLIzfU,563
+toml_repo/http_client.py,sha256=xFts05ZcOVpHxx-keZXH6OwnBJYxgEqM9WdeLDouW18,224
+toml_repo/manager.py,sha256=5ULNRrXDwiFQ-UKHefBV7H5dLs30vJM0hg4a7t9cru4,4497
+toml_repo/py.typed,sha256=Enkyrr7t9bKZQk8ywVperZB_J3TbNaaRpp6qn8sI34s,9
+toml_repo/repo.py,sha256=pF9Tfr4X8HE4dxi3Vgn19OJkW1Njb_QH-mYjskvC9vc,28046
+toml_repo-0.1.2.dist-info/METADATA,sha256=yQmFdgDqB91COXk2JrreI50nF2Nevb2PT2B6T6YmY2k,4844
+toml_repo-0.1.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+toml_repo-0.1.2.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+toml_repo-0.1.2.dist-info/RECORD,,

toml_repo-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any