Metadata-Version: 2.4
Name: cml-python-adapter
Version: 0.1.1
Summary: Dependency-free Python adapter for the CML reference compiler.
Keywords: cml,compiler,continuity,adapter
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# CML Python Adapter

Version 0.1.1

This package lets Python applications compile `.cml` files through the
authoritative JavaScript CML reference compiler. It does not reimplement or
modify the CML language.

## Requirements

- Python 3.10 or newer
- Node.js 18.19 or newer
- A local copy of the CML reference compiler

## Install

```bash
python -m pip install -e .
```

Set the compiler location:

```bash
export CML_COMPILER_DIR="/absolute/path/to/CML-Reference-Compiler"
```

Windows PowerShell:

```powershell
$env:CML_COMPILER_DIR = "C:\absolute\path\to\CML-Reference-Compiler"
```

## Use

```python
from cml_adapter import compile_file

result = compile_file("scene.cml")

if result.valid:
    print(result.ir)
else:
    for diagnostic in result.diagnostics:
        print(diagnostic.code, diagnostic.message)
```

The adapter returns canonical CML-IR as Python dictionaries. Invalid CML
returns structured diagnostics without converting CML into Python syntax.

The adapter accepts CML language version `1.0.0` by default and rejects a
different compiler language version. It limits source input to 10 MiB and
removes `NODE_OPTIONS` and `NODE_PATH` before starting the compiler.

## Security boundary

`CML_COMPILER_DIR` points to JavaScript that the adapter executes with Node.js.
Only configure a trusted, verified CML reference compiler. The adapter uses an
argument array rather than a command shell, enforces a timeout, limits source
size, validates JSON output, and returns structured compiler diagnostics.

## Test

```bash
python -m unittest discover -s tests -v
```
