Datový model CITES

Knihovna Python s kompletním datovým modelem pro informační systém CITES (Convention on International Trade in Endangered Species).

Postaveno na Pydantic v2. Od verze 1.8.0 všechny třídy s atributy datetime dědí z GlobalModel — datum a čas je vždy ukládán v UTC.

Instalace

pip install cites-model

Nebo přímo z repozitáře:

pip install git+https://github.com/SYSNET-CZ/models.git#subdirectory=cites

Rychlý start

from cites_model import (
    CitesDocumentPrincipalType,
    GeneralType,
    PermitTypeEnum,
    IssuingType,
)
from datetime import datetime

doc = CitesDocumentPrincipalType(
    doc_code="DD01",
    document=GeneralType(
        id_no="24CZ123456",
        permit_type=PermitTypeEnum.EXPORT,
        date_valid=datetime(2025, 12, 31),   # naivní → automaticky UTC
    ),
    issuing=IssuingType(
        date_issued=datetime(2024, 6, 15, 10, 0),  # naivní → UTC
        issuing_authority="MŽP",
    ),
)
print(doc.document.date_valid)  # 2025-12-30T23:00:00+00:00  (UTC)

Struktura balíčku

cites_model/
├── __init__.py          # Veřejné API — 100+ exportů + __all__
├── cites_common.py      # Sdílené modely (osoby, zboží, workflow)
├── cites_document.py    # Povolení CITES (DD01–DD08)
├── cites_additional.py  # Doplňkové dokumenty
├── cites_reg_card.py    # Registrační karty (evidenční listy)
├── cites_statement.py   # Stanoviska k výjimkám (AOPK)
├── cites_taxon.py       # Taxony (druhy živočichů a rostlin)
├── cites_template.py    # Šablony dokumentů
├── cites_swin.py        # Integrace Single Window (celnictví)
├── customs_permit.py    # Celní výměna dat
└── traces.py            # Integrace TRACES NT (EU systém)

Moduly a třídy

cites_common — sdílené základní typy

Enumerace

Typy osob

Modely zboží

Modely dokumentu

cites_document — povolení CITES

cites_additional — doplňkové dokumenty

cites_reg_card — registrační karty

cites_statement — stanoviska AOPK

cites_taxon — taxony

cites_template — šablony dokumentů

customs_permit — celní výměna

Konverzní metody load_production() mapují CitesDocumentPrincipalType → CustomsExchangeCitesPermitType.

cites_swin — Single Window

traces — TRACES NT integrace

Zpracování data a času (od verze 1.8.0)

Všechny třídy s atributy datetime dědí z GlobalModel (sysnet_pyutils.globalmodel.GlobalModel).

GlobalModel zajišťuje jednotnou normalizaci při každém přiřazení hodnoty:

from cites_model import GeneralType
from datetime import datetime

# Naivní datetime — automaticky Europe/Prague → UTC
g = GeneralType(date_valid=datetime(2025, 6, 15, 12, 0))
print(g.date_valid)  # 2025-06-15T10:00:00+00:00

Závislosti

pydantic[email] >= 2.11.3
sysnet-pyutils  >= 1.7.4
typing-extensions >= 4

Testování

# Unit testy (bez API)
cd D:\development\git\models\cites
.venv\Scripts\python.exe -m pytest tests/ -m "not integration" -v

# Vč. integračních (vyžaduje .env s CITES_DOCS_API_KEY)
.venv\Scripts\python.exe -m pytest tests/ -v

Testovací soubory:

Historie verzí

Verze 1.8.0

Migrace na GlobalModel — správné ukládání data a času.

Všechny třídy s atributy datetime nyní dědí z GlobalModel (místo BaseModel). Naivní datetime je automaticky lokalizován jako Europe/Prague a převeden do UTC před uložením.

Migrované třídy (18 tříd ve 4 souborech):

• cites_common.py (13): PersonExtendedType, PersonHistoryItemType, GeneralType, TransactionType, IssuingType, PermitStatusValidityType, PermitStatusIntroductionType, OtherType, DocumentPrincipalCustomsPermitType, GoodsIdetificationHistoryItemType, GoodsBirthType, GoodsRequestType, DocumentPrincipalCustomsGoodsType
• cites_additional.py (1): CitesDocumentAdditionalTypeWrite
• cites_statement.py (2): StatementCertificateType, StatementCertificateComplementType
• customs_permit.py (2): CustomsExchangeCitesPermitType, CustomsExchangeCitesGoodsType

Přidán testovací soubor tests/test_globalmodel_datetime.py (24 testů). Celkem 106 testů passing.

Poslední verze s BaseModel jako základem je 1.7.28.

Verze 1.7.27 a starší

Viz docs/dev_diary.md pro podrobný přehled změn v předchozích verzích.

Stručný přehled:

Licence

Free For Home Use — viz soubor LICENSE.md.