fastapi-error-map 0.9.2__tar.gz → 0.9.4__tar.gz

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-error-map
-Version: 0.9.2
+Version: 0.9.4
 Summary: Elegant per-endpoint error handling in FastAPI with OpenAPI schema generation
 Project-URL: Homepage, https://github.com/ivan-borovets/fastapi-error-map
 Project-URL: Repository, https://github.com/ivan-borovets/fastapi-error-map
@@ -41,8 +41,9 @@ Description-Content-Type: text/markdown
 
 ## FastAPI Error Map
 
-[![PyPI version](https://badge.fury.io/py/fastapi-error-map.svg?cacheBust=1)](https://badge.fury.io/py/fastapi-error-map)
+[![PyPI version](https://badge.fury.io/py/fastapi-error-map.svg?cacheBust=4)](https://badge.fury.io/py/fastapi-error-map)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastapi-error-map?cacheBust=1)
+[![codecov](https://codecov.io/gh/ivan-borovets/fastapi-error-map/branch/master/graph/badge.svg?token=ABTVQLI0RL)](https://codecov.io/gh/ivan-borovets/fastapi-error-map)
 ![GitHub License](https://img.shields.io/github/license/ivan-borovets/fastapi-error-map?cacheBust=1)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ivan-borovets/fastapi-error-map/ci.yaml?cacheBust=1)
 
@@ -122,7 +123,7 @@ there's no single source of truth.
 `fastapi-error-map` solves this by letting you define error handling rules right in the route declaration.
 See the [example in the 🚀 Quickstart](#-quickstart).
 
-### ⚙ How `error_map` Works
+### ⚙ Using `error_map`
 
 Error handling rules are defined directly in the route declaration of an `ErrorAwareRouter`, using the `error_map`
 parameter.
@@ -151,7 +152,7 @@ In both cases, the default translator is used, which returns JSON like:
 
 ```json
 {
-  "error": "SomeError"
+  "error": "..."
 }
 ```
 
@@ -177,6 +178,13 @@ Parameters of `rule(...)`, * — required:
   `{ "error": "..." }`)
 - `on_error` — function to call when an exception occurs (e.g. logging or alerting)
 
+#### 🧩 Matching semantics
+
+`error_map` matches **exact** exception types only (no inheritance).
+If you map `BaseError` and raise `ChildError(BaseError)`, the rule won’t apply.
+This is by design to keep routing explicit.
+If there’s demand, inheritance-based resolving may be added later as an opt-in.
+
 ### 🧰 Custom Translators
 
 If you want to change the error response format, define your own `translator` — object that implements `ErrorTranslator`
@@ -212,11 +220,16 @@ class MyTranslator(ErrorTranslator[MyErrorResponse]):
 
 ```
 
+#### ⚠️ Translator robustness
+
+Custom translators should not raise exceptions.
+If `from_error(...)` fails at runtime, the exception will propagate to FastAPI’s global handlers.
+
 ### 🔄 Side Effects (`on_error`)
 
 The `on_error` parameter in `rule(...)` allows specifying function to run when exception occurs, before response is
 generated.
-It doesn't affect the HTTP response, but it's useful for:
+It doesn’t change the response status/body when it succeeds and is useful for:
 
 - logging
 - sending alerts
@@ -240,6 +253,18 @@ error_map = {
 
 ```
 
+#### 🚨 Strict side effects
+
+`on_error` is executed before the response is generated.
+If it raises, the exception propagates and the request fails.
+This is intentional to avoid hiding errors in side effects — they should be fixed rather than silently ignored.
+Keep `on_error` robust or wrap it on your side if you prefer soft-fail logging.
+
+> [!NOTE]
+> Both translator and `on_error` receive the raised exception as an argument.
+> If your implementation does not use it, suppress the unused-argument warning from your linter (e.g. `# noqa: ARG002`
+> for Ruff).
+
 ### 🧠 Parameter Precedence
 
 Error handling and schema generation in `fastapi-error-map` are fully driven by route-level arguments to `.get()`,
@@ -298,7 +323,7 @@ from `error_map` — but only for the specified status codes.
 
 ```
 
-#### 🚨 Handling Unmapped Exceptions (`warn_on_unmapped`)
+#### ❗ Handling Unmapped Exceptions (`warn_on_unmapped`)
 
 By default (`warn_on_unmapped=True`), `fastapi-error-map` expects every exception raised in a handler to be explicitly
 listed in `error_map`.  
@@ -320,3 +345,8 @@ This behavior is not affected by `warn_on_unmapped`.
 
 If the error is declared in `error_map`, `fastapi-error-map` handles the response itself — the global handler will not
 be triggered.
+
+### 📚 Examples
+
+- Minimal usage: [`examples/`](./examples/main.py)
+- More advanced usage: [Clean Architecture example app](https://github.com/ivan-borovets/fastapi-clean-example)

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/README.md

@@ -1,7 +1,8 @@
 ## FastAPI Error Map
 
-[![PyPI version](https://badge.fury.io/py/fastapi-error-map.svg?cacheBust=1)](https://badge.fury.io/py/fastapi-error-map)
+[![PyPI version](https://badge.fury.io/py/fastapi-error-map.svg?cacheBust=4)](https://badge.fury.io/py/fastapi-error-map)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastapi-error-map?cacheBust=1)
+[![codecov](https://codecov.io/gh/ivan-borovets/fastapi-error-map/branch/master/graph/badge.svg?token=ABTVQLI0RL)](https://codecov.io/gh/ivan-borovets/fastapi-error-map)
 ![GitHub License](https://img.shields.io/github/license/ivan-borovets/fastapi-error-map?cacheBust=1)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ivan-borovets/fastapi-error-map/ci.yaml?cacheBust=1)
 
@@ -81,7 +82,7 @@ there's no single source of truth.
 `fastapi-error-map` solves this by letting you define error handling rules right in the route declaration.
 See the [example in the 🚀 Quickstart](#-quickstart).
 
-### ⚙ How `error_map` Works
+### ⚙ Using `error_map`
 
 Error handling rules are defined directly in the route declaration of an `ErrorAwareRouter`, using the `error_map`
 parameter.
@@ -110,7 +111,7 @@ In both cases, the default translator is used, which returns JSON like:
 
 ```json
 {
-  "error": "SomeError"
+  "error": "..."
 }
 ```
 
@@ -136,6 +137,13 @@ Parameters of `rule(...)`, * — required:
   `{ "error": "..." }`)
 - `on_error` — function to call when an exception occurs (e.g. logging or alerting)
 
+#### 🧩 Matching semantics
+
+`error_map` matches **exact** exception types only (no inheritance).
+If you map `BaseError` and raise `ChildError(BaseError)`, the rule won’t apply.
+This is by design to keep routing explicit.
+If there’s demand, inheritance-based resolving may be added later as an opt-in.
+
 ### 🧰 Custom Translators
 
 If you want to change the error response format, define your own `translator` — object that implements `ErrorTranslator`
@@ -171,11 +179,16 @@ class MyTranslator(ErrorTranslator[MyErrorResponse]):
 
 ```
 
+#### ⚠️ Translator robustness
+
+Custom translators should not raise exceptions.
+If `from_error(...)` fails at runtime, the exception will propagate to FastAPI’s global handlers.
+
 ### 🔄 Side Effects (`on_error`)
 
 The `on_error` parameter in `rule(...)` allows specifying function to run when exception occurs, before response is
 generated.
-It doesn't affect the HTTP response, but it's useful for:
+It doesn’t change the response status/body when it succeeds and is useful for:
 
 - logging
 - sending alerts
@@ -199,6 +212,18 @@ error_map = {
 
 ```
 
+#### 🚨 Strict side effects
+
+`on_error` is executed before the response is generated.
+If it raises, the exception propagates and the request fails.
+This is intentional to avoid hiding errors in side effects — they should be fixed rather than silently ignored.
+Keep `on_error` robust or wrap it on your side if you prefer soft-fail logging.
+
+> [!NOTE]
+> Both translator and `on_error` receive the raised exception as an argument.
+> If your implementation does not use it, suppress the unused-argument warning from your linter (e.g. `# noqa: ARG002`
+> for Ruff).
+
 ### 🧠 Parameter Precedence
 
 Error handling and schema generation in `fastapi-error-map` are fully driven by route-level arguments to `.get()`,
@@ -257,7 +282,7 @@ from `error_map` — but only for the specified status codes.
 
 ```
 
-#### 🚨 Handling Unmapped Exceptions (`warn_on_unmapped`)
+#### ❗ Handling Unmapped Exceptions (`warn_on_unmapped`)
 
 By default (`warn_on_unmapped=True`), `fastapi-error-map` expects every exception raised in a handler to be explicitly
 listed in `error_map`.  
@@ -279,3 +304,8 @@ This behavior is not affected by `warn_on_unmapped`.
 
 If the error is declared in `error_map`, `fastapi-error-map` handles the response itself — the global handler will not
 be triggered.
+
+### 📚 Examples
+
+- Minimal usage: [`examples/`](./examples/main.py)
+- More advanced usage: [Clean Architecture example app](https://github.com/ivan-borovets/fastapi-clean-example)

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/fastapi_error_map/error_handling.py

@@ -18,10 +18,12 @@ def wrap_with_error_handling(
     default_server_error_translator: ErrorTranslator[Any],
     default_on_error: Optional[Callable[[Exception], None]],
 ) -> Callable[..., Any]:
+    is_coro = inspect.iscoroutinefunction(func)
+
     @wraps(func)
     async def wrapped(*args: Any, **kwargs: Any) -> Any:
         try:
-            if inspect.iscoroutinefunction(func):
+            if is_coro:
                 return await func(*args, **kwargs)
             return func(*args, **kwargs)
         except Exception as error:
@@ -57,7 +59,8 @@ def handle_with_error_map(
     except RuntimeError as exc:
         if warn_on_unmapped:
             raise
-        raise (exc.__cause__ or exc) from None
+        original = exc.__cause__ or exc
+        raise original.with_traceback(original.__traceback__) from None
 
     if rule.on_error is not None:
         rule.on_error(error)

fastapi_error_map-0.9.4/fastapi_error_map/openapi.py

@@ -0,0 +1,34 @@
+from typing import Any, Union
+
+from fastapi_error_map.rules import ErrorMap
+from fastapi_error_map.translator_policy import pick_translator_for_status
+from fastapi_error_map.translators import ErrorTranslator
+
+
+def build_openapi_responses(
+    *,
+    error_map: ErrorMap,
+    default_client_error_translator: ErrorTranslator[Any],
+    default_server_error_translator: ErrorTranslator[Any],
+) -> dict[Union[int, str], dict[str, Any]]:
+    responses: dict[Union[int, str], dict[str, Any]] = {}
+
+    for value in error_map.values():
+        if isinstance(value, int):
+            status = value
+            translator = None
+        else:
+            status = value.status
+            translator = value.translator
+
+        if translator is None:
+            translator = pick_translator_for_status(
+                status=status,
+                default_client_error_translator=default_client_error_translator,
+                default_server_error_translator=default_server_error_translator,
+            )
+
+        response_model = translator.error_response_model_cls
+        responses[status] = {"model": response_model}
+
+    return responses

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/fastapi_error_map/routing.py

@@ -100,7 +100,11 @@ class ErrorAwareRoute(APIRoute):
                 default_server_error_translator=self.default_server_error_translator,
             )
         responses = {
-            **build_openapi_responses(self.error_map),
+            **build_openapi_responses(
+                error_map=self.error_map,
+                default_client_error_translator=self.default_client_error_translator,
+                default_server_error_translator=self.default_server_error_translator,
+            ),
             **(responses if responses is not None else {}),
         }
         super().__init__(

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/fastapi_error_map/rules.py

@@ -1,8 +1,7 @@
 from dataclasses import dataclass
 from typing import Any, Callable, Optional, Union
 
-from starlette import status as http_status
-
+from fastapi_error_map.translator_policy import pick_translator_for_status
 from fastapi_error_map.translators import ErrorTranslator
 
 
@@ -62,6 +61,7 @@ def resolve_rule_for_error(
         status_or_rule = error_map[type(error)]
     except KeyError:
         raise RuntimeError(f"No rule defined for {type(error).__name__}") from error
+
     if isinstance(status_or_rule, int):
         status, translator, on_error = status_or_rule, None, default_on_error
     else:
@@ -70,12 +70,14 @@ def resolve_rule_for_error(
             status_or_rule.translator,
             status_or_rule.on_error or default_on_error,
         )
+
     if translator is None:
-        translator = (
-            default_server_error_translator
-            if status >= http_status.HTTP_500_INTERNAL_SERVER_ERROR
-            else default_client_error_translator
+        translator = pick_translator_for_status(
+            status=status,
+            default_client_error_translator=default_client_error_translator,
+            default_server_error_translator=default_server_error_translator,
         )
+
     return ResolvedRule(
         status=status,
         translator=translator,

fastapi_error_map-0.9.4/fastapi_error_map/translator_policy.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from starlette import status as http_status
+
+from fastapi_error_map.translators import ErrorTranslator
+
+
+def is_server_error(status: int) -> bool:
+    return status >= http_status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+def pick_translator_for_status(
+    *,
+    status: int,
+    default_client_error_translator: ErrorTranslator[Any],
+    default_server_error_translator: ErrorTranslator[Any],
+) -> ErrorTranslator[Any]:
+    return (
+        default_server_error_translator
+        if is_server_error(status)
+        else default_client_error_translator
+    )

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/fastapi_error_map/translators.py

@@ -71,5 +71,5 @@ class DefaultServerErrorTranslator(ErrorTranslator[SimpleErrorResponseModel]):
     def error_response_model_cls(self) -> type[SimpleErrorResponseModel]:
         return SimpleErrorResponseModel
 
-    def from_error(self, _err: Exception) -> SimpleErrorResponseModel:
-        return SimpleErrorResponseModel(error="Internal server error.")
+    def from_error(self, err: Exception) -> SimpleErrorResponseModel:
+        return SimpleErrorResponseModel(error="Internal server error")

{fastapi_error_map-0.9.2 → fastapi_error_map-0.9.4}/pyproject.toml

@@ -7,7 +7,7 @@ sources = ["src"]
 
 [project]
 name = "fastapi-error-map"
-version = "0.9.2"
+version = "0.9.4"
 description = "Elegant per-endpoint error handling in FastAPI with OpenAPI schema generation"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -160,6 +160,7 @@ split-on-trailing-comma = true
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
+    "ARG002", # unused-method-argument
     "PLR2004", # magic-value-comparison
     "S101", # assert
 ]
@@ -175,6 +176,9 @@ split-on-trailing-comma = true
     "UP006", # non-pep585-annotation
     "UP035", # deprecated-import
 ]
+"src/fastapi_error_map/translators.py" = [
+    "ARG002", # unused-method-argument
+]
 
 [tool.slotscheck]
 strict-imports = true

fastapi_error_map-0.9.4/tests/unit/test_openapi.py

@@ -0,0 +1,65 @@
+from typing import TYPE_CHECKING
+
+from fastapi_error_map.openapi import build_openapi_responses
+from fastapi_error_map.rules import rule
+from tests.unit.error_stubs import DatabaseError, ValidationError
+from tests.unit.translator_stubs import (
+    ClientErrorStub,
+    CustomTranslator,
+    DummyClientErrorTranslator,
+    DummyServerErrorTranslator,
+    ServerErrorStub,
+)
+
+if TYPE_CHECKING:
+    from fastapi_error_map.rules import ErrorMap
+
+
+def test_builds_response_from_short_form_rule() -> None:
+    error_map: ErrorMap = {
+        ValidationError: 400,
+        DatabaseError: 503,
+    }
+
+    responses = build_openapi_responses(
+        error_map=error_map,
+        default_client_error_translator=DummyClientErrorTranslator(),
+        default_server_error_translator=DummyServerErrorTranslator(),
+    )
+
+    assert responses == {
+        400: {"model": ClientErrorStub},
+        503: {"model": ServerErrorStub},
+    }
+
+
+def test_builds_response_from_full_form_rule() -> None:
+    error_map: ErrorMap = {
+        ValidationError: rule(status=400),
+        DatabaseError: rule(status=503),
+    }
+
+    responses = build_openapi_responses(
+        error_map=error_map,
+        default_client_error_translator=DummyClientErrorTranslator(),
+        default_server_error_translator=DummyServerErrorTranslator(),
+    )
+
+    assert responses == {
+        400: {"model": ClientErrorStub},
+        503: {"model": ServerErrorStub},
+    }
+
+
+def test_builds_response_with_custom_translator() -> None:
+    error_map: ErrorMap = {
+        ValidationError: rule(status=400, translator=CustomTranslator()),
+    }
+
+    responses = build_openapi_responses(
+        error_map=error_map,
+        default_client_error_translator=DummyClientErrorTranslator(),
+        default_server_error_translator=DummyServerErrorTranslator(),
+    )
+
+    assert responses == {400: {"model": dict}}

fastapi_error_map-0.9.4/tests/unit/translator_stubs.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+
+from fastapi_error_map import ErrorTranslator
+
+
+@dataclass
+class ClientErrorStub:
+    error: str
+
+
+@dataclass
+class ServerErrorStub:
+    error: str
+
+
+class DummyClientErrorTranslator(ErrorTranslator[ClientErrorStub]):
+    @property
+    def error_response_model_cls(self) -> type[ClientErrorStub]:
+        return ClientErrorStub
+
+    def from_error(self, err: Exception) -> ClientErrorStub:
+        return ClientErrorStub(error=f"client:{err}")
+
+
+class DummyServerErrorTranslator(ErrorTranslator[ServerErrorStub]):
+    @property
+    def error_response_model_cls(self) -> type[ServerErrorStub]:
+        return ServerErrorStub
+
+    def from_error(self, err: Exception) -> ServerErrorStub:
+        return ServerErrorStub(error="internal")
+
+
+class CustomTranslator(ErrorTranslator[dict[str, str]]):
+    @property
+    def error_response_model_cls(self) -> type[dict[str, str]]:
+        return dict
+
+    def from_error(self, err: Exception) -> dict[str, str]:
+        return {"msg": "explicit"}

fastapi_error_map-0.9.2/fastapi_error_map/openapi.py

@@ -1,26 +0,0 @@
-from typing import Any, Union
-
-from fastapi_error_map.rules import ErrorMap
-from fastapi_error_map.translators import SimpleErrorResponseModel
-
-
-def build_openapi_responses(
-    error_map: ErrorMap,
-    default_response_model: type[Any] = SimpleErrorResponseModel,
-) -> dict[Union[int, str], dict[str, Any]]:
-    responses: dict[Union[int, str], dict[str, Any]] = {}
-
-    for value in error_map.values():
-        if isinstance(value, int):
-            status_code = value
-            response_model: type[Any] = default_response_model
-        else:
-            status_code = value.status
-            response_model = (
-                value.translator.error_response_model_cls
-                if value.translator is not None
-                else default_response_model
-            )
-        responses[status_code] = {"model": response_model}
-
-    return responses

fastapi_error_map-0.9.2/tests/unit/test_openapi.py

@@ -1,48 +0,0 @@
-from typing import TYPE_CHECKING
-
-from fastapi_error_map import SimpleErrorResponseModel
-from fastapi_error_map.openapi import build_openapi_responses
-from fastapi_error_map.rules import rule
-from tests.unit.error_stubs import DatabaseError, ValidationError
-from tests.unit.translator_stubs import CustomTranslator
-
-if TYPE_CHECKING:
-    from fastapi_error_map.rules import ErrorMap
-
-
-def test_builds_response_from_short_form_rule() -> None:
-    error_map: ErrorMap = {
-        ValidationError: 400,
-        DatabaseError: 503,
-    }
-
-    responses = build_openapi_responses(error_map)
-
-    assert responses == {
-        400: {"model": SimpleErrorResponseModel},
-        503: {"model": SimpleErrorResponseModel},
-    }
-
-
-def test_builds_response_from_full_form_rule() -> None:
-    error_map: ErrorMap = {
-        ValidationError: rule(status=400),
-        DatabaseError: rule(status=503),
-    }
-
-    responses = build_openapi_responses(error_map)
-
-    assert responses == {
-        400: {"model": SimpleErrorResponseModel},
-        503: {"model": SimpleErrorResponseModel},
-    }
-
-
-def test_builds_response_with_custom_translator() -> None:
-    error_map: ErrorMap = {
-        ValidationError: rule(status=400, translator=CustomTranslator()),
-    }
-
-    responses = build_openapi_responses(error_map)
-
-    assert responses == {400: {"model": dict}}

fastapi_error_map-0.9.2/tests/unit/translator_stubs.py

@@ -1,28 +0,0 @@
-from fastapi_error_map import ErrorTranslator
-
-
-class DummyClientErrorTranslator(ErrorTranslator[dict[str, str]]):
-    @property
-    def error_response_model_cls(self) -> type[dict[str, str]]:
-        return dict
-
-    def from_error(self, err: Exception) -> dict[str, str]:
-        return {"error": f"client:{err}"}
-
-
-class DummyServerErrorTranslator(ErrorTranslator[dict[str, str]]):
-    @property
-    def error_response_model_cls(self) -> type[dict[str, str]]:
-        return dict
-
-    def from_error(self, _err: Exception) -> dict[str, str]:
-        return {"error": "internal"}
-
-
-class CustomTranslator(ErrorTranslator[dict[str, str]]):
-    @property
-    def error_response_model_cls(self) -> type[dict[str, str]]:
-        return dict
-
-    def from_error(self, _err: Exception) -> dict[str, str]:
-        return {"msg": "explicit"}