sysnet-pyutils 1.7.4__tar.gz → 1.7.5__tar.gz

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysnet-pyutils
-Version: 1.7.4
+Version: 1.7.5
 Summary: SYSNET Python Utilities - kompletní sada nástrojů pro Python aplikace
 Author-email: Data Developer <info@sysnet.cz>
 Maintainer-email: SYSNET Development Team <info@sysnet.cz>
@@ -958,6 +958,7 @@ from sysnet_pyutils import (
     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'}
@@ -977,6 +978,21 @@ paging = paging_to_mongo(start=20, page_size=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
 ```
 
 ---
@@ -1299,6 +1315,14 @@ pyutils/
 
 ## 📚 Changelog
 
+### 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:**

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/README.md

@@ -235,6 +235,7 @@ from sysnet_pyutils import (
     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'}
@@ -254,6 +255,21 @@ paging = paging_to_mongo(start=20, page_size=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
 ```
 
 ---
@@ -576,6 +592,14 @@ pyutils/
 
 ## 📚 Changelog
 
+### 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:**

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sysnet-pyutils"
-version = "1.7.4"
+version = "1.7.5"
 description = "SYSNET Python Utilities - kompletní sada nástrojů pro Python aplikace"
 readme = "README.md"
 license = { file = "LICENSE" }

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/sysnet_pyutils/__init__.py

@@ -62,6 +62,8 @@ from sysnet_pyutils.data_utils import (
     get_dict_value_string,
     get_dict_value_uuid,
     get_object_attr,
+    localize_datetime,
+    normalize_datetime,
     paging_to_mongo,
     recursive_update,
 )

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/sysnet_pyutils/data_utils.py

@@ -333,6 +333,50 @@ def adjust_datetime_to_utc(date_value: date | datetime | None, for_store: bool =
     return date_value
 
 
+def normalize_datetime(value: date | datetime | None) -> datetime | None:
+    """
+    Převede date nebo datetime na datetime v UTC.
+
+    Naivní datetime (bez tzinfo) dostane časovou zónu dle env proměnné TZ (výchozí: Europe/Prague).
+    Čistý date se převede na půlnoc v lokální zóně (TZ), poté na UTC.
+    Hodnota None je vrácena beze změny.
+
+    :param value:   Vstupní datum nebo datetime
+    :return:        datetime v UTC, nebo None
+    """
+    if value is None:
+        return None
+    local_tz = pytz.timezone(TZ)
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = local_tz.localize(value)
+        return value.astimezone(pytz.UTC)
+    # čistý date → půlnoc v lokální zóně → UTC
+    return local_tz.localize(datetime(value.year, value.month, value.day, 0, 0, 0)).astimezone(pytz.UTC)
+
+
+def localize_datetime(value: date | datetime | None) -> datetime | None:
+    """
+    Převede date nebo datetime na datetime v lokální časové zóně (dle env proměnné TZ).
+
+    Naivní datetime (bez tzinfo) je považován za UTC.
+    Čistý date se převede na půlnoc v UTC, poté do lokální zóny.
+    Hodnota None je vrácena beze změny.
+
+    :param value:   Vstupní datum nebo datetime
+    :return:        datetime v lokální zóně (TZ), nebo None
+    """
+    if value is None:
+        return None
+    local_tz = pytz.timezone(TZ)
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = pytz.UTC.localize(value)
+        return value.astimezone(local_tz)
+    # čistý date → půlnoc v UTC → lokální zóna
+    return pytz.UTC.localize(datetime(value.year, value.month, value.day, 0, 0, 0)).astimezone(local_tz)
+
+
 def dict_convert_date_to_str(data: dict | list) -> None:
     """
     Rekurzivně převede všechny časové položky ve slovníku na ISO text

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/sysnet_pyutils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysnet-pyutils
-Version: 1.7.4
+Version: 1.7.5
 Summary: SYSNET Python Utilities - kompletní sada nástrojů pro Python aplikace
 Author-email: Data Developer <info@sysnet.cz>
 Maintainer-email: SYSNET Development Team <info@sysnet.cz>
@@ -958,6 +958,7 @@ from sysnet_pyutils import (
     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'}
@@ -977,6 +978,21 @@ paging = paging_to_mongo(start=20, page_size=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
 ```
 
 ---
@@ -1299,6 +1315,14 @@ pyutils/
 
 ## 📚 Changelog
 
+### 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:**

{sysnet_pyutils-1.7.4 → sysnet_pyutils-1.7.5}/sysnet_pyutils.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ sysnet_pyutils/syslog/factory.py
 tests/test_cron_utils.py
 tests/test_cron_validation_edge.py
 tests/test_data_utils.py
+tests/test_data_utils_datetime.py
 tests/test_data_utils_edge.py
 tests/test_data_utils_missing_branches.py
 tests/test_domino.py

sysnet_pyutils-1.7.5/tests/test_data_utils_datetime.py

@@ -0,0 +1,156 @@
+"""
+Testy pro normalize_datetime a localize_datetime v sysnet_pyutils.data_utils
+"""
+
+from datetime import date, datetime
+
+import pytz
+import pytest
+
+from sysnet_pyutils.data_utils import localize_datetime, normalize_datetime
+
+# Referenční zóna shodná s výchozí TZ env proměnnou (Europe/Prague)
+PRAGUE = pytz.timezone("Europe/Prague")
+UTC = pytz.UTC
+
+
+# ---------------------------------------------------------------------------
+# normalize_datetime
+# ---------------------------------------------------------------------------
+
+class TestNormalizeDatetime:
+    """normalize_datetime → výstup vždy datetime v UTC (nebo None)"""
+
+    def test_none_returns_none(self):
+        assert normalize_datetime(None) is None
+
+    def test_naive_datetime_treated_as_local(self):
+        # naivní 2024-03-10 12:00:00 → Prague je UTC+1 (zimní čas)
+        naive = datetime(2024, 3, 10, 12, 0, 0)
+        result = normalize_datetime(naive)
+        expected = PRAGUE.localize(naive).astimezone(UTC)
+        assert result == expected
+
+    def test_naive_datetime_summer_time(self):
+        # letní čas: Prague je UTC+2
+        naive = datetime(2024, 7, 1, 12, 0, 0)
+        result = normalize_datetime(naive)
+        expected = PRAGUE.localize(naive).astimezone(UTC)
+        assert result == expected
+
+    def test_aware_utc_unchanged(self):
+        aware = datetime(2024, 6, 15, 10, 0, 0, tzinfo=UTC)
+        result = normalize_datetime(aware)
+        assert result == aware
+        assert result.tzinfo == UTC
+
+    def test_aware_prague_converted_to_utc(self):
+        aware = PRAGUE.localize(datetime(2024, 6, 15, 12, 0, 0))
+        result = normalize_datetime(aware)
+        assert result.tzinfo == UTC
+        assert result == aware.astimezone(UTC)
+
+    def test_date_midnight_local_to_utc(self):
+        # date 2024-01-15 → půlnoc v Prague (UTC+1 zimní čas) → 23:00 předchozího dne UTC
+        d = date(2024, 1, 15)
+        result = normalize_datetime(d)
+        expected = PRAGUE.localize(datetime(2024, 1, 15, 0, 0, 0)).astimezone(UTC)
+        assert result == expected
+        assert result.tzinfo == UTC
+
+    def test_date_summer_midnight_local_to_utc(self):
+        # date 2024-07-01 → půlnoc v Prague (UTC+2) → 22:00 předchozího dne UTC
+        d = date(2024, 7, 1)
+        result = normalize_datetime(d)
+        expected = PRAGUE.localize(datetime(2024, 7, 1, 0, 0, 0)).astimezone(UTC)
+        assert result == expected
+
+    def test_result_is_always_datetime(self):
+        assert isinstance(normalize_datetime(date(2024, 1, 1)), datetime)
+        assert isinstance(normalize_datetime(datetime(2024, 1, 1)), datetime)
+
+    def test_result_tzinfo_is_utc(self):
+        result = normalize_datetime(datetime(2024, 5, 1, 8, 0, 0))
+        assert result.utcoffset().total_seconds() == 0
+
+
+# ---------------------------------------------------------------------------
+# localize_datetime
+# ---------------------------------------------------------------------------
+
+class TestLocalizeDatetime:
+    """localize_datetime → výstup vždy datetime v lokální zóně (TZ) nebo None"""
+
+    def test_none_returns_none(self):
+        assert localize_datetime(None) is None
+
+    def test_naive_datetime_treated_as_utc(self):
+        # naivní → považuje se za UTC → převede do Prague
+        naive = datetime(2024, 3, 10, 11, 0, 0)
+        result = localize_datetime(naive)
+        expected = UTC.localize(naive).astimezone(PRAGUE)
+        assert result == expected
+
+    def test_aware_utc_converted_to_local(self):
+        aware = datetime(2024, 1, 15, 23, 0, 0, tzinfo=UTC)
+        result = localize_datetime(aware)
+        # UTC+1 zimní čas → 00:00 následujícího dne v Prague
+        assert result.tzinfo.zone == "Europe/Prague"
+        assert result == aware.astimezone(PRAGUE)
+
+    def test_aware_prague_unchanged_zone(self):
+        aware = PRAGUE.localize(datetime(2024, 6, 15, 12, 0, 0))
+        result = localize_datetime(aware)
+        assert result.tzinfo.zone == "Europe/Prague"
+
+    def test_date_midnight_utc_to_local(self):
+        # date 2024-07-01 → půlnoc UTC → 02:00 Prague (UTC+2 letní čas)
+        d = date(2024, 7, 1)
+        result = localize_datetime(d)
+        expected = UTC.localize(datetime(2024, 7, 1, 0, 0, 0)).astimezone(PRAGUE)
+        assert result == expected
+        assert result.tzinfo.zone == "Europe/Prague"
+
+    def test_date_winter_midnight_utc_to_local(self):
+        # date 2024-01-15 → půlnoc UTC → 01:00 Prague (UTC+1 zimní čas)
+        d = date(2024, 1, 15)
+        result = localize_datetime(d)
+        expected = UTC.localize(datetime(2024, 1, 15, 0, 0, 0)).astimezone(PRAGUE)
+        assert result == expected
+
+    def test_result_is_always_datetime(self):
+        assert isinstance(localize_datetime(date(2024, 1, 1)), datetime)
+        assert isinstance(localize_datetime(datetime(2024, 1, 1)), datetime)
+
+    def test_result_tzinfo_is_local(self):
+        result = localize_datetime(datetime(2024, 5, 1, 8, 0, 0))
+        assert result.tzinfo.zone == "Europe/Prague"
+
+
+# ---------------------------------------------------------------------------
+# Symetrie: roundtrip normalize → localize
+# ---------------------------------------------------------------------------
+
+class TestRoundtrip:
+    """normalize_datetime a localize_datetime jsou inverzní operace."""
+
+    @pytest.mark.parametrize("naive", [
+        datetime(2024, 1, 15, 10, 30, 0),
+        datetime(2024, 7, 1, 0, 0, 0),
+        datetime(2024, 3, 31, 1, 30, 0),   # těsně před přechodem na letní čas
+    ])
+    def test_normalize_then_localize_roundtrip(self, naive):
+        utc = normalize_datetime(naive)
+        back = localize_datetime(utc)
+        # Po roundtripu musí být hodnota čas. shodná
+        assert back.astimezone(UTC) == utc
+
+    @pytest.mark.parametrize("d", [
+        date(2024, 1, 15),
+        date(2024, 7, 1),
+    ])
+    def test_date_normalize_then_localize(self, d):
+        utc = normalize_datetime(d)
+        local = localize_datetime(utc)
+        # Půlnoc v lokální zóně → UTC → zpět do lokální → stále půlnoc
+        assert local.hour == 0 and local.minute == 0 and local.second == 0