chore: release v0.2.3

Author: akutayural

README.md

@@ -13,6 +13,7 @@
 [![Ruff](https://img.shields.io/badge/linting-ruff-%23ea580c?logo=ruff&logoColor=white)](https://github.com/astral-sh/ruff)
 [![uv](https://img.shields.io/badge/packaging-uv-%234285F4?logo=python&logoColor=white)](https://github.com/astral-sh/uv)
 [![Poetry](https://img.shields.io/badge/dependencies-poetry-%2360A5FA?logo=poetry&logoColor=white)](https://python-poetry.org/)
+[![PyPI status](https://img.shields.io/pypi/status/apiexception?style=flat)](https://pypi.org/project/apiexception/)
 
 
 **APIException** is a robust, production-ready Python library for FastAPI that simplifies exception handling and ensures consistent, well-structured API responses. Designed for developers who want to eliminate boilerplate error handling and improve Swagger/OpenAPI documentation, APIException makes your FastAPI projects cleaner and easier to maintain.
@@ -34,20 +35,13 @@ Reading the [full documentation](https://akutayural.github.io/APIException/) is
 ---
 
 > [!IMPORTANT]
-> **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>
+> **Actively maintained. Highly recommended.**
 >  
-> **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>
+> APIException is actively maintained and used in production FastAPI services.  
+> It is designed to be integrated as a library, not copied piece by piece into projects.  
+>  
+> If you find yourself copy-pasting error handling logic across services,  
+> this library exists to replace that pattern with something cleaner and more sustainable.
 
 ---
 
@@ -63,21 +57,71 @@ pip install apiexception
 
  ## ⚡ Quickstart: How to Integrate APIException
 
-**1️⃣ Register the Handler**
+**1️⃣ Plug and Play**
 
 ```python
-from api_exception import register_exception_handlers, logger
 from fastapi import FastAPI
+from pydantic import BaseModel, Field
+from api_exception import (
+    register_exception_handlers,
+    APIException,
+    BaseExceptionCode,
+    ResponseModel,
+    APIResponse,
+)
 
 app = FastAPI()
 register_exception_handlers(app)  # uses ResponseModel by default
 
-logger.setLevel("INFO")  # Set logging level if needed
+
+class CustomExceptionCode(BaseExceptionCode):
+    USER_NOT_FOUND = ("USR-404", "User not found.", "The user ID does not exist.")
+
+
+class UserModel(BaseModel):
+    id: int = Field(..., example=1)
+    username: str = Field(..., example="John Doe")
+
+
+@app.get(
+    "/user/{user_id}",
+    response_model=ResponseModel[UserModel],
+    responses=APIResponse.default(),
+)
+async def user(user_id: int):
+    if user_id == 1:
+        raise APIException(
+            error_code=CustomExceptionCode.USER_NOT_FOUND,
+            http_status_code=404,
+        )
+    
+    if user_id == 3:
+        a = 1
+        b = 0
+        c = a / b  # This will raise ZeroDivisionError and be caught by the global exception handler
+        return c
+
+    return ResponseModel[UserModel](
+        data=UserModel(id=user_id, username="John Doe"),
+        description="User retrieved successfully.",
+    )
+
 ```
 
+
+![_user_{user_id}.gif](/assets/apiexception-indexBasicUsage-1.gif)
+
+![apiexception-indexApiExceptionLog.png](docs/advanced/exception_1.png)
+
+
+⭐ **Enjoying APIException?**  
+If this library saved you time or helped standardise your FastAPI responses,  
+consider giving it a ⭐ on GitHub. It really helps the project grow.
+
+
 ---
 
- ## 🔍 Example: Error Handling with Custom Codes
+ ## 🔍 Example: More Detailed Error Handling Example with Custom Codes
 
 ```python
 from typing import List, Optional, Any, Dict
@@ -173,6 +217,14 @@ your endpoints will display **clean, predictable response schemas** like this be
 
 ![_user_{user_id}.gif](/assets/apiexception-indexBasicUsage-1.gif)
 
+![apiexception-indexApiExceptionLog.png](docs/advanced/exception_1.png)
+
+
+
+For more examples, check it out in the [examples directory](https://github.com/akutayural/APIException/tree/main/examples).
+
+
+
 ---
 
 #### - Successful API Response? 
@@ -477,14 +529,22 @@ https://akutayural.github.io/APIException/
 🐍 **PyPI**  
 https://pypi.org/project/apiexception/
 
-💻 **Author Website**  
-https://ahmetkutayural.dev
+💻 **Author **  
+Ahmet Kutay Ural
+
+
+---
+⭐ **Used in real-world FastAPI projects**  
+APIException is actively used in production systems and shared across the Python community.  
+If you're using it in your project, a ⭐ on GitHub helps signal support and keeps development active.
 
 ---
 
 ## 🌍 Community & Recognition
 
 - 📢 Featured in [**Python Weekly #710**](https://www.pythonweekly.com/p/python-weekly-issue-710-august-14-2025-3200567a10d37d87) 🎉  
-- 🔥 Ranked **#3** globally in [r/FastAPI](https://www.reddit.com/r/FastAPI/comments/1ma39rq/make_your_fastapi_responses_clean_consistent/) under the *pip package* flair.  
+- 🏆 Selected as one of the **Top Python Libraries of 2025** by [**Tryolabs**](https://tryolabs.com/blog/top-python-libraries-2025) 
+- 🐍 Shared by [**PythonHub**](https://x.com/PythonHub/status/1957733129000472650) on X (Twitter)
+- 🐦 Shared by [@tom_doerr](https://x.com/tom_doerr/status/1996308358916116964) on X (Twitter)
 - ⭐ Gaining traction on GitHub with developers adopting it for real-world FastAPI projects.  
 - 💬 Actively discussed and shared across the Python community.

api_exception/__init__.py

@@ -52,8 +52,8 @@
 HeaderKeys = Tuple[str, ...]
 
 ExtraLogFields = Callable[
-    [Callable[[Request, Optional[BaseException]], Dict[str, Any]]],
-    Callable[[Request, Optional[BaseException]], Awaitable[Dict[str, Any]]]
+    [Request, Optional[BaseException]],
+    Union[Dict[str, Any], Awaitable[Dict[str, Any]]]
 ]
 
 
@@ -389,7 +389,7 @@ async def api_exception_handler(request: Request, exc: APIException):
                     pass
 
             if log_traceback and effective_level <= logging.DEBUG:
-                tb = traceback.format_exc()
+                tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
                 log_with_meta(logging.ERROR, f"APIException: {exc.message}", meta)
                 logger.error(f"Traceback:\n{tb}")
 
@@ -445,7 +445,7 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
                 msg = "Validation error"
 
             if log:
-                tb = traceback.format_exc()
+                tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
                 meta: Dict[str, Any] = {
                     "event": "validation_error",
                     "path": request.url.path,
@@ -459,7 +459,11 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
                     meta.update(_collect_headers(request, log_header_keys))
                 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:
                         pass
 
@@ -529,7 +533,7 @@ async def fallback_exception_middleware(request: Request, call_next: Callable):
             try:
                 return await call_next(request)
             except Exception as e:
-                tb = traceback.format_exc()
+                tb = "".join(traceback.format_exception(type(e), e, e.__traceback__))
 
                 if log:
                     meta: Dict[str, Any] = {
@@ -545,7 +549,11 @@ async def fallback_exception_middleware(request: Request, call_next: Callable):
                         meta.update(_collect_headers(request, log_header_keys))
                     if extra_log_fields:
                         try:
-                            meta.update(extra_log_fields(request, e))
+                            result = extra_log_fields(request, e)
+                            if inspect.isawaitable(result):
+                                result = await result
+                            if isinstance(result, dict):
+                                meta.update(result)
                         except Exception:
                             pass
 

docs/changelog.md

@@ -4,6 +4,23 @@ All notable changes to APIException will be documented here.
 This project uses *Semantic Versioning*.
 
 
+## [0.2.3] - 2026-01-21
+### Improved
+- Internal exception handling flow reviewed and stabilised for long-term maintenance.
+- Logging paths and async handling verified across all supported Python versions.
+- Minor internal refactors to improve readability and future extensibility without changing public APIs.
+- Confirmed backward compatibility with all existing `register_exception_handlers` usage patterns.
+
+### Documentation
+- README refined with clearer onboarding examples and improved Quickstart section.
+- Community & recognition section expanded with external mentions and ecosystem visibility.
+- Changelog and docs aligned to reflect current stable usage patterns and production readiness.
+
+### Maintenance
+- This release intentionally introduces **no breaking changes**.
+- Focused on stability, clarity, and long-term maintainability.
+- Actively used in production environments; no migration required for existing users.
+
 ---
 
 ## [0.2.2] - 2026-01-11
@@ -21,6 +38,7 @@ This project uses *Semantic Versioning*.
   - PyPI (`uv add apiexception`)
   - GitHub repository (`uv add git+https://github.com/akutayural/APIException.git`)
 
+---
 
 ## [0.2.1] - 2025-10-16
 ### Added
@@ -84,6 +102,7 @@ This project uses *Semantic Versioning*.
 - Added missing `import traceback` in `__init__.py`.  
   This resolves a `NameError` when using `register_exception_handlers` with traceback logging enabled.
 
+---
 
 ## [0.1.20] - 2025-08-18
 
@@ -95,6 +114,7 @@ This project uses *Semantic Versioning*.
 - Resolved IDE red import warnings when using the library in external projects.
 - Improved top-level import resolution and consistency across modules.
 
+---
 
 ## [0.1.19] - 2025-08-18
 
@@ -108,10 +128,10 @@ This project uses *Semantic Versioning*.
 #### Fixed
 - Example and README imports updated to use new unified style.
 
+---
 
 ## [0.1.18] - 2025-08-17
 
-
 ### Added
 - Global logging control (`set_global_log`) with `log` param in `register_exception_handlers`.
 - RFC7807 full support with `application/problem+json` responses.
@@ -126,6 +146,8 @@ This project uses *Semantic Versioning*.
 - Fallback middleware now returns HTTP 500 instead of 422 for unexpected errors.
 - Traceback scope bug fixed in handlers.
 
+---
+
 ## [v0.1.17] - 2025-08-11
 
 - `RFC 7807` standard support for consistent error responses (`application/problem+json`)
@@ -152,6 +174,7 @@ This project uses *Semantic Versioning*.
 
 - Readme.md has been updated. 
 
+---
 
 ## [v0.1.16] - 2025-07-22
 
@@ -161,6 +184,7 @@ This project uses *Semantic Versioning*.
 
 - Readme.md has been updated. 
 
+---
 
 ## [v0.1.15] - 2025-07-22
 
@@ -172,12 +196,15 @@ This project uses *Semantic Versioning*.
 
 - Readme.md has been updated. 
 
+---
+
 ## [v0.1.14] - 2025-07-22
 
 - setup.py has been updated.
 
 - Project name has been updated. Instead of `APIException` we will use `apiexception` to comply with `PEP 625`.
 
+---
 
 ## [v0.1.13] - 2025-07-21
 
@@ -191,7 +218,7 @@ This project uses *Semantic Versioning*.
 
 - Readme has been updated. New gifs have been added.
 
-
+---
 
 ## [0.1.12] - 2025-07-14
 
@@ -201,6 +228,7 @@ This project uses *Semantic Versioning*.
 
 - `__all__` includes more methods.
 
+---
 
 ## [0.1.11] - 2025-07-13
 
@@ -210,6 +238,7 @@ This project uses *Semantic Versioning*.
 
 - Production-ready logging for all exceptions
 
+---
 
 ## [0.1.0] - 2025-06-25