Metadata-Version: 2.4
Name: gemara-python
Version: 0.1.0
Summary: Gemara v1 schema types as Pydantic v2 models
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
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: Typing :: Typed
Requires-Dist: pydantic>=2.9
Requires-Dist: pyyaml>=6.0
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/gemaraproj/gemara-python
Project-URL: Repository, https://github.com/gemaraproj/gemara-python
Project-URL: Issues, https://github.com/gemaraproj/gemara-python/issues
Description-Content-Type: text/markdown

# gemara-python

## What This Is

`gemara-python` provides generated Pydantic v2 models for
[Gemara](https://github.com/gemaraproj/gemara) v1 documents.
Use it to load, validate, and work with Gemara JSON or YAML in Python.

## How to Install

```bash
pip install gemara-python
```

## Getting Started

```python
from gemara.v1 import ControlCatalog, Lexicon, load

doc = load("catalog.yaml")  # dispatches on metadata.type

match doc:
    case ControlCatalog():
        print(len(doc.controls or []))
    case Lexicon():
        print(len(doc.terms))
```

`load` accepts a file path or open file. Use `loads` for JSON or YAML text and
bytes. Both return the model selected by `metadata.type`.

When the expected document type is already known, load it directly from the
model to receive that concrete type without dispatching:

```python
from gemara.v1 import GuidanceCatalog

guidance = GuidanceCatalog.from_file("guidance.yaml")
```

`from_file` accepts a file path or open file. `from_text` accepts JSON or YAML
text and bytes. Both validate the input as the selected document model.

## Reference

- `DOCUMENT_TYPES` contains the supported document models.
- `GemaraDocument` is the union type returned by `load` and `loads`.
- Catalog documents share the `Catalog` base and log documents share `Log`, so
  `isinstance(doc, Catalog)` or `isinstance(doc, Log)` narrows a dispatched
  document to its category.
- `SCHEMA_VERSION` is the Gemara release used to generate the models
- `__version__` is the installed `gemara-python` distribution version.
- Invalid input raises `GemaraError`, `UnknownDocumentTypeError`, or
  `pydantic.ValidationError`.
- `load` and `from_file` also propagate filesystem and stream I/O exceptions.

## Compatibility

Changes within Gemara v1 are additive, so these models read every v1.x document,
including ones written against a minor newer than `SCHEMA_VERSION`. Properties
they do not recognize are accepted and dropped rather than carried onto the
model.

## Known limitations

**These models are a structural validator, not a full Gemara validator.** CUE
enforces cross-field semantics — uniqueness via hidden `_unique*` fields,
referential integrity via comprehensions -- that cannot survive projection into
JSON Schema.

What still applies: required fields, enums, patterns, and length bounds. If you
need full validation, run `cue vet` against the Gemara schemas.

## License

Apache-2.0.
