fastapi-errors-plus 0.6.2__tar.gz → 0.8.0__tar.gz

{fastapi_errors_plus-0.6.2 → fastapi_errors_plus-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.6.2
+Version: 0.8.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -22,6 +22,9 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
 # fastapi-errors-plus
@@ -30,12 +33,12 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-72%20passed-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-117-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
 
-> [Русская версия README](README.ru.md)
+> [Русская версия README](https://github.com/seligoroff/fastapi-errors-plus/blob/main/README.ru.md)
 
 ## Philosophy
 
@@ -164,7 +167,7 @@ class MyErrorDTO:
     status_code = 404
     message = "Not found"
     
-    def to_example(self):
+    def to_examples(self):
         return {
             "Not found": {
                 "value": {"detail": "Not found"},
@@ -207,6 +210,39 @@ def delete_item(id: int):
     pass
 ```
 
+#### OpenAPI extras (`schema`) next to examples
+
+ADR-style payloads (`code`, `detail`, optional `context`) need a **`schema`** in the spec besides **`examples`**. On **`BaseErrorDTO`** / **`StandardErrorDTO`** / **`ErrorDoc`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_examples()`** still defines examples):
+
+```python
+from fastapi import APIRouter, status
+from fastapi_errors_plus import BaseErrorDTO, Errors
+
+ADR_ERROR_BODY_SCHEMA = {
+    "type": "object",
+    "required": ["code", "detail"],
+    "properties": {
+        "code": {"type": "string"},
+        "detail": {"type": "string"},
+        "context": {"type": "object"},
+    },
+}
+
+business_conflict = BaseErrorDTO(
+    status_code=status.HTTP_409_CONFLICT,
+    message="BusinessRuleViolation",
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+router = APIRouter()
+
+@router.post("/items", responses=Errors(business_conflict, validation_error=False))
+def create_item():
+    ...
+```
+
+Custom **`ErrorDTO`** classes may instead define **`to_openapi_json_media_type_extras()`** returning a **`dict`**; if present and non-empty, it overrides **`openapi_json_extras`**. Any later **`dict`** in **`Errors`** for that status still overrides the same **`application/json`** keys (same precedence as merging two dicts).
+
 #### StandardErrorDTO
 
 Extended implementation for errors with multiple examples (useful for standard HTTP errors):
@@ -251,6 +287,37 @@ def delete_item(id: int):
 - Reusable across all endpoints
 - Supports inheritance for custom logic
 
+`examples` values may be **strings** (shorthand for `{"detail": text}`) or full OpenAPI Example Objects with **`summary`** and **`value`**.
+
+#### ErrorDoc
+
+For arbitrary response bodies (ADR `code` / `detail` / `context`, not only `detail` strings), use **`ErrorDoc`**:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+permission_denied = ErrorDoc(
+    status_code=403,
+    message="Insufficient permissions",
+    examples={
+        "MissingRole": {
+            "summary": "User lacks required role",
+            "value": {
+                "code": "FORBIDDEN",
+                "detail": "Role admin required",
+            },
+        },
+    },
+    openapi_json_extras={"schema": ADR_ERROR_BODY_SCHEMA},
+)
+
+@router.delete("/{id}", responses=Errors(permission_denied))
+def delete_item(id: int):
+    ...
+```
+
+A **plain dict** as an example value is treated as the full response **body** unless it looks like an OpenAPI Example Object (keys only among `value`, `summary`, `description`, `externalValue`).
+
 ### 5. Mixed Usage
 
 Combine flags, dict, and ErrorDTO:
@@ -297,9 +364,40 @@ def update_item(id: int):
 
 The OpenAPI spec will contain both examples under the 404 status code.
 
+When merging the same status code: a **dict** wins for **`description`** over the bundled standard-flag wording; an **ErrorDTO**’s `message` can replace the description only while it still matches the library’s default label for that code (custom descriptions coming from dicts are not overwritten by DTOs).
+
+Under `content["application/json"]`, `example` / `examples` are merged as before; any **other** OpenAPI Media Type fields from a later **`dict`** (for example **`schema`**, **`encoding`**) are **copied in** as well—the later dict wins on conflict (**same rule as `description`**).  
+
+You can combine one **`ErrorDTO`** (examples) with a **`dict`** for the **same numeric status code** listing only **`schema`** (or other non-example keys) without repeating the boilerplate examples block:
+
+```python
+Errors(
+    conflict_error_doc,   # implements ErrorDTO, e.g. .for_openapi() for ADR-shaped examples
+    {
+        status.HTTP_409_CONFLICT: {
+            "description": "Business rule violation",
+            "content": {
+                "application/json": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "code": {"type": "string"},
+                            "detail": {"type": "string"},
+                            "context": {"type": "object"},
+                        },
+                    },
+                },
+            },
+        },
+    },
+)
+```
+
+Order matters only for overlaps: whichever **`dict`** is applied **later** in the **`Errors`** argument list overwrites **`schema`** / **`encoding`** (and **`model`** on the outer response dict, if provided) when the same keys appear again.
+
 ## ErrorDTO Protocol
 
-The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
+The canonical **`ErrorDTO`** protocol defines the interface for error objects compatible with the library:
 
 ```python
 from typing import Protocol, Dict, Any
