crackerjack 0.32.0__py3-none-any.whl → 0.33.1__py3-none-any.whl

crackerjack/core/resource_manager.py

@@ -1,10 +1,3 @@
-"""Comprehensive resource management with automatic cleanup patterns.
-
-This module provides RAII (Resource Acquisition Is Initialization) patterns
-and comprehensive resource lifecycle management to prevent resource leaks
-even in error scenarios.
-"""
-
 import asyncio
 import contextlib
 import logging
@@ -19,16 +12,10 @@ from types import TracebackType
 
 
 class ResourceProtocol(t.Protocol):
-    """Protocol for resources that can be cleaned up."""
-
-    async def cleanup(self) -> None:
-        """Clean up the resource."""
-        ...
+    async def cleanup(self) -> None: ...
 
 
 class ResourceManager:
-    """Centralized resource management with automatic cleanup on error scenarios."""
-
     def __init__(self, logger: logging.Logger | None = None) -> None:
         self.logger = logger or logging.getLogger(__name__)
         self._resources: list[ResourceProtocol] = []
@@ -37,10 +24,8 @@ class ResourceManager:
         self._closed = False
 
     def register_resource(self, resource: ResourceProtocol) -> None:
-        """Register a resource for automatic cleanup."""
         with self._lock:
             if self._closed:
-                # If already closed, immediately clean up the resource
                 asyncio.create_task(resource.cleanup())
                 return
             self._resources.append(resource)
@@ -48,10 +33,8 @@ class ResourceManager:
     def register_cleanup_callback(
         self, callback: t.Callable[[], t.Awaitable[None]]
     ) -> None:
-        """Register a cleanup callback to be called during shutdown."""
         with self._lock:
             if self._closed:
-                # If already closed, immediately call the callback
                 coro = callback()
                 if asyncio.iscoroutine(coro):
                     asyncio.ensure_future(coro)
@@ -59,7 +42,6 @@ class ResourceManager:
             self._cleanup_callbacks.append(callback)
 
     async def cleanup_all(self) -> None:
-        """Clean up all registered resources."""
         with self._lock:
             if self._closed:
                 return
@@ -68,14 +50,12 @@ class ResourceManager:
             resources = self._resources.copy()
             callbacks = self._cleanup_callbacks.copy()
 
-        # Clean up resources
         for resource in resources:
             try:
                 await resource.cleanup()
             except Exception as e:
                 self.logger.warning(f"Error cleaning up resource {resource}: {e}")
 
-        # Call cleanup callbacks
         for callback in callbacks:
             try:
                 await callback()
@@ -99,8 +79,6 @@ class ResourceManager:
 
 
 class ManagedResource(ABC):
-    """Base class for managed resources with automatic cleanup."""
-
     def __init__(self, manager: ResourceManager | None = None) -> None:
         self.manager = manager
         self._closed = False
@@ -110,19 +88,15 @@ class ManagedResource(ABC):
 
     @abstractmethod
     async def cleanup(self) -> None:
-        """Clean up the resource. Must be implemented by subclasses."""
         pass
 
     async def close(self) -> None:
-        """Manually close the resource."""
         if not self._closed:
             self._closed = True
             await self.cleanup()
 
     def __del__(self) -> None:
-        """Ensure cleanup is called even if explicitly forgotten."""
         if not self._closed:
-            # Create cleanup task if event loop is available
             with contextlib.suppress(RuntimeError):
                 loop = asyncio.get_event_loop()
                 if loop.is_running():
@@ -130,8 +104,6 @@ class ManagedResource(ABC):
 
 
 class ManagedTemporaryFile(ManagedResource):
