sysnet-pyutils

SYSNET Python Utilities Library

Knihovna obsahuje základní, v aplikacích hojně používané, utility pro Python projekty.

📋 Obsah

• Instalace
• Rychlý start
• Moduly
  • utils
  • data_utils
  • domino
  • geo
  • cron_utils
  • globalmodel
  • log
  • ses
  • syslog
  • models.general
  • Info/Health modely
• Volitelné závislosti
• Testování
• Vývoj
  • CI/CD
• Systémové proměnné
• Changelog
• Podpora

🚀 Instalace

Základní instalace

pip install sysnet-pyutils

S volitelnými závislostmi

# Podpora AWS SES
pip install sysnet-pyutils[aws]

# Podpora MongoDB
pip install sysnet-pyutils[mongodb]

# Podpora cron validace
pip install sysnet-pyutils[cron]

# Vše najednou
pip install sysnet-pyutils[all]

Instalace z repository

git clone https://github.com/SYSNET-CZ/pyutils.git
cd pyutils
pip install -e .

Požadavky

• Python 3.10+
• Hlavní závislosti (automaticky nainstalovány):
  • pydantic[email]>=2.10.6
  • pytz>=2023.3
  • python-dateutil>=2.8.2
  • PyYAML>=6.0.1
  • xmltodict>=1.0.0
  • typing-extensions>=4.12.0

⚡ Rychlý start

import sysnet_pyutils as pu

# Generování identifikátorů
pid = pu.pid_next()
uuid = pu.uuid_next()

# Validace
is_valid = pu.is_valid_email("test@example.com")
is_valid_ico = pu.is_valid_ico("27074358")

# Datum a čas
today = pu.today()
now = pu.local_now()

# Hash
sha256 = pu.hash_sha256("text")

# Konfigurace
config = pu.Config(config_path='config.yml', config_dict={'key': 'value'})

📦 Moduly

utils.py — Hlavní modul

Obsahuje nejčastěji používané utility funkce, třídy a vzory.

Singleton pattern

from sysnet_pyutils import Singleton

class MyClass(metaclass=Singleton):
    def __init__(self):
        self.value = 42

instance1 = MyClass()
instance2 = MyClass()
assert instance1 is instance2  # Vždy stejná instance

Konfigurace

from sysnet_pyutils import Config

config = Config(
    config_path='app_config.yml',
    config_dict={'database': 'mongodb://localhost'}
)

if config.loaded:
    db_url = config.config['database']

Context a autentizace

from sysnet_pyutils import Context, api_keys_init

# Generování API klíčů
keys = api_keys_init(agenda='my_app', amount=3)

config = {'my_app': {'api_keys': keys}}

ctx = Context(config=config)
if ctx.check_api_key('some_key'):
    print(f"Přihlášen jako: {ctx.user_name}")

Identifikátory a validace

from sysnet_pyutils import pid_next, pid_check, pid_correct
from sysnet_pyutils import is_valid_uuid, is_valid_ico, is_valid_email, repair_ico

# PID — 12místný identifikátor s kontrolním součtem
pid = pid_next()
is_valid = pid_check(pid)
corrected = pid_correct("SNT12345678X")

# Validace
is_valid_ico("27074358")           # True
is_valid_email("user@example.com") # True
repair_ico("2707435X")             # Opraví kontrolní součet

Hash funkce

from sysnet_pyutils import hash_md5, hash_sha1, hash_sha256, hash_sha384

sha256 = hash_sha256("Hello World")

Datum a čas

from sysnet_pyutils import local_now, gmt_now, today, tomorrow
from sysnet_pyutils import date_to_datetime, date_to_datetime_utc, date_to_iso
from datetime import date

dt = date_to_datetime(date(2023, 5, 15))      # datetime v lokální TZ
dt_utc = date_to_datetime_utc(date(2023, 5, 15))  # datetime v UTC
iso = date_to_iso(date(2023, 5, 15))          # "2023-05-15"

Base64

from sysnet_pyutils import encode_string_b64, decode_b64_string
from sysnet_pyutils import encode_file_b64, decode_b64_to_file

encoded = encode_string_b64("Hello")
decoded = decode_b64_string(encoded)

Konverze case a XML

from sysnet_pyutils import to_snake, to_camel, to_snake_dict, to_camel_dict
from sysnet_pyutils import xml_to_dict, dict_to_xml

snake = to_snake("camelCase")        # "camel_case"
camel = to_camel("snake_case")       # "snakeCase"
data = xml_to_dict("<root><n>X</n></root>")

CITES utility

from sysnet_pyutils import order_to_cites, cites_to_order

