apierrors

Name	apierrors JSON
Version	0.0.5 JSON
	download
home_page	None
Summary	Transport-agnostic, typed error DTOs and envelopes for APIs
upload_time	2025-10-14 18:18:51
maintainer	None
docs_url	None
author	None
requires_python	>=3.11
license	MIT License Copyright (c) 2025 ArtemTaU 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.
keywords	errors api http status-codes fastapi exceptions
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # apierrors

_Transport-agnostic, typed error DTOs and envelopes for APIs._
Use the same domain error objects across HTTP, gRPC, GraphQL, WebSocket, JSON-RPC, 
and message queues—with first-class support for HTTP out of the box and 
a 422 format compatible with FastAPI.

---
 
## Why

Framework built-ins (e.g., `HTTPException`) are convenient but **hard-wire 
errors to one transport**. `apierrors` keeps your domain errors independent 
and **adds thin adapters per transport**. Your handlers build rich, typed errors; 
adapters serialize them for the wire.

---

### Features

- **Typed DTOs:** `Err400/401/403/404/405/409/422/...` with critical fields (e.g., 
`loc` for 422, `allowed_methods` for 405, `permission` for 403).
- **Transport-agnostic core:** domain errors don’t depend on HTTP.
- **HTTP envelopes:** `HttpErrorEnvelope[T]` with `status_code`, optional `headers`.
- **FastAPI-style 422:** `Err422` supports `loc`, `error_type` (aka type), `ctx`, `message` (aka msg).
- **Consistent JSON:** stable shape for clients & SDKs.
- **Headers helpers:** easy `WWW-Authenticate`, `Allow`, Retry-`After`.
- **Adapters (extensible):** examples for gRPC, GraphQL, WS.

---

### Install
```commandline
pip install apierrors
```

Python 3.11+.

---

### Why not just `HTTPException` (FastAPI / Starlette)?

| Aspect                   | `HTTPException`      | **apierrors**                                                     |
| ------------------------ | -------------------- |-------------------------------------------------------------------|
| Transport                | HTTP-only            | Transport-agnostic domain errors + HTTP adapter                   |
| Typing/DTOs              | Message + status     | Rich typed DTOs per status (401, 403, 405, 409, 422…)             |
| 422 details              | Framework-controlled | Explicit `loc`/`error_type`/`ctx`, same across transports         |
| Headers                  | Manual, ad-hoc       | DTO fields + helper factories (e.g., `Allow`, `WWW-Authenticate`) |
| Reuse in gRPC/GraphQL/WS | No                   | Yes, via adapters                                                 |
| Client SDKs              | Ad-hoc parsing       | Stable JSON shapes for codegen/SDKs                               |
| Testability              | Inspect exception    | Assert on DTO fields & envelopes                                  |

**Bottom line**: keep domain errors independent; adapt once per transport.

---

### Comparison to other libs

- **Starlette / FastAPI exceptions**: great for quick HTTP flows but hard-wire 
transport and shape; 422 format depends on framework internals. `apierrors` 
gives you the same clarity for 422 while remaining cross-transport.
- **DRF APIException / Marshmallow errors**: framework-centric, tightly coupled
to serializers/validators. `apierrors` can ingest their outputs and 
produce a consistent cross-transport error shape.
- **Werkzeug/HTTPX exceptions**: HTTP-only and less prescriptive about rich detail.

---

### Best practices

- **Build domain errors, not responses.** Keep HTTP concerns at the edge.
- **Use specific DTOs.** Prefer `Err403(resource=..., action=..., permission=...) `over a generic message.
- **422 consistently**. Use loc paths identical to your validator (`("body","items",0,"price")`).
- **Set headers via envelope**. Mirror DTO fields into `headers` (e.g., `Allow`).
- **Log** `request_id`. Populate for traceability; ship `timestamp` automatically.

---

# Roadmap

- More transports & adapters
  - gRPC error details (`google.rpc.BadRequest` / `ErrorInfo`)
  - GraphQL `extensions` & Apollo format
  - JSON-RPC 2.0 (`code`/`message`/`data`)
  - WebSocket/SSE payloads & close codes
  - Message buses (Kafka/RabbitMQ) error envelopes
