fastapi-errors-plus 0.4.0__py3-none-any.whl → 0.6.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.4.0"
+__version__ = "0.6.0"
 

fastapi_errors_plus/base.py

@@ -120,3 +120,5 @@ class StandardErrorDTO(BaseErrorDTO):
             for key, message in self.examples.items()
         }
 
+
+

fastapi_errors_plus/errors.py

@@ -1,7 +1,7 @@
 """Main Errors class for documenting errors in FastAPI endpoints."""
 
 from collections.abc import Mapping
-from typing import Any, Dict, Iterator, Union
+from typing import Any, Dict, Iterator, Optional, Union
 
 from fastapi import status
 
@@ -29,10 +29,7 @@ class Errors(Mapping):
         @router.delete(
             "/{id}",
             responses=Errors(
-                unauthorized_401=True,      # 401 (explicit)
-                forbidden_403=True,          # 403 (explicit)
-                validation_error_422=True,   # 422 (explicit)
-                {404: {                      # 404 via dict
+                {404: {                      # 404 via dict (positional first)
                     "description": "Not found",
                     "content": {
                         "application/json": {
@@ -40,6 +37,9 @@ class Errors(Mapping):
                         },
                     },
                 }},
+                unauthorized_401=True,      # 401 (explicit, named after positional)
+                forbidden_403=True,          # 403 (explicit)
+                # validation_error_422=True - not needed, defaults to True
             ),
         )
         def delete_item(id: int):
@@ -55,12 +55,12 @@ class Errors(Mapping):
         # Old parameters (for backward compatibility)
         unauthorized: bool = False,           # 401
         forbidden: bool = False,              # 403
-        validation_error: bool = None,        # 422 (None = use default True, False = disable, True = enable)
+        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: bool = None,   # 422 (explicit, None = use default True, False = disable, True = enable)
+        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.
@@ -73,7 +73,10 @@ 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. Defaults to True (None means True).
+            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
                 FastAPI automatically validates all parameters (Path, Query, Body), so 422 is relevant
                 in 95%+ of endpoints. Set to False only for endpoints without parameters.
                 Deprecated: Use `validation_error_422` instead for explicit status code.
@@ -81,7 +84,10 @@ 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). Defaults to True (None means True).
+            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.
@@ -205,6 +211,38 @@ class Errors(Mapping):
                 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")
+            "default_2"
+            >>> errors._unique_key({"default": {}, "default_2": {}}, "default")
+            "default_3"
+        """
+        key = base
+        i = 2
+        while key in examples:
+            key = f"{base}_{i}"
+            i += 1
+        return key
+    
+    # Standard descriptions for priority checking
+    STANDARD_DESCRIPTIONS = {
+        status.HTTP_401_UNAUTHORIZED: "Unauthorized",
+        status.HTTP_403_FORBIDDEN: "Forbidden",
+        status.HTTP_422_UNPROCESSABLE_ENTITY: "Validation Error",
+        status.HTTP_500_INTERNAL_SERVER_ERROR: "Internal Server Error",
+    }
+    
     def _add_standard_error(
         self,
         status_code: int,
@@ -257,7 +295,9 @@ class Errors(Mapping):
                     content["examples"] = {}
             
             # Add new example with unique key (don't overwrite existing!)
-            content["examples"][example_key] = {"value": example}
+            # 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
@@ -334,7 +374,8 @@ class Errors(Mapping):
                                 existing_json["examples"]["default"] = {"value": response_json["example"]}
                             else:
                                 # If default exists, add with a unique key
-                                existing_json["examples"]["CustomExample"] = {"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).
@@ -373,6 +414,11 @@ 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
+            
             existing_content = existing.setdefault("content", {})
             content_json = existing_content.setdefault("application/json", {})
             existing_examples = content_json.get("examples", {})

fastapi_errors_plus/protocol.py

@@ -48,3 +48,5 @@ class ErrorDTO(Protocol):
         ...
 
 
+
+

{fastapi_errors_plus-0.4.0.dist-info → fastapi_errors_plus-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.4.0
+Version: 0.6.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -246,10 +246,10 @@ def delete_item(id: int):
 ```
 
 **Benefits:**
-- ✅ No need to write ErrorDTO classes from scratch
-- ✅ Correct implementation out of the box
-- ✅ Reusable across all endpoints
-- ✅ Supports inheritance for custom logic
+- No need to write ErrorDTO classes from scratch
+- Correct implementation out of the box
+- Reusable across all endpoints
+- Supports inheritance for custom logic
 
 ### 5. Mixed Usage
 
@@ -319,6 +319,8 @@ class ErrorDTO(Protocol):
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**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
 
 **Use Protocol (structural typing)** when:
@@ -333,6 +335,71 @@ 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!
 
+## Best Practice: Connecting Exceptions and ErrorDTO
+
+### Problem
+
+It's not always clear which exception corresponds to which ErrorDTO:
+
+```python
+# Not clear which exception this documents
+responses=Errors(notification_not_found_error)
+```
+
+### Solution: Domain Exception as ErrorDTO
+
+**Recommended approach** — make your exceptions implement ErrorDTO protocol:
+
+```python
+# domain/exceptions.py
+from typing import Dict, Any
+
+class DomainException(Exception):
+    """Base exception implementing ErrorDTO protocol."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        return {self.message: {"value": {"detail": self.message}}}
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls()
+
+class NotificationNotFoundError(DomainException):
+    status_code = 404
+    message = "Notification not found"
+    
+    def __init__(self, notification_id: str = ""):
+        self.notification_id = notification_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        return cls(notification_id="example_id")
+
+# In endpoint
+@router.delete(
+    "/{notificationId}",
+    responses=Errors(
+        NotificationNotFoundError.for_openapi(),  # Clear connection!
+    ),
+)
+async def delete_notification(notification_id: str):
+    if not notification:
+        raise NotificationNotFoundError(notification_id)  # Same exception!
+```
+
+**Benefits:**
+- Exception and ErrorDTO are one class
+- Clear connection visible in endpoint
+- No duplication
+- Type-safe
+- Works with any project architecture
+
+See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete example.
+
 ## 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:
@@ -375,11 +442,11 @@ Errors(
     *errors: Union[Dict[int, Dict[str, Any]], ErrorDTO],
     unauthorized: bool = False,
     forbidden: bool = False,
-    validation_error: bool = True,  # Defaults to True (FastAPI validates all parameters)
+    validation_error: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error: bool = False,
     unauthorized_401: bool = False,
     forbidden_403: bool = False,
-    validation_error_422: bool = True,  # Defaults to True (FastAPI validates all parameters)
+    validation_error_422: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error_500: bool = False,
 )
 ```
@@ -388,18 +455,25 @@ Errors(
 - `*errors`: Arbitrary errors as dict or ErrorDTO objects
 - `unauthorized_401`: Add 401 Unauthorized error (recommended, explicit). Defaults to `False`.
 - `forbidden_403`: Add 403 Forbidden error (recommended, explicit). Defaults to `False`.
-- `validation_error_422`: Add 422 Unprocessable Entity error (recommended, explicit). Defaults to `True` (FastAPI validates all parameters).
+- `validation_error_422`: Add 422 Unprocessable Entity error (recommended, explicit). 
+  - `None` (default): Add 422 (True by default, FastAPI validates all parameters)
+  - `False`: Explicitly disable 422
+  - `True`: Explicitly enable 422
 - `internal_server_error_500`: Add 500 Internal Server Error (recommended, explicit). Defaults to `False`.
 - `unauthorized`: Add 401 Unauthorized error (legacy, for backward compatibility). Defaults to `False`.
 - `forbidden`: Add 403 Forbidden error (legacy, for backward compatibility). Defaults to `False`.
-- `validation_error`: Add 422 Unprocessable Entity error (legacy, for backward compatibility). Defaults to `True` (FastAPI validates all parameters).
+- `validation_error`: Add 422 Unprocessable Entity error (legacy, for backward compatibility). 
+  - `None` (default): Add 422 (True by default, FastAPI validates all parameters)
+  - `False`: Explicitly disable 422
+  - `True`: Explicitly enable 422
 - `internal_server_error`: Add 500 Internal Server Error (legacy, for backward compatibility). Defaults to `False`.
 
 **Why `validation_error=True` by default?**
 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:**
-- Callable object that returns `Dict[int, Dict[str, Any]]` in FastAPI responses format
+- 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(...)`
 
 #### Usage
 

fastapi_errors_plus-0.6.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastapi_errors_plus/__init__.py,sha256=6xx4sQHjvhEHcxsenhJMZlR2RrH-FnahEPVoRvAjakI,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.0.dist-info/licenses/LICENSE,sha256=W_dONuuw-DA1UPcP9NPnQbhCbtMkLjhUr3Ne96398VU,1093
+fastapi_errors_plus-0.6.0.dist-info/METADATA,sha256=03r27kEKm4G10pYJ77aBQecEQOq_8hTlndEuYYWpzo4,21455
+fastapi_errors_plus-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fastapi_errors_plus-0.6.0.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
+fastapi_errors_plus-0.6.0.dist-info/RECORD,,

{fastapi_errors_plus-0.4.0.dist-info → fastapi_errors_plus-0.6.0.dist-info}/licenses/LICENSE

@@ -21,3 +21,5 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
+
+

fastapi_errors_plus-0.4.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-fastapi_errors_plus/__init__.py,sha256=0f8Avw6S8rxv_dq54spP7DsIrgcOlZ8TAMWPfd0XoRQ,454
-fastapi_errors_plus/base.py,sha256=SpZxS_avOr1kwcuJXjR-BQbeKX8Yp3pExCujR76E8Uk,3578
-fastapi_errors_plus/errors.py,sha256=pz7AJQoGc6vqVIA0ZA6agrq-QHxvL6wOMutR0gmB-tI,18899
-fastapi_errors_plus/protocol.py,sha256=pFIVjMB5foltP_BINLllo6wEDdVncXeNIpOEbd2_o4o,1216
-fastapi_errors_plus-0.4.0.dist-info/licenses/LICENSE,sha256=yQIQ4Uyt7lAeNcxDofCQTLZA7G5hkHqJc0BKHC4CDXk,1091
-fastapi_errors_plus-0.4.0.dist-info/METADATA,sha256=WDr9qBzVqBcte5CTQpUVl8zxXxQ1OkHw0UL3PXIpwec,19186
-fastapi_errors_plus-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fastapi_errors_plus-0.4.0.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
-fastapi_errors_plus-0.4.0.dist-info/RECORD,,