@@ -308,27 +406,30 @@ class ErrorDTO(Protocol):
     status_code: int
     message: str
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI.
-        
-        Returns:
-            Dict in format: {"key": {"value": {"detail": "message"}}}
-        """
+    def to_examples(self) -> Dict[str, Any]:
+        """OpenAPI ``examples`` map: {"Key": {"value": {...}, "summary": "..."}}."""
         ...
 ```
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**Legacy migration:** classes that only define **`to_example()`** still work at **runtime** (`DeprecationWarning` once per class per `Errors()` call). For static typing use **`LegacyErrorDTO`** or the union alias **`ErrorDTOLike`** (`ErrorDTO | LegacyErrorDTO`).
+
 **Best Practice:** For maximum clarity, consider making your domain exceptions implement the ErrorDTO protocol directly. See [Best Practice: Connecting Exceptions and ErrorDTO](#best-practice-connecting-exceptions-and-errordto) for details.
 
 ### When to Use Protocol vs BaseErrorDTO
 
+Optional on custom DTOs (OpenAPI media-type extras without duplicating a status `dict`):
+
+- attribute **`openapi_json_extras`**: fragment for **`content["application/json"]`** (often `{"schema": ...}` — not for `example` / `examples`);
+- or method **`to_openapi_json_media_type_extras() -> Optional[dict]`** — when non-empty, overrides **`openapi_json_extras`**.
+
 **Use Protocol (structural typing)** when:
 - Your project already has error DTOs that implement the protocol
 - You need maximum flexibility and custom implementations
 - You want to keep your existing error infrastructure
 
-**Use BaseErrorDTO/StandardErrorDTO** when:
+**Use BaseErrorDTO/StandardErrorDTO/ErrorDoc** when:
 - Starting a new project or adding error documentation
 - You want a ready-to-use implementation without boilerplate
 - You need multiple examples for standard HTTP errors (401, 403, etc.)
@@ -339,7 +440,7 @@ Both approaches work together — you can mix them in the same `Errors()` call!
 
 **Note:** Pydantic is **not required** to use this library. This section is for projects that already use Pydantic and want to integrate it with the ErrorDTO protocol.
 
-Since the library uses structural typing (Protocol), any class that implements the required attributes (`status_code`, `message`, `to_example()`) will work, including Pydantic models.
+Since the library uses structural typing (Protocol), any class that implements the required attributes (`status_code`, `message`, `to_examples()`) will work, including Pydantic models. Legacy `to_example()` is still accepted at runtime.
 
 ### Simple Pydantic Model as ErrorDTO
 
@@ -353,8 +454,8 @@ class PydanticErrorDTO(BaseModel):
     status_code: int = Field(..., ge=400, le=599, description="HTTP status code")
     message: str = Field(..., min_length=1, description="Error message")
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate examples for OpenAPI."""
         return {
             self.message: {
                 "value": {"detail": self.message},
@@ -397,8 +498,8 @@ class DetailedErrorDTO(BaseModel):
     error_code: Optional[str] = Field(None, description="Internal error code")
     timestamp: Optional[str] = Field(None, description="Error timestamp")
     
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate examples for OpenAPI."""
         example = {"detail": self.message}
         if self.error_code:
             example["error_code"] = self.error_code
@@ -455,7 +556,7 @@ class DomainException(Exception):
     status_code: int
     message: str
     
-    def to_example(self) -> Dict[str, Any]:
+    def to_examples(self) -> Dict[str, Any]:
         return {self.message: {"value": {"detail": self.message}}}
     
     @classmethod
@@ -498,7 +599,7 @@ See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete
 
 ## Compatibility with Existing Projects
 
-If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol:
+If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol (or legacy `to_example()` during migration):
 
 ```python
 # Your existing ApiErrorDTO
@@ -507,7 +608,7 @@ class ApiErrorDTO:
     status_code: int
     message: str
     
-    def to_example(self) -> dict:
+    def to_examples(self) -> dict:
         return {
             self.message: {
                 "value": {"detail": self.message},
@@ -568,16 +669,21 @@ Errors(
 FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant in 95%+ of endpoints. For endpoints without parameters, explicitly set `validation_error=False` or `validation_error_422=False`.
 
 **Returns:**
-- Mapping object (dict-like) that implements `Dict[int, Dict[str, Any]]` for FastAPI responses
-- Can be used directly in `responses` parameter without calling: `responses=Errors(...)`
+- A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
+- Pass the instance as-is — **do not** call it like a function: `responses=Errors(...)`
 
 #### Usage
 
 ```python
-# Call the instance to get responses dict
-responses = Errors(unauthorized=True)
+# Instances are Mapping keyed by HTTP status codes
+error_responses = Errors(unauthorized_401=True, forbidden_403=True)
+documented = error_responses[401]  # deep copy — safe to read, won't mutate internal state
 ```
 
+**Isolation (0.8+):** incoming response **dicts** are **deep-copied** on ingest; **`errors[status]`** returns a **deep copy** so callers cannot corrupt shared registry templates or internal merge state.
+
+**Descriptions:** response blocks with only **`model`** (no `description`) get a default from **`HTTPStatus.phrase`** so OpenAPI generation does not fail.
+
 ### `ErrorDTO`
 
 Protocol for error objects compatible with the library.
@@ -587,7 +693,32 @@ Protocol for error objects compatible with the library.
 - `message: str` — Error message description
 
 **Required methods:**
-- `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
+- `to_examples() -> Dict[str, Any]` — OpenAPI `examples` map for `application/json`
+
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable **`to_examples()`** / **`to_example()`** raise **`TypeError`** naming what was missing.
+
+### `LegacyErrorDTO` / `ErrorDTOLike`
+
+- **`LegacyErrorDTO`** — typing helper for classes that only implement deprecated **`to_example()`**.
+- **`ErrorDTOLike`** — `Union[ErrorDTO, LegacyErrorDTO]` for transitional annotations.
+
+### `ErrorDoc`
+
+Declarative DTO for arbitrary example bodies and per-example **`summary`**.
+
+**Constructor:**
+```python
+ErrorDoc(
+    status_code: int,
+    message: str,
+    examples: Optional[Dict[str, str | dict]] = None,
+    body: Optional[Dict[str, Any]] = None,
+    example_key: Optional[str] = None,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
+)
+```
+
+When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
 
 ### `BaseErrorDTO`
 
@@ -598,6 +729,7 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
@@ -615,6 +747,7 @@ Extended implementation for errors with multiple examples.
 StandardErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
     examples: Optional[Dict[str, str]] = None,
 )
 ```
@@ -666,7 +799,7 @@ def delete_item(id: int):
 ```python
 from fastapi import APIRouter
 from fastapi_errors_plus import Errors
-from api.exceptions.dto import errors  # Your project's error DTOs
+from api.exceptions.dto import notification_not_found_error  # ErrorDTO-compatible instance
 
 router = APIRouter()
 
@@ -675,7 +808,7 @@ router = APIRouter()
     responses=Errors(
         unauthorized=True,
         forbidden=True,
-        errors.notification_not_found_error,  # Your ErrorDTO
+        notification_not_found_error,
     ),
 )
 async def delete_notification(notification_id: int):
@@ -714,40 +847,32 @@ This example shows how to use `fastapi-errors-plus` in a FastAPI project with Cl
 
 **Domain Layer** (`domain/errors.py`):
 ```python
-from typing import Protocol, Dict, Any
+from typing import Dict, Any
 
-class DomainError(Protocol):
-    """Domain error protocol compatible with ErrorDTO."""
+class DomainException(Exception):
+    """Domain exception usable as runtime error and shaped like ErrorDTO for OpenAPI."""
     status_code: int
     message: str
-    
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI."""
-        ...
 
-class ItemNotFoundError:
-    """Domain error for item not found."""
-    status_code = 404
-    message = "Item not found"
-    
-    def to_example(self) -> Dict[str, Any]:
+    def __init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_examples(self) -> Dict[str, Any]:
         return {
-            "ItemNotFound": {
-                "value": {"detail": "Item not found"},
+            self.message: {
+                "value": {"detail": self.message},
             },
         }
 
-class ItemAlreadyExistsError:
-    """Domain error for item already exists."""
+
+class ItemNotFoundError(DomainException):
+    status_code = 404
+    message = "Item not found"
+
+
+class ItemAlreadyExistsError(DomainException):
     status_code = 409
     message = "Item already exists"
-    
-    def to_example(self) -> Dict[str, Any]:
-        return {
-            "ItemAlreadyExists": {
-                "value": {"detail": "Item already exists"},
-            },
-        }
 ```
 
 **Application Layer** (`application/use_cases.py`):