fastapi-errors-plus 0.1.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

fastapi_errors_plus/__init__.py

@@ -1,8 +1,14 @@
 """Universal library for documenting errors in FastAPI endpoints."""
 
+from fastapi_errors_plus.base import BaseErrorDTO, StandardErrorDTO
 from fastapi_errors_plus.errors import Errors
 from fastapi_errors_plus.protocol import ErrorDTO
 
-__all__ = ["Errors", "ErrorDTO"]
-__version__ = "0.1.0"
+__all__ = [
+    "Errors",
+    "ErrorDTO",  # Protocol (for structural typing)
+    "BaseErrorDTO",  # Base implementation (optional)
+    "StandardErrorDTO",  # Extended implementation (optional)
+]
+__version__ = "0.4.0"
 

fastapi_errors_plus/base.py

@@ -0,0 +1,122 @@
+"""Base implementations of ErrorDTO protocol for convenience."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@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),
+        )
+        def delete_item(id: int):
+            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"},
+                },
+            }
+            ```
+        """
+        return {
+            self.message: {
+                "value": {"detail": self.message},
+            },
+        }
+
+
+@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",
+            examples={
+                "InvalidToken": "Ошибка декодирования токена.",
+                "SessionNotFound": "Сессия пользователя не была найдена.",
+            },
+        )
+        
+        @router.delete(
+            "/{id}",
+            responses=Errors(unauthorized_error),
+        )
+        def delete_item(id: int):
+            pass
+        ```
+    """
+    examples: Optional[Dict[str, str]] = field(default=None)
+    """Dictionary of examples: {"key": "message"}."""
+    
+    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()
+        }
+

fastapi_errors_plus/errors.py

@@ -29,9 +29,9 @@ class Errors(Mapping):
         @router.delete(
             "/{id}",
             responses=Errors(
-                unauthorized=True,           # 401
-                forbidden=True,               # 403
-                validation_error=True,       # 422
+                unauthorized_401=True,      # 401 (explicit)
+                forbidden_403=True,          # 403 (explicit)
+                validation_error_422=True,   # 422 (explicit)
                 {404: {                      # 404 via dict
                     "description": "Not found",
                     "content": {
@@ -52,10 +52,16 @@ class Errors(Mapping):
         # Arbitrary errors (dict or ErrorDTO) - must come first
         *errors: Union[Dict[int, Dict[str, Any]], ErrorDTO],
         # Standard HTTP statuses (boolean flags)
+        # Old parameters (for backward compatibility)
         unauthorized: bool = False,           # 401
         forbidden: bool = False,              # 403
-        validation_error: bool = False,       # 422
+        validation_error: 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)
+        internal_server_error_500: bool = False,  # 500 (explicit)
     ) -> None:
         """Initialize Errors instance.
         
@@ -64,9 +70,21 @@ class Errors(Mapping):
                 Dict should be in FastAPI responses format: {status_code: {...}}.
                 ErrorDTO objects must implement the ErrorDTO protocol.
             unauthorized: Add 401 Unauthorized error. Defaults to False.
+                Deprecated: Use `unauthorized_401` instead for explicit status code.
             forbidden: Add 403 Forbidden error. Defaults to False.
-            validation_error: Add 422 Unprocessable Entity 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).
+                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.
             internal_server_error: Add 500 Internal Server Error. Defaults to False.
+                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).
+                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.
         
         Example:
             ```python
@@ -90,25 +108,37 @@ class Errors(Mapping):
         self._responses: Dict[int, Dict[str, Any]] = {}
         
         # Add standard errors
-        if unauthorized:
+        # New parameters with explicit codes have priority, but old ones still work
+        if unauthorized_401 or unauthorized:
             self._add_standard_error(
                 status.HTTP_401_UNAUTHORIZED,
                 "Unauthorized",
                 {"detail": "Unauthorized"},
             )
-        if forbidden:
+        if forbidden_403 or forbidden:
             self._add_standard_error(
                 status.HTTP_403_FORBIDDEN,
                 "Forbidden",
                 {"detail": "Forbidden"},
             )
-        if validation_error:
+        # For validation_error: True by default (FastAPI validates all parameters)
+        # Add 422 unless at least one parameter is explicitly False
+        # If user sets validation_error=False, they want to disable 422 (even if validation_error_422 defaults to True)
+        # If user sets validation_error_422=False, they want to disable 422 (even if validation_error defaults to True)
+        # Only if both are explicitly False, we definitely don't add
+        # If at least one is True (or None which defaults to True) and neither is explicitly False, add
+        add_422 = True  # Default is True
+        if validation_error is False or validation_error_422 is False:
+            # At least one is explicitly False - don't add
+            add_422 = False
+        
+        if add_422:
             self._add_standard_error(
                 status.HTTP_422_UNPROCESSABLE_ENTITY,
                 "Validation Error",
                 {"detail": "Validation error"},
             )
