mdb-engine 0.1.6__py3-none-any.whl → 0.4.12__py3-none-any.whl

mdb_engine/observability/README.md

@@ -99,9 +99,11 @@ record_operation(
 )
 
 # Record failed operation
+from pymongo.errors import PyMongoError
+
 try:
     await db.collection.insert_one(document)
-except Exception as e:
+except PyMongoError as e:
     record_operation(
         operation_name="database.insert_one",
         duration_ms=0,
@@ -368,7 +370,7 @@ async def check_custom_service():
                 message="Service responded with error",
                 details={"status_code": response.status_code}
             )
-    except Exception as e:
+    except (httpx.HTTPError, ConnectionError, TimeoutError) as e:
         return HealthCheckResult(
             name="custom_service",
             status=HealthStatus.UNHEALTHY,

mdb_engine/observability/__init__.py

@@ -5,15 +5,32 @@ Provides structured logging, metrics collection, request tracing,
 and health check capabilities.
 """
 
-from .health import (HealthChecker, HealthCheckResult, HealthStatus,
-                     check_engine_health, check_mongodb_health,
-                     check_pool_health)
-from .logging import (ContextualLoggerAdapter, clear_app_context,
-                      clear_correlation_id, get_correlation_id, get_logger,
-                      get_logging_context, log_operation, set_app_context,
-                      set_correlation_id)
-from .metrics import (MetricsCollector, OperationMetrics,
-                      get_metrics_collector, record_operation, timed_operation)
+from .health import (
+    HealthChecker,
+    HealthCheckResult,
+    HealthStatus,
+    check_engine_health,
+    check_mongodb_health,
+    check_pool_health,
+)
+from .logging import (
+    ContextualLoggerAdapter,
+    clear_app_context,
+    clear_correlation_id,
+    get_correlation_id,
+    get_logger,
+    get_logging_context,
+    log_operation,
+    set_app_context,
+    set_correlation_id,
+)
+from .metrics import (
+    MetricsCollector,
+    OperationMetrics,
+    get_metrics_collector,
+    record_operation,
+    timed_operation,
+)
 
 __all__ = [
     # Metrics

mdb_engine/observability/health.py

@@ -6,13 +6,17 @@ Provides health check functions for monitoring system status.
 
 import asyncio
 import logging
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any
 
-from pymongo.errors import (ConnectionFailure, OperationFailure,
-                            ServerSelectionTimeoutError)
+from pymongo.errors import (
+    ConnectionFailure,
+    OperationFailure,
+    ServerSelectionTimeoutError,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -33,10 +37,10 @@ class HealthCheckResult:
     name: str
     status: HealthStatus
     message: str
-    details: Optional[Dict[str, Any]] = None
+    details: dict[str, Any] | None = None
     timestamp: datetime = field(default_factory=datetime.now)
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary."""
         return {
             "name": self.name,
@@ -54,7 +58,7 @@ class HealthChecker:
 
     def __init__(self):
         """Initialize the health checker."""
-        self._checks: List[callable] = []
+        self._checks: list[callable] = []
 
     def register_check(self, check_func: Callable) -> None:
         """
@@ -65,14 +69,14 @@ class HealthChecker:
         """
         self._checks.append(check_func)
 
-    async def check_all(self) -> Dict[str, Any]:
+    async def check_all(self) -> dict[str, Any]:
         """
         Run all registered health checks.
 
         Returns:
             Dictionary with overall status and individual check results
         """
-        results: List[HealthCheckResult] = []
+        results: list[HealthCheckResult] = []
 
         for check_func in self._checks:
             try:
@@ -86,9 +90,7 @@ class HealthChecker:
                 ConnectionError,
                 OSError,
             ) as e:
-                logger.error(
-                    f"Health check {check_func.__name__} failed: {e}", exc_info=True
-                )
+                logger.error(f"Health check {check_func.__name__} failed: {e}", exc_info=True)
                 results.append(
                     HealthCheckResult(
                         name=check_func.__name__,
@@ -116,7 +118,7 @@ class HealthChecker:
 
 
 async def check_mongodb_health(
-    mongo_client: Optional[Any], timeout_seconds: float = 5.0
+    mongo_client: Any | None, timeout_seconds: float = 5.0
 ) -> HealthCheckResult:
     """
     Check MongoDB connection health.
@@ -137,9 +139,7 @@ async def check_mongodb_health(
 
     try:
         # Try to ping MongoDB with timeout
-        await asyncio.wait_for(
-            mongo_client.admin.command("ping"), timeout=timeout_seconds
-        )
+        await asyncio.wait_for(mongo_client.admin.command("ping"), timeout=timeout_seconds)
 
         return HealthCheckResult(
             name="mongodb",
@@ -167,7 +167,7 @@ async def check_mongodb_health(
         )
 
 
-async def check_engine_health(engine: Optional[Any]) -> HealthCheckResult:
+async def check_engine_health(engine: Any | None) -> HealthCheckResult:
     """
     Check MongoDB Engine health.
 
@@ -206,7 +206,7 @@ async def check_engine_health(engine: Optional[Any]) -> HealthCheckResult:
 
 
 async def check_pool_health(
-    get_pool_metrics_func: Optional[Callable[[], Any]] = None
+    get_pool_metrics_func: Callable[[], Any] | None = None,
 ) -> HealthCheckResult:
     """
     Check connection pool health.

mdb_engine/observability/logging.py

@@ -8,25 +8,25 @@ import contextvars
 import logging
 import uuid
 from datetime import datetime
-from typing import Any, Dict, Optional
+from typing import Any
 
 # Context variable for correlation ID
-_correlation_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+_correlation_id: contextvars.ContextVar[str | None] = contextvars.ContextVar(
     "correlation_id", default=None
 )
 
 # Context variable for app context
-_app_context: contextvars.ContextVar[Optional[Dict[str, Any]]] = contextvars.ContextVar(
+_app_context: contextvars.ContextVar[dict[str, Any] | None] = contextvars.ContextVar(
     "app_context", default=None
 )
 
 
-def get_correlation_id() -> Optional[str]:
+def get_correlation_id() -> str | None:
     """Get the current correlation ID from context."""
     return _correlation_id.get()
 
 
-def set_correlation_id(correlation_id: Optional[str] = None) -> str:
+def set_correlation_id(correlation_id: str | None = None) -> str:
     """
     Set a correlation ID in the current context.
 
@@ -47,7 +47,7 @@ def clear_correlation_id() -> None:
     _correlation_id.set(None)
 
 
-def set_app_context(app_slug: Optional[str] = None, **kwargs: Any) -> None:
+def set_app_context(app_slug: str | None = None, **kwargs: Any) -> None:
     """
     Set app context for logging.
 
@@ -64,14 +64,14 @@ def clear_app_context() -> None:
     _app_context.set(None)
 
 
-def get_logging_context() -> Dict[str, Any]:
+def get_logging_context() -> dict[str, Any]:
     """
     Get current logging context (correlation ID and app context).
 
     Returns:
         Dictionary with context information
     """
-    context: Dict[str, Any] = {
+    context: dict[str, Any] = {
         "timestamp": datetime.now().isoformat(),
     }
 
@@ -91,7 +91,7 @@ class ContextualLoggerAdapter(logging.LoggerAdapter):
     Logger adapter that automatically adds context to log records.
     """
 
-    def process(self, msg: str, kwargs: Dict[str, Any]) -> tuple[str, Dict[str, Any]]:
+    def process(self, msg: str, kwargs: dict[str, Any]) -> tuple[str, dict[str, Any]]:
         """Add context to log records."""
         # Get base context
         context = get_logging_context()
@@ -124,7 +124,7 @@ def log_operation(
     operation: str,
     level: int = logging.INFO,
     success: bool = True,
-    duration_ms: Optional[float] = None,
+    duration_ms: float | None = None,
     **context: Any,
 ) -> None:
     """

mdb_engine/observability/metrics.py

@@ -9,9 +9,10 @@ import logging
 import threading
 import time
 from collections import OrderedDict
+from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Any, Callable, Dict, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -26,7 +27,7 @@ class OperationMetrics:
     min_duration_ms: float = float("inf")
     max_duration_ms: float = 0.0
     error_count: int = 0
-    last_execution: Optional[datetime] = None
+    last_execution: datetime | None = None
 
     @property
     def avg_duration_ms(self) -> float:
@@ -48,23 +49,19 @@ class OperationMetrics:
             self.error_count += 1
         self.last_execution = datetime.now()
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """Convert metrics to dictionary."""
         return {
             "operation": self.operation_name,
             "count": self.count,
             "avg_duration_ms": round(self.avg_duration_ms, 2),
             "min_duration_ms": (
-                round(self.min_duration_ms, 2)
-                if self.min_duration_ms != float("inf")
-                else 0.0
+                round(self.min_duration_ms, 2) if self.min_duration_ms != float("inf") else 0.0
             ),
             "max_duration_ms": round(self.max_duration_ms, 2),
             "error_count": self.error_count,
             "error_rate_percent": round(self.error_rate, 2),
-            "last_execution": (
-                self.last_execution.isoformat() if self.last_execution else None
-            ),
+            "last_execution": (self.last_execution.isoformat() if self.last_execution else None),
         }
 
 
@@ -125,7 +122,7 @@ class MetricsCollector:
 
             self._metrics[key].record(duration_ms, success)
 
-    def get_metrics(self, operation_name: Optional[str] = None) -> Dict[str, Any]:
+    def get_metrics(self, operation_name: str | None = None) -> dict[str, Any]:
         """
         Get metrics for operations.
 
@@ -138,9 +135,7 @@ class MetricsCollector:
         with self._lock:
             if operation_name:
                 metrics = {
-                    k: v.to_dict()
-                    for k, v in self._metrics.items()
-                    if k.startswith(operation_name)
+                    k: v.to_dict() for k, v in self._metrics.items() if k.startswith(operation_name)
                 }
                 # Move accessed metrics to end (LRU)
                 for key in list(self._metrics.keys()):
@@ -160,7 +155,7 @@ class MetricsCollector:
             "total_operations": total_operations,
         }
 
-    def get_summary(self) -> Dict[str, Any]:
+    def get_summary(self) -> dict[str, Any]:
         """
         Get a summary of all metrics.
 
@@ -176,9 +171,9 @@ class MetricsCollector:
                 }
 
             # Aggregate by base operation name (without tags)
-            aggregated: Dict[str, OperationMetrics] = {}
+            aggregated: dict[str, OperationMetrics] = {}
 
-            for key, metric in self._metrics.items():
+            for _key, metric in self._metrics.items():
                 base_name = metric.operation_name
                 if base_name not in aggregated:
                     aggregated[base_name] = OperationMetrics(operation_name=base_name)
@@ -223,7 +218,7 @@ class MetricsCollector:
 
 
 # Global metrics collector instance
-_metrics_collector: Optional[MetricsCollector] = None
+_metrics_collector: MetricsCollector | None = None
 
 
 def get_metrics_collector() -> MetricsCollector:
@@ -260,6 +255,32 @@ def timed_operation(operation_name: str, **tags: Any):
             ...
     """
 
+    # Common exceptions that indicate operation failure (not system-level exits)
+    # This is comprehensive to handle any decorated function's failures
+    _OPERATION_FAILURES = (
+        RuntimeError,
+        ValueError,
+        TypeError,
+        KeyError,
+        AttributeError,
+        IndexError,
+        LookupError,
+        IOError,
+        OSError,
+        ConnectionError,
+        TimeoutError,
+        PermissionError,
+        FileNotFoundError,
+        AssertionError,
+        ArithmeticError,
+        BufferError,
+        ImportError,
+        MemoryError,
+        StopIteration,
+        StopAsyncIteration,
+        UnicodeError,
+    )
+
     def decorator(func: Callable) -> Callable:
         if hasattr(func, "__code__") and func.__code__.co_flags & 0x80:  # CO_COROUTINE
             # Async function
@@ -269,7 +290,7 @@ def timed_operation(operation_name: str, **tags: Any):
                 try:
                     result = await func(*args, **kwargs)
                     return result
-                except Exception:
+                except _OPERATION_FAILURES:
                     success = False
                     raise
                 finally:
@@ -285,7 +306,7 @@ def timed_operation(operation_name: str, **tags: Any):
                 try:
                     result = func(*args, **kwargs)
                     return result
-                except Exception:
+                except _OPERATION_FAILURES:
                     success = False
                     raise
                 finally:

mdb_engine/repositories/__init__.py

@@ -0,0 +1,34 @@
+"""
+MDB Engine Repository Pattern
+
+Provides abstract repository interfaces and MongoDB implementations
+for clean data access patterns.
+
+Usage:
+    from mdb_engine.repositories import Repository, MongoRepository
+
+    # In domain services
+    class UserService:
+        def __init__(self, users: Repository[User]):
+            self._users = users
+
+        async def get_user(self, id: str) -> User:
+            return await self._users.get(id)
+
+    # In FastAPI routes using UnitOfWork
+    @app.get("/users/{user_id}")
+    async def get_user(user_id: str, ctx: RequestContext = Depends()):
+        user = await ctx.uow.users.get(user_id)
+        return user
+"""
+
+from .base import Entity, Repository
+from .mongo import MongoRepository
+from .unit_of_work import UnitOfWork
+
+__all__ = [
+    "Repository",
+    "Entity",
+    "MongoRepository",
+    "UnitOfWork",
+]