python3-commons 0.24.6__py3-none-any.whl → 0.25.0__py3-none-any.whl

python3_commons/api_client.py

@@ -17,7 +17,7 @@ except ImportError as e:
     raise RuntimeError(msg) from e
 
 from python3_commons import audit
-from python3_commons.conf import s3_settings
+from python3_commons.conf import api_client_settings, s3_settings
 from python3_commons.helpers import request_to_curl
 from python3_commons.serializers.json import CustomJSONEncoder
 
@@ -34,9 +34,15 @@ async def _store_response_for_audit(
         date_path = now.strftime('%Y/%m/%d')
         timestamp = now.strftime('%H%M%S_%f')
 
+        if api_client_settings.audit_path:
+            audit_root = api_client_settings.audit_path.strip('/')
+            path = f'{audit_root}/{date_path}/{audit_name}/{uri_path}/{method}_{timestamp}_{request_id}_response.txt'
+        else:
+            path = f'{date_path}/{audit_name}/{uri_path}/{method}_{timestamp}_{request_id}_response.txt'
+
         await audit.write_audit_data(
             s3_settings,
-            f'{date_path}/{audit_name}/{uri_path}/{method}_{timestamp}_{request_id}_response.txt',
+            path,
             response_text.encode('utf-8'),
         )
 
@@ -75,9 +81,15 @@ async def request(
             )
 
         if curl_request:
+            if api_client_settings.audit_path:
+                audit_root = api_client_settings.audit_path.strip('/')
+                path = f'{audit_root}/{date_path}/{audit_name}/{uri_path}/{method}_{timestamp}_{request_id}_request.txt'
+            else:
+                path = f'{date_path}/{audit_name}/{uri_path}/{method}_{timestamp}_{request_id}_request.txt'
+
             await audit.write_audit_data(
                 s3_settings,
-                f'{date_path}/{audit_name}/{uri_path}/{method}_{timestamp}_{request_id}_request.txt',
+                path,
                 curl_request.encode('utf-8'),
             )
 

python3_commons/audit.py

@@ -14,7 +14,7 @@ except ImportError as e:
     raise RuntimeError(msg) from e
 
 from python3_commons import object_storage
-from python3_commons.conf import s3_settings
+from python3_commons.conf import api_client_settings, object_storage_settings, s3_settings
 
 if TYPE_CHECKING:
     from zeep import AsyncClient
@@ -25,16 +25,28 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-async def write_audit_data(settings: S3Settings, key: str, data: bytes) -> None:
-    if settings.s3_secret_access_key:
+async def write_audit_data(settings: S3Settings = s3_settings, key: str = '', data: bytes = b'') -> None:
+    if settings.secret_access_key or api_client_settings.audit_path or object_storage_settings.work_path:
         try:
-            await object_storage.put_object(settings.s3_bucket, f'audit/{key}', io.BytesIO(data), len(data))
+            if api_client_settings.audit_path and key.startswith(api_client_settings.audit_path.strip('/')):
+                work_path = api_client_settings.audit_path
+                path = key
+            elif api_client_settings.audit_path:
+                work_path = api_client_settings.audit_path
+                path = key.lstrip('/')
+            elif object_storage_settings.work_path:
+                work_path = object_storage_settings.work_path
+                path = f'audit/{key.lstrip("/")}'
+            else:
+                work_path = 'audit'
+                path = key.lstrip('/')
+            await object_storage.put_object(work_path=work_path, path=path, data=io.BytesIO(data), length=len(data))
         except Exception:
             logger.exception('Failed storing object in storage.')
         else:
             logger.debug('Stored object in storage: %s', key)
     else:
-        logger.debug('S3 is not configured, not storing object in storage: %s', key)
+        logger.debug('Storage is not configured, not storing object in storage: %s', key)
 
 
 class ZeepAuditPlugin(Plugin):

python3_commons/conf.py

@@ -86,17 +86,31 @@ class DBSettings(BaseSettings):
 
 
 class S3Settings(BaseSettings):
-    s3_access_key_id: SecretStr | None = None
-    s3_addressing_style: Literal['path', 'virtual'] = 'virtual'
-    s3_allow_http: bool = False
-    s3_bucket: str | None = None
-    s3_bucket_root: str | None = None
-    s3_cert_verify: bool = True
-    s3_region: str | None = None
-    s3_secret_access_key: SecretStr | None = None
+    model_config = SettingsConfigDict(env_prefix='S3_')
+
+    access_key_id: SecretStr | None = None
+    addressing_style: Literal['path', 'virtual'] = 'virtual'
+    allow_http: bool = False
+    cert_verify: bool = True
+    region: str | None = None
+    secret_access_key: SecretStr | None = None
+
+
+class ObjectStorageSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix='OBJECT_STORAGE_')
+
+    work_path: str | None = None
+
+
+class ApiClientSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix='API_CLIENT_')
+
+    audit_path: str | None = None
 
 
 settings = CommonSettings()
 valkey_settings = ValkeySettings()
 db_settings = DBSettings()
+api_client_settings = ApiClientSettings()
 s3_settings = S3Settings()
+object_storage_settings = ObjectStorageSettings()

python3_commons/object_storage.py

@@ -1,28 +1,22 @@
 from __future__ import annotations
 
+import io
 import logging
 import threading
 from contextlib import asynccontextmanager
+from datetime import datetime
 from typing import TYPE_CHECKING
+from urllib.parse import urlparse
 
 try:
-    import aiobotocore.session
-    from botocore.config import Config
-    from object_storage_client import ObjectStorageClient
+    from object_storage_client import ByteStream, ObjectStorageClient
 except ImportError as e:
     msg = 'Install python3-commons[object-storage] to use this feature'
     raise RuntimeError(msg) from e
 
 if TYPE_CHECKING:
-    import io
-    from collections.abc import AsyncGenerator, Iterable, Mapping, Sequence
-    from datetime import datetime
+    from collections.abc import AsyncGenerator, AsyncIterator, Iterable, Mapping, Sequence
 
-    from aiobotocore.response import StreamingBody
-    from types_aiobotocore_s3.client import S3Client
-
-from python3_commons.conf import S3Settings, s3_settings
-from python3_commons.helpers import SingletonMeta
 
 logger = logging.getLogger(__name__)
 _CLIENT: ObjectStorageClient | None = None
