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

provide/foundation/file/__init__.py

@@ -0,0 +1,79 @@
+"""File operations with safety, atomicity, and format support.
+
+This module provides comprehensive file operations including:
+- Atomic writes to prevent corruption
+- Safe operations with error handling
+- Directory management utilities
+- Format-specific helpers for JSON, YAML, TOML
+- File locking for concurrent access
+- Various utility functions
+"""
+
+from provide.foundation.file.atomic import (
+    atomic_replace,
+    atomic_write,
+    atomic_write_text,
+)
+from provide.foundation.file.directory import (
+    ensure_dir,
+    ensure_parent_dir,
+    safe_rmtree,
+    temp_dir,
+)
+from provide.foundation.file.formats import (
+    read_json,
+    read_toml,
+    read_yaml,
+    write_json,
+    write_toml,
+    write_yaml,
+)
+from provide.foundation.file.lock import FileLock, LockError
+from provide.foundation.file.safe import (
+    safe_copy,
+    safe_delete,
+    safe_move,
+    safe_read,
+    safe_read_text,
+)
+from provide.foundation.file.utils import (
+    backup_file,
+    find_files,
+    get_mtime,
+    get_size,
+    touch,
+)
+
+__all__ = [
+    # From lock
+    "FileLock",
+    "LockError",
+    "atomic_replace",
+    # From atomic
+    "atomic_write",
+    "atomic_write_text",
+    "backup_file",
+    # From directory
+    "ensure_dir",
+    "ensure_parent_dir",
+    "find_files",
+    "get_mtime",
+    # From utils
+    "get_size",
+    # From formats
+    "read_json",
+    "read_toml",
+    "read_yaml",
+    "safe_copy",
+    "safe_delete",
+    "safe_move",
+    # From safe
+    "safe_read",
+    "safe_read_text",
+    "safe_rmtree",
+    "temp_dir",
+    "touch",
+    "write_json",
+    "write_toml",
+    "write_yaml",
+]

provide/foundation/file/atomic.py

