fastapi-errors-plus 0.6.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

fastapi_errors_plus/__init__.py

@@ -10,5 +10,5 @@ __all__ = [
     "BaseErrorDTO",  # Base implementation (optional)
     "StandardErrorDTO",  # Extended implementation (optional)
 ]
-__version__ = "0.6.1"
+__version__ = "0.7.0"
 

fastapi_errors_plus/base.py

@@ -37,6 +37,12 @@ class BaseErrorDTO:
     message: str
     """Error message description."""
     
+    openapi_json_extras: Optional[Dict[str, Any]] = field(default=None)
+    """Optional OpenAPI fragment under ``content['application/json']`` besides examples,
+    typically ``{\"schema\": ...}`` or ``encoding``. Do **not** put ``example`` / ``examples``
+    here — use :meth:`to_example`. Arbitrary implementations may instead implement
+    :meth:`to_openapi_json_media_type_extras`; that return value wins over this attribute."""
+    
     def to_example(self) -> Dict[str, Any]:
         """Generate example for OpenAPI.
         
@@ -122,3 +128,4 @@ class StandardErrorDTO(BaseErrorDTO):
 
 
 
+

fastapi_errors_plus/errors.py

@@ -7,6 +7,43 @@ from fastapi import status
 
 from fastapi_errors_plus.protocol import ErrorDTO
 
+# Starlette (via FastAPI) prefers HTTP_422_UNPROCESSABLE_CONTENT over ENTITY.
+# Older pins may lack CONTENT (import crash); avoid nested getattr(, default=)
+# touching ENTITY when CONTENT exists (DeprecationWarning).
+_HTTP_422 = getattr(status, "HTTP_422_UNPROCESSABLE_CONTENT", None)
+if _HTTP_422 is None:
+    _HTTP_422 = getattr(status, "HTTP_422_UNPROCESSABLE_ENTITY", 422)
+
+# OpenAPI Media Type: merge example/examples separately; other keys (schema, encoding, …) from an extra dict win.
+_OPENAPI_MEDIA_TYPE_EXAMPLE_KEYS = frozenset({"example", "examples"})
+
+
+def _merge_openapi_application_json_non_example(
+    existing_json: Dict[str, Any],
+    response_json: Dict[str, Any],
+) -> None:
+    """Apply schema/encoding/extra fields from incoming media type; incoming overwrites on conflict."""
+    for key, value in response_json.items():
+        if key not in _OPENAPI_MEDIA_TYPE_EXAMPLE_KEYS:
+            existing_json[key] = value
+
+
+def _pick_error_dto_application_json_extra(error_dto: Any) -> Optional[Dict[str, Any]]:
+    """Optional OpenAPI ``application/json`` keys from DTO (e.g. ``schema``, ``encoding``).
+
+    Prefer ``to_openapi_json_media_type_extras()`` when present and returns a truthy mapping;
+    otherwise ``openapi_json_extras`` attribute. Must not rely on ``example`` / ``examples`` here —
+    ``to_example()`` covers those."""
+    getter = getattr(error_dto, "to_openapi_json_media_type_extras", None)
+    if callable(getter):
+        out = getter()
+        if isinstance(out, dict) and out:
+            return dict(out)
+    extra = getattr(error_dto, "openapi_json_extras", None)
+    if isinstance(extra, dict) and extra:
+        return dict(extra)
+    return None
+
 
 class Errors(Mapping):
     """Universal class for documenting errors in FastAPI endpoints.
@@ -140,7 +177,7 @@ class Errors(Mapping):
         
         if add_422:
             self._add_standard_error(
-                status.HTTP_422_UNPROCESSABLE_ENTITY,
+                _HTTP_422,
                 "Validation Error",
                 {"detail": "Validation error"},
             )
@@ -239,7 +276,7 @@ class Errors(Mapping):
     STANDARD_DESCRIPTIONS = {
         status.HTTP_401_UNAUTHORIZED: "Unauthorized",
         status.HTTP_403_FORBIDDEN: "Forbidden",
-        status.HTTP_422_UNPROCESSABLE_ENTITY: "Validation Error",
+        _HTTP_422: "Validation Error",
         status.HTTP_500_INTERNAL_SERVER_ERROR: "Internal Server Error",
     }
     
@@ -263,7 +300,7 @@ class Errors(Mapping):
         standard_keys = {
             status.HTTP_401_UNAUTHORIZED: "StandardUnauthorized",
             status.HTTP_403_FORBIDDEN: "StandardForbidden",
-            status.HTTP_422_UNPROCESSABLE_ENTITY: "StandardValidationError",
+            _HTTP_422: "StandardValidationError",
             status.HTTP_500_INTERNAL_SERVER_ERROR: "StandardInternalServerError",
         }
         example_key = standard_keys.get(status_code, f"Standard{status_code}")
