Metadata-Version: 2.4
Name: taut-shape
Version: 0.9.1
Summary: taut-shape — pure-Python delivery-shape engine (`log` first): a clean-room mailbox LogNode gated by the taut-shape behavioral oracle (import: `taut_shape`)
Author-email: Gianni Mariani <gianni@mariani.ws>
License-Expression: MIT
Project-URL: Homepage, https://github.com/owebeeone/taut-shape-py
Project-URL: Repository, https://github.com/owebeeone/taut-shape-py
Keywords: taut,log,delivery-shape,mailbox,streaming,oracle
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: taut-proto<0.10,>=0.9.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: syrupy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# taut-shape (Python)

`pip install taut-shape` → `import taut_shape`.

A **pure-Python** implementation of the Taut `atom`, `log`, `stream`, and `value` delivery shapes. No Rust,
no PyO3, no native extension. The engine is a synchronous **mailbox endpoint**
(`LogNode.handle(msg) -> [outputs]`); the only concurrency is an optional
`asyncio` shell layered on top (not yet built).

This is a **clean-room** implementation: written against the shared plan
(`taut-shape/dev-docs/TautClientImplPlan.md`, D1–D19) and the behavioral oracle
(`taut-shape/corpus/log.v0.json`) only — it does not mirror `taut-shape-rs`. A
hand-written engine that still reproduces every oracle vector is the evidence
that **the oracle, not shared source, is the contract**.

## Status

- Phase 0 — scaffold + vendored generated message types. ✓
- Phase 1 — the `LogNode` mailbox engine (pure, sync). ✓
- Phase 2 — oracle conformance (`tests/test_oracle.py`, whole-transcript `==`). ✓
- Phase 4 — the `taut-shape-tool` CLI (`node`/`client` modes over stdin/stdout
  framing, `python3 -m taut_shape.tool`; see `src/taut_shape/tool/main.py`). ✓
- Phase 5 — interop matrix participation (`taut-shape/matrix/driver.py` runs
  this tool as the `py` language). ✓
- Phase 3 (an `asyncio` shell) — not built; the engine has no built-in
  concurrency layer beyond the CLI's synchronous read/handle/write loop.

## Layout

```
src/taut_shape/log/
  _generated.py   # tautc-generated message/value types (vendored, do NOT edit)
  messages.py     # InMsg/OutMsg unions + re-exports
  _window.py      # store core: bounded window, head/floor, evict (internal)
  _sessions.py    # session table: held reads, timers, watermarks (internal)
  engine.py       # LogNode.handle + read-only accessors
src/taut_shape/value/
  _generated.py   # tautc-generated value messages (vendored, do NOT edit)
  engine.py       # attributed LWW ValueNode
src/taut_shape/atom/
  _generated.py   # tautc-generated atom messages (vendored, do NOT edit)
  engine.py       # latest-state AtomNode
src/taut_shape/stream/
  _generated.py   # tautc-generated stream messages (vendored, do NOT edit)
  engine.py       # bounded live-only StreamNode
```

## Tool (node / client)

Run the framing CLI as a module. Both modes accept exact `--shape <NAME>`
selection and default to `log`; the implemented registry contains `atom`, `log`,
`stream`, and `value`.

```
PYTHONPATH=../taut/src:src python3 -m taut_shape.tool node --shape log
PYTHONPATH=../taut/src:src python3 -m taut_shape.tool client --shape log \
  --stream-id s1 --from 0
PYTHONPATH=../taut/src:src python3 -m taut_shape.tool client --shape value \
  --value-id value-A --stream-id s1 --reads 1
PYTHONPATH=../taut/src:src python3 -m taut_shape.tool client --shape atom \
  --atom-id atom-A --stream-id s1 --from 0
PYTHONPATH=../taut/src:src python3 -m taut_shape.tool client --shape stream \
  --stream-id live-metrics
```

An unsupported name exits 2 with `TAUT_SHAPE_UNSUPPORTED_SHAPE` before stdin is
read or a client request is written.

## Running the tests

The `taut` codec is a workspace sibling; point `PYTHONPATH` at it:

```
PYTHONPATH=../taut/src:src pytest
```
