zerofilesystem 0.1.0__py3-none-any.whl

zerofilesystem/__init__.py

@@ -0,0 +1,326 @@
+"""zerofilesystem - Cross-platform file system utilities.
+
+Usage:
+    import zerofilesystem as zo
+
+    # Read/write files
+    zo.write_text("file.txt", "Hello World")
+    content = zo.read_text("file.txt")
+
+    # JSON operations
+    zo.write_json("data.json", {"key": "value"})
+    data = zo.read_json("data.json")
+
+    # Find files
+    py_files = zo.find_files(".", pattern="**/*.py")
+
+    # File locking
+    with zo.FileLock("/tmp/my.lock"):
+        # Critical section
+        pass
+
+    # Transactions
+    with zo.FileTransaction() as tx:
+        tx.write_text("file1.txt", "content1")
+        tx.write_text("file2.txt", "content2")
+
+    # Archives
+    zo.create_zip("./src", "backup.zip")
+    zo.extract("backup.zip", "./extracted")
+
+Copyright (c) 2025 Francesco Favi
+License: MIT
+"""
+
+from zerofilesystem._platform import IS_LINUX, IS_MACOS, IS_UNIX, IS_WINDOWS, Pathish
+from zerofilesystem.classes import (
+    ArchiveError,
+    ArchiveHandler,
+    DirectoryOps,
+    EventType,
+    FileCleaner,
+    FileFinder,
+    FileHasher,
+    FileIO,
+    FileLock,
+    FileLockedError,
+    FileMeta,
+    FilePermissions,
+    FileSync,
+    FileTransaction,
+    FileUtils,
+    FileWatcher,
+    Finder,
+    GzipHandler,
+    HashMismatchError,
+    IntegrityChecker,
+    IntegrityError,
+    InvalidPathError,
+    JsonHandler,
+    PathUtils,
+    PermissionDeniedError,
+    SecureDeleteError,
+    SecureOps,
+    SyncError,
+    TransactionError,
+    Watcher,
+    WatchEvent,
+    ZeroOSError,
+)
+from zerofilesystem.zerofilesystem import ZeroOS
+
+__version__ = "0.1.0"
+__author__ = "Francesco Favi"
+__email__ = "14098835+francescofavi@users.noreply.github.com"
+
+# =============================================================================
+# BASIC I/O
+# =============================================================================
+
+read_text = FileIO.read_text
+write_text = FileIO.write_text
+read_bytes = FileIO.read_bytes
+write_bytes = FileIO.write_bytes
+
+# =============================================================================
+# JSON
+# =============================================================================
+
+read_json = JsonHandler.read_json
+write_json = JsonHandler.write_json
+
+# =============================================================================
+# GZIP
+# =============================================================================
+
+gzip_compress = GzipHandler.compress
+gzip_decompress = GzipHandler.decompress
+
+# =============================================================================
+# DISCOVERY
+# =============================================================================
+
+find_files = FileFinder.find_files
+walk_files = FileFinder.walk_files
+is_hidden = FileFinder.is_hidden
+
+# =============================================================================
+# CLEANUP
+# =============================================================================
+
+delete_files = FileCleaner.delete_files
+delete_empty_dirs = FileCleaner.delete_empty_dirs
+
+# =============================================================================
+# SYNC
+# =============================================================================
+
+move_if_absent = FileSync.move_if_absent
+copy_if_newer = FileSync.copy_if_newer
+
+# =============================================================================
+# HASH
+# =============================================================================
+
+file_hash = FileHasher.file_hash
+
+# =============================================================================
+# META
+# =============================================================================
+
+ensure_dir = FileMeta.ensure_dir
+touch = FileMeta.touch
+file_size = FileMeta.file_size
+disk_usage = FileMeta.disk_usage
+
+# =============================================================================
+# UTILS
+# =============================================================================
+
+safe_filename = FileUtils.safe_filename
+atomic_write = FileUtils.atomic_write
+
+# =============================================================================
+# PATH UTILS
+# =============================================================================
+
+normalize_path = PathUtils.normalize
+to_absolute = PathUtils.to_absolute
+to_relative = PathUtils.to_relative
+to_posix = PathUtils.to_posix
+expand_path = PathUtils.expand
+is_subpath = PathUtils.is_subpath
+common_path = PathUtils.common_path
+validate_path = PathUtils.validate_path
+
+# =============================================================================
+# PERMISSIONS
+# =============================================================================
+
+get_metadata = FilePermissions.get_metadata
+set_readonly = FilePermissions.set_readonly
+set_hidden = FilePermissions.set_hidden
+set_executable = FilePermissions.set_executable
+set_permissions = FilePermissions.set_permissions
+copy_permissions = FilePermissions.copy_permissions
+set_timestamps = FilePermissions.set_timestamps
+mode_to_string = FilePermissions.mode_to_string
+string_to_mode = FilePermissions.string_to_mode
+
+# =============================================================================
+# DIRECTORY OPS
+# =============================================================================
+
+copy_tree = DirectoryOps.copy_tree
+move_tree = DirectoryOps.move_tree
+sync_dirs = DirectoryOps.sync
+temp_directory = DirectoryOps.temp_directory
+tree_size = DirectoryOps.tree_size
+tree_file_count = DirectoryOps.tree_file_count
+flatten_tree = DirectoryOps.flatten
+
+# =============================================================================
+# INTEGRITY
+# =============================================================================
+
+directory_hash = IntegrityChecker.directory_hash
+create_manifest = IntegrityChecker.create_manifest
+save_manifest = IntegrityChecker.save_manifest
+load_manifest = IntegrityChecker.load_manifest
+verify_manifest = IntegrityChecker.verify_manifest
+verify_file = IntegrityChecker.verify_file
+compare_directories = IntegrityChecker.compare_directories
+snapshot_hash = IntegrityChecker.snapshot_hash
+
+# =============================================================================
+# SECURE
+# =============================================================================
+
+secure_delete = SecureOps.secure_delete
+secure_delete_directory = SecureOps.secure_delete_directory
+private_directory = SecureOps.private_directory
+create_private_file = SecureOps.create_private_file
+
+# =============================================================================
+# ARCHIVE
+# =============================================================================
+
+create_tar = ArchiveHandler.create_tar
+create_zip = ArchiveHandler.create_zip
+extract_tar = ArchiveHandler.extract_tar
+extract_zip = ArchiveHandler.extract_zip
+extract = ArchiveHandler.extract
+list_archive = ArchiveHandler.list_archive
+
+# =============================================================================
+# __all__
+# =============================================================================
+
+__all__ = [
+    # Facade class
+    "ZeroOS",
+    # Platform constants
+    "IS_WINDOWS",
+    "IS_MACOS",
+    "IS_LINUX",
+    "IS_UNIX",
+    "Pathish",
+    # Classes (for advanced usage)
+    "Finder",
+    "Watcher",
+    "WatchEvent",
+    "EventType",
+    "FileLock",
+    "FileTransaction",
+    "FileWatcher",  # Legacy
+    # Exceptions
+    "ZeroOSError",
+    "FileLockedError",
+    "InvalidPathError",
+    "HashMismatchError",
+    "IntegrityError",
+    "TransactionError",
+    "ArchiveError",
+    "PermissionDeniedError",
+    "SecureDeleteError",
+    "SyncError",
+    # Basic I/O
+    "read_text",
+    "write_text",
+    "read_bytes",
+    "write_bytes",
+    # JSON
+    "read_json",
+    "write_json",
+    # Gzip
+    "gzip_compress",
+    "gzip_decompress",
+    # Discovery
+    "find_files",
+    "walk_files",
+    "is_hidden",
+    # Cleanup
+    "delete_files",
+    "delete_empty_dirs",
+    # Sync
+    "move_if_absent",
+    "copy_if_newer",
+    # Hash
+    "file_hash",
+    # Meta
+    "ensure_dir",
+    "touch",
+    "file_size",
+    "disk_usage",
+    # Utils
+    "safe_filename",
+    "atomic_write",
+    # Path utils
+    "normalize_path",
+    "to_absolute",
+    "to_relative",
+    "to_posix",
+    "expand_path",
+    "is_subpath",
+    "common_path",
+    "validate_path",
+    # Permissions
+    "get_metadata",
+    "set_readonly",
+    "set_hidden",
+    "set_executable",
+    "set_permissions",
+    "copy_permissions",
+    "set_timestamps",
+    "mode_to_string",
+    "string_to_mode",
+    # Directory ops
+    "copy_tree",
+    "move_tree",
+    "sync_dirs",
+    "temp_directory",
+    "tree_size",
+    "tree_file_count",
+    "flatten_tree",
+    # Integrity
+    "directory_hash",
+    "create_manifest",
+    "save_manifest",
+    "load_manifest",
+    "verify_manifest",
+    "verify_file",
+    "compare_directories",
+    "snapshot_hash",
+    # Secure
+    "secure_delete",
+    "secure_delete_directory",
+    "private_directory",
+    "create_private_file",
+    # Archive
+    "create_tar",
+    "create_zip",
+    "extract_tar",
+    "extract_zip",
+    "extract",
+    "list_archive",
+]