@@ -40,174 +34,214 @@ def get_client() -> ObjectStorageClient:
     return _CLIENT
 
 
-class ObjectStorage(metaclass=SingletonMeta):
-    def __init__(self, settings: S3Settings) -> None:
-        self._session = aiobotocore.session.get_session()
-        config = {
-            'region_name': settings.s3_region,
-            'use_ssl': not settings.s3_allow_http,
-            'verify': settings.s3_cert_verify,
-            'config': Config(s3={'addressing_style': settings.s3_addressing_style}, signature_version='s3v4'),
-        }
+class ObjectStorageStream:
+    def __init__(self, stream: ByteStream) -> None:
+        self._stream = stream
+
+    async def read(self) -> bytes:
+        chunks = []
+
+        while chunk := await self._stream.next():
+            chunks.append(chunk)
+
+        return b''.join(chunks)
+
+    async def next(self) -> bytes:
+        return await self._stream.next()
+
+    def __aiter__(self) -> AsyncIterator[bytes]:
+        return self
+
+    async def __anext__(self) -> bytes:
+        chunk = await self._stream.next()
+
+        if not chunk:
+            raise StopAsyncIteration
+
+        return chunk
 
-        if s3_access_key_id := settings.s3_access_key_id:
-            config['aws_access_key_id'] = s3_access_key_id.get_secret_value()
 
-        if s3_secret_access_key := settings.s3_secret_access_key:
-            config['aws_secret_access_key'] = s3_secret_access_key.get_secret_value()
+def build_url(work_path: str, path: str = '') -> str:
+    path = path.lstrip('/')
 
-        self._config = config
+    if path.startswith(('s3://', 'file://', 'gs://', 'az://')):
+        return path
 
-    @asynccontextmanager
-    async def get_client(self) -> AsyncGenerator[S3Client]:
-        async with self._session.create_client('s3', **self._config) as client:
-            yield client
+    base = work_path.rstrip('/')
 
+    if not base.startswith(('s3://', 'file://', 'gs://', 'az://', '/')):
+        base = f's3://{base}'
 
-def get_absolute_path(path: str) -> str:
-    path = path.removeprefix('/')
+    if not path:
+        return base
 
-    if bucket_root := s3_settings.s3_bucket_root:
-        path = f'{bucket_root[:1] if bucket_root.startswith("/") else bucket_root}/{path}'
+    base_no_scheme = base.split('://', 1)[-1].lstrip('/')
 
-    return path
+    if path.startswith(f'{base_no_scheme}/') or path == base_no_scheme:
+        scheme = base.split('://', 1)[0] + '://' if '://' in base else ''
 
+        return f'{scheme}{path}'
 
-async def put_object(bucket_name: str, path: str, data: io.BytesIO, length: int, part_size: int = 0) -> str | None:
+    parsed = urlparse(base)
+    base_path = parsed.path.lstrip('/')
+
+    if base_path and (path.startswith(f'{base_path}/') or path == base_path):
+        prefix_url = f'{parsed.scheme}://{parsed.netloc}' if parsed.scheme else ''
+
+        return f'{prefix_url}/{path}'
+
+    return f'{base}/{path}'
+
+
+async def put_object(
+    work_path: str,
+    path: str = '',
+    data: io.BytesIO | bytes | None = None,
+    length: int = 0,
+    part_size: int = 0,
+) -> str | None:
     try:
         client = get_client()
-        data.seek(0)
-        absolute_path = get_absolute_path(path)
-        url = f's3://{bucket_name}/{absolute_path}'
 
-        await client.put_object(url, data.getvalue())
+        if isinstance(data, io.BytesIO):
+            content = data.getvalue()
+            data.seek(0)
+        elif isinstance(data, bytes):
+            content = data
+        elif data is None:
+            content = b''
+        else:
+            content = bytes(data)
 
-        logger.debug('Stored object into object storage: %s:%s', bucket_name, path)
+        url = build_url(work_path, path)
+        await client.put_object(url, content)
+        logger.debug('Stored object into object storage: %s', url)
     except Exception as e:
-        logger.exception('Failed to put object to object storage: %s:%s', bucket_name, path, exc_info=e)
-
+        logger.exception('Failed to put object to object storage: %s:%s', work_path, path, exc_info=e)
         raise
 
-    return f's3://{bucket_name}/{path}'
+    return url
 
 
 @asynccontextmanager
-async def get_object_stream(bucket_name: str, path: str) -> AsyncGenerator[StreamingBody]:
-    storage = ObjectStorage(s3_settings)
-
-    async with storage.get_client() as s3_client:
-        logger.debug('Getting object from object storage: %s:%s', bucket_name, path)
-
-        try:
-            response = await s3_client.get_object(Bucket=bucket_name, Key=path)
+async def get_object_stream(work_path: str, path: str = '') -> AsyncGenerator[ObjectStorageStream]:
+    logger.debug('Getting object stream from object storage: %s:%s', work_path, path)
 
-            async with response['Body'] as stream:
-                yield stream
-        except Exception as e:
-            logger.exception('Failed getting object from object storage: %s:%s', bucket_name, path, exc_info=e)
-
-            raise
+    try:
+        client = get_client()
+        url = build_url(work_path, path)
+        stream = await client.get_object_stream(url)
+        yield ObjectStorageStream(stream)
+    except Exception as e:
+        logger.exception('Failed getting object from object storage: %s:%s', work_path, path, exc_info=e)
+        raise
 
 
-async def get_object(bucket_name: str, path: str) -> bytes:
-    logger.debug('Getting object from object storage: %s:%s', bucket_name, path)
+async def get_object(work_path: str, path: str = '') -> bytes:
+    logger.debug('Getting object from object storage: %s:%s', work_path, path)
 
     try:
         client = get_client()
-        absolute_path = get_absolute_path(path)
-        url = f's3://{bucket_name}/{absolute_path}'
+        url = build_url(work_path, path)
         body = await client.get_object(url)
     except Exception as e:
-        logger.exception('Failed getting object from object storage: %s:%s', bucket_name, path, exc_info=e)
-
+        logger.exception('Failed getting object from object storage: %s:%s', work_path, path, exc_info=e)
         raise
 
     return body
 
 
