Metadata-Version: 2.4
Name: sdsavior
Version: 1.0.1
Summary: Crash-recoverable memory-mapped ring buffer for JSON records (SD-card friendly-ish)
Author-email: Antonio D'Angelo <antonio@bastardi.net>
License: CC0-1.0
License-File: LICENSE
Keywords: durability,embedded,jsonl,mmap,raspberry-pi,ring-buffer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: System :: Logging
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# sdsavior
Most likely i have re-invented the wheel here. But i was to lazy to find something like this. 
So, here you go...

A crash-recoverable, memory-mapped ring buffer for JSON records, designed for SD-card-ish environments
(where constant small writes are a fun way to speedrun media death).

## Install

```bash
pip install sdsavior
```

## Quick Start

```python
from sdsavior import SDSavior

rb = SDSavior(
    data_path="data.ring",
    meta_path="data.meta",
    capacity_bytes=8 * 1024 * 1024,
)

rb.open()
rb.append({"hello": "pi"})
rb.append({"n": 123})

for seq, ts_ns, obj in rb.iter_records():
    print(seq, ts_ns, obj)

rb.close()
```

Or with a context manager:

```python
from sdsavior import SDSavior

with SDSavior("data.ring", "data.meta", 8 * 1024 * 1024) as rb:
    rb.append({"ok": True})
```

## CLI
Export current contents to a JSONL

```bash
sdsavior export --data data.ring --meta data.meta --capacity 8388608 --out out.jsonl
```

## IMPORTANT NOTES
- Records are stored as JSON lines (`\\n` appended).
- Metadata is double-buffered with CRC and a commit counter for crash recovery.
- By default it does not fsync data pages on every append (to reduce wear); metadata is fsync'd.

# TODO
- fix ci for pypy publishing...