Ref Bundle
Ref Bundle recursively resolves JSON References ($ref) across JSON, YAML,
and XML configuration and writes one self-contained JSON, YAML, or XML
artifact.
ref-bundle config/root.yaml --output build/config.yaml
Maintaining reusable policy, runtime profiles, workflows, and other generic configuration as named components keeps root documents focused on application intent. Ref Bundle collects those modular sources for downstream tools that only accept a single file.
Documentation
The documentation follows the Diátaxis structure:
- Tutorial: bundle your first configuration
- How to build a modular configuration
- How to use the playground
- CLI reference
$refreference- Explanation: why modular configuration?
- Explanation: how the implementation is organized
Install
Ref Bundle requires Python 3.10 or newer. After configuring access to the package registry used by your organization:
python -m pip install ref-bundle
ref-bundle --help
Hatch projects
To add Ref Bundle to a named Hatch environment, configure the package index
and dependency in pyproject.toml:
[tool.hatch.envs.prod.env-vars]
PIP_EXTRA_INDEX_URL = "https://token:{env:TOKEN_PYPI_REGISTRY}@git.terradue.com/api/v4/projects/{env:PYPI_PROJECT_ID}/packages/pypi/simple/"
[tool.hatch.envs.prod]
path = "/app/envs/my-hatch-env"
dependencies = [
"ref-bundle",
]
If Ref Bundle is a runtime dependency of the package itself rather than a
development environment, declare it under [project] instead:
[project]
dependencies = [
"ref-bundle",
]
Quick example
Given components/runtimes.yaml:
python:
image: python:3.13-slim
replicas: 2
and config.yaml:
service:
runtime:
$ref: components/runtimes.yaml#/python
run:
ref-bundle config.yaml --ext json --output build/config.json
The output is a single JSON document with the referenced runtime inlined.
Playground
The Streamlit playground provides an editor for trying YAML references and viewing the resolved result:
task run_playground
See Use the playground for published-container, development-container, and direct-run instructions.
Local quality checks
Install Hatch and Taskfiles then install the Git hook:
task quality:pre-commit:install
Every commit runs Ruff (including the configured McCabe complexity limit), Ruff formatting, strict mypy checks, and the pytest suite. Run the complete hook explicitly with:
task quality:pre-commit:run
License
Metadata
Release files for ref-bundle 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ref_bundle-1.0.0.tar.gz | 111.0 kB | With provenance | Details for ref_bundle-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ref_bundle-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for ref_bundle-1.0.0-py3-none-any.whl |
Total release size: 127.8 kB
Release files / ref_bundle-1.0.0.tar.gz
| Download URL | ref_bundle-1.0.0.tar.gz |
|---|---|
| Size | 111.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
045ada10a350ec712d758ae49874669fe4314c6d4a1edc34c99f5effe7f1c539
|
|
BLAKE2b-256 checksum How to use checksums |
08c8f43e29c77d63ce7800099d30a0efd9a3f62ceb2a44c14e19a76ace7ce84b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / ref_bundle-1.0.0-py3-none-any.whl
| Download URL | ref_bundle-1.0.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c6c9406177eafd59a5c515872c78eb2349307ea8f2eecadb86519f9bc7afcfa6
|
|
BLAKE2b-256 checksum How to use checksums |
67607824b7cd74910e01844e91a6056b0f021eb255cf2202a9b6ed1010e8042f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logSecurity for ref-bundle 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for ref_bundle-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.