"Release 0.2.1: async support for extra_log_fields + Python 3.9 compatibility"

Author: akutayural

README.md

@@ -34,15 +34,20 @@ Reading the [full documentation](https://akutayural.github.io/APIException/) is
 ---
 
 > [!IMPORTANT]
-    New in v0.2.0: <br>
-    - Advanced structured logging (`log_level`, `log_header_keys`, `extra_log_fields`)  
-    - Response headers echo (`response_headers`)  
-    - Type-safety improvements with `mypy`  
-    - APIException accepts `headers` param <br>
-    - Cleaner import/export structure <br>
-    - 📢 Featured in [**Python Weekly #710**](https://www.pythonweekly.com/p/python-weekly-issue-710-august-14-2025-3200567a10d37d87) 🎉<br>
-    - 👉 For full details and usage examples, see  
-    [**register_exception_handlers reference**](https://akutayural.github.io/APIException/usage/register_exception_handlers/)
+> **New in v0.2.1:**   <br>
+> - ✨ **Async support** for `extra_log_fields` → you can now use `await request.body()` directly.  
+> - 🧩 **Python 3.9 compatibility restored** with `typing_extensions.TypeGuard`.  
+> - ⚡ Improved `response_utils.py` type-safety for all Python versions.   <br>
+> - 📦 Updated dependencies and `pyproject.toml` for wider environment support.   <br>
+>  
+> **Previously in v0.2.0:**   <br>
+> - Advanced structured logging (`log_level`, `log_header_keys`, `extra_log_fields`)  
+> - Response headers echo (`response_headers`)  
+> - Type-safety improvements with `mypy`  
+> - `APIException` accepts `headers` param   <br>
+> - Cleaner import/export structure   <br>
+> - 📢 Featured in [**Python Weekly #710**](https://www.pythonweekly.com/p/python-weekly-issue-710-august-14-2025-3200567a10d37d87) 🎉   <br>
+> - 👉 For full details and usage examples, see [**register_exception_handlers reference**](https://akutayural.github.io/APIException/usage/register_exception_handlers/) <br>
 
 ---
 
@@ -448,7 +453,7 @@ Benchmark scripts and raw Locust reports are available in the [benchmark](https:
 
 ## 📜 Changelog
 
-Currently, the most stable and suggested version is v0.2.0
+Currently, the most stable and suggested version is v0.2.1
 
 👉 [See full changelog](https://akutayural.github.io/APIException/changelog/)
 

api_exception/__init__.py

@@ -2,8 +2,10 @@
 
 import logging
 import traceback
-from typing import Callable, Tuple, Optional, Dict, Any, Iterable, Union
+from typing import Callable, Tuple, Optional, Dict, Any, Iterable, Union, Awaitable
 from typing import Literal
+import inspect
+
 
 from fastapi import FastAPI, Request
 from fastapi.encoders import jsonable_encoder
@@ -40,7 +42,11 @@
 
 LogLevelLiteral = Literal[10, 20, 30, 40, 50]
 HeaderKeys = Tuple[str, ...]
-ExtraLogFields = Callable[[Request, Optional[BaseException]], Dict[str, Any]]
+
+ExtraLogFields = Callable[
+    [Callable[[Request, Optional[BaseException]], Dict[str, Any]]],
+    Callable[[Request, Optional[BaseException]], Awaitable[Dict[str, Any]]]
+]
 
 
 def register_exception_handlers(
@@ -115,6 +121,8 @@ def register_exception_handlers(
     extra_log_fields : Callable[[Request, Optional[BaseException]], Dict[str, Any]] | None, default=None
         A hook to inject **custom** fields into the log `meta`. Receives `(request, exc)` and must return a dict.
         Useful for business context (tenant_id, feature flags, masked user ids, etc.).
+        def my_fields(req, exc): ...
+        async def my_fields(req, exc): ...
         Example:
             ```python
             def my_extra_fields(req, exc):
@@ -364,9 +372,12 @@ async def api_exception_handler(request: Request, exc: APIException):
 
             if extra_log_fields:
                 try:
-                    meta.update(extra_log_fields(request, exc))
+                    result = extra_log_fields(request, exc)
+                    if inspect.isawaitable(result):
+                        result = await result
+                    if isinstance(result, dict):
+                        meta.update(result)
                 except Exception:
-                    # Avoid breaking the handler due to user hook errors
                     pass
 
             if log_traceback and effective_level <= logging.DEBUG:

api_exception/response_utils.py

@@ -1,4 +1,12 @@
-from typing import Dict, Tuple, TypeGuard, Union
+from typing import Dict, Tuple, Union
+
+# --- Backward-compatible TypeGuard import (Python 3.8–3.9 support) ---
+try:
+    from typing import TypeGuard  # Python 3.10+
+except ImportError:
+    from typing_extensions import TypeGuard  # For Python <3.10
+
+
 from api_exception.response_model import ResponseModel
 from api_exception.enums import ExceptionStatus, BaseExceptionCode
 from api_exception.rfc7807_model import RFC7807ResponseModel

docs/changelog.md

@@ -4,6 +4,34 @@ All notable changes to APIException will be documented here.
 This project uses *Semantic Versioning*.
 
 
+---
+
+## [0.2.1] - 2025-10-16
+### Added
+- **Async support** for `extra_log_fields`:  
+  You can now define your callback as an `async def` function and directly use  
+  `await request.body()` or other asynchronous operations inside it.  
+  Backward compatibility for sync functions is fully preserved.
+- **Python 3.9 compatibility restored**:  
+  Introduced conditional import of `TypeGuard` via `typing_extensions`  
+  to ensure full support for Python 3.9 environments.
+- **typing-extensions** added as a dependency for backward-compatible typing features.
+
+### Changed
+- `response_utils.py` refactored for cleaner type-safety and full cross-version support.  
+- Updated `pyproject.toml`:
+  - Python version lowered to `>=3.9,<4.0`
+  - Added `typing-extensions>=4.0.0`
+- Internal handlers now safely await async results from `extra_log_fields`,  
+  ensuring consistent behavior across all exception types.
+
+### Fixed
+- Fixed `ImportError` on Python 3.9 caused by direct import of `TypeGuard` from `typing`.
+- Minor logging improvements and better exception trace readability.
+
+---
+
+
 ## [0.2.0] - 2025-08-23
 ### Added
 - **Advanced logging customizations** in `register_exception_handlers`:

examples/fastapi_usage.py

@@ -17,8 +17,8 @@
 app = FastAPI()
 
 
-def my_extra_fields(request: Request, exc: Optional[BaseException]) -> Dict[str, Any]:
-    # Örn. özel header'ı maskeyle logla
+async def my_extra_fields(request: Request, exc: Optional[BaseException]) -> Dict[str, Any]:
+    # Ex: Mask extra fields
     user_id = request.headers.get("x-user-id", "anonymous")
     return {
         "masked_user_id": f"user-{user_id[-2:]}",

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "apiexception"
-version = "0.2.0"
+version = "0.2.1"
 description = "Consistent JSON response formatting and exception & error handling for FastAPI applications"
 authors = ["Ahmet Kutay URAL <ahmetkutayural@gmail.com>"]
 readme = "README.md"
@@ -14,6 +14,7 @@ classifiers = [
   "Operating System :: OS Independent",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -34,11 +35,12 @@ packages = [
 "Changelog" = "https://github.com/akutayural/APIException/blob/main/docs/changelog.md"
 
 [tool.poetry.dependencies]
-python = ">=3.10"
+python = ">=3.9,<4.0"
 fastapi = ">=0.115.4"
 httpx = ">=0.27.0"
 pydantic = ">=2.0.0"
 click = ">=8.0.0"
+typing-extensions = ">=4.0.0"
 
 [tool.poetry.group.dev.dependencies]
 mkdocs-awesome-pages-plugin = ">=2.10.1"
@@ -62,7 +64,7 @@ build-backend = "poetry.core.masonry.api"
 api_exception = ["py.typed"]
 
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.9"
 ignore_missing_imports = true
 strict_optional = true
 warn_unused_ignores = true