letters = order_to_cites(1458)  # "BDB"
number = cites_to_order("BDB")  # 1458

data_utils.py

Utility pro práci se slovníky, konverzi typů a stránkování MongoDB.

from sysnet_pyutils import (
    get_dict_value_string, get_dict_value_int, get_dict_value_float,
    get_dict_value_bool, get_dict_value_date, get_dict_value_datetime,
    get_dict_value_email, get_dict_value_code, get_dict_value_uuid,
    convert_iso_to_date, convert_cz_to_date,
    paging_to_mongo, address_to_string,
    normalize_datetime, localize_datetime,
)

data = {'name': 'John', 'age': '30', 'email': 'john@example.com'}

name = get_dict_value_string(data, 'name')   # "John"
age = get_dict_value_int(data, 'age')         # 30
email = get_dict_value_email(data, 'email')   # "john@example.com"

# Konverze datumů
d = convert_iso_to_date('2023-05-15')
d_cz = convert_cz_to_date('15.05.2023')

# Stránkování pro MongoDB
paging = paging_to_mongo(start=20, page_size=10)
# {'start': 0, 'page': 2, 'skip': 20, 'limit': 10}

# Adresa na string
address = {'street': 'Main St 123', 'city': 'Prague', 'zip': '110 00'}
addr_str = address_to_string(address)

# Normalizace datetime na UTC
# Naivní datetime dostane zónu dle env TZ (výchozí: Europe/Prague), pak se převede na UTC.
# Čistý date → půlnoc v lokální zóně → UTC.
from datetime import date, datetime
utc_dt = normalize_datetime(datetime(2024, 7, 1, 12, 0, 0))   # naive → Prague → UTC
utc_dt = normalize_datetime(date(2024, 7, 1))                  # půlnoc Prague → UTC
utc_dt = normalize_datetime(None)                              # None → None

# Lokalizace datetime do lokální zóny (env TZ)
# Naivní datetime se považuje za UTC a převede do lokální zóny.
# Čistý date → půlnoc UTC → lokální zóna.
local_dt = localize_datetime(datetime(2024, 7, 1, 10, 0, 0))  # naive UTC → Prague
local_dt = localize_datetime(date(2024, 7, 1))                 # půlnoc UTC → Prague
local_dt = localize_datetime(None)                             # None → None

domino.py

Práce s HCL Domino Data Service (DDS).

from sysnet_pyutils import DdsDictionaryFactory

dds_data = {
    'Title': 'Test Document',
    'DateCreated': '2023-05-15T10:00:00',
    'IsActive': '1',
    'Amount': '99.99'
}

factory = DdsDictionaryFactory(dds_data)

title = factory.get_value_string('Title')
is_active = factory.get_value_bool('IsActive')
amount = factory.get_value_float('Amount')
date_created = factory.get_value_datetime('DateCreated')

factory.set_value_string('Status', 'Approved')
factory.set_value_bool('Published', True)

geo.py

Geografické transformace — konverze mezi WGS84 a S-JTSK.

from sysnet_pyutils import Wgs84, JTSK

wgs = Wgs84(latitude=50.0755, longitude=14.4378, altitude=200.0)

jtsk = JTSK(0, 0)
jtsk.from_wgs84(lon=wgs.longitude, lat=wgs.latitude, alt=wgs.altitude)

print(f"JTSK X: {jtsk.x:.2f}, Y: {jtsk.y:.2f}")

cron_utils

Validace cron výrazů (syntaktická i sémantická).

Vyžaduje volitelnou závislost: pip install sysnet-pyutils[cron]

from sysnet_pyutils.cron_utils.validation import (
    is_cron_syntax_valid,
    has_next_occurrence,
    validate_cron,
    summarize_cron,
)

# Syntaktická validace
is_cron_syntax_valid("0 9 * * 1-5")   # True
is_cron_syntax_valid("60 * * * *")    # False — minuta mimo rozsah

# Sémantická validace
has_next_occurrence("0 0 31 2 *")     # False — 31.2. nikdy nenastane

# Kompletní validace
is_valid, errors = validate_cron("0 9 * * 1-5")

# Sumarizace s dalším výskytem
summary = summarize_cron("0 9 * * 1-5")
if summary.syntax_ok and summary.has_occurrence:
    print(f"Další spuštění: {summary.next_run}")

globalmodel

Pydantic BaseModel s automatickou normalizací datetime do UTC.

from sysnet_pyutils import GlobalModel, PRAGUE_TZ
from datetime import datetime

class MyModel(GlobalModel):
    created_at: datetime | None = None

