cites-model 1.8.0

CITES Data Model

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

Třída	Popis
PermitTypeEnum	IMPORT / EXPORT / RE-EXPORT / OTHER
MetricEnum	NUMBER / WEIGHT / VOLUME / OTHER
BirthTypeEnum	DATE / INTERVAL / MONTH / OTHER
CertifiedEnum	Stupeň certifikace 1–7
CertifiedLegacyEnum	Certifikace 1–8 (historické dokumenty)
ValidityEnum	Platnost povolení 1–4
IssuingPurposeEnum	Účel vydání 1–5
IssuingPurposeLegacyEnum	Historický účel vydání 1–3
DeliveryEnum	Osobně / poštou
CertificateTypeEnum	LEG / COM / MOV
RegulationCitesEnum	Přílohy CITES (I, II, III)
RegulationEuEnum	Přílohy EU nařízení (A–D)
Regulation449Enum	Zákon č. 449 (myslivost)
PublishedEnum	Stav publikace
ThreeStateEnum	Třístavový boolean
DocumentCodeEnum	Kódy typů dokumentů (DD01–DD64)
AdditionalTypeEnum	Typy doplňkových dokumentů
GoodsIdentificationChangeEnum	N / CH / R
DiscardEnum	D / E / OR
StatementRequestedEnum	Stav žádosti o stanovisko
IntentEnum	Účel výjimky
ExceptionTypeEnum	Na transakci / na exemplář
AgreeKeyEnum, AgreeValueEnum	Klíče a hodnoty souhlasu

Typy osob

Třída	Základ	Popis
PersonReducedType	BaseModel	Redukovaný model pro tisky a přehledy
PersonExtendedType	PersonBaseType, GlobalModel	Plný model (žadatel, vývozce, dovozce) — birthdate → UTC
PersonHistoryItemType	PersonBaseType, GlobalModel	Vlastník v čase — date_from, date_to → UTC
PhoneNumberType	BaseModel	Telefonní číslo s prefixem
MailAddressType	BaseModel	E-mailová adresa s názvem

Modely zboží

Třída	Základ	Popis
TaxonItemType	BaseModel	Druh — propojení s taxonem v číselníku
GoodsQuantityType	BaseModel	Množství s metrikou a jednotkami
GoodsIdetificationType	BaseModel	Identifikace exempláře (čip, kroužek…)
GoodsIdetificationHistoryItemType	GoodsIdetificationType, GlobalModel	Historie identifikace — date_valid_from, date_valid_to → UTC
GoodsBirthType	GlobalModel	Datum a místo narození — birth_date → UTC
GoodsItemBaseType	BaseModel	Základní položka zboží
GoodsPrincipalTypeWrite	GoodsItemBaseType	Zápisový model zboží povolení
GoodsPrincipalType	GoodsPrincipalTypeWrite	Čtecí model — load_dds() pro DDS/Lotus
GoodsOrderType	BaseModel	Pořadí zboží v povolení
GoodsRequestType	GlobalModel	Žádost o zboží — date_import → UTC

Modely dokumentu

Třída	Základ	Popis
GeneralType	GlobalModel	Hlavička dokumentu — date_acquired, date_delivered, date_valid, date_valid_from → UTC
TransactionType	GlobalModel	Transakce (původ, dovoz, reexport) — date_issued, date_realized, date_canceled → UTC
IssuingType	GlobalModel	Vydavatel — date_issued → UTC
ConditionsType	BaseModel	Podmínky vydání
ConditionsLegacyType	BaseModel	Podmínky pro historické DD64
OtherType	GlobalModel	Ostatní údaje — date_statement → UTC
PermitStatusValidityType	GlobalModel	Stavová platnost EU-CITES — date → UTC
PermitStatusIntroductionType	GlobalModel	Uvedení na trh EU — date → UTC
PermitStatusType	BaseModel	Stavová informace EU-CITES
PermitStatusExtendedType	PermitStatusType	Rozšířená stavová informace
PermitSpecialConditionsType	BaseModel	Zvláštní podmínky povolení
DocumentPrincipalCustomsPermitType	GlobalModel	Celní údaje povolení — date_customs, date_returned → UTC
DocumentPrincipalCustomsGoodsType	GlobalModel	Celní údaje zboží — date_customs → UTC
RelatedType	BaseModel	Odkaz na související dokument
WorkflowCitesType	WorkflowType	Uzel životního cyklu
WorkflowListType	BaseListType	Historie životního cyklu dokumentu

