sysnet-pyutils 1.7.12__tar.gz → 1.8.0__tar.gz

{sysnet_pyutils-1.7.12/sysnet_pyutils.egg-info → sysnet_pyutils-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysnet-pyutils
-Version: 1.7.12
+Version: 1.8.0
 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>
@@ -729,7 +729,7 @@ Knihovna obsahuje základní, v aplikacích hojně používané, utility pro Pyt
 
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Verze](https://img.shields.io/badge/version-1.7.12-blue.svg)](https://pypi.org/project/sysnet-pyutils/1.7.12/)
+[![Verze](https://img.shields.io/badge/version-1.8.0-blue.svg)](https://pypi.org/project/sysnet-pyutils/1.8.0/)
 [![Tests](https://github.com/SYSNET-CZ/pyutils/actions/workflows/ci.yml/badge.svg)](https://github.com/SYSNET-CZ/pyutils/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](tests/)
 
@@ -866,6 +866,26 @@ if config.loaded:
     db_url = config.config['database']
 ```
 
+Chování `Config`:
+
+- **Soubor:** ukládá se atomicky (dočasný soubor + přejmenování), čitelně (diakritika bez `\u` escape) a v pořadí klíčů z paměti. Nový soubor má práva 600 a chybějící adresáře
+  se vytvoří s právy 700; práva existujícího souboru se nemění a volnější než 600 se při načtení zalogují jako varování.
+- **Výchozí cesta:** nezadáte-li `config_path`, použije se proměnná prostředí `PYUTILS_CONFIG_PATH`. Bez ní platí dosavadní
+  umístění `conf/config.yml` vedle modulu (s varováním); není-li zapisovatelné, vyhodí se `ConfigError` s radou.
+- **Chyby:** poškozený YAML vyhodí `ConfigParseError` (podtřída `ConfigError` i `yaml.YAMLError`) s cestou, popisem a
+  řádkem, nikdy s obsahem souboru; soubor zůstane nepřepsaný.
+- **Nové výchozí hodnoty:** s existujícím souborem se `config_dict` ignoruje. Chcete-li po upgradu aplikace doplnit chybějící
+  klíče, použijte `Config(config_path=..., config_dict=..., merge_defaults=True)`: doplní se jen to, co v souboru chybí
+  (vnořené slovníky do hloubky, seznamy ne) a hodnoty ze souboru se nikdy nepřepíšou.
+- **Secrets:** hodnotu v YAML lze zadat odkazem `${env:NAZEV}` nebo `${file:/absolutni/cesta}` (i uvnitř textu, např.
+  `mongodb://u:${env:MONGO_PASSWORD}@h`); rozliší se při načtení na `Secret` (podtřída `str`, `repr` a log maskované,
+  `reveal()` vrací čistý `str`). Chybějící zdroj je `ConfigError`, nikdy tichý prázdný řetězec. `store()` zapisuje
+  zpět odkaz, nikdy hodnotu. `config.redacted()` vrací kopii pro health a debug, `config.audit()` cesty k heslům
+  v otevřené podobě. Doslovné `${` zapište jako `$${`. Viz `docs/adr/0001-config-secrets.md`.
+- **Vstup:** `config_dict` se při inicializaci zkopíruje; pozdější změny `config` neovlivní slovník volajícího a naopak.
+- **Opakované volání:** `Config(...)` vrací stále tutéž instanci; odlišná cesta nebo `config_dict` se ignoruje a zaloguje
+  se varování.
+
 #### Context a autentizace
 
 ```python
@@ -1355,12 +1375,12 @@ 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.
+1. Změňte `version` v `pyproject.toml` (například na `1.8.0`) 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:
 
    ```bash
-   git tag v1.7.12 && git push origin v1.7.12
+   git tag v1.8.0 && git push origin v1.8.0
    ```
 
 4. GitHub Actions automaticky provedou kontroly, build a publikaci.
@@ -1389,6 +1409,15 @@ při běžném vydání již lokálně nic nenahrávejte na PyPI.
 
 Podrobnosti nových změn jsou v [CHANGELOG.md](CHANGELOG.md).
 
+### Verze 1.8.0 (2026-10-27)
+
+- 🔐 `Config`: ochrana secrets. Hodnotu v YAML lze zadat odkazem `${env:NAZEV}` nebo `${file:/absolutni/cesta}`; rozlišuje se při načtení na nový typ `Secret` (maskovaný `repr`, `str` a log), `store()` zapisuje zpět odkaz, nikdy hodnotu. Nově `Config.redacted()` a `Config.audit()`. Viz `docs/adr/0001-config-secrets.md`.
+- 💾 `Config.store()` a `replace()` zapisují atomicky (dočasný soubor + přejmenování); nový soubor má práva 600, chybějící adresáře se vytvoří s právy 700.
+- ⚠️ `Config` bez `config_dict` má `config == {}` místo `None` a nezapisuje `null`; `config_dict` se při inicializaci kopíruje; YAML se ukládá čitelně (diakritika) a v pořadí klíčů z paměti. První `store()` po upgradu přepíše soubor v novém formátu.
+- ✅ `ConfigParseError` pro poškozený YAML (i `yaml.YAMLError`), výchozí cesta z `PYUTILS_CONFIG_PATH`, opt-in `merge_defaults=True`, varování při ignorovaných parametrech opakovaného `Config(...)`.
+
+Podrobnosti a dopady na stávající aplikace jsou v [CHANGELOG.md](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*`.
@@ -1526,6 +1555,6 @@ Tento projekt je licencován pod MIT licencí — viz [LICENSE](LICENSE) soubor.
  
  **Vytvořeno s ❤️ týmem SYSNET**
  
-*Verze: 1.7.12*
+*Verze: 1.8.0*
 
 *Datum: 2026-10-27*

{sysnet_pyutils-1.7.12 → sysnet_pyutils-1.8.0}/README.md

@@ -6,7 +6,7 @@ Knihovna obsahuje základní, v aplikacích hojně používané, utility pro Pyt
 
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Verze](https://img.shields.io/badge/version-1.7.12-blue.svg)](https://pypi.org/project/sysnet-pyutils/1.7.12/)
+[![Verze](https://img.shields.io/badge/version-1.8.0-blue.svg)](https://pypi.org/project/sysnet-pyutils/1.8.0/)
 [![Tests](https://github.com/SYSNET-CZ/pyutils/actions/workflows/ci.yml/badge.svg)](https://github.com/SYSNET-CZ/pyutils/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](tests/)
 
@@ -143,6 +143,26 @@ if config.loaded:
     db_url = config.config['database']
 ```
 
+Chování `Config`:
+
+- **Soubor:** ukládá se atomicky (dočasný soubor + přejmenování), čitelně (diakritika bez `\u` escape) a v pořadí klíčů z paměti. Nový soubor má práva 600 a chybějící adresáře
+  se vytvoří s právy 700; práva existujícího souboru se nemění a volnější než 600 se při načtení zalogují jako varování.
+- **Výchozí cesta:** nezadáte-li `config_path`, použije se proměnná prostředí `PYUTILS_CONFIG_PATH`. Bez ní platí dosavadní
+  umístění `conf/config.yml` vedle modulu (s varováním); není-li zapisovatelné, vyhodí se `ConfigError` s radou.
+- **Chyby:** poškozený YAML vyhodí `ConfigParseError` (podtřída `ConfigError` i `yaml.YAMLError`) s cestou, popisem a
+  řádkem, nikdy s obsahem souboru; soubor zůstane nepřepsaný.
+- **Nové výchozí hodnoty:** s existujícím souborem se `config_dict` ignoruje. Chcete-li po upgradu aplikace doplnit chybějící
+  klíče, použijte `Config(config_path=..., config_dict=..., merge_defaults=True)`: doplní se jen to, co v souboru chybí
+  (vnořené slovníky do hloubky, seznamy ne) a hodnoty ze souboru se nikdy nepřepíšou.
+- **Secrets:** hodnotu v YAML lze zadat odkazem `${env:NAZEV}` nebo `${file:/absolutni/cesta}` (i uvnitř textu, např.
+  `mongodb://u:${env:MONGO_PASSWORD}@h`); rozliší se při načtení na `Secret` (podtřída `str`, `repr` a log maskované,
+  `reveal()` vrací čistý `str`). Chybějící zdroj je `ConfigError`, nikdy tichý prázdný řetězec. `store()` zapisuje
+  zpět odkaz, nikdy hodnotu. `config.redacted()` vrací kopii pro health a debug, `config.audit()` cesty k heslům
+  v otevřené podobě. Doslovné `${` zapište jako `$${`. Viz `docs/adr/0001-config-secrets.md`.
+- **Vstup:** `config_dict` se při inicializaci zkopíruje; pozdější změny `config` neovlivní slovník volajícího a naopak.
+- **Opakované volání:** `Config(...)` vrací stále tutéž instanci; odlišná cesta nebo `config_dict` se ignoruje a zaloguje
+  se varování.
+
 #### Context a autentizace
 
 ```python
@@ -632,12 +652,12 @@ 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.
+1. Změňte `version` v `pyproject.toml` (například na `1.8.0`) 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:
 
    ```bash
-   git tag v1.7.12 && git push origin v1.7.12
+   git tag v1.8.0 && git push origin v1.8.0
    ```
 
 4. GitHub Actions automaticky provedou kontroly, build a publikaci.
@@ -666,6 +686,15 @@ při běžném vydání již lokálně nic nenahrávejte na PyPI.
 
 Podrobnosti nových změn jsou v [CHANGELOG.md](CHANGELOG.md).
 
+### Verze 1.8.0 (2026-10-27)
+
+- 🔐 `Config`: ochrana secrets. Hodnotu v YAML lze zadat odkazem `${env:NAZEV}` nebo `${file:/absolutni/cesta}`; rozlišuje se při načtení na nový typ `Secret` (maskovaný `repr`, `str` a log), `store()` zapisuje zpět odkaz, nikdy hodnotu. Nově `Config.redacted()` a `Config.audit()`. Viz `docs/adr/0001-config-secrets.md`.
+- 💾 `Config.store()` a `replace()` zapisují atomicky (dočasný soubor + přejmenování); nový soubor má práva 600, chybějící adresáře se vytvoří s právy 700.
+- ⚠️ `Config` bez `config_dict` má `config == {}` místo `None` a nezapisuje `null`; `config_dict` se při inicializaci kopíruje; YAML se ukládá čitelně (diakritika) a v pořadí klíčů z paměti. První `store()` po upgradu přepíše soubor v novém formátu.
+- ✅ `ConfigParseError` pro poškozený YAML (i `yaml.YAMLError`), výchozí cesta z `PYUTILS_CONFIG_PATH`, opt-in `merge_defaults=True`, varování při ignorovaných parametrech opakovaného `Config(...)`.
+
+Podrobnosti a dopady na stávající aplikace jsou v [CHANGELOG.md](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*`.
@@ -803,6 +832,6 @@ Tento projekt je licencován pod MIT licencí — viz [LICENSE](LICENSE) soubor.
  
  **Vytvořeno s ❤️ týmem SYSNET**
  
-*Verze: 1.7.12*
+*Verze: 1.8.0*
 
 *Datum: 2026-10-27*

{sysnet_pyutils-1.7.12 → sysnet_pyutils-1.8.0}/pyproject.toml

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

{sysnet_pyutils-1.7.12 → sysnet_pyutils-1.8.0}/sysnet_pyutils/__init__.py

@@ -123,9 +123,11 @@ from sysnet_pyutils.utils import (  # API klíče; Konverze; Hashe; Base64; Vali
     Config,
     ConfigError,
     ConfigFlag,
+    ConfigParseError,
     Context,
     Log,
     LoggedObject,
+    Secret,
     Singleton,
     api_key_generate,
     api_key_next,