fastapi-errors-plus 0.4.0__py3-none-any.whl → 0.5.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.5.0"
 

fastapi_errors_plus/base.py

@@ -120,3 +120,4 @@ 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,4 @@ class ErrorDTO(Protocol):
         ...
 
 
+

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

@@ -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.5.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastapi_errors_plus/__init__.py,sha256=uc5QIsWWvHQWAOA2Ri94hIWBAiT_QhmL4YOnUCMVqA8,454
+fastapi_errors_plus/base.py,sha256=9158lfwZ5pPbgFJqmL1V6bFEivxr1UpwCwR4cL87ZVo,3579
+fastapi_errors_plus/errors.py,sha256=7ikmrSphWOH_nnxLC0HPQ0RPiuR1u8olw3bxGxdLv50,20868
+fastapi_errors_plus/protocol.py,sha256=krTYPOWTxbz_I4w2ESzGHgE6trONa1wDMQgErMs1nLc,1217
+fastapi_errors_plus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_errors_plus-0.5.0.dist-info/licenses/LICENSE,sha256=Ilkf6MRaeVru1agPGtmMlsxEY-4DEUIo1_3PGkTdzm0,1092
+fastapi_errors_plus-0.5.0.dist-info/METADATA,sha256=sRjs9kYXl3d69iwWAVAmgFH96tKTaSSgHANr3_iPbeo,19511
+fastapi_errors_plus-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fastapi_errors_plus-0.5.0.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
+fastapi_errors_plus-0.5.0.dist-info/RECORD,,

{fastapi_errors_plus-0.4.0.dist-info → fastapi_errors_plus-0.5.0.dist-info}/licenses/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.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,,