Metadata-Version: 2.4
Name: theoworks-core
Version: 0.1.0
Summary: TheoWorks core — byte-stable sphinx-needs round-trip, schema, validation, and traceability (pure-Python, no runtime dependencies)
Author: TheoWorks
License-Expression: Apache-2.0
Project-URL: Homepage, https://theoworks.io
Project-URL: Source, https://gitlab.com/theoworks/theoworks
Keywords: sphinx,sphinx-needs,requirements,ASPICE,traceability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# theoworks-core

Core library for [TheoWorks](https://theoworks.io) — a byte-stable, round-trip
toolkit for [sphinx-needs](https://sphinx-needs.readthedocs.io) requirements
projects.

`theoworks-core` is pure Python with **no runtime dependencies**. It provides:

- **Byte-stable RST round-trip** — parse and re-serialize `.. <type>::` need
  directives (and surrounding prose) with minimal, clean diffs.
- **Schema model** — load a project's need types, fields, and links from
  `conf.py`, a pack manifest, or observed usage.
- **Validation** — check needs against the resolved schema and summarize
  findings (errors / warnings).
- **Traceability** — compute link coverage and gaps across a needs graph.
- **Packs** — starter project templates (`default`, `blank`, `aspice`,
  `vmodel`) used to scaffold a new project.

## Install

```bash
pip install theoworks-core
```

## Usage

```python
from theoworks_core import parse_document, serialize_document

doc = parse_document(open("docs/index.rst", encoding="utf-8").read())
for block in doc.blocks:
    print(block)

# Round-trips byte-for-byte:
assert serialize_document(doc) == open("docs/index.rst", encoding="utf-8").read()
```

Scaffold a new project:

```python
from theoworks_core import scaffold_project

scaffold_project("my-project", name="My Project", pack="aspice")
```

## Related packages

- [`theoworks-sphinx`](https://pypi.org/project/theoworks-sphinx/) — the Sphinx
  extension that emits the needs graph (`needs.json`).
- [`theoworks-cli`](https://pypi.org/project/theoworks-cli/) — the `theoworks`
  command-line interface.

## License

Apache-2.0. See [LICENSE](LICENSE).
