Metadata-Version: 2.3
Name: mace-python
Version: 2.0.0
Summary: Official Python bindings for Mace
Author: the-code-fixer-23
Maintainer: the-code-fixer-23
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# mace-python

Official Python bindings for Mace.

## Status

This package provides a Python-native API around the `mace` CLI. Supported
release binaries are included in the package and selected automatically for the
current platform. Pass `mace_path` when a project needs a different Mace
executable.

## Development

This package is managed with `uv`.

```bash
cd packages/python
python -m uv sync
python -m uv build
```

## Usage

```python
from mace_python import json, output, transform

value = json("./config.mace")
inline_value = transform('{ name: "Mace", }')
output_record = output("./config.mace")
```

## API

- `json(path, input=None, mace_path=None, cwd=None) -> MaceRecord`
- `transform(source, input=None, mace_path=None, cwd=None) -> MaceRecord`
- `json_text(path, input=None, mace_path=None, cwd=None) -> MaceRecord`
- `output(path, mace_path=None, cwd=None) -> MaceRecord`
- `import_json(input_text, mace_path=None, cwd=None) -> MaceRecord`
- `import_yaml(input_text, mace_path=None, cwd=None) -> MaceRecord`
- `import_toml(input_text, mace_path=None, cwd=None) -> MaceRecord`
- `import_file(path, mace_path=None, cwd=None) -> MaceRecord`

All `mace_path` arguments are optional; the package uses its bundled platform
binary when they are omitted.

## Records and errors

`transform` writes Mace source to a temporary file, evaluates it through the
CLI, and deserializes its JSON result into a `MaceRecord`. `json_text` is
retained as an alias for `json`; `output` evaluates the supplied Mace file; and
`import_*` evaluates the Mace source generated by the CLI import command. A
record contains strings, numbers, booleans, nested records, and lists.

CLI failures raise `MaceError`. Alongside `str(error)` and `exit_code`, its
`diagnostic` provides a best-effort structured view of the CLI stderr:
`category`, `code`, `message`, `range.start.line`, `range.start.column`, and
`path`. The current CLI text protocol does not always provide every field, so
`category`, `code`, `range`, and `path` may be `None`.
