sysnet-pyutils 1.7.0

SYSNET Python Utilities - kompletní sada nástrojů pro Python aplikace

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
  • models.general
• Testování
• Vývoj
• Changelog
• Podpora

---

🚀 Instalace

Základní instalace

pip install sysnet-pyutils

Instalace z repository

git clone https://github.com/your-org/pyutils.git
cd pyutils
pip install -e .

Požadavky

• Python 3.10+
• Dependencies (automaticky nainstalovány):
  • pydantic>=2.0
  • pytz
  • python-dateutil
  • PyYAML
  • xmltodict
  • croniter (pro cron_utils)

---

⚡ Rychlý start

from sysnet_pyutils import utils as pu

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

# Práce s datumy
today = pu.today()  # ISO 8601 datum
tomorrow = pu.tomorrow()

# Validace
is_valid = pu.is_valid_email("[e-mail]")
is_valid_ico = pu.is_valid_ico("12345678")

# Hash funkce
hash_val = 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.

Singleton pattern

from sysnet_pyutils.utils import Singleton

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

# Vždy vrátí stejnou instanci
instance1 = MyClass()
instance2 = MyClass()
assert instance1 is instance2

Konfigurace

from sysnet_pyutils.utils import Config

# Vytvoření konfigurace
config = Config(
    config_path='app_config.yml',
    config_dict={'database': 'mongodb://localhost'}
)

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

Identifikátory a validace

from sysnet_pyutils import utils as pu

# PID (12místný identifikátor s kontrolním součtem)
pid = pu.pid_next()  # Generování
is_valid = pu.pid_check(pid)  # Validace
corrected = pu.pid_correct("BAD_PID")  # Oprava

# UUID
uuid = pu.uuid_next(uuid_type=4)  # UUID verze 4
is_valid = pu.is_valid_uuid(uuid)

# IČO
is_valid = pu.is_valid_ico("27074358")
repaired = pu.repair_ico("2707435X")

# Email
is_valid = pu.is_valid_email("[e-mail]")

Hash funkce

from sysnet_pyutils import utils as pu

text = "Hello World"

md5 = pu.hash_md5(text)  # MD5 (zastaralé)
sha1 = pu.hash_sha1(text)  # SHA-1
sha256 = pu.hash_sha256(text)  # SHA-256
sha384 = pu.hash_sha384(text)  # SHA-384

Datum a čas

from sysnet_pyutils import utils as pu
from datetime import date

# Aktuální datum
today = pu.today()  # ISO 8601 string
tomorrow = pu.tomorrow()

# Konverze
dt = pu.date_to_datetime(date(2023, 5, 15))
dt_utc = pu.date_to_datetime_utc(date(2023, 5, 15))
iso_str = pu.date_to_iso(date(2023, 5, 15))

# Časové zóny
local_time = pu.local_now()  # Lokální čas
gmt_time = pu.gmt_now()  # GMT/UTC čas

Base64

from sysnet_pyutils import utils as pu

# String ↔ Base64
encoded = pu.encode_string_b64("Hello")
decoded = pu.decode_b64_string(encoded)

# File ↔ Base64
b64_data = pu.encode_file_b64("input.txt")
pu.decode_b64_to_file(b64_data, "output.txt")

Case konverze

from sysnet_pyutils import utils as pu

# String
snake = pu.to_snake("camelCase")  # "camel_case"
camel = pu.to_camel("snake_case")  # "snakeCase"

# Dictionary
data = {"firstName": "John", "lastName": "Doe"}
snake_dict = pu.to_snake_dict(data)
# {"first_name": "John", "last_name": "Doe"}

camel_dict = pu.to_camel_dict(snake_dict)
# {"firstName": "John", "lastName": "Doe"}

XML

from sysnet_pyutils import utils as pu

# XML → Dict
xml = "<root><name>John</name><age>30</age></root>"
data = pu.xml_to_dict(xml)

# Dict → XML
xml_str = pu.dict_to_xml(data)

CITES utility

from sysnet_pyutils import utils as pu

# Číslo ↔ Písmena (CITES notace)
letters = pu.order_to_cites(1458)  # "BDB"
number = pu.cites_to_order("BDB")  # 1458

