litestar-google-errors 0.1.1__py3-none-any.whl

litestar_google_errors/__init__.py

@@ -0,0 +1,12 @@
+from litestar_google_errors.models import GoogleError, GoogleErrorItem, GoogleErrorResponse, LocationType
+from litestar_google_errors.openapi import create_error_responses
+from litestar_google_errors.plugin import GoogleErrorResponsesPlugin
+
+__all__ = (
+    "GoogleError",
+    "GoogleErrorItem",
+    "GoogleErrorResponse",
+    "GoogleErrorResponsesPlugin",
+    "LocationType",
+    "create_error_responses",
+)

litestar_google_errors/models.py

@@ -0,0 +1,40 @@
+"""Google JSON style error payload models."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from msgspec import Struct
+
+__all__ = ("GoogleError", "GoogleErrorItem", "GoogleErrorResponse", "LocationType")
+
+
+class LocationType(str, Enum):
+    FIELD = "field"
+    PARAMETER = "parameter"
+    PATH = "path"
+    HEADER = "header"
+    BODY = "body"
+    QUERY = "query"
+    COOKIE = "cookie"
+    ENDPOINT = "endpoint"
+    DOMAIN = "domain"
+
+
+class GoogleErrorItem(Struct):
+    domain: str
+    reason: str
+    message: str
+    locationType: Optional[str] = None
+    location: Optional[str] = None
+
+
+class GoogleError(Struct):
+    errors: list[GoogleErrorItem]
+    code: int
+    message: str
+
+
+class GoogleErrorResponse(Struct):
+    error: GoogleError

litestar_google_errors/openapi.py

@@ -0,0 +1,114 @@
+"""OpenAPI schema generation for Google JSON style error responses."""
+
+from __future__ import annotations
+
+import contextlib
+from http import HTTPStatus
+from typing import Iterator
+
+from litestar import MediaType
+from litestar.exceptions import HTTPException
+from litestar.openapi.spec import OpenAPIMediaType, OpenAPIResponse, OpenAPIType, Schema
+
+__all__ = ("create_error_responses",)
+
+
+def _status_phrase(status_code: int) -> str:
+    with contextlib.suppress(ValueError):
+        return HTTPStatus(status_code).phrase
+    return ""
+
+
+def _status_description(status_code: int) -> str:
+    with contextlib.suppress(ValueError):
+        return HTTPStatus(status_code).description
+    return ""
+
+
+def _error_schema(
+    exc: type[HTTPException],
+    status_code: int,
+    detail: str,
+    domain: str,
+    location_type: str,
+    location: str,
+) -> Schema:
+    return Schema(
+        type=OpenAPIType.OBJECT,
+        required=["error"],
+        description=exc.__name__,
+        properties={
+            "error": Schema(
+                type=OpenAPIType.OBJECT,
+                required=["code", "message", "errors"],
+                properties={
+                    "code": Schema(type=OpenAPIType.INTEGER),
+                    "message": Schema(type=OpenAPIType.STRING),
+                    "errors": Schema(
+                        type=OpenAPIType.ARRAY,
+                        items=Schema(
+                            type=OpenAPIType.OBJECT,
+                            required=["domain", "reason", "message"],
+                            properties={
+                                "domain": Schema(type=OpenAPIType.STRING),
+                                "reason": Schema(type=OpenAPIType.STRING),
+                                "message": Schema(type=OpenAPIType.STRING),
+                                "locationType": Schema(type=[OpenAPIType.STRING, OpenAPIType.NULL]),
+                                "location": Schema(type=[OpenAPIType.STRING, OpenAPIType.NULL]),
+                            },
+                        ),
+                    ),
+                },
+            )
+        },
+        examples=[
+            {
+                "error": {
+                    "code": status_code,
+                    "message": detail,
+                    "errors": [
+                        {
+                            "domain": domain,
+                            "reason": exc.__name__,
+                            "message": detail,
+                            "locationType": location_type,
+                            "location": location,
+                        }
+                    ],
+                }
+            }
+        ],
+    )
+
+
+def create_error_responses(
+    exceptions: list[type[HTTPException]],
+    *,
+    domain: str = "global",
+    location_type: str = "endpoint",
+    location: str = "/example",
+) -> Iterator[tuple[str, OpenAPIResponse]]:
+    """Create OpenAPI responses for ``exceptions`` in the Google JSON error format.
+
+    Exceptions sharing a status code are combined into a single response using ``oneOf``.
+    """
+    grouped: dict[int, list[type[HTTPException]]] = {}
+    for exc in exceptions:
+        grouped.setdefault(getattr(exc, "status_code", 500), []).append(exc)
+
+    for status_code, group in grouped.items():
+        description = ""
+        schemas: list[Schema] = []
+        for exc in group:
+            detail = getattr(exc, "detail", None) or _status_phrase(status_code)
+            description = description or getattr(exc, "detail", None) or ""
+            schemas.append(_error_schema(exc, status_code, detail, domain, location_type, location))
+
+        schema = schemas[0] if len(schemas) == 1 else Schema(one_of=schemas)
+        yield (
+            str(status_code),
+            OpenAPIResponse(
+                description=description or _status_description(status_code),
+                content={MediaType.JSON: OpenAPIMediaType(schema=schema)},
+            ),
+        )

litestar_google_errors/plugin.py

@@ -0,0 +1,41 @@
+"""Litestar plugin wiring the Google error schema into OpenAPI generation."""
+
+from __future__ import annotations
+
+from functools import partial
+
+import litestar._openapi.responses as response_factory
+from litestar.config.app import AppConfig
+from litestar.plugins import InitPlugin
+
+from litestar_google_errors.openapi import create_error_responses
+
+__all__ = ("GoogleErrorResponsesPlugin",)
+
+
+class GoogleErrorResponsesPlugin(InitPlugin):
+    """Render ``HTTPException`` responses in the OpenAPI schema using the Google JSON error format.
+
+    Litestar has no public hook for error response schemas, so the plugin replaces
+    ``litestar._openapi.responses.create_error_responses``. The replacement is process-wide.
+    """
+
+    def __init__(
+        self,
+        *,
+        domain: str = "global",
+        location_type: str = "endpoint",
+        example_location: str = "/example",
+    ) -> None:
+        self.domain = domain
+        self.location_type = location_type
+        self.example_location = example_location
+
+    def on_app_init(self, app_config: AppConfig) -> AppConfig:
+        response_factory.create_error_responses = partial(  # type: ignore[assignment]
+            create_error_responses,
+            domain=self.domain,
+            location_type=self.location_type,
+            location=self.example_location,
+        )
+        return app_config

litestar_google_errors-0.1.1.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: litestar-google-errors
+Version: 0.1.1
+Summary: Litestar plugin for Google JSON style error responses in OpenAPI (Swagger) schemas, with typed msgspec error models
+Project-URL: Homepage, https://github.com/alexkorolex/litestar-google-errors
+Project-URL: Repository, https://github.com/alexkorolex/litestar-google-errors
+Project-URL: Issues, https://github.com/alexkorolex/litestar-google-errors/issues
+Author: alexkorolex
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,error-handling,errors,google-json-style,http-exception,json-api,litestar,litestar-plugin,msgspec,openapi,rest-api,swagger
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Litestar
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: litestar<3,>=2.16
+Description-Content-Type: text/markdown
+
+# litestar-google-errors
+
+[![PyPI](https://img.shields.io/pypi/v/litestar-google-errors.svg)](https://pypi.org/project/litestar-google-errors/)
+[![Python versions](https://img.shields.io/pypi/pyversions/litestar-google-errors.svg)](https://pypi.org/project/litestar-google-errors/)
+[![CI](https://github.com/alexkorolex/litestar-google-errors/actions/workflows/ci.yml/badge.svg)](https://github.com/alexkorolex/litestar-google-errors/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/alexkorolex/litestar-google-errors/blob/main/LICENSE)
+
+**Google JSON style error responses for [Litestar](https://litestar.dev) OpenAPI.**
+
+`litestar-google-errors` is a Litestar plugin that documents `HTTPException` error responses in
+the OpenAPI (Swagger) schema using the
+[Google JSON Style Guide](https://google.github.io/styleguide/jsoncstyleguide.xml#error) error
+format, instead of Litestar's default `{"status_code", "detail", "extra"}` body. It also ships
+typed `msgspec` models to return the same error shape from your API at runtime.
+
+## Features
+
+- Documents error responses in the OpenAPI schema using the Google JSON error format
+- Covers every exception listed in a route handler's `raises=[...]`
+- Combines exceptions that share an HTTP status code with `oneOf`
+- Lets you configure the example `domain`, `locationType` and `location`
+- Ships typed `msgspec` models (`GoogleErrorResponse`, `GoogleError`, `GoogleErrorItem`) for runtime error bodies
+- Includes `py.typed` for type checkers
+- Supports Python 3.10+ and Litestar 2.16+
+
+## Litestar error format: before and after
+
+Litestar's default error body:
+
+```json
+{
+  "status_code": 404,
+  "detail": "Order not found"
+}
+```
+
+Google JSON style error body, as documented by this plugin:
+
+```json
+{
+  "error": {
+    "code": 404,
+    "message": "Order not found",
+    "errors": [
+      {
+        "domain": "global",
+        "reason": "OrderNotFound",
+        "message": "Order not found",
+        "locationType": "endpoint",
+        "location": "/example"
+      }
+    ]
+  }
+}
+```
+
+## Installation
+
+```bash
+pip install litestar-google-errors
+# or
+uv add litestar-google-errors
+```
+
+## Quick start
+
+Register the plugin on your Litestar app:
+
+```python
+from litestar import Litestar
+from litestar_google_errors import GoogleErrorResponsesPlugin
+
+app = Litestar(
+    route_handlers=[...],
+    plugins=[GoogleErrorResponsesPlugin()],
+)
+```
+
+Every exception listed in a handler's `raises=[...]` appears in the OpenAPI schema in the Google
+format. Exceptions that share a status code are combined with `oneOf`.
+
+### Configure the OpenAPI examples
+
+```python
+GoogleErrorResponsesPlugin(domain="orders", location_type="path", example_location="/orders/1")
+```
+
+### Return Google-style errors at runtime
+
+The plugin only changes the **OpenAPI documentation**. To return the same JSON error shape from
+your API, use the bundled `msgspec` models in a Litestar exception handler:
+
+```python
+from litestar import MediaType, Request, Response
+from litestar.exceptions import HTTPException
+from litestar_google_errors import GoogleError, GoogleErrorItem, GoogleErrorResponse, LocationType
+
+
+def http_exception_handler(request: Request, exc: HTTPException) -> Response[GoogleErrorResponse]:
+    body = GoogleErrorResponse(
+        error=GoogleError(
+            code=exc.status_code,
+            message=exc.detail,
+            errors=[
+                GoogleErrorItem(
+                    domain="global",
+                    reason=type(exc).__name__,
+                    message=exc.detail,
+                    locationType=LocationType.ENDPOINT,
+                    location=request.url.path,
+                )
+            ],
+        )
+    )
+    return Response(body, status_code=exc.status_code, media_type=MediaType.JSON)
+
+
+app = Litestar(
+    route_handlers=[...],
+    plugins=[GoogleErrorResponsesPlugin()],
+    exception_handlers={HTTPException: http_exception_handler},
+)
+```
+
+## Limitations
+
+Litestar has no public hook for error response schemas, so the plugin replaces the private
+`litestar._openapi.responses.create_error_responses` function. The replacement is process-wide,
+and the dependency is pinned to `litestar<3` because that internal may change.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv build
+```
+
+## License
+
+[MIT](https://github.com/alexkorolex/litestar-google-errors/blob/main/LICENSE)

litestar_google_errors-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+litestar_google_errors/__init__.py,sha256=OS34sKiHpi8URg4WoDzZ7hZy4WZ-w9fDXBdinO4FQ4o,409
+litestar_google_errors/models.py,sha256=0rgugNUDxozbrRZCOdy_DisLZNXU_NU2UYIbqBccxbM,785
+litestar_google_errors/openapi.py,sha256=IYwtacsRJiwsRcW8WdAsraie2xWOwFi6X1PGpY9qL4s,3947
+litestar_google_errors/plugin.py,sha256=Ck_vWWDx28aTDH2Uv3VP1xzTwG-7lc2O3l81-Xs6aHY,1368
+litestar_google_errors/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+litestar_google_errors-0.1.1.dist-info/METADATA,sha256=i_cqEUFi5ZnFQDYA7WKbXwGdvSoZq0551N2xYctdD9M,5693
+litestar_google_errors-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+litestar_google_errors-0.1.1.dist-info/licenses/LICENSE,sha256=BJKFz45zVBAQfQYAtSP__R4P5-xxJJx5QLK8_2IArSE,1068
+litestar_google_errors-0.1.1.dist-info/RECORD,,

litestar_google_errors-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

litestar_google_errors-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alexkorolex
+
+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.