awesome-errors 0.3.0__tar.gz

awesome_errors-0.3.0/.gitignore

@@ -0,0 +1,118 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+debug.log
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+*.local.*
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pyright
+pyrightconfig.json
+
+# VS Code
+.vscode/
+
+# Ruff
+.ruff_cache/
+
+# System files
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+test-results/
+
+# Locales cache
+src/awesome_errors/i18n/locales/empty/
+
+# Examples cache
+examples/locales/en/empty/
+examples/locales/uk/empty/ 

awesome_errors-0.3.0/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.

awesome_errors-0.3.0/PKG-INFO

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

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

@@ -0,0 +1,74 @@
+[project]
+name = "awesome-errors"
+version = "0.3.0"
+description = "A comprehensive error handling library for Python applications with i18n support"
+authors = [{ name = "THEROER", email = "theroer09@gmail.com" }]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10,<4"
+keywords = ["error-handling", "exceptions", "i18n", "fastapi", "litestar"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "msgspec>=0.21.0,<0.22",
+]
+
+[project.optional-dependencies]
+sqlalchemy = [
+    "sqlalchemy>=2.0,<3",
+]
+litestar = [
+    "litestar>=2.21.1,<3",
+]
+fastapi = [
+    "fastapi>=0.115.14,<0.116",
+    "pydantic[email]>=2.0,<3",
+]
+pydantic = [
+    "pydantic[email]>=2.0,<3",
+]
+all = [
+    "sqlalchemy>=2.0,<3",
+    "litestar>=2.21.1,<3",
+    "fastapi>=0.115.14,<0.116",
+    "pydantic[email]>=2.0,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/THEROER/awesome-errors"
+Repository = "https://github.com/THEROER/awesome-errors"
+Issues = "https://github.com/THEROER/awesome-errors/issues"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.2,<10",
+    "pytest-cov>=4.0,<5",
+    "pytest-asyncio>=1.3.0,<2",
+    "black>=23.0,<24",
+    "mypy>=1.0,<2",
+    "httpx>=0.28.1,<1",
+    "ruff>=0.15.5,<0.16",
+    "fastapi>=0.115.14,<0.116",
+    "pydantic[email]>=2.0,<3",
+    "sqlalchemy>=2.0,<3",
+    "litestar>=2.21.1,<3",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/awesome_errors"]
+
+[tool.hatch.build.targets.wheel]
+include = ["src/awesome_errors"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/awesome_errors" = "awesome_errors"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"