fastapi-errors-plus 0.6.2__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.6.2"
-
+__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,45 +34,48 @@ class BaseErrorDTO:
             pass
         ```
     """
+
     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
-            {
-                "Notification not found": {
-                    "value": {"detail": "Notification not found"},
-                },
-            }
-            ```
-        """
+
+    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_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",
@@ -78,7 +84,7 @@ class StandardErrorDTO(BaseErrorDTO):
                 "SessionNotFound": "Сессия пользователя не была найдена.",
             },
         )
-        
+
         @router.delete(
             "/{id}",
             responses=Errors(unauthorized_error),
@@ -87,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()