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

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.5.0}/LICENSE

@@ -21,3 +21,4 @@ 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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.4.0
+Version: 0.5.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -375,11 +375,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 +388,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.5.0}/README.md

@@ -349,11 +349,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 +362,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.5.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.5.0"
 

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.5.0}/fastapi_errors_plus/base.py

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

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.5.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.5.0}/fastapi_errors_plus/protocol.py

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

{fastapi_errors_plus-0.4.0 → fastapi_errors_plus-0.5.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.5.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -375,11 +375,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 +388,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.5.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.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-errors-plus"
-version = "0.4.0"
+version = "0.5.0"
 description = "Universal library for documenting errors in FastAPI endpoints"
 readme = "README.md"
 requires-python = ">=3.8"

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

@@ -302,3 +302,4 @@ 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.5.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"
+