@@ -0,0 +1,157 @@
+"""Atomic file operations using temp file + rename pattern."""
+
+import contextlib
+import os
+from pathlib import Path
+import tempfile
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def atomic_write(
+    path: Path | str,
+    data: bytes,
+    mode: int | None = None,
+    backup: bool = False,
+    preserve_mode: bool = True,
+) -> None:
+    """Write file atomically using temp file + rename.
+
+    This ensures that the file is either fully written or not written at all,
+    preventing partial writes or corruption.
+
+    Args:
+        path: Target file path
+        data: Binary data to write
+        mode: Optional file permissions (e.g., 0o644)
+        backup: Create .bak file before overwrite
+        preserve_mode: Whether to preserve existing file permissions when mode is None
+
+    Raises:
+        OSError: If file operation fails
+    """
+    path = Path(path)
+
+    # Create backup if requested and file exists
+    if backup and path.exists():
+        backup_path = path.with_suffix(path.suffix + ".bak")
+        try:
+            path.rename(backup_path)
+            log.debug("Created backup", backup=str(backup_path))
+        except OSError as e:
+            log.warning("Failed to create backup", error=str(e))
+
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Create temp file in same directory for atomic rename
+    # Note: mkstemp creates files with 0o600 by default for security
+    fd, temp_path = tempfile.mkstemp(
+        dir=path.parent, prefix=f".{path.name}.", suffix=".tmp"
+    )
+
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+
+        # Set permissions if specified
+        if mode is not None:
+            os.chmod(temp_path, mode)
+        elif preserve_mode and path.exists():
+            # Preserve existing permissions if requested
+            try:
+                existing_mode = path.stat().st_mode
+                os.chmod(temp_path, existing_mode)
+            except OSError:
+                pass
+        elif not preserve_mode:
+            # When not preserving, set to standard default permissions
+            # mkstemp creates with 0o600, but we want standard defaults
+            # Apply umask manually since os.chmod doesn't respect it
+            default_mode = 0o666
+            current_umask = os.umask(0)  # Get current umask
+            os.umask(current_umask)  # Restore it
+            os.chmod(temp_path, default_mode & ~current_umask)
+
+        # Atomic rename
+        os.replace(temp_path, path)
+
+        log.debug(
+            "Atomically wrote file",
+            path=str(path),
+            size=len(data),
+            mode=oct(mode) if mode else None,
+        )
+    except Exception:
+        # Clean up temp file on error
+        with contextlib.suppress(OSError):
+            os.unlink(temp_path)
+        raise
+
+
+def atomic_write_text(
+    path: Path | str,
+    text: str,
+    encoding: str = "utf-8",
+    mode: int | None = None,
+    backup: bool = False,
+    preserve_mode: bool = True,
+) -> None:
+    """Write text file atomically.
+
+    Args:
+        path: Target file path
+        text: Text content to write
+        encoding: Text encoding (default: utf-8)
+        mode: Optional file permissions
+        backup: Create .bak file before overwrite
+        preserve_mode: Whether to preserve existing file permissions when mode is None
+
+    Raises:
+        OSError: If file operation fails
+        UnicodeEncodeError: If text cannot be encoded
+    """
+    data = text.encode(encoding)
+    atomic_write(path, data, mode=mode, backup=backup, preserve_mode=preserve_mode)
+
+
+def atomic_replace(
+    path: Path | str,
+    data: bytes,
+    preserve_mode: bool = True,
+) -> None:
+    """Replace existing file atomically, preserving permissions.
+
+    Args:
+        path: Target file path (must exist)
+        data: Binary data to write
+        preserve_mode: Whether to preserve file permissions
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        OSError: If file operation fails
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"File does not exist: {path}")
+
+    mode = None
+    if preserve_mode:
+        with contextlib.suppress(OSError):
+            mode = path.stat().st_mode
+
+    # When preserve_mode is False, we explicitly pass preserve_mode=False to atomic_write
+    # and let it handle the non-preservation (atomic_write won't preserve even if file exists)
+    atomic_write(path, data, mode=mode, backup=False, preserve_mode=preserve_mode)
+
+
+__all__ = [
+    "atomic_replace",
+    "atomic_write",
+    "atomic_write_text",
+]

provide/foundation/file/directory.py

@@ -0,0 +1,134 @@
+"""Directory operations and utilities."""
+
+from contextlib import contextmanager
+from typing import Generator
+from pathlib import Path
+import shutil
+import tempfile
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def ensure_dir(
+    path: Path | str,
+    mode: int = 0o755,
+    parents: bool = True,
+) -> Path:
+    """Ensure directory exists with proper permissions.
+
+    Args:
+        path: Directory path
+        mode: Directory permissions
+        parents: Create parent directories if needed
+
+    Returns:
+        Path object for the directory
+    """
+    path = Path(path)
+
+    if not path.exists():
+        path.mkdir(mode=mode, parents=parents, exist_ok=True)
+        log.debug("Created directory", path=str(path), mode=oct(mode))
+    elif not path.is_dir():
+        raise NotADirectoryError(f"Path exists but is not a directory: {path}")
+
+    return path
+
+
+def ensure_parent_dir(
+    file_path: Path | str,
+    mode: int = 0o755,
+) -> Path:
+    """Ensure parent directory of file exists.
+
+    Args:
+        file_path: File path whose parent to ensure
+        mode: Directory permissions
+
+    Returns:
+        Path object for the parent directory
+    """
+    file_path = Path(file_path)
+    parent = file_path.parent
+
+    if parent and parent != Path():
+        return ensure_dir(parent, mode=mode, parents=True)
+
+    return parent
+
+
+@contextmanager
+def temp_dir(
+    prefix: str = "provide_",
+    cleanup: bool = True,
+) -> Generator[Path, None, None]:
+    """Create temporary directory with automatic cleanup.
+
+    Args:
+        prefix: Directory name prefix
+        cleanup: Whether to remove directory on exit
+
+    Yields:
+        Path object for the temporary directory
+    """
+    temp_path = None
+    try:
+        temp_path = Path(tempfile.mkdtemp(prefix=prefix))
+        log.debug("Created temp directory", path=str(temp_path))
+        yield temp_path
+    finally:
+        if cleanup and temp_path and temp_path.exists():
+            try:
+                shutil.rmtree(temp_path)
+                log.debug("Cleaned up temp directory", path=str(temp_path))
+            except Exception as e:
+                log.warning(
+                    "Failed to cleanup temp directory",
+                    path=str(temp_path),
+                    error=str(e),
+                )
+
+
+def safe_rmtree(
+    path: Path | str,
+    missing_ok: bool = True,
+) -> bool:
+    """Remove directory tree safely.
+
+    Args:
+        path: Directory to remove
+        missing_ok: If True, don't raise error if doesn't exist
+
+    Returns:
+        True if removed, False if didn't exist
+
+    Raises:
+        OSError: If removal fails and directory exists
+    """
+    path = Path(path)
+
+    try:
+        if path.exists():
+            shutil.rmtree(path)
+            log.debug("Removed directory tree", path=str(path))
+            return True
+        elif missing_ok:
+            log.debug("Directory already absent", path=str(path))
+            return False
+        else:
+            raise FileNotFoundError(f"Directory does not exist: {path}")
+    except Exception as e:
+        if not path.exists() and missing_ok:
+            return False
+        log.error("Failed to remove directory tree", path=str(path), error=str(e))
+        raise
+
+
+__all__ = [
+    "ensure_dir",
+    "ensure_parent_dir",
+    "safe_rmtree",
+    "temp_dir",
+]

provide/foundation/file/formats.py

@@ -0,0 +1,236 @@
+"""Format-specific file operations for JSON, YAML, TOML."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from provide.foundation.file.atomic import atomic_write_text
+from provide.foundation.file.safe import safe_read_text
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+def read_json(
+    path: Path | str,
+    default: Any = None,
+    encoding: str = "utf-8",
+) -> Any:
+    """Read JSON file with error handling.
+
+    Args:
+        path: JSON file path
+        default: Default value if file doesn't exist or is invalid
+        encoding: Text encoding
+
+    Returns:
+        Parsed JSON data or default value
+    """
+    content = safe_read_text(path, default="", encoding=encoding)
+
+    if not content:
+        log.debug("Empty or missing JSON file, returning default", path=str(path))
+        return default
+
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError as e:
+        log.warning("Invalid JSON file", path=str(path), error=str(e))
+        return default
+
+
+def write_json(
+    path: Path | str,
+    data: Any,
+    indent: int = 2,
+    sort_keys: bool = False,
+    atomic: bool = True,
+    encoding: str = "utf-8",
+) -> None:
+    """Write JSON file, optionally atomic.
+
+    Args:
+        path: JSON file path
+        data: Data to serialize
+        indent: Indentation level (None for compact)
+        sort_keys: Whether to sort dictionary keys
+        atomic: Use atomic write
+        encoding: Text encoding
+    """
+    path = Path(path)
+
+    try:
+        content = json.dumps(
+            data, indent=indent, sort_keys=sort_keys, ensure_ascii=False
+        )
+
+        if atomic:
+            atomic_write_text(path, content, encoding=encoding)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding=encoding)
+
+        log.debug("Wrote JSON file", path=str(path), atomic=atomic)
+    except Exception as e:
+        log.error("Failed to write JSON file", path=str(path), error=str(e))
+        raise
+
+
+def read_yaml(
+    path: Path | str,
+    default: Any = None,
+    encoding: str = "utf-8",
+) -> Any:
+    """Read YAML file with error handling.
+
+    Args:
+        path: YAML file path
+        default: Default value if file doesn't exist or is invalid
+        encoding: Text encoding
+
+    Returns:
+        Parsed YAML data or default value
+    """
+    try:
+        import yaml
+    except ImportError:
+        log.warning("PyYAML not installed, returning default")
+        return default
+
+    content = safe_read_text(path, default="", encoding=encoding)
+
+    if not content:
+        log.debug("Empty or missing YAML file, returning default", path=str(path))
+        return default
+
+    try:
+        return yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        log.warning("Invalid YAML file", path=str(path), error=str(e))
+        return default
+
+
+def write_yaml(
+    path: Path | str,
+    data: Any,
+    atomic: bool = True,
+    encoding: str = "utf-8",
+    default_flow_style: bool = False,
+) -> None:
+    """Write YAML file, optionally atomic.
+
+    Args:
+        path: YAML file path
+        data: Data to serialize
+        atomic: Use atomic write
+        encoding: Text encoding
+        default_flow_style: Use flow style (JSON-like) instead of block style
+    """
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError("PyYAML is required for YAML operations")
+
+    path = Path(path)
+
+    try:
+        content = yaml.dump(
+            data,
+            default_flow_style=default_flow_style,
+            allow_unicode=True,
+            sort_keys=False,
+        )
+
+        if atomic:
+            atomic_write_text(path, content, encoding=encoding)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding=encoding)
+
+        log.debug("Wrote YAML file", path=str(path), atomic=atomic)
+    except Exception as e:
+        log.error("Failed to write YAML file", path=str(path), error=str(e))
+        raise
+
+
+def read_toml(
+    path: Path | str,
+    default: Any = None,
+    encoding: str = "utf-8",
+) -> dict[str, Any]:
+    """Read TOML file with error handling.
+
+    Args:
+        path: TOML file path
+        default: Default value if file doesn't exist or is invalid
+        encoding: Text encoding
+
+    Returns:
+        Parsed TOML data or default value
+    """
+    try:
+        import tomllib
+    except ImportError:
+        try:
+            import tomli as tomllib
+        except ImportError:
+            log.warning("tomllib/tomli not available, returning default")
+            return default if default is not None else {}
+
+    content = safe_read_text(path, default="", encoding=encoding)
+
+    if not content:
+        log.debug("Empty or missing TOML file, returning default", path=str(path))
+        return default if default is not None else {}
+
+    try:
+        return tomllib.loads(content)
+    except Exception as e:
+        log.warning("Invalid TOML file", path=str(path), error=str(e))
+        return default if default is not None else {}
+
+
+def write_toml(
+    path: Path | str,
+    data: dict[str, Any],
+    atomic: bool = True,
+    encoding: str = "utf-8",
+) -> None:
+    """Write TOML file, optionally atomic.
+
+    Args:
+        path: TOML file path
+        data: Data to serialize (must be a dictionary)
+        atomic: Use atomic write
+        encoding: Text encoding
+    """
+    try:
+        import tomli_w
+    except ImportError:
+        raise ImportError("tomli-w is required for TOML write operations")
+
+    path = Path(path)
+
+    try:
+        content = tomli_w.dumps(data)
+
+        if atomic:
+            atomic_write_text(path, content, encoding=encoding)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding=encoding)
+
+        log.debug("Wrote TOML file", path=str(path), atomic=atomic)
+    except Exception as e:
+        log.error("Failed to write TOML file", path=str(path), error=str(e))
+        raise
+
+
+__all__ = [
+    "read_json",
+    "read_toml",
+    "read_yaml",
+    "write_json",
+    "write_toml",
+    "write_yaml",
+]