- RFC7807 adapter (Problem Details) with per-status extensions
- Pydantic & Marshmallow bridges (auto-convert validation errors → `Err422`)
- i18n: message translation hooks
- Retry semantics: helpers for `Retry-After`, backoff hints
- Codegen: JSON Schema for errors to power SDKs
- 5xx suite: `Err500`..`Err504` with incident/trace fields

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "apierrors",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "errors, api, http, status-codes, fastapi, exceptions",
    "author": null,
    "author_email": "Artem Tilhanovskii <tikhanovskii.artem@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/f0/54/d727878bb50332d1a464281bd4df47b9ce530f08e1f7ab416b2e88716ddf/apierrors-0.0.5.tar.gz",
    "platform": null,
    "description": "# apierrors\r\n\r\n_Transport-agnostic, typed error DTOs and envelopes for APIs._\r\nUse the same domain error objects across HTTP, gRPC, GraphQL, WebSocket, JSON-RPC, \r\nand message queues\u2014with first-class support for HTTP out of the box and \r\na 422 format compatible with FastAPI.\r\n\r\n---\r\n \r\n## Why\r\n\r\nFramework built-ins (e.g., `HTTPException`) are convenient but **hard-wire \r\nerrors to one transport**. `apierrors` keeps your domain errors independent \r\nand **adds thin adapters per transport**. Your handlers build rich, typed errors; \r\nadapters serialize them for the wire.\r\n\r\n---\r\n\r\n### Features\r\n\r\n- **Typed DTOs:** `Err400/401/403/404/405/409/422/...` with critical fields (e.g., \r\n`loc` for 422, `allowed_methods` for 405, `permission` for 403).\r\n- **Transport-agnostic core:** domain errors don\u2019t depend on HTTP.\r\n- **HTTP envelopes:** `HttpErrorEnvelope[T]` with `status_code`, optional `headers`.\r\n- **FastAPI-style 422:** `Err422` supports `loc`, `error_type` (aka type), `ctx`, `message` (aka msg).\r\n- **Consistent JSON:** stable shape for clients & SDKs.\r\n- **Headers helpers:** easy `WWW-Authenticate`, `Allow`, Retry-`After`.\r\n- **Adapters (extensible):** examples for gRPC, GraphQL, WS.\r\n\r\n---\r\n\r\n### Install\r\n```commandline\r\npip install apierrors\r\n```\r\n\r\nPython 3.11+.\r\n\r\n---\r\n\r\n### Why not just `HTTPException` (FastAPI / Starlette)?\r\n\r\n| Aspect                   | `HTTPException`      | **apierrors**                                                     |\r\n| ------------------------ | -------------------- |-------------------------------------------------------------------|\r\n| Transport                | HTTP-only            | Transport-agnostic domain errors + HTTP adapter                   |\r\n| Typing/DTOs              | Message + status     | Rich typed DTOs per status (401, 403, 405, 409, 422\u2026)             |\r\n| 422 details              | Framework-controlled | Explicit `loc`/`error_type`/`ctx`, same across transports         |\r\n| Headers                  | Manual, ad-hoc       | DTO fields + helper factories (e.g., `Allow`, `WWW-Authenticate`) |\r\n| Reuse in gRPC/GraphQL/WS | No                   | Yes, via adapters                                                 |\r\n| Client SDKs              | Ad-hoc parsing       | Stable JSON shapes for codegen/SDKs                               |\r\n| Testability              | Inspect exception    | Assert on DTO fields & envelopes                                  |\r\n\r\n**Bottom line**: keep domain errors independent; adapt once per transport.\r\n\r\n---\r\n\r\n### Comparison to other libs\r\n\r\n- **Starlette / FastAPI exceptions**: great for quick HTTP flows but hard-wire \r\ntransport and shape; 422 format depends on framework internals. `apierrors` \r\ngives you the same clarity for 422 while remaining cross-transport.\r\n- **DRF APIException / Marshmallow errors**: framework-centric, tightly coupled\r\nto serializers/validators. `apierrors` can ingest their outputs and \r\nproduce a consistent cross-transport error shape.\r\n- **Werkzeug/HTTPX exceptions**: HTTP-only and less prescriptive about rich detail.\r\n\r\n---\r\n\r\n### Best practices\r\n\r\n- **Build domain errors, not responses.** Keep HTTP concerns at the edge.\r\n- **Use specific DTOs.** Prefer `Err403(resource=..., action=..., permission=...) `over a generic message.\r\n- **422 consistently**. Use loc paths identical to your validator (`(\"body\",\"items\",0,\"price\")`).\r\n- **Set headers via envelope**. Mirror DTO fields into `headers` (e.g., `Allow`).\r\n- **Log** `request_id`. Populate for traceability; ship `timestamp` automatically.\r\n\r\n---\r\n\r\n# Roadmap\r\n\r\n- More transports & adapters\r\n  - gRPC error details (`google.rpc.BadRequest` / `ErrorInfo`)\r\n  - GraphQL `extensions` & Apollo format\r\n  - JSON-RPC 2.0 (`code`/`message`/`data`)\r\n  - WebSocket/SSE payloads & close codes\r\n  - Message buses (Kafka/RabbitMQ) error envelopes\r\n- RFC7807 adapter (Problem Details) with per-status extensions\r\n- Pydantic & Marshmallow bridges (auto-convert validation errors \u2192 `Err422`)\r\n- i18n: message translation hooks\r\n- Retry semantics: helpers for `Retry-After`, backoff hints\r\n- Codegen: JSON Schema for errors to power SDKs\r\n- 5xx suite: `Err500`..`Err504` with incident/trace fields\r\n",
    "bugtrack_url": null,
    "license": "MIT License\r\n        \r\n        Copyright (c) 2025 ArtemTaU\r\n        \r\n        Permission is hereby granted, free of charge, to any person obtaining a copy\r\n        of this software and associated documentation files (the \"Software\"), to deal\r\n        in the Software without restriction, including without limitation the rights\r\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n        copies of the Software, and to permit persons to whom the Software is\r\n        furnished to do so, subject to the following conditions:\r\n        \r\n        The above copyright notice and this permission notice shall be included in all\r\n        copies or substantial portions of the Software.\r\n        \r\n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n        SOFTWARE.\r\n        ",
    "summary": "Transport-agnostic, typed error DTOs and envelopes for APIs",
    "version": "0.0.5",
    "project_urls": {
        "Homepage": "https://github.com/ArtemTaU/apierrors",
        "Issues": "https://github.com/ArtemTaU/apierrors/issues"
    },
    "split_keywords": [
        "errors",
        " api",
        " http",
        " status-codes",
        " fastapi",
        " exceptions"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "47ce62d7f67d2ee31c131a4b48a729c9c5b4212e907242406296b0bd42a57cac",
                "md5": "9d49f14665c865de6849fb47caeaefdc",
                "sha256": "8fb8821bba6781ede415466862428e9bf6786324fdbdb8a5f199f4ef7298a0ac"
            },
            "downloads": -1,
            "filename": "apierrors-0.0.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9d49f14665c865de6849fb47caeaefdc",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 15621,
            "upload_time": "2025-10-14T18:18:50",
            "upload_time_iso_8601": "2025-10-14T18:18:50.815687Z",
            "url": "https://files.pythonhosted.org/packages/47/ce/62d7f67d2ee31c131a4b48a729c9c5b4212e907242406296b0bd42a57cac/apierrors-0.0.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "f054d727878bb50332d1a464281bd4df47b9ce530f08e1f7ab416b2e88716ddf",
                "md5": "28530b455cd0bf41ee93388ac4c3d536",
                "sha256": "031795dc2505b8d8665af7fa86d2a7d6e3f1a7be1af873557df0aaf112a3d137"
            },
            "downloads": -1,
            "filename": "apierrors-0.0.5.tar.gz",
            "has_sig": false,
            "md5_digest": "28530b455cd0bf41ee93388ac4c3d536",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 12750,
            "upload_time": "2025-10-14T18:18:51",
            "upload_time_iso_8601": "2025-10-14T18:18:51.743960Z",
            "url": "https://files.pythonhosted.org/packages/f0/54/d727878bb50332d1a464281bd4df47b9ce530f08e1f7ab416b2e88716ddf/apierrors-0.0.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-14 18:18:51",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "ArtemTaU",
    "github_project": "apierrors",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "apierrors"
}