fastapi-errors-plus 0.4.0__tar.gz → 0.6.0__tar.gz

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.6.0}/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 → fastapi_errors_plus-0.6.0}/PKG-INFO

@@ -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.4.0 → fastapi_errors_plus-0.6.0}/README.md

@@ -220,10 +220,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
 
@@ -293,6 +293,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:
@@ -307,6 +309,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:
@@ -349,11 +416,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,
 )
 ```
@@ -362,18 +429,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.4.0 → fastapi_errors_plus-0.6.0}/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-0.4.0 → fastapi_errors_plus-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-0.4.0 → fastapi_errors_plus-0.6.0}/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-0.4.0 → fastapi_errors_plus-0.6.0}/fastapi_errors_plus/protocol.py

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

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.6.0}/fastapi_errors_plus.egg-info/PKG-INFO

@@ -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.4.0 → fastapi_errors_plus-0.6.0}/fastapi_errors_plus.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ fastapi_errors_plus/__init__.py
 fastapi_errors_plus/base.py
 fastapi_errors_plus/errors.py
 fastapi_errors_plus/protocol.py
+fastapi_errors_plus/py.typed
 fastapi_errors_plus.egg-info/PKG-INFO
 fastapi_errors_plus.egg-info/SOURCES.txt
 fastapi_errors_plus.egg-info/dependency_links.txt

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-errors-plus"
-version = "0.4.0"
+version = "0.6.0"
 description = "Universal library for documenting errors in FastAPI endpoints"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -46,3 +46,29 @@ python_files = "test_*.py"
 python_classes = "Test*"
 python_functions = "test_*"
 
+[tool.coverage.run]
+source = ["fastapi_errors_plus"]
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*",
+    "*/venv/*",
+    "*/.venv/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]
+precision = 2
+show_missing = true
+skip_covered = false
+
+[tool.coverage.html]
+directory = "tests/htmlcov"
+

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.6.0}/tests/test_base.py

@@ -302,3 +302,5 @@ class TestBaseErrorDTOCompatibility:
         assert status.HTTP_404_NOT_FOUND in responses
         assert status.HTTP_500_INTERNAL_SERVER_ERROR in responses
 
+
+

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.6.0}/tests/test_errors.py

@@ -446,6 +446,82 @@ class TestErrorsEdgeCases:
         assert len(errors) == 1
 
 
+class TestUniqueKeys:
+    """Tests for unique key generation to prevent collisions."""
+    
+    def test_unique_keys_for_standard_errors(self):
+        """Test that standard error keys are unique when merging."""
+        # First add flag (creates example), then add dict with examples containing same key
+        errors = Errors(
+            {401: {  # Positional first - adds "StandardUnauthorized" to examples
+                "content": {
+                    "application/json": {
+                        "examples": {
+                            "StandardUnauthorized": {"value": {"detail": "Custom"}},
+                        },
+                    },
+                },
+            }},
+            unauthorized_401=True,  # Named after positional - should use unique key
+        )
+        
+        # Should have both examples
+        examples = errors[401]["content"]["application/json"]["examples"]
+        # When dict is added first with "StandardUnauthorized", then flag is added
+        # Flag creates "example" which gets converted to "default" (not "StandardUnauthorized_2")
+        # This is because flag creates "example" first, then it's converted
+        assert "StandardUnauthorized" in examples  # From dict
+        assert "default" in examples  # From flag (converted from example)
+        
+        # Both examples should be present
+        assert len(examples) == 2
+        assert examples["StandardUnauthorized"]["value"]["detail"] == "Custom"
+        assert examples["default"]["value"]["detail"] == "Unauthorized"
+    
+    def test_unique_keys_for_dict_errors(self):
+        """Test that dict error keys are unique when merging."""
+        errors = Errors(
+            {401: {
+                "content": {
+                    "application/json": {
+                        "example": {"detail": "First"},
+                    },
+                },
+            }},
+            {401: {
+                "content": {
+                    "application/json": {
+                        "example": {"detail": "Second"},
+                    },
+                },
+            }},
+        )
+        
+        examples = errors[401]["content"]["application/json"]["examples"]
+        assert "default" in examples
+        # Second example should have unique key
+        assert "CustomExample" in examples or "CustomExample_2" in examples
+        assert len(examples) == 2
+    
+    def test_unique_keys_multiple_collisions(self):
+        """Test unique key generation with multiple collisions."""
+        errors = Errors()
+        examples = {
+            "CustomExample": {"value": {"detail": "First"}},
+            "CustomExample_2": {"value": {"detail": "Second"}},
+        }
+        
+        # Add another CustomExample - should become CustomExample_3
+        unique_key = errors._unique_key(examples, "CustomExample")
+        assert unique_key == "CustomExample_3"
+        
+        examples[unique_key] = {"value": {"detail": "Third"}}
+        
+        # Add another - should become CustomExample_4
+        unique_key = errors._unique_key(examples, "CustomExample")
+        assert unique_key == "CustomExample_4"
+
+
 class TestErrorsValidation:
     """Tests for ErrorDTO validation."""
     
@@ -531,3 +607,50 @@ class TestErrorsValidation:
         assert "to_example" in error_msg
         assert "BadObject" in error_msg
 
+
+class TestDTODescriptionPriority:
+    """Tests for DTO description priority over standard flags."""
+    
+    def test_dto_overrides_standard_description(self):
+        """Test that ErrorDTO description overrides standard flag description."""
+        from fastapi_errors_plus import StandardErrorDTO
+        
+        custom_401 = StandardErrorDTO(
+            status_code=401,
+            message="Custom Unauthorized",
+            examples={"Custom": "Custom auth error"},
+        )
+        
+        errors = Errors(
+            custom_401,  # Positional first
+            unauthorized_401=True,  # Named after - adds "Unauthorized"
+        )
+        
+        # DTO should override standard description
+        assert errors[401]["description"] == "Custom Unauthorized"
+    
+    def test_dto_does_not_override_custom_description(self):
+        """Test that DTO does not override non-standard description."""
+        from fastapi_errors_plus import StandardErrorDTO
+        
+        custom_401 = StandardErrorDTO(
+            status_code=401,
+            message="Another Custom",
+            examples={"Custom": "Custom auth error"},
+        )
+        
+        errors = Errors(
+            {401: {  # Positional first - custom description
+                "description": "My Custom Description",
+                "content": {
+                    "application/json": {
+                        "example": {"detail": "Custom"},
+                    },
+                },
+            }},
+            custom_401,  # DTO should not override dict description
+        )
+        
+        # Dict description should be preserved (dict > DTO)
+        assert errors[401]["description"] == "My Custom Description"
+