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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysnet-pyutils
-Version: 1.7.12
+Version: 1.9.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.9.0-blue.svg)](https://pypi.org/project/sysnet-pyutils/1.9.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
@@ -881,6 +901,44 @@ if ctx.check_api_key('some_key'):
     print(f"Přihlášen jako: {ctx.user_name}")
 ```
 
+> **`Context` je singleton se sdíleným stavem.** `check_api_key()` ukládá identitu do jediné instance, kterou sdílejí
+> všechny souběžné požadavky. Ve webové službě (FastAPI) může jeden požadavek po `await` vidět identitu jiného.
+> Pokus se dvěma souběžnými požadavky to potvrdil: `Context` vrátil první osobě jméno druhé.
+> **Ověřování API klíčů patří knihovně `sysnet-apikeys`** (standard CML `api-keys.md`); `check_api_key()` a
+> **Ověřování API klíčů patří knihovně `sysnet-apikeys`** (standard CML `api-keys.md`); `check_api_key()`,
+> `check_user()` a `api_keys_init()` jsou zastaralé (`DeprecationWarning`) a zůstávají jen kvůli stávajícím službám.
+> Tajemství (`config`, `api_key`, `cert_pass`) se čtou jako dřív, ale nejsou ve `vars()`, v `repr` ani v `pickle`/`copy`;
+> pro diagnostiku slouží `ctx.safe_dict()`.
+
+##### Per-request kontext (`RequestContext`)
+
+`RequestContext` jen **nese** identitu ověřenou jinde, v `ContextVar`, takže ji každý požadavek vidí jen svou.
+Ověřuje `sysnet-apikeys`; služba převede jeho `Principal` na kontext:
+
+```python
+from fastapi import Depends
+from sysnet_apikeys.fastapi import ApiKeyAuth
+from sysnet_pyutils import RequestContext, current_request_context, set_request_context
+
+auth = ApiKeyAuth(service)  # sysnet-apikeys
+
+
+async def authenticated(principal=Depends(auth)) -> RequestContext:
+    ctx = RequestContext(user_name=principal.client, agenda=principal.agenda)
+    set_request_context(ctx)
+    return ctx
+
+
+# kdekoli později ve stejném požadavku:
+agenda = current_request_context().agenda
+```
+
+- `RequestContext` je neměnný (`frozen`); `api_key` a `cert_pass` jsou typu `Secret` (repr a log skrývají hodnotu).
+- `authenticated` je `True`, nese-li kontext identitu (`user_name` nebo `api_key`); samotná `agenda` ji nedělá.
+- Kontext nastavujte v **`async def`** závislosti. `ContextVar` nastavený v synchronní závislosti (`def`, běží ve vlákně)
+  se do endpointu nepřenese; ověřeno pokusem s FastAPI 0.150. Případně použijte hodnotu vrácenou z `Depends`.
+- Pro dočasné nastavení v bloku: `with use_request_context(ctx): ...` (vždy vrátí předchozí hodnotu).
+
 #### Identifikátory a validace
 
 ```python
@@ -1355,12 +1413,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 +1447,24 @@ 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.9.0 (2026-10-28)
+
+- 🧭 `RequestContext`: nosič identity jednoho požadavku v `ContextVar` (`set_request_context`, `current_request_context`, `use_request_context`); souběžné požadavky se nevidí. Ověřování API klíčů záměrně neobsahuje, patří knihovně `sysnet-apikeys`.
+- ⚠️ `Context.check_api_key()`, `Context.check_user()` a `api_keys_init()` jsou zastaralé (`DeprecationWarning` jednou za proces); chování pro platné konfigurace se nemění.
+- 🛡️ `Context`: vadná konfigurace nebo klíč jiného typu než neprázdný řetězec vrací `False` místo výjimky.
+- 🔐 `Context`: tajemství (`config`, `api_key`, `cert_pass`) nejsou ve `vars()`, v `repr` ani v `pickle`/`copy`; čtení atributů beze změny, nová metoda `safe_dict()`.
+
+Podrobnosti a dopady na stávající aplikace 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 +1602,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.9.0*
 
 *Datum: 2026-10-27*

{sysnet_pyutils-1.7.12 → sysnet_pyutils-1.9.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.9.0-blue.svg)](https://pypi.org/project/sysnet-pyutils/1.9.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
@@ -158,6 +178,44 @@ if ctx.check_api_key('some_key'):
     print(f"Přihlášen jako: {ctx.user_name}")
 ```
 
+> **`Context` je singleton se sdíleným stavem.** `check_api_key()` ukládá identitu do jediné instance, kterou sdílejí
+> všechny souběžné požadavky. Ve webové službě (FastAPI) může jeden požadavek po `await` vidět identitu jiného.
+> Pokus se dvěma souběžnými požadavky to potvrdil: `Context` vrátil první osobě jméno druhé.
+> **Ověřování API klíčů patří knihovně `sysnet-apikeys`** (standard CML `api-keys.md`); `check_api_key()` a
+> **Ověřování API klíčů patří knihovně `sysnet-apikeys`** (standard CML `api-keys.md`); `check_api_key()`,
+> `check_user()` a `api_keys_init()` jsou zastaralé (`DeprecationWarning`) a zůstávají jen kvůli stávajícím službám.
+> Tajemství (`config`, `api_key`, `cert_pass`) se čtou jako dřív, ale nejsou ve `vars()`, v `repr` ani v `pickle`/`copy`;
+> pro diagnostiku slouží `ctx.safe_dict()`.
+
+##### Per-request kontext (`RequestContext`)
+
+`RequestContext` jen **nese** identitu ověřenou jinde, v `ContextVar`, takže ji každý požadavek vidí jen svou.
+Ověřuje `sysnet-apikeys`; služba převede jeho `Principal` na kontext:
+
+```python
+from fastapi import Depends
+from sysnet_apikeys.fastapi import ApiKeyAuth
+from sysnet_pyutils import RequestContext, current_request_context, set_request_context
+
+auth = ApiKeyAuth(service)  # sysnet-apikeys
+
+
+async def authenticated(principal=Depends(auth)) -> RequestContext:
+    ctx = RequestContext(user_name=principal.client, agenda=principal.agenda)
+    set_request_context(ctx)
+    return ctx
+
+
+# kdekoli později ve stejném požadavku:
+agenda = current_request_context().agenda
+```
+
+- `RequestContext` je neměnný (`frozen`); `api_key` a `cert_pass` jsou typu `Secret` (repr a log skrývají hodnotu).
+- `authenticated` je `True`, nese-li kontext identitu (`user_name` nebo `api_key`); samotná `agenda` ji nedělá.
+- Kontext nastavujte v **`async def`** závislosti. `ContextVar` nastavený v synchronní závislosti (`def`, běží ve vlákně)
+  se do endpointu nepřenese; ověřeno pokusem s FastAPI 0.150. Případně použijte hodnotu vrácenou z `Depends`.
+- Pro dočasné nastavení v bloku: `with use_request_context(ctx): ...` (vždy vrátí předchozí hodnotu).
+
 #### Identifikátory a validace
 
 ```python
@@ -632,12 +690,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 +724,24 @@ 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.9.0 (2026-10-28)
+
+- 🧭 `RequestContext`: nosič identity jednoho požadavku v `ContextVar` (`set_request_context`, `current_request_context`, `use_request_context`); souběžné požadavky se nevidí. Ověřování API klíčů záměrně neobsahuje, patří knihovně `sysnet-apikeys`.
+- ⚠️ `Context.check_api_key()`, `Context.check_user()` a `api_keys_init()` jsou zastaralé (`DeprecationWarning` jednou za proces); chování pro platné konfigurace se nemění.
+- 🛡️ `Context`: vadná konfigurace nebo klíč jiného typu než neprázdný řetězec vrací `False` místo výjimky.
+- 🔐 `Context`: tajemství (`config`, `api_key`, `cert_pass`) nejsou ve `vars()`, v `repr` ani v `pickle`/`copy`; čtení atributů beze změny, nová metoda `safe_dict()`.
+
+Podrobnosti a dopady na stávající aplikace 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 +879,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.9.0*
 
 *Datum: 2026-10-27*

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sysnet-pyutils"
-version = "1.7.12"
+version = "1.9.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.9.0}/sysnet_pyutils/__init__.py

@@ -116,6 +116,13 @@ from sysnet_pyutils.models.general import (
     WorkflowType,
     calculate_status,
 )
+from sysnet_pyutils.request_context import (
+    RequestContext,
+    current_request_context,
+    reset_request_context,
+    set_request_context,
+    use_request_context,
+)
 
 # Syslog
 from sysnet_pyutils.syslog import SyslogFactory
@@ -123,9 +130,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,

sysnet_pyutils-1.9.0/sysnet_pyutils/request_context.py

@@ -0,0 +1,90 @@
+"""Nosič kontextu jednoho požadavku (ASGI-safe doplněk ke třídě ``Context``).
+
+``sysnet_pyutils.Context`` je singleton: drží stav posledního ověření a sdílí ho všechny souběžné požadavky.
+Pokud si dva požadavky vymění stav, jeden z nich uvidí identitu druhého. Tento modul nabízí jen **nosič**
+identity bez sdíleného stavu:
+
+* neměnný :class:`RequestContext`,
+* ``set_request_context`` / ``current_request_context`` / ``reset_request_context`` / ``use_request_context``
+  ukládají kontext do :class:`contextvars.ContextVar`, takže každá asynchronní úloha (požadavek) vidí jen svůj.
+
+**Modul neověřuje API klíče.** Ověřování, hashování a správa klíčů patří výhradně knihovně ``sysnet-apikeys``
+(standard CML ``constitution/standards/api-keys.md``, pravidlo 1). Identitu, kterou ``sysnet-apikeys`` vrátí
+(``Principal`` s ``client``, ``agenda`` a ``scopes``), si služba převede na :class:`RequestContext` sama::
+
+    async def authenticated(principal: Principal = Depends(auth)) -> RequestContext:
+        ctx = RequestContext(user_name=principal.client, agenda=principal.agenda)
+        set_request_context(ctx)
+        return ctx
+
+``ContextVar`` nastavený v **synchronní** závislosti (``def``, běží ve vlákně) se do endpointu nepřenese. Nastavujte
+ho v ``async def`` závislosti, nebo použijte vrácenou hodnotu (``Depends``) přímo.
+
+Starý singleton ``Context`` zůstává beze změny kvůli stávajícím konzumentům.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+
+from sysnet_pyutils.utils import Secret
+
+
+@dataclass(frozen=True)
+class RequestContext:
+    """Neměnný kontext jednoho požadavku.
+
+    ``frozen`` brání tomu, aby se změnou sdílené prázdné instance změnil stav všech úloh, které kontext ještě
+    nenastavily. ``api_key`` a ``cert_pass`` jsou typu :class:`Secret`, takže se neobjeví v ``repr``, ``str`` ani
+    v logu; čistou hodnotu vrací ``.reveal()``.
+    """
+
+    api_key: Secret | None = None
+    agenda: str | None = None
+    user_name: str | None = None
+    cert_file: str | None = None
+    cert_pass: Secret | None = None
+
+    @property
+    def authenticated(self) -> bool:
+        """``True``, pokud kontext nese identitu volajícího (``user_name`` nebo ``api_key``).
+
+        ``sysnet-apikeys`` otevřený klíč nevrací (ukládá se jen hash), proto ``api_key`` bývá prázdný a identitu
+        nese ``user_name`` (klient z ``Principal``). Samotná ``agenda`` identitou není.
+        """
+        return self.api_key is not None or self.user_name is not None
+
+
+_EMPTY: RequestContext = RequestContext()
+_request_ctx: ContextVar[RequestContext] = ContextVar("sysnet_pyutils_request_context", default=_EMPTY)
+
+
+def current_request_context() -> RequestContext:
+    """Kontext aktuální úlohy; pokud nebyl nastaven, vrací prázdný (neověřený)."""
+    return _request_ctx.get()
+
+
+def set_request_context(ctx: RequestContext) -> Token[RequestContext]:
+    """Nastaví kontext pro aktuální úlohu. Vrací token pro :func:`reset_request_context`."""
+    return _request_ctx.set(ctx)
+
+
+def reset_request_context(token: Token[RequestContext] | None = None) -> None:
+    """Vrátí předchozí hodnotu (podle ``token``), nebo bez tokenu nastaví prázdný kontext."""
+    if token is not None:
+        _request_ctx.reset(token)
+    else:
+        _request_ctx.set(_EMPTY)
+
+
+@contextlib.contextmanager
+def use_request_context(ctx: RequestContext) -> Iterator[RequestContext]:
+    """Nastaví kontext po dobu bloku a vždy ho vrátí zpět (i při výjimce)."""
+    token = set_request_context(ctx)
+    try:
+        yield ctx
+    finally:
+        reset_request_context(token)