Metadata-Version: 2.4
Name: stapel-docs
Version: 0.7.0
Summary: Documents: storage, revisions and per-type editors for the Stapel framework
License: MIT
Project-URL: Homepage, https://github.com/usestapel/stapel-docs
Project-URL: Repository, https://github.com/usestapel/stapel-docs
Project-URL: Documentation, https://github.com/usestapel/stapel-docs#readme
Project-URL: Changelog, https://github.com/usestapel/stapel-docs/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/usestapel/stapel-docs/issues
Keywords: django,stapel,docs
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: stapel-core<1.0,>=0.27.0
Provides-Extra: s3
Requires-Dist: boto3>=1.26; extra == "s3"
Provides-Extra: pdf
Requires-Dist: fpdf2>=2.8; extra == "pdf"
Requires-Dist: markdown>=3.4; extra == "pdf"
Provides-Extra: thumbnails
Requires-Dist: Pillow>=10; extra == "thumbnails"
Provides-Extra: crdt
Requires-Dist: pycrdt<0.15,>=0.12; extra == "crdt"
Provides-Extra: realtime
Requires-Dist: stapel-realtime[channels]<1.0,>=0.1.2; extra == "realtime"
Provides-Extra: all
Requires-Dist: boto3>=1.26; extra == "all"
Requires-Dist: fpdf2>=2.8; extra == "all"
Requires-Dist: markdown>=3.4; extra == "all"
Requires-Dist: Pillow>=10; extra == "all"
Requires-Dist: pycrdt<0.15,>=0.12; extra == "all"
Requires-Dist: stapel-realtime[channels]<1.0,>=0.1.2; extra == "all"
Dynamic: license-file

<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->

# stapel-docs

