First commit

utils.py

@@ -0,0 +1,45 @@
+"""
+Utility Module for Bagheera.
+
+This module contains general-purpose utility functions and context managers
+used throughout the application, such as file system helpers.
+"""
+import os
+from contextlib import contextmanager
+
+
+@contextmanager
+def preserve_mtime(path_or_fd):
+    """
+    Context manager to preserve the modification time (mtime) of a file.
+
+    This is useful when performing operations that might inadvertently update
+    the file's modification time (like modifying extended attributes), but
+    where the original timestamp should be retained. Supports both file paths
+    and file descriptors.
+
+    Args:
+        path_or_fd (str | int): The file path or file descriptor.
+
+    Yields:
+        None: Control is yielded back to the caller context.
+    """
+    mtime = None
+    try:
+        # Check for valid input (non-empty string or integer)
+        if path_or_fd is not None and (not isinstance(path_or_fd, str) or path_or_fd):
+            stat_result = os.stat(path_or_fd)
+            mtime = stat_result.st_mtime
+    except (OSError, ValueError, TypeError):
+        pass
+
+    yield
+
+    if mtime is not None:
+        try:
+            # Re-stat to get current atime, as reading might have updated it
+            stat_result = os.stat(path_or_fd)
+            atime = stat_result.st_atime
+            os.utime(path_or_fd, (atime, mtime))
+        except (OSError, ValueError, TypeError):
+            pass