# Naivní datetime je považován za Europe/Prague a převeden na UTC
m = MyModel(created_at=datetime(2023, 5, 15, 10, 0, 0))
print(m.created_at)  # 2023-05-15 08:00:00+00:00 (UTC)

log.py

MongoDB logging handler.

Vyžaduje volitelnou závislost: pip install sysnet-pyutils[mongodb]

import logging
from sysnet_pyutils.log import MongoHandler

logger = logging.getLogger("myapp")
logger.addHandler(MongoHandler(
    host="localhost",
    port=27017,
    database="logging",
    collection="app_logs",
))

logger.error("Nastala chyba!")

ses.py

Odesílání e-mailů přes Amazon SES.

Vyžaduje volitelnou závislost: pip install sysnet-pyutils[aws]

from sysnet_pyutils.ses import SesFactory

ses = SesFactory(
    aws_region='eu-west-1',
    aws_access_key='KEY',
    aws_secret_access_key='SECRET',
    sender='noreply@example.com',
)

ses.send_email(
    recipient='user@example.com',
    subject='Test',
    body_text='Tělo zprávy v plain textu.',
    body_html='<p>Tělo zprávy v HTML.</p>',
)

syslog

Asynchronní odesílání zpráv na syslog server (UDP/TCP).

import asyncio
from sysnet_pyutils import SyslogFactory

syslog = SyslogFactory(server="192.168.1.10", port=514, tag="my-app")

async def main():
    await syslog.log_info("Aplikace spuštěna")
    await syslog.log_error("Nastala chyba")

asyncio.run(main())

models.general

Datové modely kompatibilní s FastAPI a Pydantic v2.

from sysnet_pyutils import (
    PersonBaseType, LocationType, GeoPointType,
    CodeValueType, MetadataType, PersonTypeEnum,
    LogItemType, WorkflowType,
)

# Osoba
person = PersonBaseType(
    name="Test Company s.r.o.",
    ico="27074358",
    email="info@test.com",
    location=LocationType(
        street="Main Street 123",
        city="Prague",
        zip="110 00",
        wgs=GeoPointType(lat=50.0755, lon=14.4378),
        country=CodeValueType(code="CZ", value="Czech Republic"),
    ),
)
person.unid = "3005277CB984B7FFC12587890060E2BF"
person.make_identifier()

# Metadata — default_factory zajistí aktuální čas při každém vytvoření
metadata = MetadataType(title="Important Document", form="certificate")
print(metadata.date_created)  # Aktuální čas

# Log položka
log_item = LogItemType(message="Dokument autorizován", originator="SYSTEM")
print(str(log_item))  # "2023-05-15 10:00:00 [SYSTEM] Dokument autorizován"

Info/Health modely

Sjednocený formát pro sledování zdraví služby (health check).

from sysnet_pyutils import InfoType, InfoComponentType, InfoStatusEnum, calculate_status

info = InfoType(name="My Service", version="1.0.0")

# Přidání komponenty (např. MongoDB)
info.components.append(InfoComponentType(
    name="mongo",
    status=InfoStatusEnum.GREEN,
    message="Connected to localhost:27017"
))

# Přidání další komponenty s chybou
info.components.append(InfoComponentType(
    name="storage",
    status=InfoStatusEnum.RED,
    message="Disk space low"
))

# Automatický výpočet celkového statusu (RED > YELLOW > GREEN)
info.status = calculate_status([component.status for component in info.components])
print(info.status)  # RED

🔌 Volitelné závislosti

Poznámka: Moduly ses.py a log.py lze importovat i bez příslušných závislostí. ImportError se vyhodí až při pokusu o instanciaci SesFactory / MongoHandler.

🧪 Testování

Knihovna obsahuje komplexní sadu testů s >90% pokrytím kódu.

Spuštění testů

# Z kořenového adresáře projektu
cd ~/projects/pyutils

# Všechny testy
.venv/bin/python -m pytest tests/

# S podrobným výstupem
.venv/bin/python -m pytest tests/ -v

# S pokrytím kódu
.venv/bin/python -m pytest tests/ --cov=sysnet_pyutils --cov-report=html

# Konkrétní modul
.venv/bin/python -m pytest tests/test_utils.py -v

Testovací soubory

👨‍💻 Vývoj

Struktura projektu

