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

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/LICENSE

@@ -22,3 +22,4 @@ SOFTWARE.
 
 
 
+

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.5.0
+Version: 0.6.1
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -246,10 +246,10 @@ def delete_item(id: int):
 ```
 
 **Benefits:**
-- ✅ No need to write ErrorDTO classes from scratch
-- ✅ Correct implementation out of the box
-- ✅ Reusable across all endpoints
-- ✅ Supports inheritance for custom logic
+- No need to write ErrorDTO classes from scratch
+- Correct implementation out of the box
+- Reusable across all endpoints
+- Supports inheritance for custom logic
 
 ### 5. Mixed Usage
 
@@ -319,6 +319,8 @@ class ErrorDTO(Protocol):
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**Best Practice:** For maximum clarity, consider making your domain exceptions implement the ErrorDTO protocol directly. See [Best Practice: Connecting Exceptions and ErrorDTO](#best-practice-connecting-exceptions-and-errordto) for details.
+
 ### When to Use Protocol vs BaseErrorDTO
 
 **Use Protocol (structural typing)** when:
@@ -333,6 +335,71 @@ Any class implementing this protocol (through structural typing) can be used wit
 
 Both approaches work together — you can mix them in the same `Errors()` call!
 
+## Best Practice: Connecting Exceptions and ErrorDTO
+
+### Problem
+
+It's not always clear which exception corresponds to which ErrorDTO:
+
+```python
+# Not clear which exception this documents
+responses=Errors(notification_not_found_error)
+```
+
+### Solution: Domain Exception as ErrorDTO
+
+**Recommended approach** — make your exceptions implement ErrorDTO protocol:
+
+```python
+# domain/exceptions.py
+from typing import Dict, Any
+
+class DomainException(Exception):
+    """Base exception implementing ErrorDTO protocol."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        return {self.message: {"value": {"detail": self.message}}}
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls()
+
+class NotificationNotFoundError(DomainException):
+    status_code = 404
+    message = "Notification not found"
+    
+    def __init__(self, notification_id: str = ""):
+        self.notification_id = notification_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        return cls(notification_id="example_id")
+
+# In endpoint
+@router.delete(
+    "/{notificationId}",
+    responses=Errors(
+        NotificationNotFoundError.for_openapi(),  # Clear connection!
+    ),
+)
+async def delete_notification(notification_id: str):
+    if not notification:
+        raise NotificationNotFoundError(notification_id)  # Same exception!
+```
+
+**Benefits:**
+- Exception and ErrorDTO are one class
+- Clear connection visible in endpoint
+- No duplication
+- Type-safe
+- Works with any project architecture
+
+See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete example.
+
 ## Compatibility with Existing Projects
 
 If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol:

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/README.md

@@ -220,10 +220,10 @@ def delete_item(id: int):
 ```
 
 **Benefits:**
-- ✅ No need to write ErrorDTO classes from scratch
-- ✅ Correct implementation out of the box
-- ✅ Reusable across all endpoints
-- ✅ Supports inheritance for custom logic
+- No need to write ErrorDTO classes from scratch
+- Correct implementation out of the box
+- Reusable across all endpoints
+- Supports inheritance for custom logic
 
 ### 5. Mixed Usage
 
@@ -293,6 +293,8 @@ class ErrorDTO(Protocol):
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**Best Practice:** For maximum clarity, consider making your domain exceptions implement the ErrorDTO protocol directly. See [Best Practice: Connecting Exceptions and ErrorDTO](#best-practice-connecting-exceptions-and-errordto) for details.
+
 ### When to Use Protocol vs BaseErrorDTO
 
 **Use Protocol (structural typing)** when:
@@ -307,6 +309,71 @@ Any class implementing this protocol (through structural typing) can be used wit
 
 Both approaches work together — you can mix them in the same `Errors()` call!
 
+## Best Practice: Connecting Exceptions and ErrorDTO
+
+### Problem
+
+It's not always clear which exception corresponds to which ErrorDTO:
+
+```python
+# Not clear which exception this documents
+responses=Errors(notification_not_found_error)
+```
+
+### Solution: Domain Exception as ErrorDTO
+
+**Recommended approach** — make your exceptions implement ErrorDTO protocol:
+
+```python
+# domain/exceptions.py
+from typing import Dict, Any
+
+class DomainException(Exception):
+    """Base exception implementing ErrorDTO protocol."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        return {self.message: {"value": {"detail": self.message}}}
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls()
+
+class NotificationNotFoundError(DomainException):
+    status_code = 404
+    message = "Notification not found"
+    
+    def __init__(self, notification_id: str = ""):
+        self.notification_id = notification_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        return cls(notification_id="example_id")
+
+# In endpoint
+@router.delete(
+    "/{notificationId}",
+    responses=Errors(
+        NotificationNotFoundError.for_openapi(),  # Clear connection!
+    ),
+)
+async def delete_notification(notification_id: str):
+    if not notification:
+        raise NotificationNotFoundError(notification_id)  # Same exception!
+```
+
+**Benefits:**
+- Exception and ErrorDTO are one class
+- Clear connection visible in endpoint
+- No duplication
+- Type-safe
+- Works with any project architecture
+
+See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete example.
+
 ## Compatibility with Existing Projects
 
 If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol:

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/fastapi_errors_plus/__init__.py

@@ -10,5 +10,5 @@ __all__ = [
     "BaseErrorDTO",  # Base implementation (optional)
     "StandardErrorDTO",  # Extended implementation (optional)
 ]
-__version__ = "0.5.0"
+__version__ = "0.6.1"
 

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

@@ -121,3 +121,4 @@ class StandardErrorDTO(BaseErrorDTO):
         }
 
 
+

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/fastapi_errors_plus/protocol.py

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

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/fastapi_errors_plus.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.5.0
+Version: 0.6.1
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -246,10 +246,10 @@ def delete_item(id: int):
 ```
 
 **Benefits:**
