global-handler 0.1.0__py3-none-any.whl

global_handler/decorators/error_handler.py

@@ -0,0 +1,55 @@
+
+from src.controllers.base_controller import BaseController
+from src.global_handler.exceptions.http_exceptions import HttpError
+from logger_tracker import logger, _request_uuid
+from src.config import DEBUG
+
+
+def register_error_handlers(app):
+    base_controller = BaseController()
+
+    @app.errorhandler(HttpError)
+    def handle_http_error(error: HttpError):
+        request_id = getattr(_request_uuid, "id", None)
+        extra={
+                "status_code": error.status_code,
+                "details": error.details,
+                "request_id": request_id
+            }
+        logger.logg_warning(
+            f"HTTP Error {error.error_code}"
+        )
+        logger.logg_debug(
+            f"HTTP Error details: {extra}"
+        )
+
+        return base_controller.error(
+            message=error.message,
+            details=error.details,
+            status_code=error.status_code,
+            error_code=error.error_code,
+        )
+
+    @app.errorhandler(Exception)
+    def handle_unexpected_error(error: Exception):
+        request_id = getattr(_request_uuid, "id", None)
+        extra={
+                "request_id": request_id,
+                "exception_type": type(error).__name__,
+                "error_details": str(error)
+        },
+        logger.logg_error(
+            "Unhandled exception"
+        )
+        logger.logg_debug(
+            f"Unhandled exception details: {extra}"
+        )
+
+        message = "Internal server error"
+        details = str(error) if DEBUG else None
+
+        return base_controller.error(
+            message=message,
+            details=details,
+            status_code=500
+        )

global_handler/decorators/request_decorators.py

@@ -0,0 +1,118 @@
+from functools import wraps
+from flask import request
+from werkzeug.exceptions import BadRequest
+from pydantic import ValidationError
+
+from logger_tracker import logger
+from src.global_handler.exceptions.http_exceptions import (
+    ValidationHttpError,
+    InvalidJsonHttpError,
+    MissingParameterHttpError,
+    InvalidParameterHttpError,
+)
+
+
+def normalize_validation_errors(exc):
+    """Normalize Pydantic validation errors to a consistent format."""
+    return exc.errors()
+
+
+def validate_with(model):
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            if not request.is_json:
+                raise InvalidJsonHttpError("Request body must be a valid JSON")
+
+            try:
+                validated = model(**request.get_json())
+                return f(validated_data=validated, *args, **kwargs)
+
+            except BadRequest:
+                raise InvalidJsonHttpError("Request body must be a valid JSON")
+
+            except ValidationError as exc:
+                extra = {"errors": exc.errors()}
+                logger.logg_warning(
+                    f"Validation error on {model.__name__}"
+                )
+                logger.logg_debug(
+                    f"Validation error details: {extra}"
+                )
+                logger.logg_info("Aqui estamos")
+                raise ValidationHttpError(normalize_validation_errors(exc))
+
+        return wrapper
+    return decorator
+
+
+def validate_headers_with(model):
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            try:
+                # Convertir headers a dict y validar
+                headers_dict = dict(request.headers)
+                validated = model(**headers_dict)
+                return f(headers_data=validated, *args, **kwargs)
+
+            except ValidationError as exc:
+                extra = {"errors": exc.errors()}
+                logger.logg_warning(
+                    f"Header validation error on {model.__name__}"
+                )
+                logger.logg_debug(
+                    f"Header validation error details: {extra}"
+                )
+                raise ValidationHttpError(normalize_validation_errors(exc))
+
+        return wrapper
+    return decorator
+
+
+def validate_query_with(model):
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            try:
+                validated = model(**request.args.to_dict())
+                return f(query_params=validated, *args, **kwargs)
+
+            except ValidationError as exc:
+                extra = {"errors": exc.errors()}
+                logger.logg_warning(
+                    f"Query validation error on {model.__name__}"
+                )
+                logger.logg_debug(
+                    f"Query validation error details: {extra}"
+                )
+
+                for error in exc.errors():
+                    error_type = error.get("type")
+
+                    if error_type == "missing":
+                        raise MissingParameterHttpError(error)
+
+                    raise InvalidParameterHttpError(error)
+
+                raise ValidationHttpError(exc.errors())
+
+        return wrapper
+    return decorator
+
+def normalize_validation_errors(exc: ValidationError) -> list[dict]:
+    normalized_errors = []
+
+    for err in exc.errors():
+        field = ".".join(str(loc) for loc in err.get("loc", []))
+        error_type = err.get("type")
+
+        normalized_errors.append(
+            {
+                "field": field,
+                "error_type": error_type,
+                "error": err.get("msg"),
+            }
+        )
+
+    return normalized_errors

