Metadata-Version: 2.4
Name: sysnet-docversion
Version: 0.1.3
Summary: Versioned document library for MongoDB built on Pydantic 2 and Beanie 2
Project-URL: Source Code, https://github.com/SYSNET-CZ/docversion
Project-URL: Bug Tracker, https://github.com/SYSNET-CZ/docversion/issues
Author-email: SYSNET CZ <info@sysnet.cz>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: beanie,document,fastapi,mongodb,pydantic,versioning
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: beanie>=2
Requires-Dist: pydantic>=2
Requires-Dist: pymongo[srv]>=4.9
Requires-Dist: sysnet-soft-delete>=0.2.1
Description-Content-Type: text/markdown

# docversion

[![PyPI version](https://img.shields.io/pypi/v/sysnet-docversion)](https://pypi.org/project/sysnet-docversion/)
[![PyPI status](https://img.shields.io/pypi/status/sysnet-docversion)](https://pypi.org/project/sysnet-docversion/)
[![Python versions](https://img.shields.io/pypi/pyversions/sysnet-docversion)](https://pypi.org/project/sysnet-docversion/)
[![Downloads](https://img.shields.io/pypi/dm/sysnet-docversion)](https://pypi.org/project/sysnet-docversion/)
[![License: AGPL v3](https://img.shields.io/badge/license-AGPL%20v3-blue)](LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![mypy](https://img.shields.io/badge/mypy-checked-2A6DB2)](https://mypy-lang.org/)

Python knihovna pro správu verzí dokumentů postavená na **Pydantic 2**, **Beanie 2** a **MongoDB**. Navržena pro použití ve FastAPI projektech.

## Požadavky

- Python ≥ 3.11
- MongoDB ≥ 6
- pymongo ≥ 4.9 (přímé async rozhraní bez Motor)

## Instalace

```bash
pip install sysnet-docversion
```

Nebo s uv:

```bash
uv add sysnet-docversion
```

## Rychlý start

### 1. Definujte model dokumentu

```python
from docversion import VersionedDocument

class Clanek(VersionedDocument):
    nazev: str
    obsah: str

    class Settings:
        name = "clanky"
```

### 2. Inicializujte databázi

```python
from docversion import init_db

await init_db("mongodb://localhost:27017", "moje_db", [Clanek])
```

### 3. Práce s verzemi

```python
# Vytvoření dokumentu
clanek = Clanek(nazev="Úvod", obsah="Hello, world!")
await clanek.insert()

# Uložení s verzí
clanek.obsah = "Upravený obsah"
await clanek.save_version(author="alice", message="první úprava")

# Výpis verzí
verze = await clanek.list_versions()
for v in verze:
    print(f"v{v.version} — {v.author}: {v.message}")

# Načtení konkrétní verze
snapshot = await clanek.get_version(1)
print(snapshot.data)

# Návrat k předchozí verzi
await clanek.revert_to_version(1, author="bob", message="vrátit k v1")
```

### 4. Soft-delete

```python
# Smazání (soft)
await clanek.soft_delete(deleted_by="alice")

# Obnovení
await clanek.restore(restored_by="bob")
```

## Konfigurace

### Přepínání verzování

Verzování lze vypnout na úrovni třídy nebo prostřednictvím proměnné prostředí:

```python
class Clanek(VersionedDocument):
    class Settings:
        name = "clanky"
        versioning = False  # vypnuto pro celou třídu
```

```bash
DOCVERSION_ENABLED=0  # vypnuto globálně
```

Pro jednorázové volání bez verze:

```python
await clanek.save_version(versioning=False)
```

### Přepínání soft-delete

```python
class Clanek(VersionedDocument):
    class Settings:
        name = "clanky"
        soft_delete = False  # vždy fyzické smazání
```

```bash
DOCVERSION_SOFT_DELETE_ENABLED=0
```

## API

### `VersionedDocument`

| Metoda | Popis |
|--------|-------|
| `save_version(author, message, *, versioning)` | Uloží dokument a volitelně zaznamená snapshot verze |
| `list_versions()` | Vrátí seznam metadat verzí seřazených vzestupně |
| `get_version(version)` | Načte plný snapshot dané verze |
| `revert_to_version(to_version, author, message)` | Obnoví pole dokumentu do stavu dané verze; vytvoří nový snapshot |
| `soft_delete(deleted_by, *, soft_delete)` | Označí dokument jako smazaný (nebo fyzicky odstraní) |
| `restore(restored_by)` | Obnoví soft-smazaný dokument |

### `DocumentVersion`

Neměnný snapshot uložený v kolekci `document_versions`. Obsahuje pole `data` (dict), `version` (int), `author`, `message` a `created_at`.

### `init_db(mongodb_uri, database, document_models)`

Inicializuje Beanie ODM. Musí být zavoláno před jakýmikoli DB operacemi.

## Závislosti

- [Beanie](https://beanie-odm.dev/) — asynchronní ODM pro MongoDB
- [Pydantic v2](https://docs.pydantic.dev/) — validace dat
- [pymongo ≥ 4.9](https://www.mongodb.com/docs/drivers/pymongo/) — `AsyncMongoClient` (bez Motor)
- [sysnet-soft-delete](https://pypi.org/project/sysnet-soft-delete/) — mixin pro soft-delete

## Licence

Tento projekt je licencován pod [GNU Affero General Public License v3.0](LICENSE).