-        if internal_server_error:
+        if internal_server_error_500 or internal_server_error:
             self._add_standard_error(
                 status.HTTP_500_INTERNAL_SERVER_ERROR,
                 "Internal Server Error",

fastapi_errors_plus/protocol.py

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.1.0
+Version: 0.4.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -30,8 +30,8 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)
-[![Tests](https://img.shields.io/badge/tests-41%20passed-success.svg)](https://github.com/yourusername/fastapi-errors-plus)
-[![Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](https://github.com/yourusername/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-72%20passed-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Coverage](https://img.shields.io/badge/coverage-83%25-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
 
@@ -56,7 +56,7 @@ pip install fastapi-errors-plus
 Or install from source:
 
 ```bash
-git clone https://github.com/yourusername/fastapi-errors-plus.git
+git clone git@github.com:seligoroff/fastapi-errors-plus.git
 cd fastapi-errors-plus
 pip install -e .
 ```
@@ -82,9 +82,9 @@ router = APIRouter()
                 },
             },
         }},
-        unauthorized=True,           # 401 Unauthorized
-        forbidden=True,               # 403 Forbidden
-        validation_error=True,       # 422 Validation Error
+        unauthorized_401=True,      # 401 Unauthorized (explicit)
+        forbidden_403=True,          # 403 Forbidden (explicit)
+        # validation_error_422=True - not needed, defaults to True
     ),
 )
 def delete_item(id: int):
@@ -99,17 +99,26 @@ def delete_item(id: int):
 
 Use boolean flags for common HTTP status codes:
 
+**Recommended (explicit status codes):**
+- `unauthorized_401=True` → 401 Unauthorized
+- `forbidden_403=True` → 403 Forbidden
+- `validation_error_422=True` → 422 Unprocessable Entity (defaults to `True`)
+- `internal_server_error_500=True` → 500 Internal Server Error
+
+**Legacy (for backward compatibility):**
 - `unauthorized=True` → 401 Unauthorized
 - `forbidden=True` → 403 Forbidden
-- `validation_error=True` → 422 Unprocessable Entity
+- `validation_error=True` → 422 Unprocessable Entity (defaults to `True`)
 - `internal_server_error=True` → 500 Internal Server Error
 
+**Note:** `validation_error` and `validation_error_422` default to `True` because FastAPI automatically validates all parameters (Path, Query, Body), making 422 relevant in 95%+ of endpoints. Set to `False` only for endpoints without parameters.
+
 ```python
 @router.get(
     "/protected",
     responses=Errors(
-        unauthorized=True,
-        forbidden=True,
+        unauthorized_401=True,  # Explicit: 401 is visible
+        forbidden_403=True,      # Explicit: 403 is visible
     ),
 )
 def get_protected():
@@ -117,6 +126,8 @@ def get_protected():
     pass
 ```
 
+**Why explicit flags?** The new flags with status codes (`_401`, `_403`, etc.) make it immediately clear which HTTP status code corresponds to each flag, improving code readability without needing to remember the mapping.
+
 ### 2. Dict-based Errors
 
 Use standard FastAPI `responses` dict format for custom errors:
@@ -171,7 +182,76 @@ def get_resource(id: int):
     pass
 ```
 
-### 4. Mixed Usage
+### 4. BaseErrorDTO and StandardErrorDTO (Recommended)
+
+For convenience, the library provides ready-to-use implementations:
+
+#### BaseErrorDTO
+
+Simple implementation for errors with a single 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),
+)
+def delete_item(id: int):
+    """Delete an item."""
+    pass
+```
+
+#### StandardErrorDTO
+
+Extended implementation for errors with multiple examples (useful for standard HTTP errors):
+
+```python
+from fastapi_errors_plus import Errors, StandardErrorDTO
+
+unauthorized_error = StandardErrorDTO(
+    status_code=401,
+    message="Unauthorized",
+    examples={
+        "InvalidToken": "Ошибка декодирования токена.",
+        "SessionNotFound": "Сессия пользователя не была найдена.",
+    },
+)
+
+forbidden_error = StandardErrorDTO(
+    status_code=403,
+    message="Forbidden",
+    examples={
+        "AccountNotSelected": "Аккаунт не выбран.",
+        "RoleHasNoAccess": "Роль не имеет доступа.",
+    },
+)
+
+@router.delete(
+    "/{id}",
+    responses=Errors(
+        unauthorized_error,
+        forbidden_error,
+        # validation_error=True - not needed, defaults to True
+    ),
+)
+def delete_item(id: int):
+    """Delete an item."""
+    pass
+```
+
+**Benefits:**
+- ✅ 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
 
 Combine flags, dict, and ErrorDTO:
 