-async def list_objects(bucket_name: str, prefix: str, *, recursive: bool = True) -> AsyncGenerator[Mapping]:
-    storage = ObjectStorage(s3_settings)
+async def list_objects(work_path: str, prefix: str = '', *, recursive: bool = True) -> AsyncGenerator[Mapping]:
+    client = get_client()
+    url = build_url(work_path, prefix)
+    items = await client.list_objects(url)
+    prefix_clean = prefix.strip('/')
 
-    async with storage.get_client() as s3_client:
-        paginator = s3_client.get_paginator('list_objects_v2')
+    for item in items:
+        if not recursive and '/' in item:
+            continue
 
-        page_iterator = paginator.paginate(Bucket=bucket_name, Prefix=prefix, Delimiter='' if recursive else '/')
+        rel_key = f'{prefix_clean}/{item}' if prefix_clean else item
+        obj_url = build_url(work_path, rel_key)
 
-        async for page in page_iterator:
-            if 'Contents' in page:
-                for obj in page['Contents']:
-                    yield dict(obj)
+        try:
+            meta = await client.get_object_metadata(obj_url)
+            last_modified = (
+                datetime.fromisoformat(meta['last_modified']) if meta.get('last_modified') else datetime.now()
+            )
+            size = meta.get('size_bytes', 0)
+            etag = meta.get('e_tag')
+        except Exception:
+            last_modified = datetime.now()
+            size = 0
+            etag = None
+
+        yield {
+            'Key': rel_key,
+            'LastModified': last_modified,
+            'Size': size,
+            'ETag': etag,
+        }
 
 
 async def get_object_streams(
-    bucket_name: str, path: str, *, recursive: bool = True
-) -> AsyncGenerator[tuple[str, datetime, StreamingBody]]:
-    async for obj in list_objects(bucket_name, path, recursive=recursive):
+    work_path: str, path: str = '', *, recursive: bool = True
+) -> AsyncGenerator[tuple[str, datetime, ObjectStorageStream]]:
+    async for obj in list_objects(work_path, path, recursive=recursive):
         object_name = obj['Key']
         last_modified = obj['LastModified']
 
-        async with get_object_stream(bucket_name, path) as stream:
+        async with get_object_stream(work_path, object_name) as stream:
             yield object_name, last_modified, stream
 
 
 async def get_objects(
-    bucket_name: str, path: str, *, recursive: bool = True
+    work_path: str, path: str = '', *, recursive: bool = True
 ) -> AsyncGenerator[tuple[str, datetime, bytes]]:
-    async for object_name, last_modified, stream in get_object_streams(bucket_name, path, recursive=recursive):
+    async for object_name, last_modified, stream in get_object_streams(work_path, path, recursive=recursive):
         data = await stream.read()
 
         yield object_name, last_modified, data
 
 
-async def remove_object(bucket_name: str, path: str) -> None:
-    logger.debug('Removing object from object storage: %s:%s', bucket_name, path)
+async def remove_object(work_path: str, path: str = '') -> None:
+    logger.debug('Removing object from object storage: %s:%s', work_path, path)
 
     try:
         client = get_client()
-        absolute_path = get_absolute_path(path)
-        url = f's3://{bucket_name}/{absolute_path}'
+        url = build_url(work_path, path)
         await client.delete_object(url)
     except Exception as e:
-        logger.exception('Failed to remove object from object storage: %s:%s', bucket_name, path, exc_info=e)
-
+        logger.exception('Failed to remove object from object storage: %s:%s', work_path, path, exc_info=e)
         raise
 
 
 async def remove_objects(
-    bucket_name: str, prefix: str | None = None, object_names: Iterable[str] | None = None
+    work_path: str, prefix: str | None = None, object_names: Iterable[str] | None = None
 ) -> Sequence[Mapping] | None:
-    storage = ObjectStorage(s3_settings)
+    if not prefix and not object_names:
+        return None
 
-    async with storage.get_client() as s3_client:
-        if prefix:
-            objects_to_delete = tuple(
-                {'Key': obj['Key']} async for obj in list_objects(bucket_name, prefix, recursive=True)
-            )
-        elif object_names:
-            objects_to_delete = tuple({'Key': name} for name in object_names)
-        else:
-            return None
+    client = get_client()
+    errors: list[Mapping] = []
 
-        if not objects_to_delete:
-            return None
+    if prefix:
+        url = build_url(work_path, prefix)
 
         try:
-            errors = []
-            # S3 delete_objects can handle up to 1000 objects at once
-            chunk_size = 1000
-
-            for i in range(0, len(objects_to_delete), chunk_size):
-                chunk = objects_to_delete[i : i + chunk_size]
-
-                response = await s3_client.delete_objects(Bucket=bucket_name, Delete={'Objects': chunk})
-
-                if 'Errors' in response:
-                    errors.extend(response['Errors'])
-
-            logger.debug('Removed %d objects from object storage: %s', len(objects_to_delete), bucket_name)
+            await client.delete_objects_by_prefix(url)
+            logger.debug('Removed objects by prefix from object storage: %s', url)
         except Exception as e:
-            logger.exception('Failed to remove objects from object storage: %s', bucket_name, exc_info=e)
-
+            logger.exception('Failed to remove objects by prefix: %s', url, exc_info=e)
             raise
+    elif object_names:
+        for name in object_names:
+            url = build_url(work_path, name)
+
+            try:
+                await client.delete_object(url)
+            except Exception as e:
+                logger.exception('Failed to remove object: %s', url, exc_info=e)
+                errors.append({'Key': name, 'Error': str(e)})
 
-        return errors or None
+    return errors or None

python3_commons-0.25.0.dist-info/METADATA