Context a API klíče

from sysnet_pyutils.utils import Context, api_keys_init

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

# Použití Context pro autentizaci
config = {
    'my_app': {
        'api_keys': keys
    }
}

ctx = Context(config=config)
if ctx.check_api_key('some_key'):
    print(f"Authenticated as: {ctx.user_name}")

---

data_utils.py

Utility pro práci s daty, převody typů a získávání hodnot ze slovníků.

from sysnet_pyutils import data_utils as du

# Získávání hodnot ze slovníků
data = {'name': 'John', 'age': '30', 'email': '[e-mail]'}

name = du.get_dict_value_string(data, 'name')
age = du.get_dict_value_int(data, 'age')
email = du.get_dict_value_email(data, 'email')

# Konverze datumů
date_obj = du.convert_iso_to_date('2023-05-15')
date_cz = du.convert_cz_to_date('15.05.2023')

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

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

---

domino.py

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

from sysnet_pyutils.domino import DdsDictionaryFactory

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

factory = DdsDictionaryFactory(dds_data)

# Získání hodnot
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')

# Nastavení hodnot
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.geo import Wgs84, JTSK

# WGS84 souřadnice (např. z GPS)
wgs = Wgs84(latitude=50.0755, longitude=14.4378, altitude=200.0)

# Konverze na S-JTSK
jtsk = JTSK(0, 0)
jtsk.from_wgs84(lon=wgs.longitude, lat=wgs.latitude, alt=wgs.altitude)

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

---

cron_utils

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

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

# Syntaktická validace
is_valid = is_cron_syntax_valid("0 9 * * 1-5")  # True
is_valid = is_cron_syntax_valid("60 * * * *")  # False

# Sémantická validace (existuje budoucí výskyt?)
has_next = has_next_occurrence("0 0 29 2 *")  # True (v přestupném roce)
has_next = has_next_occurrence("0 0 31 2 *")  # False (31.2. neexistuje)

# Kompletní validace
is_valid, errors = validate_cron("0 9 * * 1-5")
if not is_valid:
    print(f"Chyby: {errors}")

# Sumarizace
summary = summarize_cron("0 9 * * 1-5")
if summary.syntax_ok:
    print(f"Další spuštění: {summary.next_run}")

---

models.general

Datové modely kompatibilní s FastAPI a Pydantic.

from sysnet_pyutils.models.general import (
    PersonBaseType,
    LocationType,
    GeoPointType,
    CodeValueType,
    MetadataType,
    PersonTypeEnum
)

# Vytvoření osoby
person = PersonBaseType(
    name="Test Company s.r.o.",
    ico="12345678",
    email="[e-mail]",
    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")
    )
)

# Vytvoření identifikátoru
person.unid = "3005277CB984B7FFC12587890060E2BF"
person.make_identifier()  # Vytvoří identifier z unid

# Metadata
metadata = MetadataType(
    title="Important Document",
    form="certificate",
    authorized=True
)

---

🧪 Testování

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

Spuštění testů

# Všechny testy
pytest

# S podrobným výstupem
pytest -v

# S pokrytím kódu
pytest --cov=sysnet_pyutils --cov-report=html

# Konkrétní modul
pytest tests/test_utils.py -v

Diagnostika

# Automatická diagnostika problémů
python diagnose_tests.py

# Test runner s rozumnými defaulty
python run_tests.py

# Kontrola syntaxe
python tests/check_tests.py

Řešení problémů

Pokud testy selhávají, přečtěte si:

• tests/TROUBLESHOOTING.md - Řešení běžných problémů
• FIXES_APPLIED.md - Dokumentace oprav
• CONFIG_FIX.md - Specifické opravy Config testů

---

👨‍💻 Vývoj

Struktura projektu