[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-docs/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-docs/actions/workflows/ci.yml?query=branch%3Amain)
[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-docs?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-docs)
[![pypi](https://img.shields.io/pypi/v/stapel-docs?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-docs/)
[![downloads](https://static.pepy.tech/badge/stapel-docs/month)](https://pepy.tech/project/stapel-docs)
[![python](https://img.shields.io/pypi/pyversions/stapel-docs?logo=python&logoColor=white)](https://pypi.org/project/stapel-docs/)
[![license](https://img.shields.io/github/license/usestapel/stapel-docs)](https://github.com/usestapel/stapel-docs/blob/main/LICENSE)
[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-docs/blob/main/docs/llms.txt)

> Google-Drive-style workspace documents: a folder tree, one-entity-per-type documents over an open type registry, content-addressed snapshot storage with an update journal and revision history, optimistic-lock editing (v1), trash with irreversible purge, a swappable object-storage seam, comm ingest (docs.create_document) and registry-driven export (PDF built in).

Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.

## Install

```bash
pip install stapel-docs
```

## At a glance

| Fact | Value |
|---|---|
| Version | `0.7.0` |
| Python | `>=3.11` (3.11, 3.12, 3.13) |
| HTTP operations | 44 |
| Config axes | 1 |
| Usage surface | 91 |
| Extension points | 7 |
| Error codes | 85 |
| Fleet dependencies | [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-workspaces`](https://github.com/usestapel/stapel-workspaces) (optional) |

## Documentation

[OpenAPI](https://github.com/usestapel/stapel-docs/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-docs/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-docs/blob/main/docs/llms.txt)

## What this is

Google-Drive-style **workspace documents**: a folder tree, documents that are
each ONE entity with a `type` from an open registry (`txt` / `md` / `csv` /
opaque `file` built in; live `ymd` / `ytxt` with the `[crdt]` extra), a
journal + revision versioning substrate, trash with irreversible purge, and
registry-driven export (pdf / md / txt built in).

The versioning substrate is decided for both collaboration disciplines:
**snapshot** types save whole states under optimistic lock (`If-Match` carries
the client's `head_seq` — v1's editing model), **crdt** types accumulate an
append-only update journal between snapshots with chat-pattern replay/resync.
Which discipline applies is a property of the *type*, not the request.

Object storage is content-addressed and goes through a swappable seam
(`STORAGE`); the library is **body-blind** — the storage substrate never
parses a document body, only a type's own `text_extractor` may.

## Quick start

The base install rides Django's `default_storage`; add extras for the
boto3 S3/MinIO backend, the PDF exporter and image thumbnails:

```bash
pip install "stapel-docs[s3,pdf,thumbnails]"
```

```python
INSTALLED_APPS = [
    # ...
    "stapel_docs",
]

# urls.py
path("docs/", include("stapel_docs.urls"))   # -> /docs/api/v1/...
```

Authorization asks the `workspaces.check_capability` comm Function
(fail-closed, deny-by-default) — install stapel-workspaces or provide that
Function for any HTTP request to be allowed.

## An open type registry, not an enum

```python
STAPEL_DOCS = {
    # Add or replace document types ({slug: dotted-path | None removes}):
    "DOC_TYPES": {"sheet": "myproject.docs.SHEET_SPEC"},
    # Add export formats over the built-in pdf:
    "EXPORTERS": {"docx": "myproject.docs.DocxExporter"},
    # Event-driven ingest without writing a subscriber:
    "INGEST": {"meeting.summarized": "myproject.docs.map_summary"},
    # Swap the object store:
    "STORAGE": "stapel_docs.storage.S3Backend",
}
```

A type whose spec vanishes from the registry degrades to `file` behavior —
read-only, never unreadable: revisions still list, snapshots still download,
trash/purge/export still work.

## Live collaboration (0.7.0)

With `pip install "stapel-docs[crdt]"` two live types register: `ymd`
(Markdown) and `ytxt` (plain text), Yjs on the wire (pycrdt server-side).
Clients POST opaque Y updates to the journal and replay `?since=`; the
server folds the journal into the snapshot in the background (no seq is
minted — assembly is a materialization, not an edit) and mints revisions and
`document.updated` at that debounce point. The stored body is the binary Y
state; `?format=md` / `?format=txt` / `?format=pdf` serve the human-readable
form.

With `pip install "stapel-docs[realtime]"` (and `stapel_realtime` in
INSTALLED_APPS) each document's journal also streams over
`ws/docs/<document_id>` — resumable, read-only, authorized through the same
choke point as HTTP; every document envelope carries its own `socket_path`.
Without the extra, polling `?since=` remains a first-class mode — forever.

## Export

`?format=pdf` renders `txt` verbatim, `csv` as a bordered grid, and `md`
**parsed** — headings, bold/italic, bulleted and numbered lists, fenced code
in monospace, tables, clickable links. Cyrillic (and everything else DejaVu
covers) holds throughout, code blocks included, because the fonts ship in the
wheel. Pure python: fpdf2 + Python-Markdown, no WeasyPrint and so no system
pango/cairo to install. A document body is user input on its way to an HTML
renderer, so it is sanitized to an allowlist first — images are dropped
before the renderer can fetch them, scripts and styles lose their content,
and only `http(s)`/`mailto` links become annotations.

## Ingest

Product glue dumps content in with one comm call — no HTTP, no import:

```python
call("docs.create_document", {
    "workspace_id": ws_id, "type": "md", "title": "Weekly sync",
    "body": summary_text, "folder_path": "/Meetings/2026-08",
})
```

`folder_path` materializes folders idempotently; an unknown `type` refuses
loudly so content never silently lands under a mistyped slug.

## The drive surfaces

Four per-user views over the same corpus, all behind the one authorization
choke point:

- **Starred** — `POST`/`DELETE /documents/<id>/star` and the folder twin,
  `GET /starred`. Idempotent both ways (204 whatever the previous state was)
  and gated by `docs.view`: a star is a bookmark, not an edit. Every folder
  and document envelope carries `is_starred` — `null`, not `false`, when the
  request has no user, because "not applicable" is a third answer.
- **Recents** — `GET /recents`. Written by the service layer on content read,
  download-URL issuance and accepted save; a rejected save records nothing.
  Capped by `RECENTS_MAX_PER_USER` and trimmed oldest-first on write.
- **Search** — `GET /search?workspace_id=&q=`. Workspace-scoped
  case-insensitive substring over live folder names and document titles, each
  hit carrying its `kind` and a server-built breadcrumb. A missing `q` is a
  400, not a free full-workspace listing. `?q=` also filters the documents
  listing for the in-folder case.
- **Thumbnails** — `GET /documents/<id>/thumbnail?tier=` for `image/*` file
  documents, tiers `160` and `480`. Rendered server-side with Pillow and
  cached under the document's own storage prefix, so a purge takes the
  previews with it. Without the `[thumbnails]` extra the endpoint answers 503
  and a client falls back to a type icon.

## Usage metering

`docs.usage` reports `{bytes_live, bytes_trash, bytes_total, documents,
folders, by_type}` for one workspace. `bytes_total` is the same sum the 507
quota refuses against, so a meter and a refusal can never disagree. Composing
an entitlement ceiling out of it (`billing.check_entitlement`) is the host's
glue — docs owns the measurement, never the price. The call carries its own
authority exactly like `docs.create_document`, one capability lower
(`docs.view`).

## Sharing (v1: closed by default)

The sharing axis (`SHARING`: whitelist / link modes) ships its config surface
with **closed defaults** — v1 implements exactly the immutable workspace
baseline, and opening any sharing knob before the mechanism exists is a loud
system-check error (`stapel_docs.E010-E013`), never a silent no-op.

## Settings

All configuration lives in the `STAPEL_DOCS` namespace (dict setting, flat
setting, or env var — resolved lazily). Full table in
[CONFIG.MD](https://github.com/usestapel/stapel-docs/blob/main/CONFIG.MD);
seam semantics in
[MODULE.md](https://github.com/usestapel/stapel-docs/blob/main/MODULE.md).
Highlights: `STORAGE`, `DOC_TYPES`, `EXPORTERS`, `INGEST`, `REPLAY_WINDOW`,
`AUTO_REVISION_INTERVAL_SECONDS`, `TRASH_RETENTION_DAYS`, `RECENTS_MAX_PER_USER`,
`SEARCH_MAX_RESULTS`, `SHARING`. Thumbnail tiers are deliberately a fixed
constant, not a setting: the tier is part of a URL clients cache against.

## comm surface

| Kind | Name | Contract |
|---|---|---|
| Function (provides) | `docs.create_document` | `schemas/functions/docs.create_document.json` |
| Function (provides) | `docs.usage` | `schemas/functions/docs.usage.json` |
| Action (emit) | `document.created`, `document.updated`, `document.deleted`, `document.storage_changed` | `schemas/emits/*.json` |
| Action (consume) | `user.deleted` | GDPR anonymize (authorship nulled, content survives) |
| Action (consume) | `user.merged` | authorship re-parented to the surviving account (the opposite instruction to erasure); stars and recents folded on collision |
| Function (call) | `workspaces.check_capability` | provided by stapel-workspaces |

## Operations

```bash
python manage.py docs_purge_expired   # purge trash older than TRASH_RETENTION_DAYS
```

## Development

```bash
pip install -e . && pip install pytest pytest-django ruff jsonschema djangorestframework
./setup-hooks.sh
pytest tests/
```

## License

MIT — see [LICENSE](https://github.com/usestapel/stapel-docs/blob/main/LICENSE).

---

<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>