@@ -0,0 +1,434 @@
+Metadata-Version: 2.4
+Name: python3-commons
+Version: 0.25.0
+Summary: Re-usable Python3 code
+Author-email: Oleg Korsak <kamikaze.is.waiting.you@gmail.com>
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/kamikaze/python3-commons
+Project-URL: Documentation, https://github.com/kamikaze/python3-commons/wiki
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: <3.15.0,>=3.14.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: msgpack~=1.2.2
+Requires-Dist: msgspec~=0.21.1
+Requires-Dist: pydantic-settings~=2.15.0
+Provides-Extra: all
+Requires-Dist: python3_commons[api-client,audit,authn,authz,cache,database,object-storage,soap-client]; extra == "all"
+Provides-Extra: api-client
+Requires-Dist: aiohttp[speedups]<3.15.0,>=3.14.3; extra == "api-client"
+Requires-Dist: certifi~=2026.7.22; extra == "api-client"
+Requires-Dist: python3_commons[audit,object-storage]; extra == "api-client"
+Provides-Extra: audit
+Requires-Dist: lxml~=6.1.3; extra == "audit"
+Requires-Dist: zeep[async]~=4.3.3; extra == "audit"
+Requires-Dist: python3_commons[object-storage]; extra == "audit"
+Provides-Extra: authn
+Requires-Dist: aiohttp[speedups]<3.15.0,>=3.14.3; extra == "authn"
+Requires-Dist: certifi~=2026.7.22; extra == "authn"
+Requires-Dist: python3_commons[api-client]; extra == "authn"
+Provides-Extra: authz
+Requires-Dist: python3_commons[database]; extra == "authz"
+Requires-Dist: python3_commons[api-client]; extra == "authz"
+Provides-Extra: cache
+Requires-Dist: valkey[libvalkey]~=6.1.1; extra == "cache"
+Provides-Extra: database
+Requires-Dist: asyncpg~=0.31.0; extra == "database"
+Requires-Dist: SQLAlchemy[asyncio]~=2.1.1; extra == "database"
+Provides-Extra: object-storage
+Requires-Dist: object-storage-client~=0.1.12; extra == "object-storage"
+Provides-Extra: soap-client
+Requires-Dist: aiohttp[speedups]<3.15.0,>=3.14.3; extra == "soap-client"
+Requires-Dist: certifi~=2026.7.22; extra == "soap-client"
+Requires-Dist: lxml~=6.1.3; extra == "soap-client"
+Requires-Dist: requests~=2.34.2; extra == "soap-client"
+Requires-Dist: zeep[async]~=4.3.3; extra == "soap-client"
+Dynamic: license-file
+
+# python3-commons
+
+Re-usable code for Python 3 projects.
+
+## Installation
+
+```bash
+uv add python3-commons
+```
+
+### Optional Dependencies
+
+Some features require extra dependencies. You can install them individually or all at once:
+
+- `api-client`: For `python3_commons.api_client`
+- `audit`: For `python3_commons.audit`
+- `authn`: For `python3_commons.auth`
+- `authz`: For `python3_commons.permissions`
+- `cache`: For `python3_commons.cache`
+- `database`: For `python3_commons.db`
+- `object-storage`: For `python3_commons.object_storage`
+- `soap-client`: For `python3_commons.soap_client`
+- `all`: Install all optional dependencies
+
+```bash
+uv add "python3-commons[all]"
+```
+
+## Features
+
+### Async LRU Cache
+
+An LRU cache decorator for asynchronous functions that handles `await` and prevents the dogpile effect (mitigating multiple concurrent calls for the same key by waiting for the first one to finish).
+
+```python
+from python3_commons.async_functools import async_lru_cache
+
+@async_lru_cache(maxsize=128)
+async def fetch_expensive_data(item_id: int):
+    # This function will only be called once for a given item_id 
+    # even if multiple tasks await it simultaneously.
+    return await db.get(item_id)
+
+# Usage
+result = await fetch_expensive_data(42)
+```
+
+### API Client
+
+A context manager for `aiohttp` requests with built-in audit logging to S3 and standardized error mapping to Python exceptions.
+
+#### Standardized Exception Mapping
+
+HTTP error status codes and network failures are mapped to built-in Python exceptions:
+- `400 Bad Request` -> `ValueError`
+- `401 Unauthorized`, `403 Forbidden` -> `PermissionError`
+- `404 Not Found` -> `LookupError`
+- `429 Too Many Requests` -> `InterruptedError`
+- Other 4xx/5xx responses -> `aiohttp.ClientResponseError`
+- Connection errors -> `ConnectionRefusedError` / `ConnectionResetError`
+
+#### Enabling Audit Logging
+
+Audit logging captures the outgoing request (formatted as an executable `curl` command) and the incoming response body, writing them asynchronously to Object Storage.
+
+The destination path is resolved as follows:
+- If `ApiClientSettings.audit_path` is configured (via `API_CLIENT_AUDIT_PATH`), it is used directly as the audit root for `api_client` (without prepending `"audit/"`):
+  `<audit_path>/<YYYY/MM/DD>/<audit_name>/<uri>/<method>_<timestamp>_<request_id>_{request,response}.txt`
+- Otherwise, if `ObjectStorageSettings.work_path` is configured (via `OBJECT_STORAGE_WORK_PATH`), it is used as the root with `"audit/"` prepended:
+  `<work_path>/audit/<YYYY/MM/DD>/<audit_name>/<uri>/<method>_<timestamp>_<request_id>_{request,response}.txt`
+- If neither is configured, the logs default to:
+  `audit/<YYYY/MM/DD>/<audit_name>/<uri>/<method>_<timestamp>_<request_id>_{request,response}.txt`
+
+To enable audit logging:
+1. **Configure Object Storage & S3 credentials**:
+   ```bash
+   # API client audit path or Object storage root
+   export API_CLIENT_AUDIT_PATH="my-audit-bucket/audit-logs"
+   # or export OBJECT_STORAGE_WORK_PATH="my-audit-bucket"
+
+   # S3 credentials
+   export S3_ACCESS_KEY_ID="your-access-key-id"
+   export S3_SECRET_ACCESS_KEY="your-secret-access-key"
+   export S3_REGION="us-east-1"
+   # Optional configurations:
+   # export S3_ALLOW_HTTP="false"
+   # export S3_ADDRESSING_STYLE="virtual"  # or "path"
+   # export S3_CERT_VERIFY="true"
+   ```
+   Alternatively, you can configure them directly in Python:
+   ```python
+   from python3_commons.conf import api_client_settings, object_storage_settings, s3_settings
+   from pydantic import SecretStr
+
+   api_client_settings.audit_path = "my-audit-bucket/audit-logs"
+   # or object_storage_settings.work_path = "my-audit-bucket"
+
+   s3_settings.access_key_id = SecretStr("your-access-key-id")
+   s3_settings.secret_access_key = SecretStr("your-secret-access-key")
+   s3_settings.region = "us-east-1"
+   ```
+
+2. **Pass `audit_name` to `request()`**: Provide a non-empty string identifier (such as the target service or operation name) in the `audit_name` argument. If `audit_name` is omitted (default `None`), audit logging is disabled for that call. If S3 credentials are not configured, audit logging is safely bypassed.
+
+#### Usage Example
+
+```python
+from aiohttp import ClientSession
+from python3_commons.api_client import request
+
+async with ClientSession() as session:
+    # 1. GET request with audit logging enabled
+    async with request(
+        session,
+        base_url="https://api.example.com",
+        uri="/users/123",
+        method="get",
+        headers={"Accept": "application/json"},
+        audit_name="user_service",
+    ) as response:
+        user = await response.json()
+
+    # 2. POST request with JSON body and audit logging
+    async with request(
+        session,
+        base_url="https://api.example.com",
+        uri="/users",
+        method="post",
+        json={"name": "Alice", "role": "admin"},
+        audit_name="user_service",
+    ) as response:
+        result = await response.json()
+
+    # 3. Request without audit logging (audit_name omitted)
+    async with request(
+        session,
+        base_url="https://api.example.com",
+        uri="/health",
+        method="get",
+    ) as response:
+        status = await response.json()
+```
+
+### SOAP Client
+
+Async SOAP client support for `zeep` with S3 auditing capabilities.
+
+```python
+from python3_commons.soap_client import soap_client
+
+async with soap_client("https://example.com/service?wsdl") as client:
+    result = await client.service.GetData(id=42)
+```
+
+### Database Management
+
+SQLAlchemy async engine and session management with pool tuning, health checks, dynamic query builders, and declarative base models.
+
+```python
+from python3_commons.db import AsyncSessionManager, is_healthy
+from python3_commons.db.helpers import get_query
+from python3_commons.conf import DBSettings
+
+# Configuration
+configs = {
+    "default": DBSettings(
+        dsn="postgresql+asyncpg://user:pass@localhost/db",
+        pool_size=20,
+        pool_timeout=30,
+        statement_timeout=30,
+    )
+}
+manager = AsyncSessionManager(configs)
+
+# Usage
+async with manager.get_session_context("default") as session:
+    result = await session.execute(...)
+
+# Engine health check (executes SELECT 1 with timeout)
+healthy = await is_healthy(manager.get_engine("default"))
+
+# Dynamic query filtering and sorting
+where_clause, order_clauses = get_query(
+    search={"name": "Alice"},
+    order_by="-created_at,name",
+    columns={
+        # name: (column, case_insensitive, cast_func, exact_match)
+        "name": (User.name, True, str, False),
+        "created_at": (User.created_at, False, str, True),
+    },
+)
+```
+
+### Object Storage
+
+Thin wrapper for `object-storage-client` supporting S3, GCS, Azure, and local file storage, configured via `object_storage_settings` (`OBJECT_STORAGE_WORK_PATH`) and `s3_settings` (`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_REGION`). Storage functions accept a required `work_path` parameter to define the base storage location.
+
+```python
+from python3_commons import object_storage
+import io
+
+# Upload an object
+await object_storage.put_object(
+    work_path="my-bucket", 
+    path="uploads/file.txt", 
+    data=io.BytesIO(b"Hello World"), 
+    length=11
+)
+
+# Download an object as bytes
+content = await object_storage.get_object("my-bucket", "uploads/file.txt")
+
+# Stream an object
+async with object_storage.get_object_stream("my-bucket", "uploads/file.txt") as stream:
+    data = await stream.read()
+
+# List objects with a prefix
+async for obj in object_storage.list_objects("my-bucket", "uploads/"):
+    print(obj['Key'])
+
+# Delete single or multiple objects
+await object_storage.remove_object("my-bucket", "uploads/file.txt")
+await object_storage.remove_objects("my-bucket", object_names=["uploads/file1.txt", "uploads/file2.txt"])
+```
+
+### OIDC Authentication
+
+Client for OpenID Connect authentication, supporting configuration fetching, JWKS, and token acquisition.
+
+```python
+from python3_commons.auth import OIDCClient
+from pydantic import HttpUrl
+
+client = OIDCClient(
+    authority_url=HttpUrl("https://auth.example.com/realms/myrealm"),
+    client_id="my-app-client",
+    client_secret="secret"
+)
+
+async with client:
+    token_response = await client.fetch_token(username="user", password="password")
+    print(token_response.access_token)
+```
+
+### Valkey Cache
+
+Async caching using Valkey (Redis-compatible) with automatic Msgpack serialization for complex types.
+
+```python
+from python3_commons import cache
+
+# Store a dictionary
+await cache.store("user:123", {"name": "Alice", "role": "admin"}, ttl=3600)
+
+# Retrieve it
+user_data = await cache.get("user:123")
+
+# Set operations
+await cache.add_set_item("active_users", "user:123")
+is_active = await cache.has_set_item("active_users", "user:123")
+```
+
+### Structured Logging
+
+A `JSONFormatter` for structured JSON logging and a `filter_maker` utility for level-based log filtering, compatible with standard Python `logging`.
+
+```python
+import logging
+from python3_commons.log.formatters import JSONFormatter
+from python3_commons.log.filters import filter_maker
+
+handler = logging.StreamHandler()
+handler.setFormatter(JSONFormatter())
+# Filter to process logs up to INFO level only
+handler.addFilter(filter_maker("INFO"))
+logging.getLogger().addHandler(handler)
+
+logger = logging.getLogger("app")
+logger.info("User logged in", extra={"user_id": "abc-123", "ip": "1.2.3.4"})
+```
+
+### Serialization
+
+Enhanced JSON and Msgpack serialization for types not handled by default (Decimal, datetime, date, dataclasses, Pydantic models).
+
+```python
+from python3_commons.serializers.msgspec import serialize_msgpack, deserialize_msgpack
+from decimal import Decimal
+from datetime import datetime
+
+data = {
+    "amount": Decimal("150.75"),
+    "timestamp": datetime.now(),
+    "tags": {"finance", "internal"}
+}
+
+# Serialize to Msgpack
+binary = serialize_msgpack(data)
+
+# Deserialize back
+restored = deserialize_msgpack(binary)
+```
+
+### RBAC Permissions
+
+Database-backed Role-Based Access Control (RBAC) permission checking for users and API keys.
+
+```python
+from python3_commons.permissions import has_user_permission, has_api_key_permission
+from uuid import UUID
+
+user_uuid = UUID("...")
+allowed = await has_user_permission(session, user_uuid, "reports.view")
+
+api_key_uuid = UUID("...")
+key_allowed = await has_api_key_permission(session, api_key_uuid, "reports.view")
+```
+
+### Configuration Management
+
+Typed application settings powered by Pydantic Settings:
+
+- `CommonSettings` / `settings`: General logging level and format.
+- `DBSettings` / `db_settings`: PostgreSQL database settings (`DB_` environment prefix, with `DB_PASS` alias for password).
+- `S3Settings` / `s3_settings`: S3 credentials and connection configuration (`S3_` environment prefix: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `REGION`).
+- `ObjectStorageSettings` / `object_storage_settings`: Object storage root configuration (`OBJECT_STORAGE_` environment prefix: `WORK_PATH`).
+- `ApiClientSettings` / `api_client_settings`: API client configuration (`API_CLIENT_` environment prefix: `AUDIT_PATH`).
+- `OIDCSettings`: OpenID Connect configuration (`OIDC_` environment prefix).
+- `ValkeySettings` / `valkey_settings`: Valkey/Redis cache configuration (`VALKEY_` environment prefix).
+
+### File System Utilities
+
+File system traversal helpers:
+
+```python
+from python3_commons.fs import iter_files
+from pathlib import Path
+
+# Recursively iterate files, ignoring hidden directories
+for file_path in iter_files(Path("./data"), recursive=True):
+    print(file_path)
+```
+
+### General Helpers
+
+A collection of useful utility functions:
+
+- `to_snake_case(text)`: Converts strings to snake_case.
+- `round_decimal(value, places)`: Rounds `Decimal` values.
+- `tries(n)`: An async retry decorator.
+- `log_execution_time`: An async decorator to log how long a function takes.
+- `date_from_string` / `datetime_from_string`: Flexible date/time parsing.
+- `date_range(start, end)`: Generator yielding dates in a range.
+- `request_to_curl`: Converts request parameters to a `curl` command string.
+- `SingletonMeta`: Thread-safe singleton metaclass.
+- `replace_origin(url, host_url)`: Replaces scheme, host, and port of a URL.
+- `parse_string_list`: Parses comma-separated string lists into tuples.
+
+```python
+from python3_commons.helpers import tries, log_execution_time, SingletonMeta
+
+@tries(3)
+@log_execution_time
+async def flaky_network_call():
+    ...
+
+class AppService(metaclass=SingletonMeta):
+    pass
+```
+
+### Async CSV Stream
+
+Efficiently generate CSV data as a byte stream from an async generator of tuples.
+
+```python
+from python3_commons.generators import tuple_csv_stream
+
+async def generate_rows():
+    for i in range(1000):
+        yield (i, f"Name {i}", 10.5 * i)
+
+async for chunk in tuple_csv_stream(generate_rows(), header=("ID", "Name", "Value")):
+    # Send chunk to HTTP response or write to file
+    pass
+```

