fastapi-errors-plus 0.8.0__tar.gz → 0.9.0__tar.gz

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.8.0
+Version: 0.9.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -33,7 +33,7 @@ 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-117-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-138-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 [![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
@@ -108,13 +108,13 @@ Use boolean flags for common HTTP status codes:
 - `validation_error_422=True` → 422 Unprocessable Entity (defaults to `True`)
 - `internal_server_error_500=True` → 500 Internal Server Error
 
-**Legacy (for backward compatibility):**
+**Legacy (deprecated in 0.9, removal in 1.0):**
 - `unauthorized=True` → 401 Unauthorized
 - `forbidden=True` → 403 Forbidden
-- `validation_error=True` → 422 Unprocessable Entity (defaults to `True`)
+- `validation_error=True` → 422 Unprocessable Entity
 - `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.
+**Note on 422:** If you omit both `validation_error` and `validation_error_422`, the library still adds **422** today but emits a **`DeprecationWarning`** — the default will become **`False` in 1.0**. For ADR-style APIs, set `validation_error_422=False` explicitly (or use **`ErrorProfile`** below).
 
 ```python
 @router.get(
@@ -318,6 +318,44 @@ def delete_item(id: int):
 
 A **plain dict** as an example value is treated as the full response **body** unless it looks like an OpenAPI Example Object (keys only among `value`, `summary`, `description`, `externalValue`).
 
+Optional **`model=`** (Pydantic model on the outer response object for FastAPI `$ref` registration) and **`schema=`** (JSON Schema under `application/json`) avoid a separate status `dict` for typed error bodies:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+conflict = ErrorDoc(
+    status_code=409,
+    message="BusinessRule",
+    model=ApplicationJsonError,  # optional Pydantic model
+    schema=ADR_ERROR_BODY_SCHEMA,  # or raw JSON Schema
+    body={"code": "RULE_VIOLATION", "detail": "Item exists"},
+)
+
+@router.post("/items", responses=Errors(conflict, validation_error_422=False))
+def create_item():
+    ...
+```
+
+#### ErrorProfile
+
+Project-wide defaults (frozen — not mutated by endpoint calls):
+
+```python
+from fastapi_errors_plus import ErrorDoc, ErrorProfile, Errors
+
+ADR = ErrorProfile(
+    validation_error_422=False,
+    unauthorized_401=True,
+    internal_server_error_500=True,
+)
+
+@router.post("/items", responses=Errors(business_conflict, profile=ADR))
+def create_item():
+    ...
+```
+
+Explicit `Errors` keyword flags override profile values. Positional dict/DTO errors are merged after profile-driven standard statuses.
+
 ### 5. Mixed Usage
 
 Combine flags, dict, and ErrorDTO:
@@ -645,6 +683,7 @@ Errors(
     forbidden_403: bool = False,
     validation_error_422: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error_500: bool = False,
+    profile: Optional[ErrorProfile] = None,
 )
 ```
 
@@ -663,10 +702,12 @@ Errors(
   - `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`.
+- `internal_server_error`: Add 500 Internal Server Error (legacy, **deprecated** in 0.9). Defaults to `False`.
+- `profile`: Optional **`ErrorProfile`** — project defaults; explicit kwargs override profile.
+
+**Deprecation (0.9+):** legacy kwargs above emit `DeprecationWarning` (removal in **1.0**). Omitting both `validation_error` and `validation_error_422` still adds 422 but warns; default becomes **`False` in 1.0**.
 
-**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`.
+**422 behaviour:** pass `validation_error_422=False` for endpoints without request-body validation or ADR-style error bodies. Use **`ErrorProfile`** to set this once per project.
 
 **Returns:**
 - A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
@@ -714,12 +755,27 @@ ErrorDoc(
     examples: Optional[Dict[str, str | dict]] = None,
     body: Optional[Dict[str, Any]] = None,
     example_key: Optional[str] = None,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
 When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
 
+### `ErrorProfile`
+
+Frozen project-wide defaults for standard HTTP flags.
+
+```python
+ErrorProfile(
+    unauthorized_401: bool = False,
+    forbidden_403: bool = False,
+    validation_error_422: Optional[bool] = None,
+    internal_server_error_500: bool = False,
+)
+```
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -729,6 +785,8 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/README.md

@@ -4,7 +4,7 @@
 [![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-117-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-138-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 [![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
@@ -79,13 +79,13 @@ Use boolean flags for common HTTP status codes:
 - `validation_error_422=True` → 422 Unprocessable Entity (defaults to `True`)
 - `internal_server_error_500=True` → 500 Internal Server Error
 
-**Legacy (for backward compatibility):**
+**Legacy (deprecated in 0.9, removal in 1.0):**
 - `unauthorized=True` → 401 Unauthorized
 - `forbidden=True` → 403 Forbidden
-- `validation_error=True` → 422 Unprocessable Entity (defaults to `True`)
+- `validation_error=True` → 422 Unprocessable Entity
 - `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.
+**Note on 422:** If you omit both `validation_error` and `validation_error_422`, the library still adds **422** today but emits a **`DeprecationWarning`** — the default will become **`False` in 1.0**. For ADR-style APIs, set `validation_error_422=False` explicitly (or use **`ErrorProfile`** below).
 
 ```python
 @router.get(
@@ -289,6 +289,44 @@ def delete_item(id: int):
 
 A **plain dict** as an example value is treated as the full response **body** unless it looks like an OpenAPI Example Object (keys only among `value`, `summary`, `description`, `externalValue`).
 
+Optional **`model=`** (Pydantic model on the outer response object for FastAPI `$ref` registration) and **`schema=`** (JSON Schema under `application/json`) avoid a separate status `dict` for typed error bodies:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+conflict = ErrorDoc(
+    status_code=409,
+    message="BusinessRule",
+    model=ApplicationJsonError,  # optional Pydantic model
+    schema=ADR_ERROR_BODY_SCHEMA,  # or raw JSON Schema
+    body={"code": "RULE_VIOLATION", "detail": "Item exists"},
+)
+
+@router.post("/items", responses=Errors(conflict, validation_error_422=False))
+def create_item():
+    ...
+```
+
+#### ErrorProfile
+
+Project-wide defaults (frozen — not mutated by endpoint calls):
+
+```python
+from fastapi_errors_plus import ErrorDoc, ErrorProfile, Errors
+
+ADR = ErrorProfile(
+    validation_error_422=False,
+    unauthorized_401=True,
+    internal_server_error_500=True,
+)
+
+@router.post("/items", responses=Errors(business_conflict, profile=ADR))
+def create_item():
+    ...
+```
+
+Explicit `Errors` keyword flags override profile values. Positional dict/DTO errors are merged after profile-driven standard statuses.
+
 ### 5. Mixed Usage
 
 Combine flags, dict, and ErrorDTO:
@@ -616,6 +654,7 @@ Errors(
     forbidden_403: bool = False,
     validation_error_422: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error_500: bool = False,
+    profile: Optional[ErrorProfile] = None,
 )
 ```
 
@@ -634,10 +673,12 @@ Errors(
   - `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`.
+- `internal_server_error`: Add 500 Internal Server Error (legacy, **deprecated** in 0.9). Defaults to `False`.
+- `profile`: Optional **`ErrorProfile`** — project defaults; explicit kwargs override profile.
+
+**Deprecation (0.9+):** legacy kwargs above emit `DeprecationWarning` (removal in **1.0**). Omitting both `validation_error` and `validation_error_422` still adds 422 but warns; default becomes **`False` in 1.0**.
 
-**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`.
+**422 behaviour:** pass `validation_error_422=False` for endpoints without request-body validation or ADR-style error bodies. Use **`ErrorProfile`** to set this once per project.
 
 **Returns:**
 - A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
@@ -685,12 +726,27 @@ ErrorDoc(
     examples: Optional[Dict[str, str | dict]] = None,
     body: Optional[Dict[str, Any]] = None,
     example_key: Optional[str] = None,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
 When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
 
+### `ErrorProfile`
+
+Frozen project-wide defaults for standard HTTP flags.
+
+```python
+ErrorProfile(
+    unauthorized_401: bool = False,
+    forbidden_403: bool = False,
+    validation_error_422: Optional[bool] = None,
+    internal_server_error_500: bool = False,
+)
+```
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -700,6 +756,8 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/fastapi_errors_plus/__init__.py

@@ -2,6 +2,7 @@
 
 from fastapi_errors_plus.base import BaseErrorDTO, StandardErrorDTO
 from fastapi_errors_plus.error_doc import ErrorDoc
+from fastapi_errors_plus.error_profile import ErrorProfile
 from fastapi_errors_plus.errors import Errors
 from fastapi_errors_plus.protocol import ErrorDTO, ErrorDTOLike, LegacyErrorDTO
 
@@ -11,7 +12,8 @@ __all__ = [
     "LegacyErrorDTO",
     "ErrorDTOLike",
     "ErrorDoc",
+    "ErrorProfile",
     "BaseErrorDTO",
     "StandardErrorDTO",
 ]
-__version__ = "0.8.0"
+__version__ = "0.9.0"

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/fastapi_errors_plus/base.py

@@ -41,6 +41,12 @@ class BaseErrorDTO:
     message: str
     """Error message description."""
 
+    model: Any = field(default=None, repr=False)
+    """Optional Pydantic model for FastAPI ``responses`` (outer ``model=`` key)."""
+
+    schema: Optional[Dict[str, Any]] = field(default=None, repr=False)
+    """Optional JSON Schema under ``content['application/json']['schema']``."""
+
     openapi_json_extras: Optional[Dict[str, Any]] = field(default=None)
     """Optional OpenAPI fragment under ``content['application/json']`` besides examples,
     typically ``{\"schema\": ...}`` or ``encoding``. Do **not** put ``example`` / ``examples``

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/fastapi_errors_plus/error_doc.py

@@ -39,6 +39,12 @@ class ErrorDoc:
     examples: Optional[Dict[str, ExampleSpec]] = None
     body: Optional[Dict[str, Any]] = None
     example_key: Optional[str] = None
+    model: Any = field(default=None, repr=False)
+    """Optional Pydantic model for FastAPI ``responses`` (outer ``model=`` key)."""
+
+    schema: Optional[Dict[str, Any]] = field(default=None, repr=False)
+    """Optional JSON Schema under ``content['application/json']['schema']``."""
+
     openapi_json_extras: Optional[Dict[str, Any]] = field(default=None)
 
     def to_examples(self) -> Dict[str, Any]:

fastapi_errors_plus-0.9.0/fastapi_errors_plus/error_profile.py

@@ -0,0 +1,31 @@
+"""Project-wide defaults for :class:`Errors` (release 0.9)."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class ErrorProfile:
+    """Immutable project defaults applied before per-endpoint ``Errors(...)`` args.
+
+    Explicit ``Errors`` keyword flags override profile values. Positional dict/DTO
+    errors are merged after profile-driven standard statuses.
+
+    Example:
+        ```python
+        ADR = ErrorProfile(
+            validation_error_422=False,
+            unauthorized_401=True,
+            internal_server_error_500=True,
+        )
+
+        @router.post("/items", responses=Errors(business_conflict, profile=ADR))
+        def create_item():
+            ...
+        ```
+    """
+
+    unauthorized_401: bool = False
+    forbidden_403: bool = False
+    validation_error_422: Optional[bool] = None
+    internal_server_error_500: bool = False

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/fastapi_errors_plus/errors.py

@@ -8,7 +8,14 @@ from typing import Any, Dict, Iterator, Optional, Union
 
 from fastapi import status
 
-from fastapi_errors_plus.protocol import ErrorDTO
+from fastapi_errors_plus.error_profile import ErrorProfile
+from fastapi_errors_plus.merge_utils import (
+    ensure_examples_dict,
+    merge_examples_map,
+    merge_singular_example,
+    standard_flag_example_key,
+)
+from fastapi_errors_plus.protocol import ErrorDTO, LegacyErrorDTO
 
 # Starlette (via FastAPI) prefers HTTP_422_UNPROCESSABLE_CONTENT over ENTITY.
 # Older pins may lack CONTENT (import crash); avoid nested getattr(, default=)
@@ -38,17 +45,26 @@ def _pick_error_dto_application_json_extra(error_dto: Any) -> Optional[Dict[str,
     """Optional OpenAPI ``application/json`` keys from DTO (e.g. ``schema``, ``encoding``).
 
     Prefer ``to_openapi_json_media_type_extras()`` when present and returns a truthy mapping;
-    otherwise ``openapi_json_extras`` attribute. Must not rely on ``example`` / ``examples`` here —
-    ``to_example()`` covers those."""
+    otherwise ``schema`` field, then ``openapi_json_extras``. Must not rely on ``example`` /
+    ``examples`` here — ``to_examples()`` covers those."""
+    extras: Dict[str, Any] = {}
+    schema = getattr(error_dto, "schema", None)
+    if isinstance(schema, dict) and schema:
+        extras["schema"] = schema
+    attr_extra = getattr(error_dto, "openapi_json_extras", None)
+    if isinstance(attr_extra, dict) and attr_extra:
+        extras.update(attr_extra)
     getter = getattr(error_dto, "to_openapi_json_media_type_extras", None)
     if callable(getter):
         out = getter()
         if isinstance(out, dict) and out:
-            return dict(out)
-    extra = getattr(error_dto, "openapi_json_extras", None)
-    if isinstance(extra, dict) and extra:
-        return dict(extra)
-    return None
+            extras.update(out)
+    return extras or None
+
+
+def _pick_error_dto_model(error_dto: Any) -> Any:
+    """Optional FastAPI ``model`` on the outer response object."""
+    return getattr(error_dto, "model", None)
 
 
 def _example_defining_class(cls: type, method: str) -> Optional[type]:
@@ -174,6 +190,7 @@ class Errors(Mapping):
             bool
         ] = None,  # 422 (explicit, None = use default True, False = disable, True = enable)
         internal_server_error_500: bool = False,  # 500 (explicit)
+        profile: Optional[ErrorProfile] = None,
     ) -> None:
         """Initialize Errors instance.
 
@@ -224,31 +241,76 @@ class Errors(Mapping):
             ```
         """
         self._responses: Dict[int, Dict[str, Any]] = {}
+        self._flag_example_keys: Dict[int, str] = {}
+
+        if unauthorized:
+            warnings.warn(
+                "unauthorized is deprecated; use unauthorized_401 instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if forbidden:
+            warnings.warn(
+                "forbidden is deprecated; use forbidden_403 instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if validation_error is not None:
+            warnings.warn(
+                "validation_error is deprecated; use validation_error_422 instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if internal_server_error:
+            warnings.warn(
+                "internal_server_error is deprecated; use internal_server_error_500 instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        use_unauthorized = unauthorized_401 or unauthorized
+        use_forbidden = forbidden_403 or forbidden
+        use_internal = internal_server_error_500 or internal_server_error
+        val_422 = (
+            validation_error_422
+            if validation_error_422 is not None
+            else validation_error
+        )
+
+        if profile is not None:
+            if not use_unauthorized:
+                use_unauthorized = profile.unauthorized_401
+            if not use_forbidden:
+                use_forbidden = profile.forbidden_403
+            if not use_internal:
+                use_internal = profile.internal_server_error_500
+            if val_422 is None:
+                val_422 = profile.validation_error_422
 
         # Add standard errors
-        # New parameters with explicit codes have priority, but old ones still work
-        if unauthorized_401 or unauthorized:
+        if use_unauthorized:
             self._add_standard_error(
                 status.HTTP_401_UNAUTHORIZED,
                 "Unauthorized",
                 {"detail": "Unauthorized"},
             )
-        if forbidden_403 or forbidden:
+        if use_forbidden:
             self._add_standard_error(
                 status.HTTP_403_FORBIDDEN,
                 "Forbidden",
                 {"detail": "Forbidden"},
             )
-        # 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 = True
+        if val_422 is False:
             add_422 = False
+        elif val_422 is None:
+            add_422 = True
+            warnings.warn(
+                "Implicit validation_error_422=True is deprecated and will default to "
+                "False in 1.0. Pass validation_error_422=False explicitly to silence.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
         if add_422:
             self._add_standard_error(
@@ -256,7 +318,7 @@ class Errors(Mapping):
                 "Validation Error",
                 {"detail": "Validation error"},
             )
-        if internal_server_error_500 or internal_server_error:
+        if use_internal:
             self._add_standard_error(
                 status.HTTP_500_INTERNAL_SERVER_ERROR,
                 "Internal Server Error",
@@ -277,37 +339,16 @@ class Errors(Mapping):
         _ensure_response_descriptions(self._responses)
 
     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")
+        """Validate that error object implements ErrorDTO or LegacyErrorDTO protocol."""
         has_to_examples = callable(getattr(error, "to_examples", None))
         has_to_example = callable(getattr(error, "to_example", None))
 
+        if isinstance(error, ErrorDTO) and has_to_examples:
+            return
+        if isinstance(error, LegacyErrorDTO) and has_to_example:
+            return
+
+        required_attrs = ("status_code", "message")
         missing_attrs = [attr for attr in required_attrs if not hasattr(error, attr)]
         if not has_to_examples and not has_to_example:
             missing_methods = ["to_examples or to_example"]
@@ -355,6 +396,10 @@ class Errors(Mapping):
         status.HTTP_500_INTERNAL_SERVER_ERROR: "Internal Server Error",
     }
 
+    def _prior_singular_example_key(self, status_code: int) -> Optional[str]:
+        """Example-map key for a singular ``example`` from a standard flag, if any."""
+        return self._flag_example_keys.get(status_code)
+
     def _add_standard_error(
         self,
         status_code: int,
@@ -365,22 +410,11 @@ class Errors(Mapping):
 
         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",
-            _HTTP_422: "StandardValidationError",
-            status.HTTP_500_INTERNAL_SERVER_ERROR: "StandardInternalServerError",
-        }
-        example_key = standard_keys.get(status_code, f"Standard{status_code}")
+        example_key = standard_flag_example_key(status_code)
 
         if status_code not in self._responses:
+            self._flag_example_keys[status_code] = example_key
             self._responses[status_code] = {
                 "description": description,
                 "content": {
@@ -390,29 +424,13 @@ class Errors(Mapping):
                 },
             }
         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!)
-            # 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
+            prior_key = self._prior_singular_example_key(status_code)
+            examples = ensure_examples_dict(content, prior_singular_key=prior_key)
+            unique_key = self._unique_key(examples, example_key)
+            examples[unique_key] = {"value": example}
 
     def _add_dict_error(self, error_dict: Dict[int, Dict[str, Any]]) -> None:
         """Add error from dict in FastAPI responses format.
@@ -457,58 +475,24 @@ class Errors(Mapping):
 
                         # 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(
-                                copy.deepcopy(response_json["examples"])
+                            prior_key = self._prior_singular_example_key(status_code)
+                            incoming_examples = response_json["examples"]
+                            if prior_key and prior_key in incoming_examples:
+                                prior_key = "default"
+                            merge_examples_map(
+                                existing_json,
+                                copy.deepcopy(incoming_examples),
+                                prior_singular_key=prior_key,
                             )
                         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
-                                unique_key = self._unique_key(
-                                    existing_json["examples"], "CustomExample"
-                                )
-                                existing_json["examples"][unique_key] = {
-                                    "value": response_json["example"]
-                                }
+                            merge_singular_example(
+                                existing_json,
+                                response_json["example"],
+                                prior_singular_key=self._prior_singular_example_key(
+                                    status_code
+                                ),
+                                unique_key_fn=self._unique_key,
+                            )
 
     def _add_error_dto(self, error_dto: ErrorDTO) -> None:
         """Add error from ErrorDTO (via Protocol).
@@ -536,6 +520,7 @@ class Errors(Mapping):
         dto_extras = _pick_error_dto_application_json_extra(error_dto)
         if dto_extras is not None:
             dto_extras = copy.deepcopy(dto_extras)
+        dto_model = _pick_error_dto_model(error_dto)
 
         if status_code not in self._responses:
             application_json: Dict[str, Any] = {"examples": examples}
@@ -543,46 +528,31 @@ class Errors(Mapping):
                 _merge_openapi_application_json_non_example(
                     application_json, dto_extras
                 )
-            self._responses[status_code] = {
+            response_block: Dict[str, Any] = {
                 "description": error_dto.message,
                 "content": {
                     "application/json": application_json,
                 },
             }
+            if dto_model is not None:
+                response_block["model"] = dto_model
+            self._responses[status_code] = response_block
         else:
-            # Merge examples for the same status code
-            # Safely access content/application/json with defaults
             existing = self._responses[status_code]
 
             _apply_dto_description(existing, error_dto, self.STANDARD_DESCRIPTIONS)
 
+            if dto_model is not None:
+                existing["model"] = dto_model
+
             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(copy.deepcopy(examples))
-            content_json["examples"] = existing_examples
+            prior_key = self._prior_singular_example_key(status_code)
+            merge_examples_map(
+                content_json,
+                copy.deepcopy(examples),
+                prior_singular_key=prior_key,
+            )
 
             if dto_extras is not None:
                 _merge_openapi_application_json_non_example(content_json, dto_extras)

fastapi_errors_plus-0.9.0/fastapi_errors_plus/merge_utils.py

@@ -0,0 +1,61 @@
+"""Shared OpenAPI example merge helpers (internal)."""
+
+from typing import Any, Callable, Dict, Optional
+
+# Example keys produced by standard HTTP status flags in :class:`Errors`.
+STANDARD_FLAG_EXAMPLE_KEYS: Dict[int, str] = {
+    401: "StandardUnauthorized",
+    403: "StandardForbidden",
+    422: "StandardValidationError",
+    500: "StandardInternalServerError",
+}
+
+
+def standard_flag_example_key(status_code: int) -> str:
+    """Return the examples-map key for a standard flag on *status_code*."""
+    return STANDARD_FLAG_EXAMPLE_KEYS.get(status_code, f"Standard{status_code}")
+
+
+def ensure_examples_dict(
+    media_json: Dict[str, Any],
+    *,
+    prior_singular_key: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Ensure ``media_json`` has an ``examples`` dict; promote singular ``example`` if needed."""
+    if "examples" in media_json:
+        return media_json["examples"]
+    examples: Dict[str, Any] = {}
+    if "example" in media_json:
+        key = prior_singular_key or "default"
+        examples[key] = {"value": media_json.pop("example")}
+    media_json["examples"] = examples
+    return examples
+
+
+def merge_singular_example(
+    media_json: Dict[str, Any],
+    example_body: Dict[str, Any],
+    *,
+    prior_singular_key: Optional[str] = None,
+    incoming_key: Optional[str] = None,
+    unique_key_fn: Callable[[Dict[str, Any], str], str],
+) -> None:
+    """Merge one OpenAPI ``example`` body into ``media_json`` as part of ``examples``."""
+    examples = ensure_examples_dict(media_json, prior_singular_key=prior_singular_key)
+    target_key = incoming_key or "default"
+    if target_key not in examples:
+        examples[target_key] = {"value": example_body}
+    else:
+        unique = unique_key_fn(examples, "CustomExample")
+        examples[unique] = {"value": example_body}
+
+
+def merge_examples_map(
+    media_json: Dict[str, Any],
+    incoming_examples: Dict[str, Any],
+    *,
+    prior_singular_key: Optional[str] = None,
+) -> None:
+    """Merge an ``examples`` map into ``media_json``."""
+    examples = ensure_examples_dict(media_json, prior_singular_key=prior_singular_key)
+    examples.update(incoming_examples)

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/fastapi_errors_plus.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-errors-plus
-Version: 0.8.0
+Version: 0.9.0
 Summary: Universal library for documenting errors in FastAPI endpoints
 Author-email: Igor Selivanov <seligoroff@gmail.com>
 License: MIT
@@ -33,7 +33,7 @@ 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-117-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
+[![Tests](https://img.shields.io/badge/tests-138-success.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 [![Coverage](https://img.shields.io/badge/coverage-80%25%2B-green.svg)](https://github.com/seligoroff/fastapi-errors-plus)
 
 Universal library for documenting errors in FastAPI endpoints.
@@ -108,13 +108,13 @@ Use boolean flags for common HTTP status codes:
 - `validation_error_422=True` → 422 Unprocessable Entity (defaults to `True`)
 - `internal_server_error_500=True` → 500 Internal Server Error
 
-**Legacy (for backward compatibility):**
+**Legacy (deprecated in 0.9, removal in 1.0):**
 - `unauthorized=True` → 401 Unauthorized
 - `forbidden=True` → 403 Forbidden
-- `validation_error=True` → 422 Unprocessable Entity (defaults to `True`)
+- `validation_error=True` → 422 Unprocessable Entity
 - `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.
+**Note on 422:** If you omit both `validation_error` and `validation_error_422`, the library still adds **422** today but emits a **`DeprecationWarning`** — the default will become **`False` in 1.0**. For ADR-style APIs, set `validation_error_422=False` explicitly (or use **`ErrorProfile`** below).
 
 ```python
 @router.get(
@@ -318,6 +318,44 @@ def delete_item(id: int):
 
 A **plain dict** as an example value is treated as the full response **body** unless it looks like an OpenAPI Example Object (keys only among `value`, `summary`, `description`, `externalValue`).
 
+Optional **`model=`** (Pydantic model on the outer response object for FastAPI `$ref` registration) and **`schema=`** (JSON Schema under `application/json`) avoid a separate status `dict` for typed error bodies:
+
+```python
+from fastapi_errors_plus import ErrorDoc, Errors
+
+conflict = ErrorDoc(
+    status_code=409,
+    message="BusinessRule",
+    model=ApplicationJsonError,  # optional Pydantic model
+    schema=ADR_ERROR_BODY_SCHEMA,  # or raw JSON Schema
+    body={"code": "RULE_VIOLATION", "detail": "Item exists"},
+)
+
+@router.post("/items", responses=Errors(conflict, validation_error_422=False))
+def create_item():
+    ...
+```
+
+#### ErrorProfile
+
+Project-wide defaults (frozen — not mutated by endpoint calls):
+
+```python
+from fastapi_errors_plus import ErrorDoc, ErrorProfile, Errors
+
+ADR = ErrorProfile(
+    validation_error_422=False,
+    unauthorized_401=True,
+    internal_server_error_500=True,
+)
+
+@router.post("/items", responses=Errors(business_conflict, profile=ADR))
+def create_item():
+    ...
+```
+
+Explicit `Errors` keyword flags override profile values. Positional dict/DTO errors are merged after profile-driven standard statuses.
+
 ### 5. Mixed Usage
 
 Combine flags, dict, and ErrorDTO:
@@ -645,6 +683,7 @@ Errors(
     forbidden_403: bool = False,
     validation_error_422: Optional[bool] = None,  # None (default) => True (FastAPI validates all parameters)
     internal_server_error_500: bool = False,
+    profile: Optional[ErrorProfile] = None,
 )
 ```
 
@@ -663,10 +702,12 @@ Errors(
   - `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`.
+- `internal_server_error`: Add 500 Internal Server Error (legacy, **deprecated** in 0.9). Defaults to `False`.
+- `profile`: Optional **`ErrorProfile`** — project defaults; explicit kwargs override profile.
+
+**Deprecation (0.9+):** legacy kwargs above emit `DeprecationWarning` (removal in **1.0**). Omitting both `validation_error` and `validation_error_422` still adds 422 but warns; default becomes **`False` in 1.0**.
 
-**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`.
+**422 behaviour:** pass `validation_error_422=False` for endpoints without request-body validation or ADR-style error bodies. Use **`ErrorProfile`** to set this once per project.
 
 **Returns:**
 - A dict-like `Mapping[int, …]` suitable for FastAPI’s `responses` / OpenAPI
@@ -714,12 +755,27 @@ ErrorDoc(
     examples: Optional[Dict[str, str | dict]] = None,
     body: Optional[Dict[str, Any]] = None,
     example_key: Optional[str] = None,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```
 
 When **`examples`** is omitted, a single example is built from **`body`** or `{"detail": message}`.
 
+### `ErrorProfile`
+
+Frozen project-wide defaults for standard HTTP flags.
+
+```python
+ErrorProfile(
+    unauthorized_401: bool = False,
+    forbidden_403: bool = False,
+    validation_error_422: Optional[bool] = None,
+    internal_server_error_500: bool = False,
+)
+```
+
 ### `BaseErrorDTO`
 
 Base implementation of ErrorDTO Protocol for convenience.
@@ -729,6 +785,8 @@ Base implementation of ErrorDTO Protocol for convenience.
 BaseErrorDTO(
     status_code: int,
     message: str,
+    model: Any = None,
+    schema: Optional[Dict[str, Any]] = None,
     openapi_json_extras: Optional[Dict[str, Any]] = None,
 )
 ```

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/fastapi_errors_plus.egg-info/SOURCES.txt

@@ -4,8 +4,10 @@ pyproject.toml
 fastapi_errors_plus/__init__.py
 fastapi_errors_plus/base.py
 fastapi_errors_plus/error_doc.py
+fastapi_errors_plus/error_profile.py
 fastapi_errors_plus/errors.py
 fastapi_errors_plus/example_utils.py
+fastapi_errors_plus/merge_utils.py
 fastapi_errors_plus/protocol.py
 fastapi_errors_plus/py.typed
 fastapi_errors_plus.egg-info/PKG-INFO
@@ -18,4 +20,5 @@ tests/test_base.py
 tests/test_errors.py
 tests/test_integration.py
 tests/test_release_08.py
-tests/test_release_08_edge_cases.py
+tests/test_release_08_edge_cases.py
+tests/test_release_09.py

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-errors-plus"
-version = "0.8.0"
+version = "0.9.0"
 description = "Universal library for documenting errors in FastAPI endpoints"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -61,6 +61,9 @@ addopts = [
     "--cov-fail-under=80",
     "-v",
 ]
+filterwarnings = [
+    "ignore:Implicit validation_error_422=True is deprecated:DeprecationWarning",
+]
 
 [tool.coverage.run]
 source = ["fastapi_errors_plus"]

{fastapi_errors_plus-0.8.0 → fastapi_errors_plus-0.9.0}/tests/test_errors.py

@@ -676,15 +676,10 @@ class TestUniqueKeys:
             unauthorized_401=True,  # Named after positional - should use unique key
         )
 
-        # Should have both examples
+        # Flag runs before positional dict: flag example becomes "default", dict keeps StandardUnauthorized
         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 "StandardUnauthorized" in examples
+        assert "default" in examples
         assert len(examples) == 2
         assert examples["StandardUnauthorized"]["value"]["detail"] == "Custom"
         assert examples["default"]["value"]["detail"] == "Unauthorized"

fastapi_errors_plus-0.9.0/tests/test_release_09.py

@@ -0,0 +1,122 @@
+"""Tests for release 0.9.0 (profile, model/schema on DTO, merge refactor, deprecations)."""
+
+import warnings
+
+import pytest
+from fastapi import status
+
+from fastapi_errors_plus import BaseErrorDTO, ErrorDoc, ErrorProfile, Errors
+
+
+@pytest.mark.unit
+class TestErrorProfile:
+    def test_profile_applies_standard_flags(self):
+        profile = ErrorProfile(
+            unauthorized_401=True,
+            validation_error_422=False,
+            internal_server_error_500=True,
+        )
+        errors = Errors(profile=profile)
+        assert 401 in errors
+        assert 500 in errors
+        assert status.HTTP_422_UNPROCESSABLE_CONTENT not in errors
+
+    def test_explicit_kwargs_override_profile(self):
+        profile = ErrorProfile(unauthorized_401=True, validation_error_422=False)
+        errors = Errors(forbidden_403=True, profile=profile, validation_error_422=False)
+        assert 401 in errors
+        assert 403 in errors
+
+    def test_profile_does_not_mutate_on_merge(self):
+        profile = ErrorProfile(validation_error_422=False)
+        Errors({409: {"description": "x"}}, profile=profile)
+        errors2 = Errors(profile=profile)
+        assert 409 not in errors2
+
+
+@pytest.mark.unit
+class TestDtoModelAndSchema:
+    def test_error_doc_model_on_response(self):
+        class M:
+            pass
+
+        doc = ErrorDoc(
+            status_code=401,
+            message="Unauthorized",
+            model=M,
+            body={"code": "UNAUTHORIZED", "detail": "bad token"},
+        )
+        errors = Errors(doc, validation_error_422=False)
+        assert errors[401]["model"] is M
+
+    def test_error_doc_schema_without_extra_dict(self):
+        schema = {
+            "type": "object",
+            "properties": {"code": {"type": "string"}, "detail": {"type": "string"}},
+        }
+        doc = ErrorDoc(
+            status_code=409,
+            message="Conflict",
+            schema=schema,
+            body={"code": "CONFLICT", "detail": "exists"},
+        )
+        errors = Errors(doc, validation_error_422=False)
+        aj = errors[409]["content"]["application/json"]
+        assert aj["schema"] == schema
+        assert "Conflict" in aj["examples"]
+
+    def test_base_error_dto_model_merges_with_flag(self):
+        class M:
+            pass
+
+        dto = BaseErrorDTO(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            message="Token expired",
+            model=M,
+        )
+        errors = Errors(dto, unauthorized_401=True, validation_error_422=False)
+        assert errors[401]["model"] is M
+
+
+@pytest.mark.unit
+class TestFlagExampleKeyRegistry:
+    def test_flag_then_dto_uses_standard_key_not_detail_guess(self):
+        dto = BaseErrorDTO(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            message="Custom auth message",
+        )
+        errors = Errors(dto, unauthorized_401=True, validation_error_422=False)
+        examples = errors[401]["content"]["application/json"]["examples"]
+        assert "StandardUnauthorized" in examples
+        assert "Custom auth message" in examples
+
+
+@pytest.mark.unit
+class TestLegacyKwargsDeprecation:
+    def test_legacy_unauthorized_warns(self):
+        with pytest.warns(DeprecationWarning, match="unauthorized_401"):
+            Errors(unauthorized=True, validation_error_422=False)
+
+    def test_implicit_422_default_warns(self):
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", DeprecationWarning)
+            Errors(unauthorized_401=True)
+        dep = [w for w in caught if "validation_error_422" in str(w.message)]
+        assert len(dep) == 1
+
+    def test_explicit_422_false_silences_implicit_warning(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+            Errors(unauthorized_401=True, validation_error_422=False)
+
+
+@pytest.mark.unit
+class TestProtocolValidation:
+    def test_non_callable_to_example_raises_before_collect(self):
+        class Bad:
+            status_code = 404
+            message = "x"
+            to_example = "nope"
+
+        with pytest.raises(TypeError, match="to_examples or to_example"):
+            Errors(Bad(), validation_error_422=False)