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

fastapi_errors_plus/__init__.py

@@ -1,14 +1,17 @@
 """Universal library for documenting errors in FastAPI endpoints."""
 
 from fastapi_errors_plus.base import BaseErrorDTO, StandardErrorDTO
+from fastapi_errors_plus.error_doc import ErrorDoc
 from fastapi_errors_plus.errors import Errors
-from fastapi_errors_plus.protocol import ErrorDTO
+from fastapi_errors_plus.protocol import ErrorDTO, ErrorDTOLike, LegacyErrorDTO
 
 __all__ = [
     "Errors",
-    "ErrorDTO",  # Protocol (for structural typing)
-    "BaseErrorDTO",  # Base implementation (optional)
-    "StandardErrorDTO",  # Extended implementation (optional)
+    "ErrorDTO",
+    "LegacyErrorDTO",
+    "ErrorDTOLike",
+    "ErrorDoc",
+    "BaseErrorDTO",
+    "StandardErrorDTO",
 ]
-__version__ = "0.7.0"
-
+__version__ = "0.8.0"

fastapi_errors_plus/base.py

@@ -1,28 +1,31 @@
 """Base implementations of ErrorDTO protocol for convenience."""
 
+import warnings
 from dataclasses import dataclass, field
 from typing import Any, Dict, Optional
 
+from fastapi_errors_plus.example_utils import ExampleSpec, _normalize_example_specs
+
 
 @dataclass
 class BaseErrorDTO:
     """Base implementation of ErrorDTO Protocol.
-    
+
     Projects can use this class directly or create their own implementation
     that implements ErrorDTO Protocol through structural typing.
-    
+
     This class provides a simple way to create error DTOs without writing
     boilerplate code in every project.
-    
+
     Example:
         ```python
         from fastapi_errors_plus import Errors, BaseErrorDTO
-        
+
         notification_error = BaseErrorDTO(
             status_code=404,
             message="Notification not found",
         )
-        
+
         @router.delete(
             "/{id}",
             responses=Errors(notification_error),
@@ -31,51 +34,48 @@ class BaseErrorDTO:
             pass
         ```
     """
+
     status_code: int
     """HTTP status code for the error."""
-    
+
     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.
-        
-        Returns:
-            Dict in format: {"key": {"value": {"detail": "message"}}}
-            
-        Example:
-            ```python
-            {
-                "Notification not found": {
-                    "value": {"detail": "Notification not found"},
-                },
-            }
-            ```
-        """
+
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate OpenAPI ``examples`` for this error."""
         return {
             self.message: {
                 "value": {"detail": self.message},
             },
         }
 
