litestar-google-errors 0.1.1__tar.gz

litestar_google_errors-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uvx twine check --strict dist/*

litestar_google_errors-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Check tag matches project version
+        run: |
+          version=$(uv version --short)
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "${tag}" != "${version}" ]; then
+            echo "::error::Release tag ${GITHUB_REF_NAME} does not match project version ${version} in pyproject.toml"
+            exit 1
+          fi
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/litestar-google-errors
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  upload-release-assets:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Attach distributions to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --clobber

litestar_google_errors-0.1.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/

litestar_google_errors-0.1.1/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.

litestar_google_errors-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "litestar-google-errors"
+version = "0.1.1"
+description = "Litestar plugin for Google JSON style error responses in OpenAPI (Swagger) schemas, with typed msgspec error models"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "alexkorolex" }]
+keywords = [
+    "litestar",
+    "litestar-plugin",
+    "openapi",
+    "swagger",
+    "errors",
+    "error-handling",
+    "http-exception",
+    "google-json-style",
+    "json-api",
+    "msgspec",
+    "asgi",
+    "rest-api",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Litestar",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = ["litestar>=2.16,<3"]
+
+[project.urls]
+Homepage = "https://github.com/alexkorolex/litestar-google-errors"
+Repository = "https://github.com/alexkorolex/litestar-google-errors"
+Issues = "https://github.com/alexkorolex/litestar-google-errors/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "httpx>=0.27"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/litestar_google_errors"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

litestar_google_errors-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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)},
+            ),
+        )