Metadata-Version: 2.4
Name: cml-python-adapter
Version: 0.1.2
Summary: Dependency-free Python adapter for the CML reference compiler.
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/cstolting-collab/CML-Python-Adapter
Project-URL: Issues, https://github.com/cstolting-collab/CML-Python-Adapter/issues
Keywords: cml,compiler,continuity,adapter
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# CML Python Adapter

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–3.13
- Node.js 18.19 or newer
- A trusted local copy of CML Reference Compiler `v1.1.0-rc.2`

## Install

Published release:

```bash
python -m pip install cml-python-adapter
```

Development checkout:

```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, compile_source

result = compile_file("scene.cml")
# result = compile_source(cml_text)

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

Invalid CML returns structured diagnostics. Inputs up to 10 MiB are accepted
by default. Small in-memory inputs use UTF-8 stdin; larger inputs are staged in
a private temporary UTF-8 file and removed immediately after compilation.

The adapter accepts CML language version `1.0.0` by default and rejects a
different compiler language version. It removes `NODE_OPTIONS` and `NODE_PATH`
before starting the compiler.

## Security boundary

`CML_COMPILER_DIR` points to JavaScript executed with the current user's
permissions. Only configure a trusted, verified compiler. The adapter uses an
argument array rather than a command shell, enforces a timeout and size limit,
validates compiler envelopes, and rejects malformed IR structures.

## License

Licensed under the Apache License 2.0. It permits commercial and private use,
modification, and redistribution subject to its license and notice conditions,
and includes an explicit patent grant. See `LICENSE` and `NOTICE`.

## Test

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

Advanced deployments can configure `stdin_safe_bytes` to control when
in-memory input is staged to a temporary file. Set
`include_paths_in_errors=False` when adapter-generated errors may cross an API
boundary and should not reveal local source/compiler paths.

GitHub Actions tests Python 3.10, 3.11, 3.12, and 3.13 on Windows, Linux, and
macOS.
