Metadata-Version: 2.4
Name: flametrench-file
Version: 0.4.0
Summary: File-metadata primitive for Flametrench: storage-agnostic metadata, lifecycle, and authz-mediated access (ADR 0020).
Author: NDC Digital, LLC
License: Apache-2.0
Project-URL: Homepage, https://flametrench.dev
Project-URL: Repository, https://github.com/flametrench/file-python
Project-URL: Specification, https://github.com/flametrench/spec
Keywords: flametrench,file-metadata,files,uploads,lifecycle
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: flametrench-ids>=0.4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# flametrench-file

File-metadata primitive for the Flametrench v0.4 platform ([ADR 0020](https://github.com/flametrench/spec/blob/main/decisions/0020-file-metadata-primitive.md)).

## What this is

Metadata and lifecycle for files — no blob bytes in the contract. `storage_ref` is an opaque adopter pointer (S3 key, GCS path, URL) stored verbatim; the primitive never dereferences it. Access is mediated by `authz` (ADR 0001); a `file_` record is an authz object.

**Lifecycle:** `pending` → `active` (freezes size_bytes/checksum/storage_ref) → `deleted` (soft — record retained). Deleted files remain fetchable.

## Install

```
pip install flametrench-file
```

Requires Python ≥ 3.11 and `flametrench-ids >= 0.4.0`.

## Quick start

```python
from flametrench_file import InMemoryFileStore

store = InMemoryFileStore()

# Register directly as active
f = store.create_file_metadata(
    scope="org_...",
    owner_usr_id="usr_...",
    name="q3-report.pdf",
    content_type="application/pdf",
    size_bytes=184320,
    checksum={"algo": "sha-256", "value": "e3b0c44..."},
    storage_ref="s3://bucket/q3-report.pdf",
    status="active",
)

# Or: pending handshake → activate on upload complete
p = store.create_file_metadata(
    scope="org_...", owner_usr_id="usr_...",
    name="upload.bin", content_type="application/octet-stream",
    status="pending",
)
store.update_file_metadata(
    p.id, status="active",
    size_bytes=4096,
    checksum={"algo": "sha-256", "value": "9f86d08..."},
    storage_ref="s3://bucket/upload.bin",
)
```

## License

Apache-2.0 © NDC Digital, LLC
