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

fastapi_errors_plus/__init__.py

@@ -0,0 +1,8 @@
+"""Universal library for documenting errors in FastAPI endpoints."""
+
+from fastapi_errors_plus.errors import Errors
+from fastapi_errors_plus.protocol import ErrorDTO
+
+__all__ = ["Errors", "ErrorDTO"]
+__version__ = "0.1.0"
+

fastapi_errors_plus/errors.py

@@ -0,0 +1,404 @@
+"""Main Errors class for documenting errors in FastAPI endpoints."""
+
+from collections.abc import Mapping
+from typing import Any, Dict, Iterator, Union
+
+from fastapi import status
+
+from fastapi_errors_plus.protocol import ErrorDTO
+
+
+class Errors(Mapping):
+    """Universal class for documenting errors in FastAPI endpoints.
+    
+    Works with any FastAPI project. Can accept:
+    - Standard HTTP statuses via boolean flags
+    - Dict in FastAPI responses format
+    - Objects implementing ErrorDTO protocol (for project compatibility)
+    
+    Implements Mapping protocol, so can be used directly in FastAPI responses
+    parameter without calling ().
+    
+    Example:
+        ```python
+        from fastapi import APIRouter
+        from fastapi_errors_plus import Errors
+        
+        router = APIRouter()
+        
+        @router.delete(
+            "/{id}",
+            responses=Errors(
+                unauthorized=True,           # 401
+                forbidden=True,               # 403
+                validation_error=True,       # 422
+                {404: {                      # 404 via dict
+                    "description": "Not found",
+                    "content": {
+                        "application/json": {
+                            "example": {"detail": "Item not found"},
+                        },
+                    },
+                }},
+            ),
+        )
+        def delete_item(id: int):
+            pass
+        ```
+    """
+    
+    def __init__(
+        self,
+        # Arbitrary errors (dict or ErrorDTO) - must come first
+        *errors: Union[Dict[int, Dict[str, Any]], ErrorDTO],
+        # Standard HTTP statuses (boolean flags)
+        unauthorized: bool = False,           # 401
+        forbidden: bool = False,              # 403
+        validation_error: bool = False,       # 422
+        internal_server_error: bool = False,  # 500
+    ) -> None:
+        """Initialize Errors instance.
+        
+        Args:
+            *errors: Arbitrary errors as dict or ErrorDTO objects.
+                Dict should be in FastAPI responses format: {status_code: {...}}.
+                ErrorDTO objects must implement the ErrorDTO protocol.
+            unauthorized: Add 401 Unauthorized error. Defaults to False.
+            forbidden: Add 403 Forbidden error. Defaults to False.
+            validation_error: Add 422 Unprocessable Entity error. Defaults to False.
+            internal_server_error: Add 500 Internal Server Error. Defaults to False.
+        
+        Example:
+            ```python
+            # Standard flags only
+            errors = Errors(unauthorized=True, forbidden=True)
+            
+            # Dict errors
+            errors = Errors({404: {"description": "Not found", ...}})
+            
+            # ErrorDTO
+            errors = Errors(MyErrorDTO())
+            
+            # Mixed
+            errors = Errors(
+                {409: {...}},
+                MyErrorDTO(),
+                unauthorized=True,
+            )
+            ```
+        """
+        self._responses: Dict[int, Dict[str, Any]] = {}
+        
+        # Add standard errors
+        if unauthorized:
+            self._add_standard_error(
+                status.HTTP_401_UNAUTHORIZED,
+                "Unauthorized",
+                {"detail": "Unauthorized"},
+            )
+        if forbidden:
+            self._add_standard_error(
+                status.HTTP_403_FORBIDDEN,
+                "Forbidden",
+                {"detail": "Forbidden"},
+            )
+        if validation_error:
+            self._add_standard_error(
+                status.HTTP_422_UNPROCESSABLE_ENTITY,
+                "Validation Error",
+                {"detail": "Validation error"},
+            )
+        if internal_server_error:
+            self._add_standard_error(
+                status.HTTP_500_INTERNAL_SERVER_ERROR,
+                "Internal Server Error",
+                {"detail": "Internal Server Error"},
+            )
+        
+        # Add arbitrary errors
+        for error in errors:
+            if isinstance(error, dict):
+                # Universal dict in FastAPI format - merge instead of overwrite
+                self._add_dict_error(error)
+            else:
+                # Validate ErrorDTO protocol before processing
+                self._validate_error_dto(error)
+                # ErrorDTO (compatible with ApiErrorDTO via Protocol)
+                self._add_error_dto(error)
+    
+    def _validate_error_dto(self, error: Any) -> None:
+        """Validate that error object implements ErrorDTO protocol.
+        
+        Args:
+            error: Object to validate
+            
+        Raises:
+            TypeError: If object doesn't implement ErrorDTO protocol
+            
+        Example:
+            ```python
+            # Valid object
+            class MyError:
+                status_code = 404
+                message = "Not found"
+                def to_example(self): ...
+            
+            errors = Errors()
+            errors._validate_error_dto(MyError())  # OK
+            
+            # Invalid object
+            class BadError:
+                status_code = 404
+                # Missing message and to_example
+            
+            errors._validate_error_dto(BadError())  # Raises TypeError
+            ```
+        """
+        required_attrs = ("status_code", "message")
+        required_methods = ("to_example",)
+        
+        missing_attrs = [
+            attr for attr in required_attrs 
+            if not hasattr(error, attr)
+        ]
+        missing_methods = [
+            method for method in required_methods 
+            if not hasattr(error, method) or not callable(getattr(error, method, None))
+        ]
+        
+        if missing_attrs or missing_methods:
+            missing = missing_attrs + missing_methods
+            raise TypeError(
+                f"ErrorDTO object must have {', '.join(required_attrs)} attributes "
+                f"and {', '.join(required_methods)}() method. "
+                f"Missing: {', '.join(missing)}. "
+                f"Got {type(error).__name__}"
+            )
+    
+    def _add_standard_error(
+        self,
+        status_code: int,
+        description: str,
+        example: Dict[str, Any],
+    ) -> None:
+        """Add standard error.
+        
+        If the status code already exists, merges the example with existing examples
+        using a unique key instead of overwriting.
+        
+        Args:
+            status_code: HTTP status code (e.g., 401, 403, 422, 500)
+            description: Error description for OpenAPI
+            example: Example response body (e.g., {"detail": "Unauthorized"})
+        """
+        # Generate unique key for standard example
+        standard_keys = {
+            status.HTTP_401_UNAUTHORIZED: "StandardUnauthorized",
+            status.HTTP_403_FORBIDDEN: "StandardForbidden",
+            status.HTTP_422_UNPROCESSABLE_ENTITY: "StandardValidationError",
+            status.HTTP_500_INTERNAL_SERVER_ERROR: "StandardInternalServerError",
+        }
+        example_key = standard_keys.get(status_code, f"Standard{status_code}")
+        
+        if status_code not in self._responses:
+            self._responses[status_code] = {
+                "description": description,
+                "content": {
+                    "application/json": {
+                        "example": example,
+                    },
+                },
+            }
+        else:
+            # If already exists, add to examples without overwriting
+            # Safely access content/application/json with defaults
+            existing = self._responses[status_code]
+            existing_content = existing.setdefault("content", {})
+            content = existing_content.setdefault("application/json", {})
+            
+            # Convert example to examples if needed
+            if "examples" not in content:
+                if "example" in content:
+                    existing_example = content.pop("example")
+                    content["examples"] = {
+                        "default": {"value": existing_example},
+                    }
+                else:
+                    content["examples"] = {}
+            
+            # Add new example with unique key (don't overwrite existing!)
+            content["examples"][example_key] = {"value": example}
+            
+            # Don't overwrite description if it already exists
+            # Priority: dict > DTO > standard flags
+    
+    def _add_dict_error(self, error_dict: Dict[int, Dict[str, Any]]) -> None:
+        """Add error from dict in FastAPI responses format.
+        
+        Merges examples instead of overwriting the entire response entry.
+        
+        Args:
+            error_dict: Dict in format {status_code: {"description": ..., "content": {...}}}
+        """
+        for status_code, response_data in error_dict.items():
+            if status_code not in self._responses:
+                # New status code - just add it
+                self._responses[status_code] = response_data
+            else:
+                # Status code already exists - merge
+                existing = self._responses[status_code]
+                
+                # Merge description (dict takes priority)
+                if "description" in response_data:
+                    existing["description"] = response_data["description"]
+                
+                # Merge content
+                if "content" in response_data:
+                    existing_content = existing.setdefault("content", {})
+                    response_content = response_data["content"]
+                    
+                    # Merge application/json
+                    if "application/json" in response_content:
+                        existing_json = existing_content.setdefault("application/json", {})
+                        response_json = response_content["application/json"]
+                        
+                        # Handle example/examples
+                        if "examples" in response_json:
+                            # Response has examples
+                            if "examples" not in existing_json:
+                                # Convert existing example to examples if needed
+                                if "example" in existing_json:
+                                    existing_example = existing_json.pop("example")
+                                    existing_json["examples"] = {
+                                        "default": {"value": existing_example},
+                                    }
+                                else:
+                                    existing_json["examples"] = {}
+                            
+                            # Merge examples
+                            existing_json["examples"].update(response_json["examples"])
+                        elif "example" in response_json:
+                            # Response has example - convert and merge
+                            if "examples" not in existing_json:
+                                # Convert existing example to examples if needed
+                                if "example" in existing_json:
+                                    existing_example = existing_json.pop("example")
+                                    # Check if existing example is from a standard flag
+                                    # Standard flags use specific messages
+                                    standard_messages = {
+                                        "Unauthorized": "StandardUnauthorized",
+                                        "Forbidden": "StandardForbidden",
+                                        "Validation error": "StandardValidationError",
+                                        "Internal Server Error": "StandardInternalServerError",
+                                    }
+                                    existing_detail = existing_example.get("detail", "")
+                                    example_key = standard_messages.get(existing_detail, "default")
+                                    existing_json["examples"] = {
+                                        example_key: {"value": existing_example},
+                                    }
+                                else:
+                                    existing_json["examples"] = {}
+                            
+                            # Add new example - use "default" if available, otherwise unique key
+                            if "default" not in existing_json["examples"]:
+                                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"]}
+    
+    def _add_error_dto(self, error_dto: ErrorDTO) -> None:
+        """Add error from ErrorDTO (via Protocol).
+        
+        If the status code already exists, merges examples with existing examples.
+        
+        Args:
+            error_dto: Error object implementing ErrorDTO protocol.
+                Must have `status_code`, `message`, and `to_example()` method.
+        
+        Example:
+            ```python
+            class MyError:
+                status_code = 404
+                message = "Not found"
+                def to_example(self):
+                    return {"Not found": {"value": {"detail": "Not found"}}}
+            
+            errors = Errors()
+            errors._add_error_dto(MyError())
+            ```
+        """
+        status_code = error_dto.status_code
+        examples = error_dto.to_example()
+        
+        if status_code not in self._responses:
+            self._responses[status_code] = {
+                "description": error_dto.message,
+                "content": {
+                    "application/json": {
+                        "examples": examples,
+                    },
+                },
+            }
+        else:
+            # Merge examples for the same status code
+            # Safely access content/application/json with defaults
+            existing = self._responses[status_code]
+            existing_content = existing.setdefault("content", {})
+            content_json = existing_content.setdefault("application/json", {})
+            existing_examples = content_json.get("examples", {})
+            
+            if "example" in content_json:
+                # Convert example to examples with correct key for standard flags
+                existing_example = content_json.pop("example")
+                existing_detail = existing_example.get("detail", "")
+                
+                # Check if existing example is from a standard flag
+                standard_messages = {
+                    "Unauthorized": "StandardUnauthorized",
+                    "Forbidden": "StandardForbidden",
+                    "Validation error": "StandardValidationError",
+                    "Internal Server Error": "StandardInternalServerError",
+                }
+                example_key = standard_messages.get(existing_detail, "default")
+                
+                existing_examples = {
+                    example_key: {
+                        "value": existing_example,
+                    },
+                }
+            
+            # Merge new examples from ErrorDTO
+            existing_examples.update(examples)
+            content_json["examples"] = existing_examples
+    
+    # Mapping protocol implementation
+    def __getitem__(self, key: int) -> Dict[str, Any]:
+        """Get response for status code.
+        
+        Args:
+            key: HTTP status code (e.g., 401, 403, 404)
+            
+        Returns:
+            Response dict in FastAPI format
+            
+        Raises:
+            KeyError: If status code not found
+        """
+        return self._responses[key]
+    
+    def __iter__(self) -> Iterator[int]:
+        """Iterate over status codes.
+        
+        Returns:
+            Iterator over status codes
+        """
+        return iter(self._responses)
+    
+    def __len__(self) -> int:
+        """Get number of status codes.
+        
+        Returns:
+            Number of documented error status codes
+        """
+        return len(self._responses)
+