@@ -322,6 +359,10 @@ class Errors(Mapping):
                 if "description" in response_data:
                     existing["description"] = response_data["description"]
                 
+                # FastAPI-style shorthand on the response object (incoming dict wins)
+                if "model" in response_data:
+                    existing["model"] = response_data["model"]
+                
                 # Merge content
                 if "content" in response_data:
                     existing_content = existing.setdefault("content", {})
@@ -332,6 +373,8 @@ class Errors(Mapping):
                         existing_json = existing_content.setdefault("application/json", {})
                         response_json = response_content["application/json"]
                         
+                        _merge_openapi_application_json_non_example(existing_json, response_json)
+                        
                         # Handle example/examples
                         if "examples" in response_json:
                             # Response has examples
@@ -400,14 +443,16 @@ class Errors(Mapping):
         """
         status_code = error_dto.status_code
         examples = error_dto.to_example()
-        
+        dto_extras = _pick_error_dto_application_json_extra(error_dto)
+
         if status_code not in self._responses:
+            application_json: Dict[str, Any] = {"examples": examples}
+            if dto_extras is not None:
+                _merge_openapi_application_json_non_example(application_json, dto_extras)
             self._responses[status_code] = {
                 "description": error_dto.message,
                 "content": {
-                    "application/json": {
-                        "examples": examples,
-                    },
+                    "application/json": application_json,
                 },
             }
         else:
@@ -446,7 +491,10 @@ class Errors(Mapping):
             # Merge new examples from ErrorDTO
             existing_examples.update(examples)
             content_json["examples"] = existing_examples
-    
+            
+            if dto_extras is not None:
+                _merge_openapi_application_json_non_example(content_json, dto_extras)
+
     # Mapping protocol implementation
     def __getitem__(self, key: int) -> Dict[str, Any]:
         """Get response for status code.

fastapi_errors_plus/protocol.py

@@ -8,6 +8,13 @@ class ErrorDTO(Protocol):
     
     Any class implementing this protocol can be used with Errors().
     
+    Optionally, objects may expose **OpenAPI extras** besides examples:
+    
+    - ``openapi_json_extras``: ``dict`` merged into ``content["application/json"]``  
+      (e.g. ``{"schema": ...}`` — do **not** use for ``example`` / ``examples``).
+    - or ``to_openapi_json_media_type_extras() -> Optional[dict]``: if present and returns a
+      non-empty ``dict``, it **takes precedence** over ``openapi_json_extras``.
+    
     Example:
         ```python
         class MyError:
@@ -50,3 +57,4 @@ class ErrorDTO(Protocol):
 
 
 
+

{fastapi_errors_plus-0.6.1.dist-info → fastapi_errors_plus-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.6.1
+Version: 0.7.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -30,12 +30,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-101-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
 
@@ -207,6 +207,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`** use **`openapi_json_extras`** (a dict merged under `content["application/json"]` — omit `example` / `examples` there; **`to_example()`** 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):
@@ -297,6 +330,37 @@ 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:
@@ -335,6 +399,102 @@ Any class implementing this protocol (through structural typing) can be used wit
 
 Both approaches work together — you can mix them in the same `Errors()` call!
 
+## Using Pydantic with ErrorDTO
+
+**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.
+
+### Simple Pydantic Model as ErrorDTO
+
+```python
+from pydantic import BaseModel, Field
+from fastapi_errors_plus import Errors
+from typing import Dict, Any
+
+class PydanticErrorDTO(BaseModel):
+    """Pydantic model implementing ErrorDTO Protocol."""
+    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."""
+        return {
+            self.message: {
+                "value": {"detail": self.message},
+            },
+        }
+
+# Usage
+notification_error = PydanticErrorDTO(
+    status_code=404,
+    message="Notification not found",
+)
+
+@router.delete(
+    "/{id}",
+    responses=Errors(notification_error),
+)
+def delete_item(id: int):
+    pass
+```
+
+**Benefits:**
+- Runtime validation through Pydantic
+- Type safety
+- Automatic field documentation
+- Works with ErrorDTO Protocol through structural typing
+
+### Complex ErrorDTO with Pydantic
+
+For errors with additional fields:
+
+```python
+from pydantic import BaseModel, Field
+from fastapi_errors_plus import Errors
+from typing import Dict, Any, Optional
+
+class DetailedErrorDTO(BaseModel):
+    """Pydantic model for errors with additional fields."""
+    status_code: int = Field(..., ge=400, le=599)
+    message: str = Field(..., min_length=1)
+    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."""
+        example = {"detail": self.message}
+        if self.error_code:
+            example["error_code"] = self.error_code
+        if self.timestamp:
+            example["timestamp"] = self.timestamp
+        
+        return {
+            self.message: {
+                "value": example,
+            },
+        }
+
+# Usage
+validation_error = DetailedErrorDTO(
+    status_code=422,
+    message="Validation failed",
+    error_code="VALIDATION_ERROR",
+    timestamp="2025-01-15T10:30:00Z",
+)
+```
+
+**When to use Pydantic with ErrorDTO:**
+- Your project already uses Pydantic extensively
+- You need runtime validation for error objects
+- You want automatic field documentation
+- You have complex error structures with multiple fields
+
+**When not to use Pydantic:**
+- Your project doesn't use Pydantic (use `BaseErrorDTO` or `StandardErrorDTO` instead)
+- You need simple error objects (dataclasses are sufficient)
+- You want to keep dependencies minimal
+
 ## Best Practice: Connecting Exceptions and ErrorDTO
 
 ### Problem