-- ✅ No need to write ErrorDTO classes from scratch
-- ✅ Correct implementation out of the box
-- ✅ Reusable across all endpoints
-- ✅ Supports inheritance for custom logic
+- No need to write ErrorDTO classes from scratch
+- Correct implementation out of the box
+- Reusable across all endpoints
+- Supports inheritance for custom logic
 
 ### 5. Mixed Usage
 
@@ -319,6 +319,8 @@ class ErrorDTO(Protocol):
 
 Any class implementing this protocol (through structural typing) can be used with `Errors()`.
 
+**Best Practice:** For maximum clarity, consider making your domain exceptions implement the ErrorDTO protocol directly. See [Best Practice: Connecting Exceptions and ErrorDTO](#best-practice-connecting-exceptions-and-errordto) for details.
+
 ### When to Use Protocol vs BaseErrorDTO
 
 **Use Protocol (structural typing)** when:
@@ -333,6 +335,71 @@ Any class implementing this protocol (through structural typing) can be used wit
 
 Both approaches work together — you can mix them in the same `Errors()` call!
 
+## Best Practice: Connecting Exceptions and ErrorDTO
+
+### Problem
+
+It's not always clear which exception corresponds to which ErrorDTO:
+
+```python
+# Not clear which exception this documents
+responses=Errors(notification_not_found_error)
+```
+
+### Solution: Domain Exception as ErrorDTO
+
+**Recommended approach** — make your exceptions implement ErrorDTO protocol:
+
+```python
+# domain/exceptions.py
+from typing import Dict, Any
+
+class DomainException(Exception):
+    """Base exception implementing ErrorDTO protocol."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        return {self.message: {"value": {"detail": self.message}}}
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls()
+
+class NotificationNotFoundError(DomainException):
+    status_code = 404
+    message = "Notification not found"
+    
+    def __init__(self, notification_id: str = ""):
+        self.notification_id = notification_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        return cls(notification_id="example_id")
+
+# In endpoint
+@router.delete(
+    "/{notificationId}",
+    responses=Errors(
+        NotificationNotFoundError.for_openapi(),  # Clear connection!
+    ),
+)
+async def delete_notification(notification_id: str):
+    if not notification:
+        raise NotificationNotFoundError(notification_id)  # Same exception!
+```
+
+**Benefits:**
+- Exception and ErrorDTO are one class
+- Clear connection visible in endpoint
+- No duplication
+- Type-safe
+- Works with any project architecture
+
+See [examples/domain_exceptions.py](examples/domain_exceptions.py) for complete example.
+
 ## Compatibility with Existing Projects
 
 If your project already has error DTOs (like `ApiErrorDTO`), they can work with `fastapi-errors-plus` if they implement the `ErrorDTO` protocol:

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/pyproject.toml

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

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/tests/test_app.py

@@ -1,5 +1,7 @@
 """Test FastAPI application for integration testing."""
 
+from typing import Dict, Any
+
 from fastapi import APIRouter, FastAPI, status
 from fastapi_errors_plus import BaseErrorDTO, Errors, StandardErrorDTO
 from tests.conftest import SimpleErrorDTO
@@ -11,6 +13,57 @@ app = FastAPI(title="Test API for fastapi-errors-plus")
 router = APIRouter()
 
 
+# Domain Exception pattern for testing (Best Practice example)
+class DomainException(Exception):
+    """Base exception implementing ErrorDTO protocol."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        """Generate example for OpenAPI."""
+        return {
+            self.message: {
+                "value": {"detail": self.message},
+            },
+        }
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls()
+
+
+class TestItemNotFoundError(DomainException):
+    """Test item not found error."""
+    status_code = status.HTTP_404_NOT_FOUND
+    message = "Test item not found"
+    
+    def __init__(self, item_id: str = ""):
+        self.item_id = item_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls(item_id="test_id")
+
+
+class TestItemAccessDeniedError(DomainException):
+    """Test item access denied error."""
+    status_code = status.HTTP_403_FORBIDDEN
+    message = "Test item access denied"
+    
+    def __init__(self, item_id: str = "", user_id: str = ""):
+        self.item_id = item_id
+        self.user_id = user_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls(item_id="test_id", user_id="test_user")
+
+
 # Example 1: Standard flags only
 @router.get(
     "/standard-flags",
@@ -220,6 +273,71 @@ def create_item_mixed_base_dto(item_id: int):
     return {"message": f"Item {item_id} created"}
 
 
+# Domain Exception pattern for testing (Best Practice example)
+class DomainException(Exception):
+    """Base exception implementing ErrorDTO protocol."""
+    status_code: int
+    message: str
+    
+    def to_example(self) -> Dict[str, Any]:
+        """Generate example for OpenAPI."""
+        return {
+            self.message: {
+                "value": {"detail": self.message},
+            },
+        }
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls()
+
+
+class TestItemNotFoundError(DomainException):
+    """Test item not found error."""
+    status_code = status.HTTP_404_NOT_FOUND
+    message = "Test item not found"
+    
+    def __init__(self, item_id: str = ""):
+        self.item_id = item_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls(item_id="test_id")
+
+
+class TestItemAccessDeniedError(DomainException):
+    """Test item access denied error."""
+    status_code = status.HTTP_403_FORBIDDEN
+    message = "Test item access denied"
+    
+    def __init__(self, item_id: str = "", user_id: str = ""):
+        self.item_id = item_id
+        self.user_id = user_id
+        super().__init__(self.message)
+    
+    @classmethod
+    def for_openapi(cls):
+        """Returns instance for OpenAPI documentation."""
+        return cls(item_id="test_id", user_id="test_user")
+
+
+# Example 11: Domain Exception as ErrorDTO (Best Practice pattern)
+@router.delete(
+    "/domain-exception/{item_id}",
+    responses=Errors(
+        TestItemNotFoundError.for_openapi(),      # Using for_openapi() pattern
+        TestItemAccessDeniedError.for_openapi(),  # Using for_openapi() pattern
+        unauthorized_401=True,                    # Standard flag
+    ),
+)
+def delete_item_domain_exception(item_id: str):
+    """Endpoint demonstrating Domain Exception as ErrorDTO pattern."""
+    return {"message": f"Item {item_id} deleted"}
+
+
 # Register router
 app.include_router(router, prefix="/api/v1", tags=["test"])
 

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

@@ -303,3 +303,4 @@ class TestBaseErrorDTOCompatibility:
         assert status.HTTP_500_INTERNAL_SERVER_ERROR in responses
 
 
+

{fastapi_errors_plus-0.5.0 → fastapi_errors_plus-0.6.1}/tests/test_integration.py

@@ -319,6 +319,93 @@ class TestMixedBaseDTOEndpoint:
         assert "500" in responses  # From flag
 
 
+class TestDomainExceptionEndpoint:
+    """Tests for Domain Exception as ErrorDTO endpoint (Best Practice pattern)."""
+    
+    def test_responses_in_openapi(self):
+        """Test that Domain Exception responses are in OpenAPI."""
+        client = TestClient(app)
+        response = client.get("/openapi.json")
+        schema = response.json()
+        
+        endpoint = schema["paths"]["/api/v1/domain-exception/{item_id}"]["delete"]
+        responses = endpoint["responses"]
+        
+        assert "401" in responses  # From flag
+        assert "403" in responses  # From TestItemAccessDeniedError.for_openapi()
+        assert "404" in responses  # From TestItemNotFoundError.for_openapi()
+    
+    def test_404_response_structure_from_domain_exception(self):
+        """Test 404 response structure from Domain Exception."""
+        client = TestClient(app)
+        response = client.get("/openapi.json")
+        schema = response.json()
+        
+        endpoint = schema["paths"]["/api/v1/domain-exception/{item_id}"]["delete"]
+        error_404 = endpoint["responses"]["404"]
+        
+        assert error_404["description"] == "Test item not found"
+        assert "content" in error_404
+        assert "application/json" in error_404["content"]
+        assert "examples" in error_404["content"]["application/json"]
+        examples = error_404["content"]["application/json"]["examples"]
+        assert "Test item not found" in examples
+    
+    def test_403_response_structure_from_domain_exception(self):
+        """Test 403 response structure from Domain Exception."""
+        client = TestClient(app)
+        response = client.get("/openapi.json")
+        schema = response.json()
+        
+        endpoint = schema["paths"]["/api/v1/domain-exception/{item_id}"]["delete"]
+        error_403 = endpoint["responses"]["403"]
+        
+        assert error_403["description"] == "Test item access denied"
+        assert "content" in error_403
+        assert "application/json" in error_403["content"]
+        assert "examples" in error_403["content"]["application/json"]
+        examples = error_403["content"]["application/json"]["examples"]
+        assert "Test item access denied" in examples
+    
+    def test_for_openapi_method_returns_error_dto(self):
+        """Test that for_openapi() method returns instance implementing ErrorDTO."""
+        from tests.test_app import TestItemNotFoundError
+        
+        error_instance = TestItemNotFoundError.for_openapi()
+        
+        # Check that it implements ErrorDTO protocol
+        assert hasattr(error_instance, "status_code")
+        assert hasattr(error_instance, "message")
+        assert hasattr(error_instance, "to_example")
+        assert callable(error_instance.to_example)
+        
+        # Check values
+        assert error_instance.status_code == 404
+        assert error_instance.message == "Test item not found"
+        assert error_instance.item_id == "test_id"
+        
+        # Check to_example() works
+        example = error_instance.to_example()
+        assert isinstance(example, dict)
+        assert "Test item not found" in example
+    
+    def test_domain_exception_works_with_errors_class(self):
+        """Test that Domain Exception instances work with Errors class."""
+        from fastapi_errors_plus import Errors
+        from tests.test_app import TestItemNotFoundError, TestItemAccessDeniedError
+        
+        errors = Errors(
+            TestItemNotFoundError.for_openapi(),
+            TestItemAccessDeniedError.for_openapi(),
+        )
+        responses = errors
+        
+        assert 404 in responses
+        assert 403 in responses
+        assert responses[404]["description"] == "Test item not found"
+        assert responses[403]["description"] == "Test item access denied"
+
+
 class TestRealEndpoints:
     """Tests for actual endpoint responses."""
     
@@ -361,5 +448,13 @@ class TestRealEndpoints:
         
         assert response.status_code == 200
         assert response.json() == {"message": "Item 1 deleted"}
+    
+    def test_domain_exception_endpoint_works(self):
+        """Test that Domain Exception endpoint returns 200."""
+        client = TestClient(app)
+        response = client.delete("/api/v1/domain-exception/1")
+        
+        assert response.status_code == 200
+        assert response.json() == {"message": "Item 1 deleted"}