{python3_commons-0.24.6.dist-info → python3_commons-0.25.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 python3_commons/__init__.py,sha256=0KgaYU46H_IMKn-BuasoRN3C4Hi45KlkHHoPbU9cwiA,189
-python3_commons/api_client.py,sha256=SThSzLhZJxVsKP8n1xDMCczA7SBFbxGFgrhKy9k-9_g,5532
+python3_commons/api_client.py,sha256=kQCTUEkMtNkoHexSEa3qQCRJyxzLKEsbP-i1g7msPxw,6106
 python3_commons/async_functools.py,sha256=A2HvwFzZHxOWTp4IQM5UiBY2yg1S_0U1CWra5BWK0gk,9101
-python3_commons/audit.py,sha256=yMhNFHYO77efNjMi_Th0SEnIrTAqI0ZBnuiDzT4lEPE,2607
+python3_commons/audit.py,sha256=y80A6cE2h3uGzjT1eg-6fiZ-IT-kKDmEtWNrXSQa5sY,3358
 python3_commons/auth.py,sha256=s928lYwpyX03BDTo1R6LpOgHiUSrjVrd1OVgTjvIiQU,8279
 python3_commons/cache.py,sha256=lowiXJqFgFy1Yg86wi9IhuoNqIUGP6nc5eNibmf0dfY,8018
-python3_commons/conf.py,sha256=p-El9tvxo4jkld3hzCH2U5ryX8sARexfv8Mgy5Cx5q8,3141
+python3_commons/conf.py,sha256=t9jE2vnsetg-GCxOqsx6pPIAFzAKwO0w0g9kqSnhv1Q,3488
 python3_commons/exceptions.py,sha256=EGjHZVBnsM6CeBfPMqhL0IPMKjDJ_2-Z-aSPXwq91LE,36
 python3_commons/fs.py,sha256=dn8ZcwsQf9xcAEg6neoxLN6IzJbWpprfm8wV8S55BL0,337
 python3_commons/generators.py,sha256=P6sKdCFhHT79-DZgzPU-qmwZvHg3wU8a75UFIwrycOY,1163
 python3_commons/helpers.py,sha256=WTPu_jIOGYtxt1GYnH6sBMNDHry99AKv6ZaggGW2l1A,4986
-python3_commons/object_storage.py,sha256=EkDPTw373UdWp6h3klOYygizx-0uyXT8Sim-zRCbB3g,7176
+python3_commons/object_storage.py,sha256=MBZdOZg8-BWoZ_8_i4-nkjlPRYV6pDxSR7fhoQmdFX4,7321
 python3_commons/permissions.py,sha256=gaMKSWg0MgPQTdP1voll4ItXcblXku9BlD0Lq3Xv64U,1724
 python3_commons/soap_client.py,sha256=w2lOyhhtkhwiNnHjvir8DfjGBO51XVg5rlDHyuudU2A,7169
 python3_commons/db/__init__.py,sha256=u-ZArdz5NQFvDLz2cjKT3_VCW3aPvEqIg1-bQ6rIDoQ,10196
@@ -27,9 +27,9 @@ python3_commons/serializers/common.py,sha256=VkA7C6wODvHk0QBXVX_x2JieDstihx3U__U
 python3_commons/serializers/json.py,sha256=UPkC3ps13x2C_NxwVV-K7Ewp4VjkVHSSUkJVw5k7Wiw,712
 python3_commons/serializers/msgpack.py,sha256=zESFBX34GsZ8rDu6Zk5V6CLT6P0mPilU0r04Ka6TblI,1474
 python3_commons/serializers/msgspec.py,sha256=upy5CBmK66-8hYnK5bAM_sZvZY5CAqZmzCw9GIF346I,2988
-python3_commons-0.24.6.dist-info/licenses/AUTHORS.rst,sha256=3R9JnfjfjH5RoPWOeqKFJgxVShSSfzQPIrEr1nxIo9Q,90
-python3_commons-0.24.6.dist-info/licenses/LICENSE,sha256=xxILuojHm4fKQOrMHPSslbyy6WuKAN2RiG74HbrYfzM,34575
-python3_commons-0.24.6.dist-info/METADATA,sha256=BlwCl4RT6crukvxjVm5VTE5GdhaetiOR-chlBg3-Qm8,9471
-python3_commons-0.24.6.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python3_commons-0.24.6.dist-info/top_level.txt,sha256=lJI6sCBf68eUHzupCnn2dzG10lH3jJKTWM_hrN1cQ7M,16
-python3_commons-0.24.6.dist-info/RECORD,,
+python3_commons-0.25.0.dist-info/licenses/AUTHORS.rst,sha256=3R9JnfjfjH5RoPWOeqKFJgxVShSSfzQPIrEr1nxIo9Q,90
+python3_commons-0.25.0.dist-info/licenses/LICENSE,sha256=xxILuojHm4fKQOrMHPSslbyy6WuKAN2RiG74HbrYfzM,34575
+python3_commons-0.25.0.dist-info/METADATA,sha256=vNf600tOvWqIn98Kc86RteZ5UhVwx0p_S2t6ZhHpsWA,15092
+python3_commons-0.25.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python3_commons-0.25.0.dist-info/top_level.txt,sha256=lJI6sCBf68eUHzupCnn2dzG10lH3jJKTWM_hrN1cQ7M,16
+python3_commons-0.25.0.dist-info/RECORD,,

python3_commons-0.24.6.dist-info/METADATA

@@ -1,310 +0,0 @@
-Metadata-Version: 2.4
-Name: python3-commons
-Version: 0.24.6
-Summary: Re-usable Python3 code
-Author-email: Oleg Korsak <kamikaze.is.waiting.you@gmail.com>
-License-Expression: GPL-3.0
-Project-URL: Homepage, https://github.com/kamikaze/python3-commons
-Project-URL: Documentation, https://github.com/kamikaze/python3-commons/wiki
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python
-Requires-Python: <3.15.0,>=3.14.0
-Description-Content-Type: text/x-rst
-License-File: LICENSE
-License-File: AUTHORS.rst
-Requires-Dist: msgpack~=1.2.1
-Requires-Dist: msgspec~=0.21.1
-Requires-Dist: pydantic-settings~=2.15.0
-Provides-Extra: all
-Requires-Dist: python3_commons[api-client,audit,authn,authz,cache,database,object-storage,soap-client]; extra == "all"
-Provides-Extra: api-client
-Requires-Dist: aiohttp[speedups]<3.15.0,>=3.14.3; extra == "api-client"
-Requires-Dist: certifi~=2026.7.22; extra == "api-client"
-Requires-Dist: python3_commons[audit,object-storage]; extra == "api-client"
-Provides-Extra: audit
-Requires-Dist: lxml~=6.1.2; extra == "audit"
-Requires-Dist: zeep[async]~=4.3.3; extra == "audit"
-Requires-Dist: python3_commons[object-storage]; extra == "audit"
-Provides-Extra: authn
-Requires-Dist: aiohttp[speedups]<3.15.0,>=3.14.3; extra == "authn"
-Requires-Dist: certifi~=2026.7.22; extra == "authn"
-Requires-Dist: python3_commons[api-client]; extra == "authn"
-Provides-Extra: authz
-Requires-Dist: python3_commons[database]; extra == "authz"
-Requires-Dist: python3_commons[api-client]; extra == "authz"
-Provides-Extra: cache
-Requires-Dist: valkey[libvalkey]~=6.1.1; extra == "cache"
-Provides-Extra: database
-Requires-Dist: asyncpg~=0.31.0; extra == "database"
-Requires-Dist: SQLAlchemy[asyncio]~=2.0.52; extra == "database"
-Provides-Extra: object-storage
-Requires-Dist: aiobotocore==3.9.0; extra == "object-storage"
-Requires-Dist: object-storage-client~=0.1.8; extra == "object-storage"
-Provides-Extra: soap-client
-Requires-Dist: aiohttp[speedups]<3.15.0,>=3.14.3; extra == "soap-client"
-Requires-Dist: certifi~=2026.7.22; extra == "soap-client"
-Requires-Dist: lxml~=6.1.3; extra == "soap-client"
-Requires-Dist: requests~=2.34.2; extra == "soap-client"
-Requires-Dist: zeep[async]~=4.3.3; extra == "soap-client"
-Dynamic: license-file
-
-Re-usable Python3 code
-======================
-
-Re-usable code for Python 3 projects.
-
-Installation
-------------
-
-.. code-block:: bash
-
-    uv add python3-commons
-
-Optional Dependencies
-~~~~~~~~~~~~~~~~~~~~~
-
-Some features require extra dependencies. You can install them individually or all at once:
-
-- ``api-client``: For ``python3_commons.api_client``
-- ``audit``: For ``python3_commons.audit``
-- ``authn``: For ``python3_commons.auth``
-- ``authz``: For ``python3_commons.permissions``
-- ``cache``: For ``python3_commons.cache``
-- ``database``: For ``python3_commons.db``
-- ``object-storage``: For ``python3_commons.object_storage``
-- ``soap-client``: For ``python3_commons.soap_client``
-- ``all``: Install all optional dependencies
-
-.. code-block:: bash
-
-    uv add "python3-commons[all]"
-
-Features
---------
-
-Async LRU Cache
-~~~~~~~~~~~~~~~
-
-An LRU cache decorator for asynchronous functions that handles ``await`` and prevents the dogpile effect (mitigating multiple concurrent calls for the same key by waiting for the first one to finish).
-
-.. code-block:: python
-
-    from python3_commons.async_functools import async_lru_cache
-
-    @async_lru_cache(maxsize=128)
-    async def fetch_expensive_data(item_id: int):
-        # This function will only be called once for a given item_id
-        # even if multiple tasks await it simultaneously.
-        return await db.get(item_id)
-
-    # Usage
-    result = await fetch_expensive_data(42)
-
-API Client
-~~~~~~~~~~
-
-A context manager for ``aiohttp`` requests with built-in audit logging to S3 and standardized error mapping to Python exceptions.
-
-.. code-block:: python
-
-    from python3_commons.api_client import request
-    from aiohttp import ClientSession
-
-    async with ClientSession() as session:
-        async with request(
-            session,
-            base_url="https://api.example.com",
-            uri="/data",
-            method="get",
-            audit_name="my_service_audit"
-        ) as response:
-            data = await response.json()
-
-SOAP Client
-~~~~~~~~~~~
-
-Async SOAP client support for ``zeep`` with S3 auditing capabilities.
-
-.. code-block:: python
-
-    from python3_commons.soap_client import soap_client
-
-    async with soap_client("https://example.com/service?wsdl") as client:
-        result = await client.service.GetData(id=42)
-
-Database Management
-~~~~~~~~~~~~~~~~~~~
-
-SQLAlchemy async engine and session management with pool tuning, health checks, and dynamic query builders.
-
-.. code-block:: python
-
-    from python3_commons.db import AsyncSessionManager
-    from python3_commons.conf import DBSettings
-
-    # Configuration
-    configs = {"default": DBSettings(dsn="postgresql+asyncpg://user:pass@localhost/db")}
-    manager = AsyncSessionManager(configs)
-
-    # Usage
-    async with manager.get_session_context("default") as session:
-        result = await session.execute(...)
-
-    # Health check
-    from python3_commons.db import is_healthy
-    await is_healthy(manager.get_engine("default"))
-
-Object Storage
-~~~~~~~~~~~~~~
-
-Utilities for async S3 operations using ``aiobotocore``.
-
-.. code-block:: python
-
-    from python3_commons import object_storage
-    import io
-
-    # Upload an object
-    await object_storage.put_object(
-        bucket_name="my-bucket",
-        path="uploads/file.txt",
-        data=io.BytesIO(b"Hello World"),
-        length=11
-    )
-
-    # Download an object
-    content = await object_storage.get_object("my-bucket", "uploads/file.txt")
-
-    # List objects
-    async for obj in object_storage.list_objects("my-bucket", "uploads/"):
-        print(obj['Key'])
-
-OIDC Authentication
-~~~~~~~~~~~~~~~~~~~
-
-Client for OpenID Connect authentication, supporting configuration fetching, JWKS, and token acquisition.
-
-.. code-block:: python
-
-    from python3_commons.auth import OIDCClient
-    from pydantic import HttpUrl
-
-    client = OIDCClient(
-        authority_url=HttpUrl("https://auth.example.com/realms/myrealm"),
-        client_id="my-app-client",
-        client_secret="secret"
-    )
-
-    async with client:
-        token_response = await client.fetch_token(username="user", password="password")
-        print(token_response.access_token)
-
-Valkey Cache
-~~~~~~~~~~~~
-
-Async caching using Valkey (Redis-compatible) with automatic Msgpack serialization for complex types.
-
-.. code-block:: python
-
-    from python3_commons import cache
-
-    # Store a dictionary
-    await cache.store("user:123", {"name": "Alice", "role": "admin"}, ttl=3600)
-
-    # Retrieve it
-    user_data = await cache.get("user:123")
-
-    # Set operations
-    await cache.add_set_item("active_users", "user:123")
-    is_active = await cache.has_set_item("active_users", "user:123")
-
-Structured Logging
-~~~~~~~~~~~~~~~~~~
-
-A ``JSONFormatter`` for structured logging, compatible with standard Python ``logging``.
-
-.. code-block:: python
-
-    import logging
-    from python3_commons.log.formatters import JSONFormatter
-
-    handler = logging.StreamHandler()
-    handler.setFormatter(JSONFormatter())
-    logging.getLogger().addHandler(handler)
-
-    logger = logging.getLogger("app")
-    logger.info("User logged in", extra={"user_id": "abc-123", "ip": "1.2.3.4"})
-
-Serialization
-~~~~~~~~~~~~~
-
-Enhanced JSON and Msgpack serialization for types not handled by default (Decimal, datetime, date, dataclasses, Pydantic models).
-
-.. code-block:: python
-
-    from python3_commons.serializers.msgspec import serialize_msgpack, deserialize_msgpack
-    from decimal import Decimal
-    from datetime import datetime
-
-    data = {
-        "amount": Decimal("150.75"),
-        "timestamp": datetime.now(),
-        "tags": {"finance", "internal"}
-    }
-
-    # Serialize to Msgpack
-    binary = serialize_msgpack(data)
-
-    # Deserialize back
-    restored = deserialize_msgpack(binary)
-
-RBAC Permissions
-~~~~~~~~~~~~~~~~
-
-Database-backed Role-Based Access Control (RBAC) permission checking.
-
-.. code-block:: python
-
-    from python3_commons.permissions import has_user_permission
-    from uuid import UUID
-
-    user_uuid = UUID("...")
-    allowed = await has_user_permission(session, user_uuid, "reports.view")
-
-General Helpers
-~~~~~~~~~~~~~~~
-
-A collection of useful utility functions:
-
-- ``to_snake_case(text)``: Converts strings to snake_case.
-- ``round_decimal(value, places)``: Rounds ``Decimal`` values.
-- ``tries(n)``: An async retry decorator.
-- ``log_execution_time``: An async decorator to log how long a function takes.
-- ``date_from_string`` / ``datetime_from_string``: Flexible date/time parsing.
-- ``request_to_curl``: Converts request parameters to a ``curl`` command string.
-
-.. code-block:: python
-
-    from python3_commons.helpers import tries, log_execution_time
-
-    @tries(3)
-    @log_execution_time
-    async def flaky_network_call():
-        ...
-
-Async CSV Stream
-~~~~~~~~~~~~~~~~
-
-Efficiently generate CSV data as a byte stream from an async generator of tuples.
-
-.. code-block:: python
-
-    from python3_commons.generators import tuple_csv_stream
-
-    async def generate_rows():
-        for i in range(1000):
-            yield (i, f"Name {i}", 10.5 * i)
-
-    async for chunk in tuple_csv_stream(generate_rows(), header=("ID", "Name", "Value")):
-        # Send chunk to HTTP response or write to file
-        pass