awesome-errors 0.3.0__py3-none-any.whl

awesome_errors-0.3.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: awesome-errors
+Version: 0.3.0
+Summary: A comprehensive error handling library for Python applications with i18n support
+Project-URL: Homepage, https://github.com/THEROER/awesome-errors
+Project-URL: Repository, https://github.com/THEROER/awesome-errors
+Project-URL: Issues, https://github.com/THEROER/awesome-errors/issues
+Author-email: THEROER <theroer09@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: error-handling,exceptions,fastapi,i18n,litestar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.10
+Requires-Dist: msgspec<0.22,>=0.21.0
+Provides-Extra: all
+Requires-Dist: fastapi<0.116,>=0.115.14; extra == 'all'
+Requires-Dist: litestar<3,>=2.21.1; extra == 'all'
+Requires-Dist: pydantic[email]<3,>=2.0; extra == 'all'
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'all'
+Provides-Extra: fastapi
+Requires-Dist: fastapi<0.116,>=0.115.14; extra == 'fastapi'
+Requires-Dist: pydantic[email]<3,>=2.0; extra == 'fastapi'
+Provides-Extra: litestar
+Requires-Dist: litestar<3,>=2.21.1; extra == 'litestar'
+Provides-Extra: pydantic
+Requires-Dist: pydantic[email]<3,>=2.0; extra == 'pydantic'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy<3,>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# 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`
+
+#### 6. **Internationalization** (`src/awesome_errors/i18n/`)
+
+- **ErrorTranslator**: Multi-language error message support
+- Locale files in `src/awesome_errors/i18n/locales/`
+
+#### 7. **Middleware** (`src/awesome_errors/middleware/`)
+
+- **setup_error_handling**: FastAPI error handling middleware
+
+## Usage Examples
+
+### Server-Side Error Handling
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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_handler` for 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
+
+```bash
+pip install awesome-errors
+```
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Run linting
+uv run ruff check src/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.

awesome_errors-0.3.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+awesome_errors/__init__.py,sha256=JseznpKN9GGclhG1u1NDbot_vkQiit9nzHJzb_BUGZk,7795
+awesome_errors/litestar_utils.py,sha256=FOEmwQNAwFvRAIIQJ4tSHOfifmWSjFh2SEEd53xlWz0,1765
+awesome_errors/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+awesome_errors/analysis/__init__.py,sha256=Yk2xHQKZfi6n9qOVkx59paVLKUvgdNOSvU1StAacw5s,177
+awesome_errors/analysis/decorators.py,sha256=qtBisesbukim5KmGQjdDmwCKo0z32fpFeT9vHj3SM_s,8607
+awesome_errors/analysis/error_analyzer.py,sha256=aIIMTubtb9PoQJxcaZaNvrEUw-9IjHIb8GlHaavKn7U,17122
+awesome_errors/client/__init__.py,sha256=5prGsahGFMH_Ld-EPhdR2c_QvSB8sZ4U6-H5NKtL55k,148
+awesome_errors/client/exceptions.py,sha256=ZEspKS7tHWxfVlFPzDffPQS7RS-gr0PiLfVuJrmfo6k,2999
+awesome_errors/client/response_parser.py,sha256=Xd1ZvdFN4o2xbG6Yy99aUIFH1p-oamI6WrAUIlt4yeI,5829
+awesome_errors/converters/__init__.py,sha256=Dm52R-BJRQTtnHmah4ToO6uPqPOsB97zUGKRhbY4CoQ,944
+awesome_errors/converters/generic.py,sha256=oiCLd25YRQTIaW7V4yEMSj0cmzUJ4JkfFoUnjRPR2TY,773
+awesome_errors/converters/pydantic_converter.py,sha256=i-QH2ZOOAZg8wT3SfVY5yZ1jy2iqHA1jg_jFoY0zcL0,2558
+awesome_errors/converters/python_converter.py,sha256=eGRbMR2D27rz-0I6R1nZhBVdOtUN9X5-NmM96K3rf54,3264
+awesome_errors/converters/sql_converter.py,sha256=zYaRBmewb-22Kg3_U3m3kiiMY6tVM5jy6TI109517RA,9210
+awesome_errors/converters/universal_converter.py,sha256=Kgv5RTDZenxptLUM4lNYn6GYeFIR65b7LeaR_3gf1b4,4186
+awesome_errors/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+awesome_errors/core/error_codes.py,sha256=nSigfn8jv7SKdcIsziyPkXUFMD4TLOpARvxtzRZzlmo,3629
+awesome_errors/core/error_response.py,sha256=uIkkdNlGgNM3lh_sdoSzeAtC7QC04lgBEL0rYR407kM,1997
+awesome_errors/core/exceptions.py,sha256=YWOIlg3BAKobAXAXwuw5jlDkUMzxbSFIoOwYDD507TA,20017
+awesome_errors/core/renderers.py,sha256=8pGVvTwZ4f0lLF2jqWKKJlCPY78QmdUg6Nzsnci9pNE,3372
+awesome_errors/i18n/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+awesome_errors/i18n/translator.py,sha256=3BmQUA-zihcbNC4GfSvi8tg2qPIFbsbgRo0MPdLkBO8,5728
+awesome_errors/i18n/locales/en/errors.json,sha256=srm5S_30DUrPa-cAYdeEHleSCtL-EUnJ4yW_xCkliSU,1484
+awesome_errors/i18n/locales/test/errors.json,sha256=UJ6fNqEhQNZ5CR47LeA8oUJN5pB9BG1pdiSLt_U76Zg,143
+awesome_errors/i18n/locales/uk/errors.json,sha256=8JutDgqx9QDv-QF5Y5WDfgmeN6ocKZrzarVG1bMcNEo,1727
+awesome_errors/integrations/__init__.py,sha256=FoloNy-8vdJg3OWqsoGrMLiAtJDhre7RVX1hCu5YKKM,244
+awesome_errors/integrations/fastapi_auto_docs.py,sha256=ph7Q7-zgkhWTcoNabHdTTOaVBIe-_0qZXZ9WoI3Qr80,8183
+awesome_errors/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+awesome_errors/middleware/fastapi.py,sha256=6PS5WGIXTFkht2vruVi9g_ByM1ZEOW1Jw56G1H4NlLM,8728
+awesome_errors/middleware/litestar.py,sha256=9w7hW_SNr3bUKwij9uiyg8qDmk6TyF6MDsQttRmQiuU,12252
+awesome_errors/websocket/__init__.py,sha256=4JcGSF3o8rLLdINWPl6_QQ_BxAAk1Gm0eXOIasq51Eg,806
+awesome_errors/websocket/error_handler.py,sha256=FWHi_ROBTGcp5h2m-U8wxxX5r9lPHV4DQOpBHlzxsSY,8413
+awesome_errors/websocket/exceptions.py,sha256=pg95MZEbyN_TMgl6Rm7TFL6iLAOpl4mM0gJ95iOslHI,9853
+awesome_errors-0.3.0.dist-info/METADATA,sha256=BgJFOvcw5WUa3_5CpVKTJAEmHZJN-9PWc3kfmn1pG84,6967
+awesome_errors-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+awesome_errors-0.3.0.dist-info/licenses/LICENSE,sha256=x32be04GnNO7nJ-rLN10jombmqZkbnJFrBjgzQI6fhk,1064
+awesome_errors-0.3.0.dist-info/RECORD,,

awesome_errors-0.3.0.dist-info/WHEEL

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

awesome_errors-0.3.0.dist-info/licenses/LICENSE

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