@@ -472,14 +632,15 @@ 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]  # response block picked up by OpenAPI
 ```
 
 ### `ErrorDTO`
@@ -493,6 +654,8 @@ Protocol for error objects compatible with the library.
 **Required methods:**
 - `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
 
+During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -502,6 +665,7 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
@@ -519,6 +683,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,
 )
 ```
@@ -570,7 +735,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()
 
@@ -579,7 +744,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):
@@ -618,40 +783,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 __init__(self) -> None:
+        super().__init__(self.message)
+
     def to_example(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`):

fastapi_errors_plus-0.7.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastapi_errors_plus/__init__.py,sha256=sL6F1BA6lB3cYkk76CKisAVAhVocChlCs_7yiHqWED8,454
+fastapi_errors_plus/base.py,sha256=WNMypKQynTwe7GDxQdCCBwts5oHMaTgURmwMUmxeO0c,4021
+fastapi_errors_plus/errors.py,sha256=Jt0lQ7HocZsT3sfAx4nvSvHGFJ3cc6o2_4VsUoBLyU0,23161
+fastapi_errors_plus/protocol.py,sha256=u5nST4HdPUROXv0b5CYLXU9BAbF5Bh7ee_1MzEzYUxU,1644
+fastapi_errors_plus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_errors_plus-0.7.0.dist-info/licenses/LICENSE,sha256=PpYbS0f6IOOqH1JNR3K1UKZdEio6iO2ur9r8TwIZ7zs,1094
+fastapi_errors_plus-0.7.0.dist-info/METADATA,sha256=RD9nST74XBbunErEBsvWvbozidkT-Pa_B7gGhlLJ9uY,27669
+fastapi_errors_plus-0.7.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fastapi_errors_plus-0.7.0.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
+fastapi_errors_plus-0.7.0.dist-info/RECORD,,

{fastapi_errors_plus-0.6.1.dist-info → fastapi_errors_plus-0.7.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{fastapi_errors_plus-0.6.1.dist-info → fastapi_errors_plus-0.7.0.dist-info}/licenses/LICENSE

@@ -23,3 +23,4 @@ SOFTWARE.
 
 
 
+

fastapi_errors_plus-0.6.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-fastapi_errors_plus/__init__.py,sha256=aYuyu5HwVWzgT0QhkKhHuJez0ARHoHG0ynQCHQPzbrc,454
-fastapi_errors_plus/base.py,sha256=iTQ6WFxc5fLoY0Omi8aPNua7wBqQj20Z5ZPOOJhTIow,3580
-fastapi_errors_plus/errors.py,sha256=7ikmrSphWOH_nnxLC0HPQ0RPiuR1u8olw3bxGxdLv50,20868
-fastapi_errors_plus/protocol.py,sha256=466lfnVKWa1jjD0iWy3r_FIXFIqTuATJOT9sqXxbKZE,1218
-fastapi_errors_plus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-fastapi_errors_plus-0.6.1.dist-info/licenses/LICENSE,sha256=W_dONuuw-DA1UPcP9NPnQbhCbtMkLjhUr3Ne96398VU,1093
-fastapi_errors_plus-0.6.1.dist-info/METADATA,sha256=PA7WauqlQWEKuOIz_Mcv5ECBaLgTCng1cSKN34fJof4,21455
-fastapi_errors_plus-0.6.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fastapi_errors_plus-0.6.1.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
-fastapi_errors_plus-0.6.1.dist-info/RECORD,,