-    """Temporary file with automatic cleanup on error scenarios."""
-
     def __init__(
         self,
         suffix: str = "",
@@ -142,43 +114,35 @@ class ManagedTemporaryFile(ManagedResource):
         self.temp_file = tempfile.NamedTemporaryFile(
             suffix=suffix,
             prefix=prefix,
-            delete=False,  # We'll handle deletion ourselves
+            delete=False,
         )
         self.path = Path(self.temp_file.name)
 
     async def cleanup(self) -> None:
-        """Clean up temporary file."""
         if not self._closed:
             self._closed = True
 
-            # Close file handle
             if not self.temp_file.closed:
                 self.temp_file.close()
 
-            # Remove file if it exists
             try:
                 if self.path.exists():
                     self.path.unlink()
             except OSError as e:
-                # Log but don't raise - cleanup should be best effort
                 logging.getLogger(__name__).warning(
                     f"Failed to remove temporary file {self.path}: {e}"
                 )
 
     def write_text(self, content: str, encoding: str = "utf-8") -> None:
-        """Write text content to the temporary file."""
         if self._closed:
             raise RuntimeError("Cannot write to closed temporary file")
         self.path.write_text(content, encoding=encoding)
 
     def read_text(self, encoding: str = "utf-8") -> str:
-        """Read text content from the temporary file."""
         return self.path.read_text(encoding=encoding)
 
 
 class ManagedTemporaryDirectory(ManagedResource):
-    """Temporary directory with automatic cleanup on error scenarios."""
-
     def __init__(
         self,
         suffix: str = "",
@@ -190,7 +154,6 @@ class ManagedTemporaryDirectory(ManagedResource):
         self.path = Path(self.temp_dir)
 
     async def cleanup(self) -> None:
-        """Clean up temporary directory and all contents."""
         if not self._closed:
             self._closed = True
 
@@ -206,8 +169,6 @@ class ManagedTemporaryDirectory(ManagedResource):
 
 
 class ManagedProcess(ManagedResource):
-    """Process with automatic cleanup on error scenarios."""
-
     def __init__(
         self,
         process: asyncio.subprocess.Process,
@@ -219,18 +180,15 @@ class ManagedProcess(ManagedResource):
         self.timeout = timeout
 
     async def cleanup(self) -> None:
-        """Clean up process with graceful termination."""
         if not self._closed and self.process.returncode is None:
             self._closed = True
 
             try:
-                # Try graceful termination first
                 self.process.terminate()
 
                 try:
                     await asyncio.wait_for(self.process.wait(), timeout=5.0)
                 except TimeoutError:
-                    # Force kill if graceful termination fails
                     self.process.kill()
                     try:
                         await asyncio.wait_for(self.process.wait(), timeout=2.0)
@@ -240,7 +198,6 @@ class ManagedProcess(ManagedResource):
                         )
 
             except ProcessLookupError:
-                # Process already terminated
                 pass
             except Exception as e:
                 logging.getLogger(__name__).warning(
@@ -249,8 +206,6 @@ class ManagedProcess(ManagedResource):
 
 
 class ManagedTask(ManagedResource):
-    """Asyncio task with automatic cancellation on error scenarios."""
-
     def __init__(
         self,
         task: asyncio.Task[t.Any],
@@ -262,7 +217,6 @@ class ManagedTask(ManagedResource):
         self.timeout = timeout
 
     async def cleanup(self) -> None:
-        """Clean up task with cancellation."""
         if not self._closed and not self.task.done():
             self._closed = True
 
@@ -271,15 +225,12 @@ class ManagedTask(ManagedResource):
             try:
                 await asyncio.wait_for(self.task, timeout=self.timeout)
             except (TimeoutError, asyncio.CancelledError):
-                # Expected when cancelling or timing out
                 pass
             except Exception as e:
                 logging.getLogger(__name__).warning(f"Error cleaning up task: {e}")
 
 
 class ManagedFileHandle(ManagedResource):
-    """File handle with automatic closing on error scenarios."""
-
     def __init__(
         self,
         file_handle: t.IO[t.Any],
@@ -289,7 +240,6 @@ class ManagedFileHandle(ManagedResource):
         self.file_handle = file_handle
 
     async def cleanup(self) -> None:
-        """Clean up file handle."""
         if not self._closed and not self.file_handle.closed:
             self._closed = True
 
@@ -300,8 +250,6 @@ class ManagedFileHandle(ManagedResource):
 
 
 class ResourceContext:
-    """Context manager for automatic resource management."""
-
     def __init__(self) -> None:
         self.resource_manager = ResourceManager()
 
@@ -310,7 +258,6 @@ class ResourceContext:
         suffix: str = "",
         prefix: str = "crackerjack-",
     ) -> ManagedTemporaryFile:
-        """Create a managed temporary file."""
         return ManagedTemporaryFile(suffix, prefix, self.resource_manager)
 
     def managed_temp_dir(
@@ -318,7 +265,6 @@ class ResourceContext:
         suffix: str = "",
         prefix: str = "crackerjack-",
     ) -> ManagedTemporaryDirectory:
-        """Create a managed temporary directory."""
         return ManagedTemporaryDirectory(suffix, prefix, self.resource_manager)
 
     def managed_process(
@@ -326,7 +272,6 @@ class ResourceContext:
         process: asyncio.subprocess.Process,
         timeout: float = 30.0,
     ) -> ManagedProcess:
-        """Create a managed process."""
         return ManagedProcess(process, timeout, self.resource_manager)
 
     def managed_task(
@@ -334,14 +279,12 @@ class ResourceContext:
         task: asyncio.Task[t.Any],
         timeout: float = 30.0,
     ) -> ManagedTask:
-        """Create a managed task."""
         return ManagedTask(task, timeout, self.resource_manager)
 
     def managed_file(
         self,
         file_handle: t.IO[t.Any],
     ) -> ManagedFileHandle:
-        """Create a managed file handle."""
         return ManagedFileHandle(file_handle, self.resource_manager)
 
     async def __aenter__(self) -> "ResourceContext":
@@ -357,18 +300,15 @@ class ResourceContext:
         await self.resource_manager.__aexit__(exc_type, exc_val, exc_tb)
 
 
-# Global resource manager registry
 _global_managers: weakref.WeakSet[ResourceManager] = weakref.WeakSet()
 
 
 def register_global_resource_manager(manager: ResourceManager) -> None:
-    """Register a resource manager for global cleanup."""
     _global_managers.add(manager)
 
 
 async def cleanup_all_global_resources() -> None:
-    """Clean up all globally registered resource managers."""
-    managers = list(_global_managers)
+    managers = list[t.Any](_global_managers)
 
     cleanup_tasks = [asyncio.create_task(manager.cleanup_all()) for manager in managers]
 
@@ -376,17 +316,16 @@ async def cleanup_all_global_resources() -> None:
         await asyncio.gather(*cleanup_tasks, return_exceptions=True)
 
 
-# Cleanup helper context managers
 @contextlib.asynccontextmanager
-async def with_resource_cleanup():
-    """Context manager that ensures resource cleanup on any exit."""
+async def with_resource_cleanup() -> t.AsyncIterator[ResourceContext]:
     async with ResourceContext() as ctx:
         yield ctx
 
 
 @contextlib.asynccontextmanager
-async def with_temp_file(suffix: str = "", prefix: str = "crackerjack-"):
-    """Context manager for temporary file with automatic cleanup."""
+async def with_temp_file(
+    suffix: str = "", prefix: str = "crackerjack-"
+) -> t.AsyncIterator[ManagedTemporaryFile]:
     async with ResourceContext() as ctx:
         temp_file = ctx.managed_temp_file(suffix, prefix)
         try:
@@ -396,8 +335,9 @@ async def with_temp_file(suffix: str = "", prefix: str = "crackerjack-"):
 
 
 @contextlib.asynccontextmanager
-async def with_temp_dir(suffix: str = "", prefix: str = "crackerjack-"):
-    """Context manager for temporary directory with automatic cleanup."""
+async def with_temp_dir(
+    suffix: str = "", prefix: str = "crackerjack-"
+) -> t.AsyncIterator[ManagedTemporaryDirectory]:
     async with ResourceContext() as ctx:
         temp_dir = ctx.managed_temp_dir(suffix, prefix)
         try:
@@ -410,20 +350,16 @@ async def with_temp_dir(suffix: str = "", prefix: str = "crackerjack-"):
 async def with_managed_process(
     process: asyncio.subprocess.Process,
     timeout: float = 30.0,
-):
-    """Context manager for process with automatic cleanup."""
+) -> t.AsyncIterator[asyncio.subprocess.Process]:
     async with ResourceContext() as ctx:
         managed_proc = ctx.managed_process(process, timeout)
         try:
-            yield managed_proc
+            yield managed_proc.process
         finally:
             await managed_proc.cleanup()
 
 
-# Enhanced error handling utilities
 class ResourceLeakDetector:
-    """Detector for potential resource leaks during development."""
-
     def __init__(self) -> None:
         self.open_files: set[str] = set()
         self.active_processes: set[int] = set()
@@ -431,35 +367,28 @@ class ResourceLeakDetector:
         self._start_time = time.time()
 
     def track_file(self, file_path: str) -> None:
-        """Track an opened file."""
         self.open_files.add(file_path)
 
     def untrack_file(self, file_path: str) -> None:
-        """Untrack a closed file."""
         self.open_files.discard(file_path)
 
     def track_process(self, pid: int) -> None:
-        """Track a spawned process."""
         self.active_processes.add(pid)
 
     def untrack_process(self, pid: int) -> None:
-        """Untrack a terminated process."""
         self.active_processes.discard(pid)
 
     def track_task(self, task: asyncio.Task[t.Any]) -> None:
-        """Track an active task."""
         self.active_tasks.add(task)
 
     def untrack_task(self, task: asyncio.Task[t.Any]) -> None:
-        """Untrack a completed task."""
         self.active_tasks.discard(task)
 
     def get_leak_report(self) -> dict[str, t.Any]:
-        """Get a report of potential resource leaks."""
         return {
             "duration_seconds": time.time() - self._start_time,
-            "open_files": list(self.open_files),
-            "active_processes": list(self.active_processes),
+            "open_files": list[t.Any](self.open_files),
+            "active_processes": list[t.Any](self.active_processes),
             "active_tasks": len([t for t in self.active_tasks if not t.done()]),
             "total_tracked_files": len(self.open_files),
             "total_tracked_processes": len(self.active_processes),
@@ -467,7 +396,6 @@ class ResourceLeakDetector:
         }
 
     def has_potential_leaks(self) -> bool:
-        """Check if there are potential resource leaks."""
         return bool(
             self.open_files
             or self.active_processes
@@ -475,24 +403,20 @@ class ResourceLeakDetector:
         )
 
 
-# Development-time resource leak detection
 _leak_detector: ResourceLeakDetector | None = None
 
 
 def enable_leak_detection() -> ResourceLeakDetector:
-    """Enable resource leak detection for development."""
     global _leak_detector
     _leak_detector = ResourceLeakDetector()
     return _leak_detector
 
 
 def get_leak_detector() -> ResourceLeakDetector | None:
-    """Get the current resource leak detector, if enabled."""
     return _leak_detector
 
 
 def disable_leak_detection() -> dict[str, t.Any] | None:
-    """Disable resource leak detection and return final report."""
     global _leak_detector
     if _leak_detector:
         report = _leak_detector.get_leak_report()