cites_document — povolení CITES

Třída	Popis
CitesDocumentPrincipalTypeWrite	Zápisový model povolení
CitesDocumentPrincipalType	Čtecí model povolení + computed properties
CitesDocumentEntryListType	Seznam povolení pro přehledy

cites_additional — doplňkové dokumenty

Třída	Základ	Popis
CitesDocumentAdditionalTypeWrite	GlobalModel	Zápisový model — date_delivered, date_checkout, date_sold → UTC
CitesDocumentAdditionalType	CitesDocumentAdditionalTypeWrite	Čtecí model
CitesDocumentAdditionalEntryListType	BaseEntryListType	Seznam doplňkových dokumentů

cites_reg_card — registrační karty

Třída	Popis
CitesDocumentRegistrationCardTypeWrite	Zápisový model evidenčního listu
CitesDocumentRegistrationCardType	Čtecí model evidenčního listu

cites_statement — stanoviska AOPK

Třída	Základ	Popis
SpecimenParentType	GoodsItemBaseType	Rodičovský exemplář
SpecimenType	GoodsItemBaseType	Exemplář v žádosti o stanovisko
StatementCertificateType	StatementCertificateCommonsType, GlobalModel	Stanovisko k výjimce — date_valid → UTC
StatementCertificateComplementType	GlobalModel	Doplněk stanoviska — date_valid → UTC
StatementDocumentCertificateRequestType	—	Žádost o stanovisko k výjimce
StatementDocumentCertificateType	—	Dokument stanoviska k výjimce
StatementDocumentPermitType	—	Stanovisko k permitu

cites_taxon — taxony

Třída	Popis
TaxonEntryType	Položka taxonu (vědecký a obecný název, přílohy)
TaxonType	Plný model taxonu (taxonomická hierarchie)
TaxonEntryListType	Seznam taxonů pro číselníky

cites_template — šablony dokumentů

Třída	Popis
TemplateTypeEnum	Typy šablon
TemplateBaseType	Základní model šablony
TemplateFullType	Plný model šablony

customs_permit — celní výměna

Třída	Základ	Popis
CustomsExchangeCitesPermitType	GlobalModel	Model povolení pro celní systém — date_created, date_modified → UTC
CustomsExchangeCitesGoodsType	GlobalModel	Model zboží pro celní systém — date_created, date_modified → UTC

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

cites_swin — Single Window

Třída	Popis
SingleWindowType	Celní Single Window data

traces — TRACES NT integrace

Třída	Popis
TracesLogType	Záznam pro TRACES NT systém EU

---

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:

Vstup	Výstup
Naivní datetime (bez tzinfo)	Považován za Europe/Prague, převeden do UTC
datetime s tzinfo (např. CEST +02:00)	Převeden do UTC
datetime již v UTC	Beze změny
None	Propuštěn beze změny

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:

Soubor	Testy	Pokrytí
test_enums.py	13	Enumerace, PhoneNumberType, MailAddressType, TransportType
test_cites_common.py	19	PersonReducedType, GoodsPrincipalType, CountryHelpers
test_documents.py	11	CitesDocumentPrincipalType, Additional, RegistrationCard
test_customs_permit.py	4	CustomsExchangeCitesPermitType, load_production
test_statement_taxon.py	17	SpecimenType, StatementTypes, TaxonEntryType
test_integration.py	9	JSON roundtrip, fetch_cites_docs() mock
test_globalmodel_datetime.py	24	Normalizace datetime ve všech třídách s GlobalModel

---

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:

Verze	Přidáno
1.7.18	ConditionsLegacyType, kód DD64
1.7.4	statement_request, date_statement, related_permit v OtherType
1.7	e_permit_purpose, e_permit_status v OtherType
1.6	Balíček cites_statement (stanoviska AOPK)
1.5.9	sysnet-pyutils >= 1.3.10, MetadataTypeBase.comment
1.5	Atribut history v hlavních dokumentech a zboží
1.4	Balíček customs_permit (celní výměna)
1.3.5	Přesun do repozitáře SYSNET-CZ/models
1.3.3	TaxonType.is_active, ThreeStateEnum
1.3	Balíček cites_additional
1.2	Balíček cites_template
1.1	Balíček cites_taxon, enumerace regulací
1.0	Základní modely (osoby, zboží, povolení, workflow)

---

Licence

Free For Home Use — viz soubor LICENSE.md.