Awesome Errors
A comprehensive Python library for standardized error handling, analysis, and documentation.
Architecture Overview
Core Components
1. Core Exceptions (src/awesome_errors/core/)
- AppError: Base exception class for server-side error handling
- ValidationError: HTTP 400 errors for input validation failures
- AuthError: HTTP 401/403 errors for authentication/authorization
- NotFoundError: HTTP 404 errors for missing resources
- DatabaseError: HTTP 500/409/422 errors for database issues
- BusinessLogicError: HTTP 422 errors for business rule violations
2. Client Exceptions (src/awesome_errors/client/)
- BackendError: Client-side exception for handling server responses
- ErrorResponseParser: Parser for backend error responses
Key Difference: Core exceptions are raised on the server, while client exceptions handle errors received from the server.
3. Error Converters (src/awesome_errors/converters/)
- UniversalErrorConverter: Handles any type of exception
- SQLErrorConverter: Converts SQLAlchemy errors
- PythonErrorConverter: Converts standard Python exceptions
- PydanticErrorConverter: Converts Pydantic validation errors
- generic_error_handler: Shared logic for unknown errors
4. Analysis Tools (src/awesome_errors/analysis/)
- ErrorAnalyzer: AST-based error analysis
- analyze_errors: Decorator for automatic error analysis
- openapi_errors: Decorator for OpenAPI documentation
5. HTTP Response Renderers (src/awesome_errors/core/renderers.py)
- ErrorResponseRenderer: Produces either legacy envelopes or RFC 7807 documents
- ErrorResponseFormat: Toggle between response formats per application
6. Framework Integrations (src/awesome_errors/middleware/)
- FastAPI middleware:
setup_error_handling - Litestar handlers:
create_litestar_exception_handlers - Both integrations share their translation, logging, and exception-mapping
logic via
middleware/_base.py.
7. Internationalization (src/awesome_errors/i18n/)
- ErrorTranslator: Multi-language error message support
- English defaults are built in; additional locales load from
src/awesome_errors/i18n/locales/(importing the library never writes to disk)
Usage Examples
Server-Side Error Handling
from awesome_errors import ValidationError, NotFoundError, ErrorCode
# Validation error
raise ValidationError("Email is required", field="email")
# Not found error
raise NotFoundError("user", user_id=123)
# Custom error code
raise ValidationError("Invalid format", code=ErrorCode("CUSTOM_ERROR"))
Client-Side Error Handling
from awesome_errors import BackendError
try:
response = api_client.get_user(123)
except BackendError as e:
if e.is_not_found_error():
print("User not found")
elif e.is_validation_error():
print("Invalid input")
FastAPI Integration
from fastapi import FastAPI
from awesome_errors import setup_error_handling, auto_analyze_errors
app = FastAPI()
setup_error_handling(app)
@auto_analyze_errors
@app.get("/users/{user_id}")
def get_user(user_id: int):
if user_id == 404:
raise NotFoundError("user", user_id)
return {"id": user_id}
Litestar Integration
from litestar import Litestar
from awesome_errors import (
ErrorResponseFormat,
ErrorTranslator,
create_litestar_exception_handlers,
)
translator = ErrorTranslator(default_locale="en")
translator.add_translations("en", {"CUSTOM": "Custom error"}, persist=False)
exception_handlers = create_litestar_exception_handlers(
translator=translator,
response_format=ErrorResponseFormat.RFC7807,
problem_type_resolver=lambda err: f"urn:demo:error:{err.code.value.lower()}",
)
app = Litestar(route_handlers=[...], exception_handlers=exception_handlers)
Error Analysis
from awesome_errors import analyze_errors, openapi_errors
@analyze_errors()
def my_function():
raise ValidationError("Test error")
@openapi_errors(additional_errors=["CUSTOM_ERROR"])
def my_api_endpoint():
# Automatically documented in OpenAPI
pass
Key Features
✅ Unified Error Models
- Lightweight msgspec structs used across server & client sides
- Single serialization layer for legacy and RFC 7807 formats
- Consistent error structure
✅ Shared Generic Error Handling
- Common
generic_error_handlerfor unknown errors - Used by all converters to avoid code duplication
- Debug mode support for detailed error information
✅ Consolidated FastAPI Integration
- Single entry point for all FastAPI integrations
- Automatic OpenAPI documentation generation
- Combined analysis and documentation decorators
✅ Clean Architecture
- Clear separation between server and client error handling
- Modular converter system
- Pluggable renderers for multiple frameworks
✅ Internationalization Support
- Multi-language error messages
- Locale-based translation
- Template parameter support
- Optional persistence when extending translations at runtime
Installation
pip install awesome-errors
Development
# Install dependencies
uv sync --dev
# Run tests
uv run pytest
# Run linting
uv run ruff check src/
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
MIT License - see LICENSE file for details.
Metadata
Release files for awesome-errors 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| awesome_errors-0.4.0.tar.gz | 36.7 kB | Without provenance | Details for awesome_errors-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| awesome_errors-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for awesome_errors-0.4.0-py3-none-any.whl |
Total release size: 87.8 kB
Release files / awesome_errors-0.4.0.tar.gz
| Download URL | awesome_errors-0.4.0.tar.gz |
|---|---|
| Size | 36.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5b783c1c01e39b30e9ca2b9231788b334d135e6dc9a44461fdb79933318e5e8b
|
|
BLAKE2b-256 checksum How to use checksums |
a20cbdbb2a7f1dada68fcadadc0c342bca6397e48702aece8347d715bdce1424
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / awesome_errors-0.4.0-py3-none-any.whl
| Download URL | awesome_errors-0.4.0-py3-none-any.whl |
|---|---|
| Size | 51.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36bc93cecf05d2113afc16b056adfff4fc8d87490902edba955592c362b9eaeb
|
|
BLAKE2b-256 checksum How to use checksums |
6e99a516b113b27435ce8808552d90b657c261858015f35c2d418734ea962110
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for awesome-errors 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.