zerofilesystem/_platform.py

@@ -0,0 +1,13 @@
+"""Platform detection constants and shared types."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+IS_WINDOWS: bool = sys.platform == "win32"
+IS_MACOS: bool = sys.platform == "darwin"
+IS_LINUX: bool = sys.platform.startswith("linux")
+IS_UNIX: bool = IS_MACOS or IS_LINUX
+
+Pathish = str | Path

zerofilesystem/classes/__init__.py

@@ -0,0 +1,84 @@
+"""Helper classes for file operations."""
+
+from zerofilesystem.classes.archive_handler import ArchiveHandler
+from zerofilesystem.classes.directory_ops import DirectoryOps
+from zerofilesystem.classes.exceptions import (
+    ArchiveError,
+    FileLockedError,
+    HashMismatchError,
+    IntegrityError,
+    InvalidPathError,
+    PermissionDeniedError,
+    SecureDeleteError,
+    SyncError,
+    TransactionError,
+    ZeroOSError,
+)
+from zerofilesystem.classes.file_lock import FileLock
+from zerofilesystem.classes.file_permissions import FilePermissions
+from zerofilesystem.classes.file_transaction import FileTransaction
+from zerofilesystem.classes.files import FileCleaner, FileFinder, FileHasher, FileMeta, FileSync
+from zerofilesystem.classes.finder import Finder
+from zerofilesystem.classes.integrity_checker import IntegrityChecker
+from zerofilesystem.classes.io import FileIO, FileUtils, GzipHandler, JsonHandler
+from zerofilesystem.classes.path_utils import PathUtils
+from zerofilesystem.classes.secure_ops import SecureOps
+from zerofilesystem.classes.watcher import (
+    EventType,
+    FileWatcher,
+    Watcher,
+    WatchEvent,
+    WatchEventType,
+)
+
+# Legacy alias
+WatchEventOld = WatchEvent
+
+__all__ = [
+    # Core I/O
+    "FileIO",
+    "JsonHandler",
+    "GzipHandler",
+    "FileUtils",
+    # Discovery and cleanup
+    "Finder",
+    "FileFinder",
+    "FileCleaner",
+    # Sync and file operations
+    "FileSync",
+    "FileHasher",
+    "FileMeta",
+    "FileLock",
+    # Path utilities
+    "PathUtils",
+    # Permissions and metadata
+    "FilePermissions",
+    # Directory operations
+    "DirectoryOps",
+    # Integrity verification
+    "IntegrityChecker",
+    # Transactions
+    "FileTransaction",
+    # Security
+    "SecureOps",
+    # Archives
+    "ArchiveHandler",
+    # File watching
+    "Watcher",
+    "WatchEvent",
+    "EventType",
+    "FileWatcher",  # Legacy
+    "WatchEventType",  # Legacy alias
+    "WatchEventOld",  # Legacy alias
+    # Exceptions
+    "ZeroOSError",
+    "FileLockedError",
+    "InvalidPathError",
+    "HashMismatchError",
+    "IntegrityError",
+    "TransactionError",
+    "ArchiveError",
+    "PermissionDeniedError",
+    "SecureDeleteError",
+    "SyncError",
+]

zerofilesystem/classes/_internal.py

@@ -0,0 +1,107 @@
+"""Shared internal utilities for zerofilesystem classes.
+
+Not part of the public API. Used by finder.py, watcher.py, and other modules
+to avoid code duplication.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from zerofilesystem._platform import IS_WINDOWS
+
+# =============================================================================
+# SHARED CONSTANTS
+# =============================================================================
+
+FILE_ATTRIBUTE_HIDDEN: int = 0x2
+FILE_ATTRIBUTE_READONLY: int = 0x1
+
+MAX_RENAME_CONFLICTS: int = 10000
+
+HASH_CHUNK_SIZE: int = 1024 * 1024  # 1 MB
+
+# Size unit multipliers (bytes)
+SIZE_UNITS: dict[str, int] = {
+    "B": 1,
+    "KB": 1024,
+    "MB": 1024 * 1024,
+    "GB": 1024 * 1024 * 1024,
+    "TB": 1024 * 1024 * 1024 * 1024,
+    "K": 1024,
+    "M": 1024 * 1024,
+    "G": 1024 * 1024 * 1024,
+    "T": 1024 * 1024 * 1024 * 1024,
+}
+
+
+# =============================================================================
+# SHARED FUNCTIONS
+# =============================================================================
+
+
+def parse_size(size: int | str) -> int:
+    """Parse size string like '1KB', '5MB', '1.5GB' to bytes."""
+    if isinstance(size, int):
+        return size
+
+    size = size.strip().upper()
+
+    match = re.match(r"^([\d.]+)\s*([A-Z]*B?)$", size)
+    if not match:
+        raise ValueError(f"Invalid size format: {size}")
+
+    value = float(match.group(1))
+    unit = match.group(2) or "B"
+
+    if unit not in SIZE_UNITS:
+        raise ValueError(f"Unknown size unit: {unit}")
+
+    return int(value * SIZE_UNITS[unit])
+
+
+def parse_datetime(dt: datetime | str | timedelta) -> datetime:
+    """Parse datetime from various formats."""
+    if isinstance(dt, datetime):
+        return dt
+
+    if isinstance(dt, timedelta):
+        return datetime.now() - dt
+
+    dt_str = dt.strip()
+
+    formats = [
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%d %H:%M",
+        "%Y-%m-%d",
+        "%Y/%m/%d %H:%M:%S",
+        "%Y/%m/%d",
+        "%d-%m-%Y",
+        "%d/%m/%Y",
+    ]
+
+    for fmt in formats:
+        try:
+            return datetime.strptime(dt_str, fmt)
+        except ValueError:
+            continue
+
+    raise ValueError(f"Cannot parse datetime: {dt}")
+
+
+def is_hidden(path: Path) -> bool:
+    """Check if file is hidden (cross-platform)."""
+    if path.name.startswith("."):
+        return True
+
+    if IS_WINDOWS:
+        try:
+            attrs = os.stat(path).st_file_attributes  # type: ignore[attr-defined]
+            return bool(attrs & FILE_ATTRIBUTE_HIDDEN)
+        except (AttributeError, OSError):
+            return False
+
+    return False