@@ -190,6 +270,7 @@ Combine flags, dict, and ErrorDTO:
         MyErrorDTO(),  # ErrorDTO
         unauthorized=True,  # Flag
         forbidden=True,  # Flag
+        # validation_error=True - not needed, defaults to True
     ),
 )
 def create_item_mixed(id: int):
@@ -197,7 +278,7 @@ def create_item_mixed(id: int):
     pass
 ```
 
-### 5. Merging Examples
+### 6. Merging Examples
 
 Multiple errors with the same status code are automatically merged:
 
@@ -238,6 +319,20 @@ class ErrorDTO(Protocol):
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+### When to Use Protocol vs BaseErrorDTO
+
+**Use Protocol (structural typing)** when:
+- Your project already has error DTOs that implement the protocol
+- You need maximum flexibility and custom implementations
+- You want to keep your existing error infrastructure
+
+**Use BaseErrorDTO/StandardErrorDTO** when:
+- Starting a new project or adding error documentation
+- You want a ready-to-use implementation without boilerplate
+- You need multiple examples for standard HTTP errors (401, 403, etc.)
+
+Both approaches work together — you can mix them in the same `Errors()` call!
+
 ## 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:
@@ -280,17 +375,28 @@ Errors(
     *errors: Union[Dict[int, Dict[str, Any]], ErrorDTO],
     unauthorized: bool = False,
     forbidden: bool = False,
-    validation_error: bool = False,
+    validation_error: bool = True,  # Defaults to 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)
+    internal_server_error_500: bool = False,
 )
 ```
 
 **Parameters:**
 - `*errors`: Arbitrary errors as dict or ErrorDTO objects
-- `unauthorized`: Add 401 Unauthorized error
-- `forbidden`: Add 403 Forbidden error
-- `validation_error`: Add 422 Unprocessable Entity error
-- `internal_server_error`: Add 500 Internal Server Error
+- `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).
+- `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).
+- `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
@@ -313,6 +419,48 @@ Protocol for error objects compatible with the library.
 **Required methods:**
 - `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
 
+### `BaseErrorDTO`
+
+Base implementation of ErrorDTO Protocol for convenience.
+
+**Constructor:**
+```python
+BaseErrorDTO(
+    status_code: int,
+    message: str,
+)
+```
+
+**Example:**
+```python
+error = BaseErrorDTO(status_code=404, message="Not found")
+```
+
+### `StandardErrorDTO`
+
+Extended implementation for errors with multiple examples.
+
+**Constructor:**
+```python
+StandardErrorDTO(
+    status_code: int,
+    message: str,
+    examples: Optional[Dict[str, str]] = None,
+)
+```
+
+**Example:**
+```python
+error = StandardErrorDTO(
+    status_code=401,
+    message="Unauthorized",
+    examples={
+        "InvalidToken": "Invalid token",
+        "SessionNotFound": "Session not found",
+    },
+)
+```
+
 ## Examples
 
 ### Example 1: Standard FastAPI Project
@@ -471,7 +619,7 @@ router = APIRouter()
     responses=Errors(
         unauthorized=True,  # From authentication dependency
         forbidden=True,     # From authorization dependency
-        validation_error=True,  # From FastAPI validation
+        # validation_error=True - not needed, defaults to True (FastAPI validates all parameters)
         ItemAlreadyExistsError(),  # Domain error
     ),
 )

fastapi_errors_plus-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+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,,

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

@@ -20,3 +20,4 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+

fastapi_errors_plus-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-fastapi_errors_plus/__init__.py,sha256=Dbn9fmqBoSa5yTF0d4gVvyoJ61pI3My3aZNMq8wsGGg,223
-fastapi_errors_plus/errors.py,sha256=kvM2DeDYJ-pMREWmSslF0KgIWixERqj-Nt5oJ8IeSHc,16325
-fastapi_errors_plus/protocol.py,sha256=mSb-nabNDz7tjbSboHOQJu6QGsUPZOivC-XztvYoHRA,1215
-fastapi_errors_plus-0.1.0.dist-info/licenses/LICENSE,sha256=wKw57ZiHT4OAK3euOE2UxSzr3RN_AEarSxQV88xMBgA,1090
-fastapi_errors_plus-0.1.0.dist-info/METADATA,sha256=wEThfjUfdMt4sUG6paPrTBE_gGVj5QVWbXg2oPe-26o,14039
-fastapi_errors_plus-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fastapi_errors_plus-0.1.0.dist-info/top_level.txt,sha256=vmHLF1-DQYB2quqrvdBA0g6rDtgOWQBrA1m-X_WyNk8,20
-fastapi_errors_plus-0.1.0.dist-info/RECORD,,