global_handler/exceptions/http_exceptions.py

@@ -0,0 +1,121 @@
+class HttpError(Exception):
+    status_code: int = 400
+    message: str = "Bad Request"
+    error_code = "BAD_REQUEST"
+
+    def __init__(self, details=None, *, message: str | None = None):
+        self.details = details
+        if message:
+            self.message = message
+        super().__init__(self.message)
+
+# -------------------------
+# Errores 400 Errores del cliente
+# -------------------------
+class BadRequestHttpError(HttpError):
+    status_code = 400
+    message = "Bad request"
+
+class ValidationHttpError(HttpError):
+    status_code = 400
+    message = "Invalid request body"
+    error_code = "VALIDATION_ERROR"
+
+class InvalidJsonHttpError(HttpError):
+    status_code = 400
+    message = "Invalid JSON payload"
+    error_code = "INVALID_JSON"
+
+class MissingParameterHttpError(HttpError):
+    status_code = 400
+    message = "Missing required parameter"
+    error_code = "MISSING_PARAMETER"
+
+class InvalidParameterHttpError(HttpError):
+    status_code = 400
+    message = "Invalid parameter value"
+    error_code = "INVALID_PARAMETER"
+
+# -------------------------
+# Errores 401 Autenticacion
+# -------------------------
+class UnauthorizedHttpError(HttpError):
+    status_code = 401
+    message = "Unauthorized"
+
+
+class InvalidCredentialsHttpError(HttpError):
+    status_code = 401
+    message = "Invalid credentials"
+
+
+class TokenExpiredHttpError(HttpError):
+    status_code = 401
+    message = "Authentication token expired"
+
+# -------------------------
+# Errores 403 Authorizacion
+# -------------------------
+class ForbiddenHttpError(HttpError):
+    status_code = 403
+    message = "Forbidden"
+
+
+class InsufficientPermissionsHttpError(HttpError):
+    status_code = 403
+    message = "Insufficient permissions"
+
+# -------------------------
+# Errores 404 Recurso no encontrado
+# -------------------------
+class NotFoundHttpError(HttpError):
+    status_code = 404
+    message = "Resource not found"
+
+class EndpointNotFoundHttpError(NotFoundHttpError):
+    message = "Endpoint not found"
+
+# -------------------------
+# Errores 409 Conflicto
+# -------------------------
+class ConflictHttpError(HttpError):
+    status_code = 409
+    message = "Conflict"
+
+class ResourceAlreadyExistsHttpError(ConflictHttpError):
+    message = "Resource already exists"
+
+# -------------------------
+# Errores 422 Entidad no procesable
+# -------------------------
+class UnprocessableEntityHttpError(HttpError):
+    status_code = 422
+    message = "Unprocessable entity"
+
+
+class InvalidStateHttpError(UnprocessableEntityHttpError):
+    message = "Invalid resource state"
+
+# -------------------------
+# Errores 429 Rate limit
+# -------------------------
+class TooManyRequestsHttpError(HttpError):
+    status_code = 429
+    message = "Too many requests"
+
+# -------------------------
+# Errores 500 Errores del servidor
+# -------------------------
+class InternalServerHttpError(HttpError):
+    status_code = 500
+    message = "Internal server error"
+
+
+class ServiceUnavailableHttpError(HttpError):
+    status_code = 503
+    message = "Service unavailable"
+
+
+class TimeoutHttpError(HttpError):
+    status_code = 504
+    message = "Gateway timeout"

global_handler/middlewares/metrics_middleware.py

@@ -0,0 +1,32 @@
+import time
+from flask import request, g
+from logger_tracker import logger, _request_uuid
+
+
+def before_request_metrics():
+    g.start_time = time.perf_counter()
+    extra={
+            "query_params": request.args.to_dict(),
+            "request_id": getattr(_request_uuid, "id", None)
+    }
+    
+    logger.logg_info(
+        f"📦 Method: {request.method} Path: {request.path}"
+    )
+    logger.logg_debug(extra)
+
+def after_request_metrics(response):
+    elapsed = time.perf_counter() - g.start_time
+    extra={
+            "request_id": getattr(_request_uuid, "id", None),
+            "method": request.method,
+            "path": request.path,
+            "status_code": response.status_code,
+            "duration_ms": round(elapsed * 1000, 2)
+    }
+    logger.logg_debug(extra)
+    logger.logg_info(
+        "HTTP request completed",
+    )
+
+    return response