pyutils/
├── sysnet_pyutils/          # Hlavní balíček
│   ├── __init__.py
│   ├── utils.py             # Hlavní modul
│   ├── data_utils.py        # Data utility
│   ├── domino.py            # Domino DDS
│   ├── geo.py               # Geografické transformace
│   ├── ident.py             # Identifikátory
│   ├── barcode.py           # Čárové kódy
│   ├── constants.py         # Konstanty
│   ├── cron_utils/          # Cron utility
│   ├── models/              # Datové modely
│   ├── globalmodel/         # Globální modely
│   └── syslog/              # Syslog factory
├── tests/                    # Testy (pytest)
│   ├── conftest.py          # Pytest konfigurace
│   ├── test_utils.py
│   ├── test_data_utils.py
│   ├── test_geo.py
│   ├── test_cron_utils.py
│   ├── test_domino.py
│   ├── test_models_general.py
│   ├── README.md            # Dokumentace testů
│   └── TROUBLESHOOTING.md   # Řešení problémů
├── pytest.ini               # Pytest konfigurace
├── pyproject.toml           # Build konfigurace
├── README.md                # Tato dokumentace
└── LICENSE                  # Licence

Přidání nové funkcionality

1. Vytvořte funkci v příslušném modulu
2. Napište testy v tests/test_<module>.py
3. Spusťte testy: pytest
4. Zkontrolujte pokrytí: pytest --cov
5. Aktualizujte dokumentaci (README.md)

Code style

Dodržujte Python konvence:

• PEP 8 pro formátování kódu
• Type hints pro všechny veřejné funkce
• Docstringy pro všechny moduly, třídy a funkce

---

📚 Changelog

Verze 1.7.0 (2026-02-13)

🎉 Hlavní změny:

• ✅ Kompletní testovací pokrytí (~435 testů, 90%+ coverage)
• ✅ Opravy importů v domino.py, log.py, ses.py
• ✅ Oprava exception handling syntaxe v domino.py
• ✅ Standardizace type hints v data_utils.py
• ✅ Diagnostické nástroje pro testy
• ✅ Kompletní dokumentace testů

📁 Nové soubory:

• tests/conftest.py - Pytest fixtures
• diagnose_tests.py - Diagnostický nástroj
• run_tests.py - Test runner
• tests/TROUBLESHOOTING.md - Průvodce řešením problémů
• Kompletní sada testů pro všechny moduly

🔧 Opravy:

• Import chyby napříč moduly
• Config singleton konflikty v testech
• Type hints standardizace
• Exception handling syntax

Verze 1.6.0

• Přidán balíček cron_utils pro validaci cron výrazů
• Vyžaduje knihovnu croniter

Verze 1.5.0

• Nový singleton SyslogFactory pro 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.4

• Přidán PersonTypeEnum z CITES modelu

Verze 1.2.0

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

Verze 1.1.3

• PersonBaseType rozšířen o identifier a make_identifier()

Verze 1.1.0

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

Verze 1.0.8

• Nové utility data_utils
• Přidána validace emailů

Verze 1.0.6

• YAML konfigurace v UTF-8
• Nová třída LoggedObject

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()

---

🛠 Systémové proměnné

Následující proměnné prostředí lze použít pro konfiguraci:

Proměnná	Popis	Výchozí hodnota
TZ	Časová zóna	'Europe/Prague'
DEBUG	Debug režim	True
LOG_FORMAT	Formát logování	'%(asctime)s - %(levelname)s in %(module)s: %(message)s'
LOG_DATE_FORMAT	Formát data v logu	'%d.%m.%Y %H:%M:%S'
LOG_FILE	Soubor pro logování	None
PID_PREFIX	Prefix pro PID	'SNT'

Příklad:

export TZ='UTC'
export DEBUG='False'
export PID_PREFIX='APP'
python my_app.py

---

📞 Podpora

Problém s testy?

1. Přečtěte si tests/TROUBLESHOOTING.md
2. Spusťte diagnostiku: python diagnose_tests.py
3. Zkontrolujte FIXES_APPLIED.md a CONFIG_FIX.md

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. Zajistěte, že všechny testy procházejí
5. Vytvořte pull request

---

📄 Licence

Tento projekt je licencován pod MIT licencí - viz LICENSE soubor pro detaily.

---

🙏 Poděkování

Děkujeme všem přispěvatelům a uživatelům knihovny sysnet-pyutils.

---

Vytvořeno s ❤️ týmem SYSNET

Verze: 1.6.1
Datum: 2026-02-13