Metadata-Version: 2.5
Name: ref-bundle
Version: 1.0.0
Summary: Assemble modular YAML/JSON/XML configuration through recursive JSON Reference `$ref` resolution
Project-URL: Documentation, https://terradue.github.io/ref-bundle/
Project-URL: Issues, https://github.com/Terradue/ref-bundle/issues
Project-URL: Source, https://github.com/Terradue/ref-bundle
Project-URL: Changelog, https://github.com/Terradue/ref-bundle/blob/main/CHANGELOG.md
Author-email: Fabrice Brito <info@terradue.com>, Simone Tripodi <info@terradue.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: $ref,JSON,JSON Reference,XML,YAML
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: click>=8.5.0
Requires-Dist: jsonref>=1.1.0
Requires-Dist: loguru==0.7.3
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Dist: session-adapters>=0.7.0
Requires-Dist: xmltodict>=1.0.4
Provides-Extra: test
Requires-Dist: pytest-cov<8,>=7.1.0; extra == 'test'
Requires-Dist: pytest<10,>=9.1.1; extra == 'test'
Description-Content-Type: text/markdown

# Ref Bundle

[![PyPI - Version](https://img.shields.io/pypi/v/ref-bundle.svg)](https://pypi.org/project/ref-bundle)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ref-bundle.svg)](https://pypi.org/project/ref-bundle)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Terradue/ref-bundle/package.yaml?branch=develop&event=push&label=build&logo=githubactions)](https://github.com/Terradue/ref-bundle/actions/workflows/package.yaml?query=branch%3Adevelop)
[![Code coverage](https://img.shields.io/codecov/c/github/Terradue/ref-bundle/develop?logo=codecov)](https://app.codecov.io/gh/Terradue/ref-bundle/tree/develop)

Ref Bundle recursively resolves JSON References (`$ref`) across JSON, YAML,
and XML configuration and writes one self-contained JSON, YAML, or XML
artifact.

```bash
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](https://diataxis.fr/) structure:

- [Tutorial: bundle your first configuration](docs/tutorials/first-bundle.md)
- [How to build a modular configuration](docs/how-to/modular-configuration.md)
- [How to use the playground](docs/how-to/playground.md)
- [CLI reference](docs/reference/cli.md)
- [`$ref` reference](docs/reference/json-reference.md)
- [Explanation: why modular configuration?](docs/explanation/modular-configuration.md)
- [Explanation: how the implementation is organized](docs/explanation/implementation.md)

## Install

Ref Bundle requires Python 3.10 or newer. After configuring access to the
package registry used by your organization:

```bash
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`:

```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:

```toml
[project]
dependencies = [
  "ref-bundle",
]
```

## Quick example

Given `components/runtimes.yaml`:

```yaml
python:
  image: python:3.13-slim
  replicas: 2
```

and `config.yaml`:

```yaml
service:
  runtime:
    $ref: components/runtimes.yaml#/python
```

run:

```bash
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:

```bash
task run_playground
```

See [Use the playground](docs/how-to/playground.md) for published-container,
development-container, and direct-run instructions.

### Local quality checks

Install [Hatch](https://hatch.pypa.io/) and [Taskfiles](https://taskfile.dev/docs/guide) then install the Git hook:

```bash
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:

```bash
task quality:pre-commit:run
```

## License

[![Apache License, Version 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)