global_handler-0.1.0.dist-info/LICENSE

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

global_handler-0.1.0.dist-info/METADATA

@@ -0,0 +1,380 @@
+Metadata-Version: 2.3
+Name: global-handler
+Version: 0.1.0
+Summary: Global Handler es una librería Python diseñada para facilitar el manejo de errores, validaciones de requests y métricas en aplicaciones web
+Author: Damian Gonzalez
+Author-email: damian27goa@gmail.com
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: flask
+Requires-Dist: logger-tracker (==1.0.9)
+Requires-Dist: pydantic
+Description-Content-Type: text/markdown
+
+# Global Handler
+
+## Descripción
+
+Global Handler es una librería Python completa para el manejo robusto de aplicaciones web basadas en Flask. Proporciona herramientas esenciales para validar datos de entrada, gestionar errores de manera elegante, y monitorear el rendimiento de tus endpoints. Diseñada para desarrolladores que buscan una solución integrada y fácil de usar para mejorar la calidad y mantenibilidad de sus APIs REST.
+
+### Características Principales
+
+- **Validación Automática de Requests**: Usa Pydantic para validar JSON, parámetros de query y headers con decoradores simples.
+- **Sistema de Excepciones HTTP Estructurado**: Excepciones personalizadas con códigos de error consistentes y mensajes descriptivos.
+- **Middlewares de Métricas**: Logging automático de requests con tiempos de ejecución y detalles de contexto.
+- **Manejo Global de Errores**: Respuestas de error estandarizadas en formato JSON.
+- **Integración Fluida con Flask**: Diseñado específicamente para aplicaciones Flask, sin configuración compleja.
+
+## Instalación
+
+### Requisitos
+
+- Python 3.13+
+- Flask
+- Pydantic
+
+### Instalación desde PyPI
+
+```bash
+pip install global-handler
+```
+
+### Instalación desde código fuente
+
+```bash
+git clone https://github.com/tu-usuario/global-handler.git
+cd global-handler
+poetry install
+```
+
+## Implementación en una Aplicación Flask
+
+### Configuración Básica
+
+1. **Importa los componentes necesarios:**
+
+```python
+from flask import Flask
+from global_handler.decorators.request_decorators import validate_with, validate_query_with, validate_headers_with
+from global_handler.decorators.error_handler import register_error_handlers
+from global_handler.middlewares.metrics_middleware import before_request_metrics, after_request_metrics
+from global_handler.exceptions.http_exceptions import ValidationHttpError
+from pydantic import BaseModel
+```
+
+2. **Crea tu aplicación Flask:**
+
+```python
+app = Flask(__name__)
+
+# Registra los manejadores de errores
+register_error_handlers(app)
+
+# Registra los middlewares de métricas
+app.before_request(before_request_metrics)
+app.after_request(after_request_metrics)
+```
+
+### Uso de Decoradores de Validación
+
+#### Validación del Cuerpo JSON (`validate_with`)
+
+Valida automáticamente el cuerpo JSON de las requests POST/PUT contra un modelo Pydantic.
+
+```python
+class UserCreateModel(BaseModel):
+    name: str
+    email: str
+    age: int
+
+@app.route('/users', methods=['POST'])
+@validate_with(UserCreateModel)
+def create_user(validated_data):
+    # validated_data es una instancia de UserCreateModel con datos validados
+    user = User(name=validated_data.name, email=validated_data.email, age=validated_data.age)
+    # ... lógica para guardar usuario
+    return {"message": "Usuario creado", "user_id": user.id}, 201
+```
+
+**Comportamiento:**
+- Si el JSON es inválido: retorna 400 con código "INVALID_JSON"
+- Si falla la validación: retorna 400 con código "VALIDATION_ERROR" y detalles de los errores
+
+#### Validación de Parámetros Query (`validate_query_with`)
+
+Valida los parámetros de la URL query string.
+
+```python
+class UserQueryModel(BaseModel):
+    page: int = 1
+    limit: int = 10
+    search: str = None
+
+@app.route('/users', methods=['GET'])
+@validate_query_with(UserQueryModel)
+def list_users(query_params):
+    users = User.query.filter_by(search=query_params.search).paginate(
+        page=query_params.page, per_page=query_params.limit
+    )
+    return {"users": [user.to_dict() for user in users.items]}, 200
+```
+
+**Comportamiento:**
+- Parámetros faltantes: usa valores por defecto del modelo
+- Tipos inválidos: retorna 400 con código "INVALID_PARAMETER"
+- Parámetros requeridos faltantes: retorna 400 con código "MISSING_PARAMETER"
+
+#### Validación de Headers (`validate_headers_with`)
+
+Valida los headers HTTP de la request.
+
+```python
+from pydantic import Field
+
+class AuthHeadersModel(BaseModel):
+    authorization: str = Field(alias="Authorization")
+    content_type: str = Field(alias="Content-Type", default="application/json")
+
+@app.route('/protected', methods=['GET'])
+@validate_headers_with(AuthHeadersModel)
+def protected_route(headers_data):
+    token = headers_data.authorization.replace("Bearer ", "")
+    # ... lógica de autenticación
+    return {"message": "Acceso autorizado"}, 200
+```
+
+**Nota:** Usa `Field(alias="Header-Name")` para mapear nombres de headers con guiones a nombres de campos válidos en Python.
+
+### Middlewares de Métricas
+
+Los middlewares registran automáticamente información sobre cada request:
+
+- **before_request_metrics**: Registra el inicio de la request con método, path, parámetros query y ID de request.
+- **after_request_metrics**: Registra el final con tiempo de ejecución, código de estado y detalles adicionales.
+
+Los logs se envían al sistema logger_tracker configurado.
+
+### Manejo de Errores
+
+La librería incluye manejadores de errores globales que convierten excepciones en respuestas JSON estandarizadas:
+
+```json
+{
+  "error": {
+    "message": "Invalid request body",
+    "code": "VALIDATION_ERROR",
+    "details": [
+      {
+        "loc": ["age"],
+        "msg": "Input should be a valid integer",
+        "type": "int_parsing"
+      }
+    ]
+  }
+}
+```
+
+### Excepciones Disponibles
+
+- `ValidationHttpError`: Errores de validación de datos (400)
+- `InvalidJsonHttpError`: JSON malformado (400)
+- `MissingParameterHttpError`: Parámetros requeridos faltantes (400)
+- `InvalidParameterHttpError`: Parámetros con tipos inválidos (400)
+- `UnauthorizedHttpError`: Autenticación requerida (401)
+- `InvalidCredentialsHttpError`: Credenciales inválidas (401)
+- `TokenExpiredHttpError`: Token expirado (401)
+- `ForbiddenHttpError`: Acceso prohibido (403)
+- `NotFoundHttpError`: Recurso no encontrado (404)
+- Y más...
+
+### Ejemplo Completo de Aplicación
+
+```python
+from flask import Flask
+from global_handler.decorators.request_decorators import validate_with, validate_query_with
+from global_handler.decorators.error_handler import register_error_handlers
+from global_handler.middlewares.metrics_middleware import before_request_metrics, after_request_metrics
+from pydantic import BaseModel
+
+app = Flask(__name__)
+
+# Configuración
+register_error_handlers(app)
+app.before_request(before_request_metrics)
+app.after_request(after_request_metrics)
+
+# Modelos
+class UserCreateModel(BaseModel):
+    name: str
+    email: str
+    age: int
+
+class UserQueryModel(BaseModel):
+    page: int = 1
+    limit: int = 10
+
+# Rutas
+@app.route('/users', methods=['POST'])
+@validate_with(UserCreateModel)
+def create_user(validated_data):
+    # Lógica de negocio
+    return {"message": "Usuario creado", "data": validated_data.model_dump()}, 201
+
+@app.route('/users', methods=['GET'])
+@validate_query_with(UserQueryModel)
+def list_users(query_params):
+    # Lógica de negocio
+    return {"users": [], "pagination": query_params.model_dump()}, 200
+
+if __name__ == '__main__':
+    app.run(debug=True)
+```
+
+## Detalles Técnicos
+
+- **Lenguaje**: Python 3.13+
+- **Framework**: Flask
+- **Validación**: Pydantic v2
+- **Logging**: Integración con logger_tracker
+- **Build System**: Poetry
+- **Licencia**: MIT
+
+### Dependencias
+
+- Flask>=2.0.0
+- Pydantic>=2.0.0
+- logger_tracker==0.1.0
+
+### Estructura del Proyecto
+
+```
+src/global_handler/
+├── decorators/
+│   ├── error_handler.py      # Manejadores de errores globales
+│   └── request_decorators.py # Decoradores de validación
+├── exceptions/
+│   └── http_exceptions.py    # Excepciones HTTP
+└── middlewares/
+    └── metrics_middleware.py # Middlewares de métricas
+```
+
+## Contribución
+
+1. Fork el proyecto
+2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
+3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
+4. Push a la rama (`git push origin feature/AmazingFeature`)
+5. Abre un Pull Request
+
+## Licencia
+
+Este proyecto está bajo la Licencia MIT. Ver el archivo `LICENSE` para más detalles.
+
+## Soporte
+
+Para preguntas o soporte, por favor abre un issue en GitHub o contacta al maintainer.
+pyproject.toml                    # Configuración del proyecto con Poetry
+```
+
+### Instalación
+
+1. Clona el repositorio:
+   ```bash
+   git clone <url-del-repositorio>
+   cd global-handler
+   ```
+
+2. Instala las dependencias con Poetry:
+   ```bash
+   poetry install
+   ```
+
+### Uso
+
+#### Configuración en Flask
+
+```python
+from flask import Flask
+from global_handler.decorators.error_handler import register_error_handlers
+from global_handler.middlewares.metrics_middleware import before_request_metrics, after_request_metrics
+
+app = Flask(__name__)
+
+# Registrar middlewares
+app.before_request(before_request_metrics)
+app.after_request(after_request_metrics)
+
+# Registrar manejadores de errores
+register_error_handlers(app)
+```
+
+#### Uso de Decoradores
+
+```python
+from pydantic import BaseModel
+from global_handler.decorators.request_decorators import validate_with
+
+class UserModel(BaseModel):
+    name: str
+    age: int
+
+@app.route('/user', methods=['POST'])
+@validate_with(UserModel)
+def create_user(validated_data):
+    # validated_data es una instancia de UserModel
+    return {"message": "User created"}
+```
+
+```python
+from global_handler.decorators.request_decorators import validate_headers_with
+
+class HeaderModel(BaseModel):
+    Authorization: str
+    Content_Type: str
+
+@app.route('/protected', methods=['GET'])
+@validate_headers_with(HeaderModel)
+def protected_route(headers_data):
+    # headers_data es una instancia de HeaderModel
+    return {"message": "Access granted"}
+```
+
+#### Excepciones
+
+```python
+from global_handler.exceptions.http_exceptions import ValidationHttpError
+
+raise ValidationHttpError("Invalid data")
+```
+
+## Tests
+
+El proyecto incluye un conjunto de tests unitarios para validar el funcionamiento de los componentes.
+
+### Ejecutar Tests
+
+Instala las dependencias de desarrollo:
+```bash
+poetry install --with dev
+```
+
+Ejecuta los tests con pytest:
+```bash
+pytest
+```
+
+### Cobertura de Tests
+
+- `test_exceptions.py`: Valida las excepciones HTTP personalizadas.
+- `test_request_decorators.py`: Prueba los decoradores de validación (body, query, headers) con mocks de Flask.
+- `test_error_handler.py`: Verifica el registro y manejo de errores.
+- `test_metrics_middleware.py`: Confirma el logging de métricas.
+
+## Contribución
+
+Para contribuir, por favor crea un issue o pull request en el repositorio.
+
+## Licencia
+
+Este proyecto está bajo la Licencia MIT. Ver archivo LICENSE para más detalles.

global_handler-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+global_handler/decorators/error_handler.py,sha256=l6SSiDgx5MM3PpGi5-_tEFA6cIRbR8QU16YLkEhIww4,1642
+global_handler/decorators/request_decorators.py,sha256=KxkarF0wDzZ9oc0jvfHfqqUT6XQQ0_KTmVraDJXJ3n0,3650
+global_handler/exceptions/http_exceptions.py,sha256=hjdgrGqUJb86NcgBXj8Lw9Qowr52Z6tXCLeMyGq0n0A,3133
+global_handler/middlewares/metrics_middleware.py,sha256=PH5Mc-rmB8oL8Xjfe5DKW6ZO1nByICpfT-6OTBWdwik,868
+global_handler-0.1.0.dist-info/LICENSE,sha256=-YS_OFJ3Tg-QOF_XKA56RibdopNB1UL0OYEv1k6JAsA,1071
+global_handler-0.1.0.dist-info/METADATA,sha256=2lKTKClUZRwioxuEWz3ga4YyypVvhk22AwvGTSicNCs,11044
+global_handler-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+global_handler-0.1.0.dist-info/RECORD,,

global_handler-0.1.0.dist-info/WHEEL

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