+    def to_example(self) -> Dict[str, Any]:
+        """Deprecated alias for :meth:`to_examples`."""
+        warnings.warn(
+            "to_example() is deprecated; use to_examples() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.to_examples()
+
 
 @dataclass
 class StandardErrorDTO(BaseErrorDTO):
     """Extended implementation for errors with multiple examples.
-    
+
     Useful for standard HTTP errors (401, 403) that can have different
     causes with different messages.
-    
+
     Example:
         ```python
         from fastapi_errors_plus import Errors, StandardErrorDTO
-        
+
         unauthorized_error = StandardErrorDTO(
             status_code=401,
             message="Unauthorized",
@@ -84,7 +84,7 @@ class StandardErrorDTO(BaseErrorDTO):
                 "SessionNotFound": "Сессия пользователя не была найдена.",
             },
         )
-        
+
         @router.delete(
             "/{id}",
             responses=Errors(unauthorized_error),
@@ -93,39 +93,25 @@ class StandardErrorDTO(BaseErrorDTO):
             pass
         ```
     """
-    examples: Optional[Dict[str, str]] = field(default=None)
-    """Dictionary of examples: {"key": "message"}."""
-    
+
+    examples: Optional[Dict[str, ExampleSpec]] = field(default=None)
+    """Examples: ``str`` detail text or full OpenAPI example object (with ``summary``)."""
+
     def __post_init__(self) -> None:
         """Initialize examples with default value if not provided."""
         if self.examples is None:
             self.examples = {self.message: self.message}
-    
-    def to_example(self) -> Dict[str, Any]:
-        """Generate examples for OpenAPI with multiple examples.
-        
-        Returns:
-            Dict in format: {"key": {"value": {"detail": "message"}}, ...}
-            
-        Example:
-            ```python
-            {
-                "InvalidToken": {
-                    "value": {"detail": "Ошибка декодирования токена."},
-                },
-                "SessionNotFound": {
-                    "value": {"detail": "Сессия пользователя не была найдена."},
-                },
-            }
-            ```
-        """
-        return {
-            key: {
-                "value": {"detail": message},
-            }
-            for key, message in self.examples.items()
-        }
-
-
 
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate OpenAPI ``examples`` with optional summaries."""
+        assert self.examples is not None
+        return _normalize_example_specs(self.examples)
 
+    def to_example(self) -> Dict[str, Any]:
+        """Deprecated alias for :meth:`to_examples`."""
+        warnings.warn(
+            "to_example() is deprecated; use to_examples() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.to_examples()

fastapi_errors_plus/error_doc.py

@@ -0,0 +1,59 @@
+"""Declarative error documentation for OpenAPI."""
+
+import warnings
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from fastapi_errors_plus.example_utils import ExampleSpec, _normalize_example_specs
+
+
+@dataclass
+class ErrorDoc:
+    """Declarative ErrorDTO with arbitrary example bodies and optional summaries.
+
+    ``examples`` values:
+
+    * **str** — shorthand ``{"detail": text}`` (same as bundled DTOs).
+    * **dict** with only OpenAPI Example Object keys (``value``, ``summary``, …) —
+      used as the Example Object.
+    * **any other dict** — treated as the full response **body** (e.g.
+      ``{"code": "...", "detail": "...", "value": 150}``).
+
+    Example:
+        ```python
+        ErrorDoc(
+            status_code=403,
+            message="Insufficient permissions",
+            examples={
+                "MissingRole": {
+                    "summary": "User lacks required role",
+                    "value": {"code": "FORBIDDEN", "detail": "Role admin required"},
+                },
+            },
+        )
+        ```
+    """
+
+    status_code: int
+    message: str
+    examples: Optional[Dict[str, ExampleSpec]] = None
+    body: Optional[Dict[str, Any]] = None
+    example_key: Optional[str] = None
+    openapi_json_extras: Optional[Dict[str, Any]] = field(default=None)
+
+    def to_examples(self) -> Dict[str, Any]:
+        """Build OpenAPI ``examples`` map for ``application/json``."""
+        if self.examples is not None:
+            return _normalize_example_specs(self.examples)
+        key = self.example_key or self.message
+        value = self.body if self.body is not None else {"detail": self.message}
+        return {key: {"value": value}}
+
+    def to_example(self) -> Dict[str, Any]:
+        """Deprecated alias for :meth:`to_examples`."""
+        warnings.warn(
+            "to_example() is deprecated; use to_examples() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.to_examples()

fastapi_errors_plus/errors.py

@@ -1,6 +1,9 @@
 """Main Errors class for documenting errors in FastAPI endpoints."""
 
+import copy
+import warnings
 from collections.abc import Mapping
+from http import HTTPStatus
 from typing import Any, Dict, Iterator, Optional, Union
 
 from fastapi import status
@@ -10,9 +13,12 @@ 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)
+_HTTP_422: int
+_http_422_attr = getattr(status, "HTTP_422_UNPROCESSABLE_CONTENT", None)
+if _http_422_attr is None:
+    _HTTP_422 = int(getattr(status, "HTTP_422_UNPROCESSABLE_ENTITY", 422))
+else:
+    _HTTP_422 = int(_http_422_attr)
 
 # OpenAPI Media Type: merge example/examples separately; other keys (schema, encoding, …) from an extra dict win.
 _OPENAPI_MEDIA_TYPE_EXAMPLE_KEYS = frozenset({"example", "examples"})
@@ -45,24 +51,89 @@ def _pick_error_dto_application_json_extra(error_dto: Any) -> Optional[Dict[str,
     return None
 
 
+def _example_defining_class(cls: type, method: str) -> Optional[type]:
+    """First class in MRO that defines *method* in its own ``__dict__``."""
+    for base in cls.__mro__:
+        if method in base.__dict__:
+            return base
+    return None
+
+
+def _collect_dto_examples(error_dto: Any) -> Dict[str, Any]:
+    """Return a deep copy of examples from an ErrorDTO.
+
+      Resolution walks the MRO: the most specific ``to_examples`` wins over an
+    inherited ``to_example`` on the same branch; legacy ``to_example`` only on
+    the defining class emits a single actionable deprecation warning.
+    """
+    cls = type(error_dto)
+    examples_cls = _example_defining_class(cls, "to_examples")
+    legacy_cls = _example_defining_class(cls, "to_example")
+
+    if examples_cls is not None:
+        use_examples = legacy_cls is None or cls.__mro__.index(
+            examples_cls
+        ) <= cls.__mro__.index(legacy_cls)
+        if use_examples:
+            return copy.deepcopy(error_dto.to_examples())
+
+    if legacy_cls is not None:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            result = error_dto.to_example()
+        warnings.warn(
+            f"{cls.__name__} implements deprecated to_example(); use to_examples() instead.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return copy.deepcopy(result)
+
+    raise TypeError(f"{cls.__name__} has no to_examples() or to_example()")
+
+
+def _apply_dto_description(
+    existing: Dict[str, Any],
+    error_dto: Any,
+    standard_descriptions: Dict[int, str],
+) -> None:
+    """Set ``description`` from DTO when missing, empty, or still a standard flag label."""
+    desc = existing.get("description")
+    if desc is None or (isinstance(desc, str) and not desc.strip()):
+        existing["description"] = error_dto.message
+    elif desc == standard_descriptions.get(error_dto.status_code):
+        existing["description"] = error_dto.message
+
+
+def _ensure_response_descriptions(responses: Dict[int, Dict[str, Any]]) -> None:
+    """Fill missing descriptions so FastAPI OpenAPI generation does not assert."""
+    for code, response in responses.items():
+        desc = response.get("description")
+        if desc is not None and isinstance(desc, str) and desc.strip():
+            continue
+        try:
+            response["description"] = HTTPStatus(code).phrase
+        except ValueError:
+            response["description"] = f"HTTP {code}"
+
+
 class Errors(Mapping):
     """Universal class for documenting errors in FastAPI endpoints.
-    
+
     Works with any FastAPI project. Can accept:
     - Standard HTTP statuses via boolean flags
     - Dict in FastAPI responses format
     - Objects implementing ErrorDTO protocol (for project compatibility)
-    
+
     Implements Mapping protocol, so can be used directly in FastAPI responses
     parameter without calling ().
-    
+
     Example:
         ```python
         from fastapi import APIRouter
         from fastapi_errors_plus import Errors
-        
+
         router = APIRouter()
-        
+
         @router.delete(
             "/{id}",
             responses=Errors(
@@ -83,25 +154,29 @@ class Errors(Mapping):
             pass
         ```
     """
-    
+
     def __init__(
         self,
         # Arbitrary errors (dict or ErrorDTO) - must come first
         *errors: Union[Dict[int, Dict[str, Any]], ErrorDTO],
         # Standard HTTP statuses (boolean flags)
         # Old parameters (for backward compatibility)
-        unauthorized: bool = False,           # 401
-        forbidden: bool = False,              # 403
-        validation_error: Optional[bool] = None,        # 422 (None = use default True, False = disable, True = enable)
+        unauthorized: bool = False,  # 401
+        forbidden: bool = False,  # 403
+        validation_error: Optional[
+            bool
+        ] = None,  # 422 (None = use default True, False = disable, True = enable)
         internal_server_error: bool = False,  # 500
         # New parameters with explicit status codes (recommended)
-        unauthorized_401: bool = False,      # 401 (explicit)
-        forbidden_403: bool = False,          # 403 (explicit)
-        validation_error_422: Optional[bool] = None,   # 422 (explicit, None = use default True, False = disable, True = enable)
+        unauthorized_401: bool = False,  # 401 (explicit)
+        forbidden_403: bool = False,  # 403 (explicit)
+        validation_error_422: Optional[
+            bool
+        ] = None,  # 422 (explicit, None = use default True, False = disable, True = enable)
         internal_server_error_500: bool = False,  # 500 (explicit)
     ) -> None:
         """Initialize Errors instance.
-        
+
         Args:
             *errors: Arbitrary errors as dict or ErrorDTO objects.
                 Dict should be in FastAPI responses format: {status_code: {...}}.
@@ -110,7 +185,7 @@ class Errors(Mapping):
                 Deprecated: Use `unauthorized_401` instead for explicit status code.
             forbidden: Add 403 Forbidden error. Defaults to False.
                 Deprecated: Use `forbidden_403` instead for explicit status code.
-            validation_error: Add 422 Unprocessable Entity error. 
+            validation_error: Add 422 Unprocessable Entity error.
                 - None (default): Add 422 (True by default, FastAPI validates all parameters)
                 - False: Explicitly disable 422
                 - True: Explicitly enable 422
@@ -121,25 +196,25 @@ class Errors(Mapping):
                 Deprecated: Use `internal_server_error_500` instead for explicit status code.
             unauthorized_401: Add 401 Unauthorized error (explicit). Defaults to False.
             forbidden_403: Add 403 Forbidden error (explicit). Defaults to False.
-            validation_error_422: Add 422 Unprocessable Entity error (explicit). 
+            validation_error_422: Add 422 Unprocessable Entity error (explicit).
                 - None (default): Add 422 (True by default, FastAPI validates all parameters)
                 - False: Explicitly disable 422
                 - True: Explicitly enable 422
                 FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant
                 in 95%+ of endpoints. Set to False only for endpoints without parameters.
             internal_server_error_500: Add 500 Internal Server Error (explicit). Defaults to False.
-        
+
         Example:
             ```python
             # Standard flags only
             errors = Errors(unauthorized=True, forbidden=True)
-            
+
             # Dict errors
             errors = Errors({404: {"description": "Not found", ...}})
-            
+
             # ErrorDTO
             errors = Errors(MyErrorDTO())
-            
+
             # Mixed
             errors = Errors(
                 {409: {...}},
@@ -149,7 +224,7 @@ class Errors(Mapping):
             ```
         """
         self._responses: Dict[int, Dict[str, Any]] = {}
-        
+
         # Add standard errors
         # New parameters with explicit codes have priority, but old ones still work
         if unauthorized_401 or unauthorized:
@@ -174,7 +249,7 @@ class Errors(Mapping):
         if validation_error is False or validation_error_422 is False:
             # At least one is explicitly False - don't add
             add_422 = False
-        
+
         if add_422:
             self._add_standard_error(
                 _HTTP_422,
@@ -187,7 +262,7 @@ class Errors(Mapping):
                 "Internal Server Error",
                 {"detail": "Internal Server Error"},
             )
-        
+
         # Add arbitrary errors
         for error in errors:
             if isinstance(error, dict):
@@ -198,16 +273,18 @@ class Errors(Mapping):
                 self._validate_error_dto(error)
                 # ErrorDTO (compatible with ApiErrorDTO via Protocol)
                 self._add_error_dto(error)
-    
+
+        _ensure_response_descriptions(self._responses)
+
     def _validate_error_dto(self, error: Any) -> None:
         """Validate that error object implements ErrorDTO protocol.
-        
+
         Args:
             error: Object to validate
-            
+
         Raises:
             TypeError: If object doesn't implement ErrorDTO protocol
-            
+
         Example:
             ```python
             # Valid object
@@ -215,49 +292,47 @@ class Errors(Mapping):
                 status_code = 404
                 message = "Not found"
                 def to_example(self): ...
-            
+
             errors = Errors()
             errors._validate_error_dto(MyError())  # OK
-            
+
             # Invalid object
             class BadError:
                 status_code = 404
                 # Missing message and to_example
-            
+
             errors._validate_error_dto(BadError())  # Raises TypeError
             ```
         """
         required_attrs = ("status_code", "message")
-        required_methods = ("to_example",)
-        
-        missing_attrs = [
-            attr for attr in required_attrs 
-            if not hasattr(error, attr)
-        ]
-        missing_methods = [
-            method for method in required_methods 
-            if not hasattr(error, method) or not callable(getattr(error, method, None))
-        ]
-        
+        has_to_examples = callable(getattr(error, "to_examples", None))
+        has_to_example = callable(getattr(error, "to_example", None))
+
+        missing_attrs = [attr for attr in required_attrs if not hasattr(error, attr)]
+        if not has_to_examples and not has_to_example:
+            missing_methods = ["to_examples or to_example"]
+        else:
+            missing_methods = []
+
         if missing_attrs or missing_methods:
             missing = missing_attrs + missing_methods
             raise TypeError(
                 f"ErrorDTO object must have {', '.join(required_attrs)} attributes "
-                f"and {', '.join(required_methods)}() method. "
+                f"and to_examples() or to_example() method. "
                 f"Missing: {', '.join(missing)}. "
                 f"Got {type(error).__name__}"
             )
-    
+
     def _unique_key(self, examples: Dict[str, Any], base: str) -> str:
         """Generate unique key for examples dict.
-        
+
         Args:
             examples: Existing examples dict
             base: Base key name
-            
+
         Returns:
             Unique key that doesn't exist in examples
-            
+
         Example:
             >>> errors = Errors()
             >>> errors._unique_key({"default": {}}, "default")
@@ -271,15 +346,15 @@ class Errors(Mapping):
             key = f"{base}_{i}"
             i += 1
         return key
-    
+
     # Standard descriptions for priority checking
-    STANDARD_DESCRIPTIONS = {
+    STANDARD_DESCRIPTIONS: Dict[int, str] = {
         status.HTTP_401_UNAUTHORIZED: "Unauthorized",
         status.HTTP_403_FORBIDDEN: "Forbidden",
         _HTTP_422: "Validation Error",
         status.HTTP_500_INTERNAL_SERVER_ERROR: "Internal Server Error",
     }
-    
+
     def _add_standard_error(
         self,
         status_code: int,
@@ -287,10 +362,10 @@ class Errors(Mapping):
         example: Dict[str, Any],
     ) -> None:
         """Add standard error.
-        
+
         If the status code already exists, merges the example with existing examples
         using a unique key instead of overwriting.
-        
+
         Args:
             status_code: HTTP status code (e.g., 401, 403, 422, 500)
             description: Error description for OpenAPI
@@ -304,7 +379,7 @@ class Errors(Mapping):
             status.HTTP_500_INTERNAL_SERVER_ERROR: "StandardInternalServerError",
         }
         example_key = standard_keys.get(status_code, f"Standard{status_code}")
-        
+
         if status_code not in self._responses:
             self._responses[status_code] = {
                 "description": description,
@@ -320,7 +395,7 @@ class Errors(Mapping):
             existing = self._responses[status_code]
             existing_content = existing.setdefault("content", {})
             content = existing_content.setdefault("application/json", {})
-            
+
             # Convert example to examples if needed
             if "examples" not in content:
                 if "example" in content:
@@ -330,51 +405,56 @@ class Errors(Mapping):
                     }
                 else:
                     content["examples"] = {}
-            
+
             # Add new example with unique key (don't overwrite existing!)
             # Check if example_key already exists in examples, use unique key if needed
             unique_key = self._unique_key(content["examples"], example_key)
             content["examples"][unique_key] = {"value": example}
-            
+
             # Don't overwrite description if it already exists
             # Priority: dict > DTO > standard flags
-    
+
     def _add_dict_error(self, error_dict: Dict[int, Dict[str, Any]]) -> None:
         """Add error from dict in FastAPI responses format.
-        
+
         Merges examples instead of overwriting the entire response entry.
-        
+
         Args:
             error_dict: Dict in format {status_code: {"description": ..., "content": {...}}}
         """
         for status_code, response_data in error_dict.items():
+            response_data = copy.deepcopy(response_data)
             if status_code not in self._responses:
-                # New status code - just add it
+                # New status code - deep copy so caller dict is not aliased
                 self._responses[status_code] = response_data
             else:
                 # Status code already exists - merge
                 existing = self._responses[status_code]
-                
+
                 # Merge description (dict takes priority)
                 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", {})
                     response_content = response_data["content"]
-                    
+
                     # Merge application/json
                     if "application/json" in response_content:
-                        existing_json = existing_content.setdefault("application/json", {})
+                        existing_json = existing_content.setdefault(
+                            "application/json", {}
+                        )
                         response_json = response_content["application/json"]
-                        
-                        _merge_openapi_application_json_non_example(existing_json, response_json)
-                        
+
+                        _merge_openapi_application_json_non_example(
+                            existing_json, response_json
+                        )
+
                         # Handle example/examples
                         if "examples" in response_json:
                             # Response has examples
@@ -387,9 +467,11 @@ class Errors(Mapping):
                                     }
                                 else:
                                     existing_json["examples"] = {}
-                            
+
                             # Merge examples
-                            existing_json["examples"].update(response_json["examples"])
+                            existing_json["examples"].update(
+                                copy.deepcopy(response_json["examples"])
+                            )
                         elif "example" in response_json:
                             # Response has example - convert and merge
                             if "examples" not in existing_json:
@@ -405,30 +487,38 @@ class Errors(Mapping):
                                         "Internal Server Error": "StandardInternalServerError",
                                     }
                                     existing_detail = existing_example.get("detail", "")
-                                    example_key = standard_messages.get(existing_detail, "default")
+                                    example_key = standard_messages.get(
+                                        existing_detail, "default"
+                                    )
                                     existing_json["examples"] = {
                                         example_key: {"value": existing_example},
                                     }
                                 else:
                                     existing_json["examples"] = {}
-                            
+
                             # Add new example - use "default" if available, otherwise unique key
                             if "default" not in existing_json["examples"]:
-                                existing_json["examples"]["default"] = {"value": response_json["example"]}
+                                existing_json["examples"]["default"] = {
+                                    "value": response_json["example"]
+                                }
                             else:
                                 # If default exists, add with a unique key
-                                unique_key = self._unique_key(existing_json["examples"], "CustomExample")
-                                existing_json["examples"][unique_key] = {"value": response_json["example"]}
-    
+                                unique_key = self._unique_key(
+                                    existing_json["examples"], "CustomExample"
+                                )
+                                existing_json["examples"][unique_key] = {
+                                    "value": response_json["example"]
+                                }
+
     def _add_error_dto(self, error_dto: ErrorDTO) -> None:
         """Add error from ErrorDTO (via Protocol).
-        
+
         If the status code already exists, merges examples with existing examples.
-        
+
         Args:
-            error_dto: Error object implementing ErrorDTO protocol.
-                Must have `status_code`, `message`, and `to_example()` method.
-        
+            error_dto: Object with ``status_code``, ``message``, and
+                ``to_examples()`` and/or legacy ``to_example()``.
+
         Example:
             ```python
             class MyError:
@@ -436,19 +526,23 @@ class Errors(Mapping):
                 message = "Not found"
                 def to_example(self):
                     return {"Not found": {"value": {"detail": "Not found"}}}
-            
+
             errors = Errors()
             errors._add_error_dto(MyError())
             ```
         """
         status_code = error_dto.status_code
-        examples = error_dto.to_example()
+        examples = _collect_dto_examples(error_dto)
         dto_extras = _pick_error_dto_application_json_extra(error_dto)
+        if dto_extras is not None:
+            dto_extras = copy.deepcopy(dto_extras)
 
         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)
+                _merge_openapi_application_json_non_example(
+                    application_json, dto_extras
+                )
             self._responses[status_code] = {
                 "description": error_dto.message,
                 "content": {
@@ -459,20 +553,18 @@ class Errors(Mapping):
             # Merge examples for the same status code
             # Safely access content/application/json with defaults
             existing = self._responses[status_code]
-            
-            # If description is standard, replace it with DTO message (priority: DTO > flags)
-            if existing.get("description") == self.STANDARD_DESCRIPTIONS.get(status_code):
-                existing["description"] = error_dto.message
-            
+
+            _apply_dto_description(existing, error_dto, self.STANDARD_DESCRIPTIONS)
+
             existing_content = existing.setdefault("content", {})
             content_json = existing_content.setdefault("application/json", {})
             existing_examples = content_json.get("examples", {})
-            
+
             if "example" in content_json:
                 # Convert example to examples with correct key for standard flags
                 existing_example = content_json.pop("example")
                 existing_detail = existing_example.get("detail", "")
-                
+
                 # Check if existing example is from a standard flag
                 standard_messages = {
                     "Unauthorized": "StandardUnauthorized",
@@ -481,48 +573,47 @@ class Errors(Mapping):
                     "Internal Server Error": "StandardInternalServerError",
                 }
                 example_key = standard_messages.get(existing_detail, "default")
-                
+
                 existing_examples = {
                     example_key: {
                         "value": existing_example,
                     },
                 }
-            
+
             # Merge new examples from ErrorDTO
-            existing_examples.update(examples)
+            existing_examples.update(copy.deepcopy(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.
-        
+
         Args:
             key: HTTP status code (e.g., 401, 403, 404)
-            
+
         Returns:
             Response dict in FastAPI format
-            
+
         Raises:
             KeyError: If status code not found
         """
-        return self._responses[key]
-    
+        return copy.deepcopy(self._responses[key])
+
     def __iter__(self) -> Iterator[int]:
         """Iterate over status codes.
-        
+
         Returns:
             Iterator over status codes
         """
         return iter(self._responses)
-    
+
     def __len__(self) -> int:
         """Get number of status codes.
-        
+
         Returns:
             Number of documented error status codes
         """
         return len(self._responses)
-

fastapi_errors_plus/example_utils.py

@@ -0,0 +1,52 @@
+"""OpenAPI example normalization shared by ErrorDoc and bundled DTOs."""
+
+import warnings
+from typing import Any, Dict, Union
+
+# OpenAPI 3 Example Object allowed keys (subset used by this library).
+_OPENAPI_EXAMPLE_OBJECT_KEYS = frozenset(
+    {"value", "summary", "description", "externalValue"}
+)
+
+ExampleSpec = Union[str, Dict[str, Any]]
+
+
+def _is_openapi_example_object(spec: Dict[str, Any]) -> bool:
+    """True if *spec* looks like an OpenAPI Example Object, not a response body."""
+    if not spec:
+        return False
+    return set(spec.keys()) <= _OPENAPI_EXAMPLE_OBJECT_KEYS
+
+
+def _normalize_example_specs(specs: Dict[str, ExampleSpec]) -> Dict[str, Any]:
+    """Normalize user specs to OpenAPI ``examples`` map.
+
+    * ``str`` — shorthand for ``{"value": {"detail": str}}`` (legacy detail shape).
+    * ``dict`` — if keys are only OpenAPI Example Object fields, used as-is;
+      otherwise the whole dict is treated as the response **body** wrapped in
+      ``{"value": body}`` (avoids mis-parsing bodies that contain a ``value`` field).
+    """
+    out: Dict[str, Any] = {}
+    for key, spec in specs.items():
+        if isinstance(spec, str):
+            out[key] = {"value": {"detail": spec}}
+        elif isinstance(spec, dict):
+            if _is_openapi_example_object(spec):
+                out[key] = dict(spec)
+            else:
+                extra = set(spec.keys()) - _OPENAPI_EXAMPLE_OBJECT_KEYS
+                if "value" in spec and extra:
+                    warnings.warn(
+                        f"Example {key!r}: keys {sorted(extra)} look like a response body, "
+                        "not an OpenAPI Example Object; wrapping the dict as the example value. "
+                        "Use explicit Example Object keys only "
+                        "(value, summary, description, externalValue) at the top level.",
+                        UserWarning,
+                        stacklevel=3,
+                    )
+                out[key] = {"value": spec}
+        else:
+            raise TypeError(
+                f"Example spec for key {key!r} must be str or dict, got {type(spec).__name__}"
+            )
+    return out

fastapi_errors_plus/protocol.py

@@ -1,60 +1,40 @@
 """Protocol for error DTOs compatible with fastapi-errors-plus."""
 
-from typing import Any, Dict, Protocol
+from typing import Any, Dict, Protocol, Union, runtime_checkable
 
 
+@runtime_checkable
 class ErrorDTO(Protocol):
-    """Protocol for error objects compatible with the library.
-    
-    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:
-            status_code = 404
-            message = "Not found"
-            
-            def to_example(self) -> Dict[str, Any]:
-                return {
-                    "Not found": {
-                        "value": {"detail": "Not found"},
-                    },
-                }
-        
-        errors = Errors(MyError())
-        ```
+    """Target interface for error objects used with :class:`Errors`.
+
+      Implement ``to_examples()`` returning an OpenAPI ``examples`` map::
+
+          {"ExampleKey": {"value": {...}, "summary": "..."}}
+
+    Legacy classes that only define ``to_example()`` are accepted at **runtime**
+    by :class:`Errors` but do **not** satisfy this protocol for static typing.
+    See :class:`LegacyErrorDTO`.
     """
+
     status_code: int
-    """HTTP status code for the error."""
-    
     message: str
-    """Error message description."""
-    
-    def to_example(self) -> Dict[str, Any]:
-        """Generate example for OpenAPI.
-        
-        Returns:
-            Dict in format: {"key": {"value": {"detail": "message"}}}
-            
-        Example:
-            ```python
-            {
-                "Not found": {
-                    "value": {"detail": "Not found"},
-                },
-            }
-            ```
-        """
+
+    def to_examples(self) -> Dict[str, Any]:
+        """Generate OpenAPI ``examples`` for this error."""
         ...
 
 
+@runtime_checkable
+class LegacyErrorDTO(Protocol):
+    """Deprecated: only ``to_example()`` — migrate to :class:`ErrorDTO`."""
 
+    status_code: int
+    message: str
+
+    def to_example(self) -> Dict[str, Any]:
+        """Deprecated OpenAPI ``examples`` map."""
+        ...
 
 
+# Annotation helper for codebases still on legacy ``to_example()`` only.
+ErrorDTOLike = Union[ErrorDTO, LegacyErrorDTO]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.7.0
+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,7 +33,7 @@ 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-101-success.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.
@@ -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"},
@@ -209,7 +212,7 @@ def delete_item(id: int):
 
 #### 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):
+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
@@ -284,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:
@@ -363,7 +397,7 @@ Order matters only for overlaps: whichever **`dict`** is applied **later** in th
 
 ## 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
@@ -372,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.)
@@ -403,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
 
@@ -417,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},
@@ -461,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
@@ -519,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
@@ -562,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
@@ -571,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},
@@ -640,9 +677,13 @@ FastAPI automatically validates all parameters (Path, Query, Body), so 422 is re
 ```python
 # 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
+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.
@@ -652,9 +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,
+)
+```
 
-During `Errors(...)` initialization, non-`dict` objects in `*errors` missing `status_code`, `message`, or a callable `to_example` raise **`TypeError`** naming what was missing.
+When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
 
 ### `BaseErrorDTO`
 
@@ -793,7 +857,7 @@ class DomainException(Exception):
     def __init__(self) -> None:
         super().__init__(self.message)
 
-    def to_example(self) -> Dict[str, Any]:
+    def to_examples(self) -> Dict[str, Any]:
         return {
             self.message: {
                 "value": {"detail": self.message},

fastapi_errors_plus-0.8.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+fastapi_errors_plus/__init__.py,sha256=sFQ2ykXQgnjAbTb6NsY8bkrAAbZTrrF_xUd8KXAXln4,484
+fastapi_errors_plus/base.py,sha256=MB_IITnVFFSP8SazHo2AJDfEJrVwhnx3DqRl2Z6I2xE,3784
+fastapi_errors_plus/error_doc.py,sha256=5DThH8WW_6R-DSIoOLq-zU4ccr8lDv0fEe0uuKS8ce8,2010
+fastapi_errors_plus/errors.py,sha256=OmdZ_-8L2k0rLPZgNr68yxs3n2YQa28RWovk6P7Qf4k,25772
+fastapi_errors_plus/example_utils.py,sha256=bHAj8dBhVxc3ozQPGuEHuXtH4--bSzJKFiqejnwCVPU,2161
+fastapi_errors_plus/protocol.py,sha256=2P04uAnItLepU0pBznFF5XhTKVPugeK5W9KjoUAwmEA,1145
+fastapi_errors_plus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_errors_plus-0.8.0.dist-info/licenses/LICENSE,sha256=PpYbS0f6IOOqH1JNR3K1UKZdEio6iO2ur9r8TwIZ7zs,1094
+fastapi_errors_plus-0.8.0.dist-info/METADATA,sha256=19pI0EfTyi7HqHmbX0lwLKjQcPAjUxxz7K2ixfJkNYE,30659
+fastapi_errors_plus-0.8.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+fastapi_errors_plus-0.8.0.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
+fastapi_errors_plus-0.8.0.dist-info/RECORD,,

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

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

fastapi_errors_plus-0.7.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-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,,