Metadata-Version: 2.4
Name: cdm-lite
Version: 0.6.0
Summary: Python CDM Models
Keywords: FINOS,CDM,Common Domain Model,ISDA,Pydantic,JSON-Schema,finance,regulation,code-generation
Author: Ben Allen
Author-email: Ben Allen <ben05allen@hotmail.com>
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: 3.15
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx2>=2.16.0
Requires-Dist: platformdirs>=4.9.6
Requires-Dist: pydantic>=2.14.0
Requires-Dist: datamodel-code-generator[ruff]>=0.86.0
Requires-Dist: typer>=0.25.1
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/ben05allen/cdm-lite
Description-Content-Type: text/markdown

# cdm-lite

[![CI](https://github.com/ben05allen/cdm-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/ben05allen/cdm-lite/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.15-blue.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

Python Pydantic models for the [FINOS Common Domain Model (CDM)](https://github.com/finos/common-domain-model).

`cdm-lite` provides a lightweight CLI to download, clean, and compile official FINOS CDM JSON
schemas into Pydantic v2 models. This enables strict validation, autocompletion, and robust
deserialization of CDM JSON payloads in Python codebases without heavy Java dependencies.

## Status

**Current Phase:** Stable (v0.6.0)

`cdm-lite` is a stable release. The CLI surface, the on-disk cache layout and the layout of the
generated models follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html): breaking
changes will only be made in a major release. The schemas published by FINOS are cleaned and
compiled on your machine, so the models you get always match the CDM version you installed.

**Feedback Welcome:** We gratefully encourage users to provide comments, recommendations, or report any issues found during usage. Your input
will help in reaching a stable 1.0 release.

## Scope & Limitations

**⚠️ Disclaimer:** `cdm-lite` is intended primarily as a lightweight **deserializer**. The generated
Python models are derived directly from the published JSON Schemas. While they provide close
structural validation, we cannot guarantee that the generated models perfectly match the
behavioral constraints of the full Common Domain Model.

Pydantic classes inherently cannot capture the full extent of the CDM's functionality,
such as complex cross-field cardinality checks, conditions, or rosetta-injected logic.
For robust **serialization** and comprehensive domain validation, we strongly recommend using the [official, full CDM project implementations](https://github.com/finos/common-domain-model) (e.g., the Java distribution).

## Installation

```bash
uv tool install cdm-lite
```

## Workflow

Download and compile the CDM models for your required schema version:

```bash
# List available FINOS CDM versions from Maven Central
cdm-lite versions

# Download schemas and compile Pydantic models locally
cdm-lite install 6.19.0

# Activate the version (updates a local symlink)
cdm-lite use 6.19.0

# Or: install the latest stable version and activate it in one step
cdm-lite upgrade
```

_Note: Models are compiled into a user-level cache directory (e.g., `~/.cache/cdm-lite/`). Run `cdm-lite status` to view your specific path._

_Downloads are verified against the SHA-1 checksum published on Maven Central, and version
discovery caches the Maven metadata so `cdm-lite versions` keeps working offline._

## Project Integration

To use the compiled models in your application, point your environment to the active models directory.

**Using `uv` (`pyproject.toml`):**

```toml
[tool.uv.sources]
# Use the exact absolute path returned by `cdm-lite use`
cdm-models = { path = "/home/user/.cache/cdm-lite/current" }

[project]
dependencies = ["cdm-models"]
```

**Using PYTHONPATH:**

```bash
# Use the exact absolute path returned by `cdm-lite use`
export PYTHONPATH="/home/user/.cache/cdm-lite/current/src:$PYTHONPATH"
```

## Deserializing JSON

Once the models are available in your path, use standard Pydantic APIs to parse, validate, and interact with incoming JSON objects:

```python
from cdm_models.models.cdm_event_common_TradeState_schema import TradeState  # Exact import paths depend on the CDM schema

payload = '{"trade": {"tradeDate": {"value": "2023-10-25"}}}'

# Deserialize and strictly validate the JSON string
trade_state = TradeState.model_validate_json(payload)

# Access typed and autocompleted attributes
print(trade_state.trade.trade_date.value)
```

## Releasing

Releases are published to PyPI automatically from a git tag, using
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) — no API token is
stored in GitHub.

1. Bump the version and update every version reference in one command:

   ```bash
   uv run python scripts/bump_version.py 0.6.1 --note "Add a cdm-lite upgrade command."
   ```

   This updates `pyproject.toml` (version and development status classifier), the README status
   line and the CHANGELOG in a single commit.

2. Open a pull request. CI checks that the CHANGELOG documents the version in `pyproject.toml`.

3. Merge, then tag and push the tag:

   ```bash
   git tag v0.6.1
   git push origin v0.6.1
   ```

4. The `Release` workflow verifies the tag matches the project version, builds the sdist and
   wheel, and publishes them to PyPI.

**One-time PyPI setup:** on the [cdm-lite project page](https://pypi.org/manage/project/cdm-lite/settings/publishing),
add a GitHub trusted publisher with owner `ben05allen`, repository `cdm-lite`, workflow
`release.yml` and environment `pypi`. The `pypi` environment must therefore be referenced by the
release workflow; if you configure the publisher without an environment name, remove the
`environment:` block from `.github/workflows/release.yml`.

## Reference Commands

- `cdm-lite --version`: Print the installed version.
- `cdm-lite versions`: View available versions on Maven Central.
- `cdm-lite install <version>`: Fetch schemas and compile models.
- `cdm-lite upgrade [version]`: Install the latest stable version (or a specific one) and make it active.
- `cdm-lite use <version>`: Set the active version for the `current` symlink.
- `cdm-lite list`: Show locally compiled versions.
- `cdm-lite status`: Print active version and system cache location.
- `cdm-lite remove <version>`: Delete a specific version from the local cache.
- `cdm-lite clear`: Remove all local schemas and generated models.