fastapi_errors_plus/protocol.py

@@ -0,0 +1,49 @@
+"""Protocol for error DTOs compatible with fastapi-errors-plus."""
+
+from typing import Any, Dict, Protocol
+
+
+class ErrorDTO(Protocol):
+    """Protocol for error objects compatible with the library.
+    
+    Any class implementing this protocol can be used with Errors().
+    
+    Example:
+        ```python
+        class MyError:
+            status_code = 404
+            message = "Not found"
+            
+            def to_example(self) -> Dict[str, Any]:
+                return {
+                    "Not found": {
+                        "value": {"detail": "Not found"},
+                    },
+                }
+        
+        errors = Errors(MyError())
+        ```
+    """
+    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
+            {
+                "Not found": {
+                    "value": {"detail": "Not found"},
+                },
+            }
+            ```
+        """
+        ...
+

fastapi_errors_plus-0.1.0.dist-info/METADATA

@@ -0,0 +1,547 @@
+Metadata-Version: 2.4
+Name: fastapi-errors-plus
+Version: 0.1.0
+Summary: Universal library for documenting errors in FastAPI endpoints
+Author-email: Igor Selivanov <seligoroff@gmail.com>
+License: MIT
+Keywords: fastapi,errors,openapi,documentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# fastapi-errors-plus
+
+[![PyPI version](https://badge.fury.io/py/fastapi-errors-plus.svg)](https://pypi.org/project/fastapi-errors-plus/)
+[![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)
+
+Universal library for documenting errors in FastAPI endpoints.
+
+> [Русская версия README](README.ru.md)
+
+## Philosophy
+
+`fastapi-errors-plus` is designed to be **universal** and work with **any** FastAPI project without requiring project-specific infrastructure. The library uses standard Python types (dict, Protocol) and allows projects to adapt their existing error infrastructure to work with the library through structural typing.
+
+**Key principles:**
+- **Universality** — works with any FastAPI project
+- **Transparency** — all documented errors are visible directly in the endpoint
+- **Self-sufficiency** — no need to search other files to understand documented errors
+- **Compatibility** — works with existing project infrastructure through Protocol
+
+## Installation
+
+```bash
+pip install fastapi-errors-plus
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/fastapi-errors-plus.git
+cd fastapi-errors-plus
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from fastapi import APIRouter
+from fastapi_errors_plus import Errors
+
+router = APIRouter()
+
+@router.delete(
+    "/{id}",
+    responses=Errors(
+        {404: {                      # 404 via dict
+            "description": "Not found",
+            "content": {
+                "application/json": {
+                    "example": {"detail": "Item not found"},
+                },
+            },
+        }},
+        unauthorized=True,           # 401 Unauthorized
+        forbidden=True,               # 403 Forbidden
+        validation_error=True,       # 422 Validation Error
+    ),
+)
+def delete_item(id: int):
+    """Delete an item."""
+    # ... your code ...
+    pass
+```
+
+## Features
+
+### 1. Standard HTTP Status Flags
+
+Use boolean flags for common HTTP status codes:
+
+- `unauthorized=True` → 401 Unauthorized
+- `forbidden=True` → 403 Forbidden
+- `validation_error=True` → 422 Unprocessable Entity
+- `internal_server_error=True` → 500 Internal Server Error
+
+```python
+@router.get(
+    "/protected",
+    responses=Errors(
+        unauthorized=True,
+        forbidden=True,
+    ),
+)
+def get_protected():
+    """Protected endpoint."""
+    pass
+```
+
+### 2. Dict-based Errors
+
+Use standard FastAPI `responses` dict format for custom errors:
+
+```python
+@router.post(
+    "/items",
+    responses=Errors(
+        {
+            409: {
+                "description": "Conflict",
+                "content": {
+                    "application/json": {
+                        "example": {"detail": "Item already exists"},
+                    },
+                },
+            },
+        }
+    ),
+)
+def create_item():
+    """Create an item."""
+    pass
+```
+
+### 3. ErrorDTO Protocol
+
+Use objects implementing the `ErrorDTO` protocol for project compatibility:
+
+```python
+from fastapi_errors_plus import Errors, ErrorDTO
+
+class MyErrorDTO:
+    status_code = 404
+    message = "Not found"
+    
+    def to_example(self):
+        return {
+            "Not found": {
+                "value": {"detail": "Not found"},
+            },
+        }
+
+@router.get(
+    "/resource/{id}",
+    responses=Errors(
+        MyErrorDTO(),
+    ),
+)
+def get_resource(id: int):
+    """Get a resource."""
+    pass
+```
+
+### 4. Mixed Usage
+
+Combine flags, dict, and ErrorDTO:
+
+```python
+@router.post(
+    "/items/{id}",
+    responses=Errors(
+        {409: {
+            "description": "Conflict",
+            "content": {
+                "application/json": {
+                    "example": {"detail": "Already exists"},
+                },
+            },
+        }},
+        MyErrorDTO(),  # ErrorDTO
+        unauthorized=True,  # Flag
+        forbidden=True,  # Flag
+    ),
+)
+def create_item_mixed(id: int):
+    """Create an item with mixed error types."""
+    pass
+```
+
+### 5. Merging Examples
+
+Multiple errors with the same status code are automatically merged:
+
+```python
+@router.put(
+    "/items/{id}",
+    responses=Errors(
+        Error1(),  # 404
+        Error2(),  # 404
+    ),
+)
+def update_item(id: int):
+    """Update an item."""
+    pass
+```
+
+The OpenAPI spec will contain both examples under the 404 status code.
+
+## ErrorDTO Protocol
+
+The `ErrorDTO` protocol defines the interface for error objects compatible with the library:
+
+```python
+from typing import Protocol, Dict, Any
+
+class ErrorDTO(Protocol):
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        """Generate example for OpenAPI.
+        
+        Returns:
+            Dict in format: {"key": {"value": {"detail": "message"}}}
+        """
+        ...
+```
+
+Any class implementing this protocol (through structural typing) can be used with `Errors()`.
+
+## 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:
+
+```python
+# Your existing ApiErrorDTO
+@dataclass
+class ApiErrorDTO:
+    status_code: int
+    message: str
+    
+    def to_example(self) -> dict:
+        return {
+            self.message: {
+                "value": {"detail": self.message},
+            },
+        }
+
+# Works directly with fastapi-errors-plus!
+@router.delete(
+    "/{id}",
+    responses=Errors(
+        ApiErrorDTO(status_code=404, message="Not found"),
+    ),
+)
+def delete_item(id: int):
+    pass
+```
+
+## API Reference
+
+### `Errors`
+
+Main class for documenting errors in FastAPI endpoints.
+
+#### Constructor
+
+```python
+Errors(
+    *errors: Union[Dict[int, Dict[str, Any]], ErrorDTO],
+    unauthorized: bool = False,
+    forbidden: bool = False,
+    validation_error: bool = False,
+    internal_server_error: 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
+
+**Returns:**
+- Callable object that returns `Dict[int, Dict[str, Any]]` in FastAPI responses format
+
+#### Usage
+
+```python
+# Call the instance to get responses dict
+responses = Errors(unauthorized=True)
+```
+
+### `ErrorDTO`
+
+Protocol for error objects compatible with the library.
+
+**Required attributes:**
+- `status_code: int` — HTTP status code
+- `message: str` — Error message description
+
+**Required methods:**
+- `to_example() -> Dict[str, Any]` — Generate example for OpenAPI
+
+## Examples
+
+### Example 1: Standard FastAPI Project
+
+```python
+from fastapi import APIRouter
+from fastapi_errors_plus import Errors
+
+router = APIRouter()
+
+@router.delete(
+    "/{id}",
+    responses=Errors(
+        {404: {
+            "description": "Not found",
+            "content": {
+                "application/json": {
+                    "example": {"detail": "Item not found"},
+                },
+            },
+        }},
+        unauthorized=True,
+        forbidden=True,
+    ),
+)
+def delete_item(id: int):
+    """Delete an item."""
+    pass
+```
+
+### Example 2: Project with ErrorDTO
+
+```python
+from fastapi import APIRouter
+from fastapi_errors_plus import Errors
+from api.exceptions.dto import errors  # Your project's error DTOs
+
+router = APIRouter()
+
+@router.delete(
+    "/{notificationId}",
+    responses=Errors(
+        unauthorized=True,
+        forbidden=True,
+        errors.notification_not_found_error,  # Your ErrorDTO
+    ),
+)
+async def delete_notification(notification_id: int):
+    """Delete a notification."""
+    pass
+```
+
+### Example 3: Multiple Examples for Same Status
+
+```python
+@router.delete(
+    "/{id}",
+    responses=Errors(
+        unauthorized=True,  # Basic 401
+        {401: {  # Override with multiple examples
+            "description": "Unauthorized",
+            "content": {
+                "application/json": {
+                    "examples": {
+                        "InvalidToken": {"value": {"detail": "Invalid token"}},
+                        "SessionNotFound": {"value": {"detail": "Session not found"}},
+                    },
+                },
+            },
+        }},
+    ),
+)
+def delete_item(id: int):
+    """Delete an item."""
+    pass
+```
+
+### Example 4: Clean Architecture Integration
+
+This example shows how to use `fastapi-errors-plus` in a FastAPI project with Clean Architecture:
+
+**Domain Layer** (`domain/errors.py`):
+```python
+from typing import Protocol, Dict, Any
+
+class DomainError(Protocol):
+    """Domain error protocol compatible with ErrorDTO."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        """Generate example for OpenAPI."""
+        ...
+
+class ItemNotFoundError:
+    """Domain error for item not found."""
+    status_code = 404
+    message = "Item not found"
+    
+    def to_example(self) -> Dict[str, Any]:
+        return {
+            "ItemNotFound": {
+                "value": {"detail": "Item not found"},
+            },
+        }
+
+class ItemAlreadyExistsError:
+    """Domain error for item already exists."""
+    status_code = 409
+    message = "Item already exists"
+    
+    def to_example(self) -> Dict[str, Any]:
+        return {
+            "ItemAlreadyExists": {
+                "value": {"detail": "Item already exists"},
+            },
+        }
+```
+
+**Application Layer** (`application/use_cases.py`):
+```python
+from domain.errors import ItemNotFoundError, ItemAlreadyExistsError
+
+class CreateItemUseCase:
+    """Use case for creating an item."""
+    
+    def execute(self, item_data: dict):
+        # Business logic here
+        if self._item_exists(item_data["id"]):
+            raise ItemAlreadyExistsError()
+        # ... create item ...
+        return item
+
+class GetItemUseCase:
+    """Use case for getting an item."""
+    
+    def execute(self, item_id: int):
+        item = self._repository.get(item_id)
+        if not item:
+            raise ItemNotFoundError()
+        return item
+```
+
+**Infrastructure/Presentation Layer** (`api/routes/items.py`):
+```python
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi_errors_plus import Errors
+from domain.errors import ItemNotFoundError, ItemAlreadyExistsError
+from application.use_cases import CreateItemUseCase, GetItemUseCase
+
+router = APIRouter()
+
+@router.post(
+    "/items",
+    status_code=status.HTTP_201_CREATED,
+    responses=Errors(
+        unauthorized=True,  # From authentication dependency
+        forbidden=True,     # From authorization dependency
+        validation_error=True,  # From FastAPI validation
+        ItemAlreadyExistsError(),  # Domain error
+    ),
+)
+async def create_item(
+    item_data: dict,
+    use_case: CreateItemUseCase = Depends(),
+):
+    """Create a new item."""
+    try:
+        item = use_case.execute(item_data)
+        return item
+    except ItemAlreadyExistsError as e:
+        raise HTTPException(
+            status_code=e.status_code,
+            detail=e.message,
+        )
+
+@router.get(
+    "/items/{item_id}",
+    responses=Errors(
+        unauthorized=True,
+        forbidden=True,
+        ItemNotFoundError(),  # Domain error
+    ),
+)
+async def get_item(
+    item_id: int,
+    use_case: GetItemUseCase = Depends(),
+):
+    """Get an item by ID."""
+    try:
+        item = use_case.execute(item_id)
+        return item
+    except ItemNotFoundError as e:
+        raise HTTPException(
+            status_code=e.status_code,
+            detail=e.message,
+        )
+```
+
+**Benefits of this approach:**
+- Domain errors are reusable across layers
+- Errors are documented directly in the endpoint
+- Clean separation of concerns
+- Domain layer doesn't depend on FastAPI
+- Easy to test domain errors independently
+
+## Limitations
+
+The library improves **transparency of documented** errors. It does **not** solve the problem of finding **all real** errors in an endpoint, which requires analyzing the entire codebase (transaction scripts, `Depends` dependencies, database operations, etc.).
+
+**What the library does:**
+- Improves transparency of documented errors
+- Simplifies syntax for documenting errors
+- Makes errors visible directly in the endpoint
+
+**What the library does not do:**
+- Find all real errors in an endpoint automatically
+- Analyze code to discover errors
+- Guarantee completeness of error lists
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed changelog.
+

fastapi_errors_plus-0.1.0.dist-info/RECORD

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

fastapi_errors_plus-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastapi_errors_plus-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 fastapi-errors-plus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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/top_level.txt

@@ -0,0 +1 @@
+fastapi_errors_plus