pyutils/
├── .github/workflows/       # GitHub Actions CI/CD
│   ├── ci.yml               # Syntax check, pytest, ruff
│   └── release.yml          # Ověření verze, testy, build a publikace na PyPI
├── sysnet_pyutils/          # Hlavní balíček
│   ├── __init__.py          # Veřejné API
│   ├── utils.py             # Hlavní utility modul
│   ├── data_utils.py        # Utility pro slovníky a typy
│   ├── domino.py            # HCL Domino DDS
│   ├── geo.py               # Geografické transformace (WGS84 ↔ JTSK)
│   ├── ident.py             # Identifikátory (PID, ID12)
│   ├── barcode.py           # Code39 čárové kódy
│   ├── constants.py         # Konfigurační konstanty
│   ├── log.py               # MongoDB logging handler
│   ├── ses.py               # AWS SES e-mail
│   ├── tools.py             # Singleton dekorátor
│   ├── cron_utils/          # Validace cron výrazů
│   │   └── validation.py
│   ├── globalmodel/         # GlobalModel s UTC normalizací
│   │   ├── global_model.py
│   │   ├── timeutils.py
│   │   └── models.py
│   ├── models/              # Pydantic datové modely
│   │   └── general.py
│   └── syslog/              # Syslog UDP/TCP klient
│       └── factory.py
├── tests/                   # Pytest testy
│   ├── conftest.py
│   └── test_*.py
├── conf/                    # Výchozí konfigurace
├── logs/                    # Adresář pro logy
├── pyproject.toml           # Build a nástroje
├── requirements.txt         # Závislosti (legacy)
├── CHANGELOG.md             # Přehled změn a vydání
└── LICENSE

Přidání nové funkcionality

1. Implementujte funkci v příslušném modulu
2. Exportujte ji v sysnet_pyutils/__init__.py
3. Napište testy v tests/test_<modul>.py
4. Spusťte testy: .venv/bin/python -m pytest tests/
5. Aktualizujte README.md a CHANGELOG.md

CI/CD

Automatizaci zajišťují GitHub Actions na self-hosted runneru s Pythonem 3.11:

Obě workflow používají čistý checkout, před instalací mažou pip cache a pro testy instalují .[dev,cron,mongodb], včetně potřebných volitelných závislostí. Ruff je v CI zatím informativní (ruff check sysnet_pyutils/ || true); chyby syntaxe a testů naopak workflow zastaví.

Release workflow porovnává tag bez prefixu v s verzí v pyproject.toml. Při nesouladu nebo selhání testů se nepublikuje. Po úspěšných kontrolách vytvoří distribuční balíčky pomocí python -m build a nahraje je přes twine. GitHub secret PYPI_API_TOKEN je nastaven v repozitáři a poskytuje token pro PyPI; token nepatří do zdrojového kódu.

Vydání nové verze

1. Změňte version v pyproject.toml (například na 1.7.12) a aktualizujte dokumentaci včetně changelogu a badge.

2. Commitněte změny a dostaňte je na main; před vytvořením tagu ověřte úspěšné CI a správný release commit.

3. Na tomto commitu vytvořte a odešlete odpovídající tag:

   git tag v1.7.12 && git push origin v1.7.12
   

4. GitHub Actions automaticky provedou kontroly, build a publikaci. Výsledek sledujte v Release workflow.

Původní ruční postup (python -m build a twine upload, dříve i Windows skripty upload.ps1 a upload.cmd, odstraněné ve verzi 1.7.12) je nahrazen touto pipeline; při běžném vydání již lokálně nic nenahrávejte na PyPI.

🛠 Systémové proměnné

📚 Changelog

Podrobnosti nových změn jsou v CHANGELOG.md.

Verze 1.7.12 (2026-10-27)

• ✅ GitHub Actions CI/CD: kontrola syntaxe, pytest a ruff při push/PR na main; ověření verze, testy, build a publikace na PyPI při tagu v*.

• ✅ Opraveny starší chyby v tests/test_models_general.py: InfoComponentType(code=...) → name=..., neexistující update_status() → funkce calculate_status().

• ✅ Doplněny veřejné exporty InfoComponentType, InfoStatusEnum, InfoType a calculate_status v sysnet_pyutils/__init__.py.

• ✅ Ukázka Info/Health výše odpovídá aktuálnímu API (name, message, calculate_status).

• 🧹 Odstraněny sledované pomocné soubory (mypy_*.txt, upload.cmd, upload.ps1, run_pytest.py, REVIZE_PROJEKTU.md); Windows cesty v README a CLAUDE.md nahrazeny linuxovými.

Verze 1.7.11 (2026-09-25)

