provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/file/lock.py

@@ -0,0 +1,175 @@
+"""File-based locking for concurrent access control."""
+
+import os
+from pathlib import Path
+import time
+
+from provide.foundation.errors.resources import LockError
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class FileLock:
+    """File-based lock for concurrent access control.
+
+    Uses exclusive file creation as the locking mechanism.
+    The lock file contains the PID of the process holding the lock.
+
+    Example:
+        with FileLock("/tmp/myapp.lock"):
+            # Exclusive access to resource
+            do_something()
+    """
+
+    def __init__(
+        self,
+        path: Path | str,
+        timeout: float = 10.0,
+        check_interval: float = 0.1,
+    ) -> None:
+        """Initialize file lock.
+
+        Args:
+            path: Lock file path
+            timeout: Max seconds to wait for lock
+            check_interval: Seconds between lock checks
+        """
+        self.path = Path(path)
+        self.timeout = timeout
+        self.check_interval = check_interval
+        self.locked = False
+        self.pid = os.getpid()
+
+    def acquire(self, blocking: bool = True) -> bool:
+        """Acquire the lock.
+
+        Args:
+            blocking: If True, wait for lock. If False, return immediately.
+
+        Returns:
+            True if lock acquired, False if not (non-blocking mode only)
+
+        Raises:
+            LockError: If timeout exceeded (blocking mode)
+        """
+        start_time = time.time()
+
+        while True:
+            try:
+                # Try to create lock file exclusively
+                fd = os.open(
+                    str(self.path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644
+                )
+                try:
+                    # Write our PID to the lock file
+                    os.write(fd, str(self.pid).encode())
+                finally:
+                    os.close(fd)
+
+                self.locked = True
+                log.debug("Acquired lock", path=str(self.path), pid=self.pid)
+                return True
+
+            except FileExistsError:
+                # Lock file exists, check if holder is still alive
+                if self._check_stale_lock():
+                    continue  # Retry after removing stale lock
+
+                if not blocking:
+                    log.debug("Lock unavailable (non-blocking)", path=str(self.path))
+                    return False
+
+                # Check timeout
+                if time.time() - start_time > self.timeout:
+                    raise LockError(
+                        f"Failed to acquire lock within {self.timeout}s",
+                        code="LOCK_TIMEOUT",
+                        path=str(self.path),
+                    )
+
+                # Wait before retry
+                time.sleep(self.check_interval)
+
+    def release(self) -> None:
+        """Release the lock.
+
+        Only removes the lock file if we own it.
+        """
+        if not self.locked:
+            return
+
+        try:
+            # Verify we own the lock before removing
+            if self.path.exists():
+                try:
+                    content = self.path.read_text().strip()
+                    if content == str(self.pid):
+                        self.path.unlink()
+                        log.debug("Released lock", path=str(self.path), pid=self.pid)
+                    else:
+                        log.warning(
+                            "Lock owned by different process",
+                            path=str(self.path),
+                            owner_pid=content,
+                            our_pid=self.pid,
+                        )
+                except Exception as e:
+                    log.warning(
+                        "Error checking lock ownership",
+                        path=str(self.path),
+                        error=str(e),
+                    )
+                    # Still try to remove if we think we own it
+                    if self.locked:
+                        self.path.unlink()
+        except FileNotFoundError:
+            pass  # Lock already released
+        except Exception as e:
+            log.error("Failed to release lock", path=str(self.path), error=str(e))
+        finally:
+            self.locked = False
+
+    def _check_stale_lock(self) -> bool:
+        """Check if lock file is stale and remove if so.
+
+        Returns:
+            True if stale lock was removed, False otherwise
+        """
+        try:
+            content = self.path.read_text().strip()
+            if content.isdigit():
+                lock_pid = int(content)
+
+                # Check if process is still alive
+                try:
+                    os.kill(lock_pid, 0)
+                    # Process exists
+                    return False
+                except ProcessLookupError:
+                    # Process doesn't exist, lock is stale
+                    log.warning(
+                        "Removing stale lock", path=str(self.path), stale_pid=lock_pid
+                    )
+                    self.path.unlink()
+                    return True
+        except Exception as e:
+            log.debug("Error checking stale lock", path=str(self.path), error=str(e))
+
+        return False
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.release()
+        return False  # Don't suppress exceptions
+
+
+__all__ = [
+    "FileLock",
+    "LockError",
+]

provide/foundation/file/safe.py

@@ -0,0 +1,179 @@
+"""Safe file operations with error handling and defaults."""
+
+from pathlib import Path
+import shutil
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def safe_read(
+    path: Path | str,
+    default: bytes | None = None,
+    encoding: str | None = None,
+) -> bytes | str | None:
+    """Read file safely, returning default if not found.
+
+    Args:
+        path: File to read
+        default: Value to return if file doesn't exist
+        encoding: If provided, decode bytes to str
+
+    Returns:
+        File contents or default value
+    """
+    path = Path(path)
+
+    try:
+        data = path.read_bytes()
+        if encoding:
+            return data.decode(encoding)
+        return data
+    except FileNotFoundError:
+        log.debug("File not found, returning default", path=str(path))
+        if default is not None and encoding:
+            return default.decode(encoding) if isinstance(default, bytes) else default
+        return default
+    except Exception as e:
+        log.warning("Failed to read file", path=str(path), error=str(e))
+        return default
+
+
+def safe_read_text(
+    path: Path | str,
+    default: str = "",
+    encoding: str = "utf-8",
+) -> str:
+    """Read text file safely with default.
+
+    Args:
+        path: File to read
+        default: Default text if file doesn't exist
+        encoding: Text encoding
+
+    Returns:
+        File contents or default text
+    """
+    result = safe_read(path, default=default.encode(encoding), encoding=encoding)
+    return result if isinstance(result, str) else default
+
+
+def safe_delete(
+    path: Path | str,
+    missing_ok: bool = True,
+) -> bool:
+    """Delete file safely.
+
+    Args:
+        path: File to delete
+        missing_ok: If True, don't raise error if file doesn't exist
+
+    Returns:
+        True if deleted, False if didn't exist
+
+    Raises:
+        OSError: If deletion fails and file exists
+    """
+    path = Path(path)
+
+    try:
+        path.unlink()
+        log.debug("Deleted file", path=str(path))
+        return True
+    except FileNotFoundError:
+        if missing_ok:
+            log.debug("File already absent", path=str(path))
+            return False
+        raise
+    except Exception as e:
+        log.error("Failed to delete file", path=str(path), error=str(e))
+        raise
+
+
+def safe_move(
+    src: Path | str,
+    dst: Path | str,
+    overwrite: bool = False,
+) -> None:
+    """Move file safely with optional overwrite.
+
+    Args:
+        src: Source file path
+        dst: Destination file path
+        overwrite: Whether to overwrite existing destination
+
+    Raises:
+        FileNotFoundError: If source doesn't exist
+        FileExistsError: If destination exists and overwrite=False
+        OSError: If move operation fails
+    """
+    src = Path(src)
+    dst = Path(dst)
+
+    if not src.exists():
+        raise FileNotFoundError(f"Source file does not exist: {src}")
+
+    if dst.exists() and not overwrite:
+        raise FileExistsError(f"Destination already exists: {dst}")
+
+    # Ensure destination directory exists
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        shutil.move(str(src), str(dst))
+        log.debug("Moved file", src=str(src), dst=str(dst))
+    except Exception as e:
+        log.error("Failed to move file", src=str(src), dst=str(dst), error=str(e))
+        raise
+
+
+def safe_copy(
+    src: Path | str,
+    dst: Path | str,
+    overwrite: bool = False,
+    preserve_mode: bool = True,
+) -> None:
+    """Copy file safely with metadata preservation.
+
+    Args:
+        src: Source file path
+        dst: Destination file path
+        overwrite: Whether to overwrite existing destination
+        preserve_mode: Whether to preserve file permissions
+
+    Raises:
+        FileNotFoundError: If source doesn't exist
+        FileExistsError: If destination exists and overwrite=False
+        OSError: If copy operation fails
+    """
+    src = Path(src)
+    dst = Path(dst)
+
+    if not src.exists():
+        raise FileNotFoundError(f"Source file does not exist: {src}")
+
+    if dst.exists() and not overwrite:
+        raise FileExistsError(f"Destination already exists: {dst}")
+
+    # Ensure destination directory exists
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if preserve_mode:
+            shutil.copy2(str(src), str(dst))
+        else:
+            shutil.copy(str(src), str(dst))
+        log.debug("Copied file", src=str(src), dst=str(dst))
+    except Exception as e:
+        log.error("Failed to copy file", src=str(src), dst=str(dst), error=str(e))
+        raise
+
+
+__all__ = [
+    "safe_copy",
+    "safe_delete",
+    "safe_move",
+    "safe_read",
+    "safe_read_text",
+]

provide/foundation/file/utils.py

@@ -0,0 +1,170 @@
+"""File utility functions."""
+
+from datetime import datetime
+from pathlib import Path
+import shutil
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def get_size(path: Path | str) -> int:
+    """Get file size in bytes, 0 if not exists.
+
+    Args:
+        path: File path
+
+    Returns:
+        Size in bytes, or 0 if file doesn't exist
+    """
+    path = Path(path)
+
+    try:
+        return path.stat().st_size
+    except FileNotFoundError:
+        return 0
+    except Exception as e:
+        log.warning("Failed to get file size", path=str(path), error=str(e))
+        return 0
+
+
+def get_mtime(path: Path | str) -> float | None:
+    """Get modification time, None if not exists.
+
+    Args:
+        path: File path
+
+    Returns:
+        Modification time as timestamp, or None if doesn't exist
+    """
+    path = Path(path)
+
+    try:
+        return path.stat().st_mtime
+    except FileNotFoundError:
+        return None
+    except Exception as e:
+        log.warning("Failed to get modification time", path=str(path), error=str(e))
+        return None
+
+
+def touch(
+    path: Path | str,
+    mode: int = 0o644,
+    exist_ok: bool = True,
+) -> None:
+    """Create empty file or update timestamp.
+
+    Args:
+        path: File path
+        mode: File permissions for new files
+        exist_ok: If False, raise error if file exists
+
+    Raises:
+        FileExistsError: If exist_ok=False and file exists
+    """
+    path = Path(path)
+
+    if path.exists() and not exist_ok:
+        raise FileExistsError(f"File already exists: {path}")
+
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Touch the file
+    path.touch(mode=mode, exist_ok=exist_ok)
+    log.debug("Touched file", path=str(path))
+
+
+def find_files(
+    pattern: str,
+    root: Path | str = ".",
+    recursive: bool = True,
+) -> list[Path]:
+    """Find files matching pattern.
+
+    Args:
+        pattern: Glob pattern (e.g., "*.py", "**/*.json")
+        root: Root directory to search from
+        recursive: If True, search recursively
+
+    Returns:
+        List of matching file paths
+    """
+    root = Path(root)
+
+    if not root.exists():
+        log.warning("Search root doesn't exist", root=str(root))
+        return []
+
+    # Use glob or rglob based on recursive flag
+    if recursive and "**" not in pattern:
+        pattern = f"**/{pattern}"
+
+    try:
+        if recursive:
+            matches = list(root.glob(pattern))
+        else:
+            matches = list(root.glob(pattern.lstrip("/")))
+
+        # Filter to files only
+        files = [p for p in matches if p.is_file()]
+
+        log.debug("Found files", pattern=pattern, root=str(root), count=len(files))
+        return files
+    except Exception as e:
+        log.error("Failed to find files", pattern=pattern, root=str(root), error=str(e))
+        return []
+
+
+def backup_file(
+    path: Path | str,
+    suffix: str = ".bak",
+    timestamp: bool = False,
+) -> Path | None:
+    """Create backup copy of file.
+
+    Args:
+        path: File to backup
+        suffix: Backup suffix
+        timestamp: If True, add timestamp to backup name
+
+    Returns:
+        Path to backup file, or None if source doesn't exist
+    """
+    path = Path(path)
+
+    if not path.exists():
+        log.debug("Source file doesn't exist, no backup created", path=str(path))
+        return None
+
+    # Build backup filename
+    if timestamp:
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_path = path.with_suffix(f".{ts}{suffix}")
+    else:
+        backup_path = path.with_suffix(path.suffix + suffix)
+
+        # Find unique name if backup already exists
+        counter = 1
+        while backup_path.exists():
+            backup_path = path.with_suffix(f"{path.suffix}{suffix}.{counter}")
+            counter += 1
+
+    try:
+        shutil.copy2(str(path), str(backup_path))
+        log.debug("Created backup", source=str(path), backup=str(backup_path))
+        return backup_path
+    except Exception as e:
+        log.error("Failed to create backup", path=str(path), error=str(e))
+        return None
+
+
+__all__ = [
+    "backup_file",
+    "find_files",
+    "get_mtime",
+    "get_size",
+    "touch",
+]

provide/foundation/hub/__init__.py

@@ -0,0 +1,88 @@
+"""
+Provide Foundation Hub - Component and Command Coordination System
+===================================================================
+
+The hub module provides a unified system for registering, discovering, and
+managing components and CLI commands across the provide-io ecosystem.
+
+Key Features:
+- Multi-dimensional component registry
+- CLI command registration and discovery
+- Entry point discovery
+- Integration with Click framework
+- Type-safe decorators using Python 3.11+ features
+
+Example Usage:
+    >>> from provide.foundation.hub import Hub, register_command
+    >>>
+    >>> class MyResource:
+    >>>     def __init__(self, name: str):
+    >>>         self.name = name
+    >>>
+    >>> @register_command("init")
+    >>> def init_command():
+    >>>     pass
+    >>>
+    >>> hub = Hub()
+    >>> hub.add_component(MyResource, name="my_resource", version="1.0.0")
+    >>> resource_class = hub.get_component("my_resource")
+    >>> command = hub.get_command("init")
+"""
+
+# Core hub components (always available)
+from provide.foundation.hub.components import (
+    ComponentCategory,
+    get_component_registry,
+)
+from provide.foundation.hub.decorators import register_command
+from provide.foundation.hub.manager import (
+    Hub,
+    clear_hub,
+    get_hub,
+)
+
+
+# CLI features (require click) - lazy loaded
+def get_click_commands():
+    """
+    Get CLI command building functions.
+
+    Returns:
+        Module with click command building functionality.
+
+    Raises:
+        ImportError: If click is not available.
+    """
+    try:
+        from provide.foundation.hub.commands import build_click_command
+
+        return {"build_click_command": build_click_command}
+    except ImportError as e:
+        if "click" in str(e):
+            raise ImportError(
+                "CLI command building requires optional dependencies. Install with: "
+                "pip install 'provide-foundation[cli]'"
+            ) from e
+        raise
+
+
+def __getattr__(name: str):
+    """Support lazy loading of CLI-dependent features."""
+    if name == "build_click_command":
+        return get_click_commands()["build_click_command"]
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = [
+    # Components
+    "get_component_registry",
+    "ComponentCategory",
+    # Hub
+    "Hub",
+    "clear_hub",
+    "get_hub",
+    # Commands (core)
+    "register_command",
+    # CLI features (lazy loaded)
+    "get_click_commands",
+]