sysnet-docversion 0.1.0

Versioned document library for MongoDB built on Pydantic 2 and Beanie 2

docversion

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

pip install sysnet-docversion

Nebo s uv:

uv add sysnet-docversion

Rychlý start

1. Definujte model dokumentu

from docversion import VersionedDocument

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

    class Settings:
        name = "clanky"

2. Inicializujte databázi

from docversion import init_db

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

3. Práce s verzemi

# 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

# 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í:

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

DOCVERSION_ENABLED=0  # vypnuto globálně

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

await clanek.save_version(versioning=False)

Přepínání soft-delete

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

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 — asynchronní ODM pro MongoDB
• Pydantic v2 — validace dat
• pymongo ≥ 4.9 — AsyncMongoClient (bez Motor)
• sysnet-soft-delete — mixin pro soft-delete

Licence

Tento projekt je licencován pod GNU Affero General Public License v3.0.