• ✅ MetadataEssentialType.creator: str | None — sjednocení s MetadataTypeBase, výchozí hodnota None (#10229).

Verze 1.7.10 (2026-09-25)

• ✅ MetadataEssentialType.creator_organization: LinkedType | None — organizace tvůrce i v základních metadatech, výchozí hodnota None (#10229).

Verze 1.7.9 (2026-09-25)

• ✅ MetadataTypeBase.creator_organization: LinkedType | None — organizace tvůrce dokumentu, výchozí hodnota None (#10229).

Verze 1.7.6 (2026-06-19)

Nové funkce:

• ✅ models/general.py — přidán InfoType, InfoComponentType a InfoStatusEnum pro sjednocené health checky napříč mikroslužbami (#9991)
• ✅ tests/test_models_general.py — doplněny testy pro výpočet statusu v InfoType

Verze 1.7.5 (2026-04-07)

Nové funkce:

• ✅ data_utils.py — přidána normalize_datetime(date | datetime | None) -> datetime | None: naivní vstup dostane zónu dle TZ, výstup vždy UTC
• ✅ data_utils.py — přidána localize_datetime(date | datetime | None) -> datetime | None: naivní vstup se považuje za UTC, výstup v lokální zóně dle TZ
• ✅ Obě funkce exportovány z sysnet_pyutils/__init__.py
• ✅ 22 nových testů v tests/test_data_utils_datetime.py (včetně DST hraničních případů a roundtrip testů)

Verze 1.7.1 (2026-03-02)

Opravy:

• ✅ constants.py — doplněna chybějící konstanta CONFIG_PASSWORD
• ✅ ses.py — import boto3 přesunut do lazy guardu (try/except ImportError)
• ✅ log.py — import pymongo přesunut do lazy guardu (try/except ImportError)
• ✅ data_utils.py — opraven zahozený výsledek datetime.replace() v adjust_datetime_to_utc()
• ✅ models/general.py — Field(default=local_now()) nahrazeno Field(default_factory=local_now) na 4 místech
• ✅ utils.py — email regex rozšířen na subdomény a TLD libovolné délky
• ✅ tests/conftest.py — bare except: nahrazeno except Exception:
• ✅ pyproject.toml — ruff konfigurace aktualizována na [tool.ruff.lint]
• ✅ sysnet_pyutils/__init__.py — doplněno kompletní veřejné API balíčku
• ✅ sysnet_pyutils/syslog/__init__.py — doplněn export SyslogFactory
• ✅ Odstraněno 21 dočasných/analytických souborů z kořenového adresáře

Verze 1.6.1

• ✅ Kompletní testovací pokrytí (251 testů, >90% coverage)
• ✅ Modernizace pyproject.toml
• ✅ Opravy singleton konfliktů v testech

Verze 1.6.0

• Přidán balíček cron_utils pro validaci cron výrazů

Verze 1.5.0

• Nový SyslogFactory pro asynchronní odesílání logů

Verze 1.4.9

• Atribut authorized přesunut do MetadataTypeBase

Verze 1.4.8

• Přidána funkce get_dict_value_as_person_type()

Verze 1.4.4

• Přidána funkce address_to_string()

Verze 1.4.0

• Do PersonBaseType přidána strukturovaná adresa location

Verze 1.3.10

• Do MetadataTypeBase přidán atribut comment

Verze 1.3.5

• Do PersonBaseType přidán atribut person_printable

Verze 1.3.1

• Přidán modul constants.py

Verze 1.3.0

• Přidána třída Context pro ověřování API klíčů

Verze 1.2.0

• UUID → str v modelech (pro MongoDB)
• Přidán BaseEnum s metodou has_value

Verze 1.1.0

• Přidán datový slovník models.general (Pydantic)

Verze 1.0.8

• Nové utility data_utils

Verze 1.0.5

• Přidána třída DdsDictionaryFactory
• Funkce local_now(), is_valid_unid()

Verze 1.0.4

• CITES utility: order_to_cites(), cites_to_order()

Verze 1.0.3

• Case konverze: to_camel(), to_snake()
• XML utility: xml_to_dict(), dict_to_xml()

📞 Podpora

Našli jste bug?

1. Zkontrolujte existující issues
2. Vytvořte nový issue s:
   • Popisem problému
   • Kroky k reprodukci
   • Očekávané a skutečné chování
   • Verze Python a sysnet-pyutils

Chcete přispět?

1. Forkněte repository
2. Vytvořte feature branch
3. Přidejte testy pro novou funkcionalitu
4. Ověřte, že všechny testy procházejí
5. Vytvořte pull request

📄 Licence

Tento projekt je licencován pod MIT licencí — viz LICENSE soubor.

Vytvořeno s ❤️ týmem SYSNET

Verze: 1.7.12

Datum: 2026-10-27