wuti-py-macos 0.2.8__tar.gz

wuti_py_macos-0.2.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WUTI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wuti_py_macos-0.2.8/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: wuti-py-macos
+Version: 0.2.8
+Summary: Clean, Pythonic utilities for macOS system operations
+Project-URL: Homepage, https://github.com/wuti-labs
+Author-email: Alex Qin <qinqinghai@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: daemon,dock,finder,macos,pasteboard,system,utility
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: wuti-py-util>=0.6.0

wuti_py_macos-0.2.8/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wuti-py-macos"
+dynamic = ["version"]
+description = "Clean, Pythonic utilities for macOS system operations"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Alex Qin", email = "qinqinghai@hotmail.com" }]
+keywords = ["macos", "system", "utility", "pasteboard", "finder", "dock", "daemon"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS :: MacOS X",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "wuti-py-util>=0.6.0",
+  "pydantic>=2.0.0",
+]
+
+
+[project.urls]
+Homepage = "https://github.com/wuti-labs"
+
+[dependency-groups]
+dev = [
+  "build",
+  "coverage[toml]>=7.13",
+  "hatchling",
+  "mypy>=1.18",
+  "pytest>=9.0.2",
+  "pytest-cov>=7.0",
+  "ruff>=0.15",
+]
+
+[tool.hatch.version]
+path = "src/wuti/macos/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wuti"]
+
+[tool.hatch.build.targets.sdist]
+ignore-vcs = true
+only-include = ["src/wuti"]
+exclude = [
+  "/.github",
+  "/tests",
+  "/README.md",
+]
+
+[tool.hatch.build.targets.sdist.hooks.custom]
+path = "scripts/hatch_sdist_hook.py"
+
+[tool.ruff]
+line-length = 140
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B017", "F841"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+mypy_path = "src"
+explicit_package_bases = true
+namespace_packages = true
+ignore_missing_imports = true
+warn_unused_configs = true
+check_untyped_defs = true
+allow_redefinition = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+addopts = "-v --cov=src --cov-branch --cov-report=html --cov-report=term --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*"]
+branch = true
+relative_files = true
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "def __repr__"]
+fail_under = 100

wuti_py_macos-0.2.8/src/wuti/macos/__init__.py

@@ -0,0 +1,29 @@
+"""wuti-py-macos: A clean and simple Python library for macOS system operations.
+
+This package provides utilities for managing various macOS system components
+including Finder, Dock, Launchpad, daemons, pasteboard, and more.
+"""
+
+from . import (
+    cleanup,
+    daemon,
+    dock,
+    finder,
+    pasteboard,
+    pkgutil,
+    utils,
+)
+
+__version__ = "0.2.8"
+__author__ = "Alex Qin"
+__email__ = "qinqinghai@hotmail.com"
+
+__all__ = [
+    "cleanup",
+    "daemon",
+    "dock",
+    "finder",
+    "pasteboard",
+    "pkgutil",
+    "utils",
+]

wuti_py_macos-0.2.8/src/wuti/macos/cleanup.py

@@ -0,0 +1,187 @@
+"""Module for system file and cache cleanup on macOS.
+
+This module provides functions for cleaning up:
+- Desktop Service Store (.DS_Store) files
+- Icon cache files
+- Icon services cache
+"""
+
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from wuti.util.log import notice, warning
+
+from .constants import ICON_SERVICES_CACHE_PATH
+from .finder import Finder, get_system_paths
+from .utils import CommandRunner, handle_keyboard_interrupt, handle_runtime_error
+
+# Cleanup patterns
+DS_STORE_PATTERNS = [".DS_Store", "**/.DS_Store"]
+ICONCACHE_PATTERNS = ["**/com.apple.dock.iconcache"]
+ICONSERVICES_PATTERNS = ["**/com.apple.iconservices"]
+
+_CLEANUP_DS_STORE_OPERATION = "cleanup Desktop Service Store files"
+
+_finder_instance: Optional[Finder] = None
+
+
+@dataclass
+class PruningMetrics:
+    removed_files: int = 0
+    removed_dirs: int = 0
+
+    def print_summary(self) -> None:
+        notice(f"Cleaned {self.removed_files} Desktop Service Store files; removed {self.removed_dirs} empty directories.")
+
+
+def _delete_ds_store_files(root: str, stats: PruningMetrics) -> None:
+    """Remove ``.DS_Store`` under *root* (top-down: shallow first)."""
+    for dirpath, _dirs, filenames in os.walk(root, topdown=True, followlinks=False):
+        if ".DS_Store" not in filenames:
+            continue
+        target = os.path.join(dirpath, ".DS_Store")
+        try:
+            os.remove(target)
+            stats.removed_files += 1
+        except OSError as e:
+            warning(f"Failed to remove '{target}': {e}")
+
+
+def _rmdir_empty_dirs_under(root: str, stats: PruningMetrics) -> None:
+    """Remove empty directories under *root*, excluding *root* itself (bottom-up)."""
+    for dirpath, _, _ in os.walk(root, topdown=False, followlinks=False):
+        if os.path.realpath(dirpath) == root:
+            continue
+        try:
+            if os.listdir(dirpath):
+                continue
+            os.rmdir(dirpath)
+            stats.removed_dirs += 1
+        except OSError as e:
+            warning(f"Failed to rmdir '{dirpath}': {e}")
+
+
+def _get_finder() -> Finder:
+    """Get or create a cached Finder instance.
+
+    Returns:
+        Finder instance for file operations.
+    """
+    global _finder_instance
+    if _finder_instance is None:
+        _finder_instance = Finder()
+    return _finder_instance
+
+
+def _private_var_folders() -> str:
+    """Path under which icon cache / icon services cleanup runs."""
+    return get_system_paths()["private_var_folders"]
+
+
+@handle_runtime_error(_CLEANUP_DS_STORE_OPERATION)
+def cleanup_ds_store(*, remove_empty_dirs: bool = False) -> Tuple[int, int]:
+    """Clean up macOS Desktop Service Store files.
+
+    Args:
+        remove_empty_dirs: If True, remove directories that become empty after .DS_Store removal
+            (excluding the scan root). If False, only delete .DS_Store files.
+
+    Returns:
+        Tuple of (number of .DS_Store files removed, number of empty directories removed).
+
+    Raises:
+        RuntimeError: If the cleanup operation fails.
+        KeyboardInterrupt: Re-raised after printing a summary of progress so far.
+
+    Note:
+        On Ctrl+C, prints the same summary line as on normal completion, then re-raises.
+    """
+    root = os.path.abspath(".")
+    stats = PruningMetrics()
+
+    def _on_interrupt(_: str) -> None:
+        stats.print_summary()
+
+    @handle_keyboard_interrupt(_CLEANUP_DS_STORE_OPERATION, on_interrupt=_on_interrupt)
+    def _run_phases() -> None:
+        _delete_ds_store_files(root, stats)
+        if remove_empty_dirs:
+            _rmdir_empty_dirs_under(root, stats)
+
+    _run_phases()
+    stats.print_summary()
+    return (stats.removed_files, stats.removed_dirs)
+
+
+def superuser_clean_icon_services() -> None:
+    """Delete the icon services cache (requires superuser privileges).
+
+    Raises:
+        subprocess.CalledProcessError: If the rm command fails.
+        RuntimeError: If icon services cache cannot be cleaned.
+    """
+    try:
+        CommandRunner.run(["rm", "-rf", ICON_SERVICES_CACHE_PATH], check=True)
+        notice("Icon services cache has been cleaned (superuser).")
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(f"Failed to clean icon services cache: {e.stderr}") from e
+    except Exception as e:
+        raise RuntimeError(f"Failed to clean icon services cache: {e}") from e
+
+
+@handle_runtime_error("clean icon cache")
+def superuser_clean_icon_cache() -> None:
+    """Delete the icon caches (requires superuser privileges).
+
+    Raises:
+        RuntimeError: If icon cache cannot be cleaned.
+    """
+    finder = _get_finder()
+    finder.cleanup_recursive(_private_var_folders(), ICONCACHE_PATTERNS)
+    notice("Icon cache has been cleaned (superuser).")
+
+
+@handle_runtime_error("find icon cache folders")
+def find_icon_cache() -> list[str]:
+    """Find the icon cache folders.
+
+    Returns:
+        List of icon cache folder paths.
+
+    Raises:
+        RuntimeError: If icon cache folders cannot be found.
+    """
+    finder = _get_finder()
+    return finder.find_recursive(_private_var_folders(), ICONCACHE_PATTERNS)
+
+
+@handle_runtime_error("clean icon services cache")
+def clean_icon_services() -> int:
+    """Delete the icon services cache.
+
+    Returns:
+        Number of icon service items cleaned.
+
+    Raises:
+        RuntimeError: If icon services cache cannot be cleaned.
+    """
+    finder = _get_finder()
+    cleanup_count = finder.cleanup_recursive(_private_var_folders(), ICONSERVICES_PATTERNS)
+    notice(f"Cleaned {cleanup_count} icon service items.")
+    return cleanup_count
+
+
+@handle_runtime_error("find icon services cache folders")
+def find_icon_services() -> list[str]:
+    """Find the icon services cache folders.
+
+    Returns:
+        List of icon services cache folder paths.
+
+    Raises:
+        RuntimeError: If icon services cache folders cannot be found.
+    """
+    finder = _get_finder()
+    return finder.find_recursive(_private_var_folders(), ICONSERVICES_PATTERNS)

wuti_py_macos-0.2.8/src/wuti/macos/constants.py

@@ -0,0 +1,15 @@
+"""Shared constants for wuti.macos."""
+
+# Process names
+FINDER = "Finder"
+DOCK = "Dock"
+
+# Preference domains
+DOMAIN_DOCK = "com.apple.dock"
+DOMAIN_FINDER = "com.apple.finder"
+
+# Delays
+APP_RESTART_DELAY = 0.2
+
+# Paths
+ICON_SERVICES_CACHE_PATH = "/Library/Caches/com.apple.iconservices.store"

wuti_py_macos-0.2.8/src/wuti/macos/daemon.py

@@ -0,0 +1,280 @@
+"""Module for managing daemons and agents on macOS."""
+
+import glob
+import os
+from functools import cached_property
+from typing import Optional
+
+from wuti.util.log import debug, indent, notice, unindent, warning
+from wuti.util.validation import validate_string_input
+
+from .finder import Finder, get_daemon_paths
+from .utils import CommandRunner, handle_runtime_error
+
+
+class Daemon:
+    """Manages daemons and agents on macOS.
+
+    Provides comprehensive methods to inspect, manage, and control macOS daemons and agents
+    through their configuration files in various LaunchDaemons and LaunchAgents directories.
+
+    This class offers functionality to:
+    - List all daemons and agents
+    - Search for specific daemons/agents
+    - Get detailed information about daemon configurations
+    - Control daemon states (load/unload)
+    - Filter and categorize daemons by type
+    """
+
+    def __init__(self):
+        """Initialize the Daemon instance."""
+        debug("Initializing Daemon instance")
+
+    @cached_property
+    def finder(self) -> Finder:
+        """The finder object for file operations.
+
+        Returns:
+            Finder: An instance for file operations.
+        """
+        return Finder()
+
+    @cached_property
+    def daemon_paths(self) -> dict[str, str]:
+        """Daemon and agent paths.
+
+        Returns:
+            dict[str, str]: A dictionary mapping path names to their absolute paths.
+        """
+        return get_daemon_paths()
+
+    @handle_runtime_error("print daemon and agent information")
+    def print_all(self) -> None:
+        """Prints all daemons and agents from all configured paths.
+
+        Raises:
+            RuntimeError: If any daemon or agent directory cannot be accessed.
+        """
+        debug("Printing all daemons and agents")
+        for path_name, path in self.daemon_paths.items():
+            notice(f"=== {path_name.replace('_', ' ').title()} ===")
+            try:
+                self.finder.print_flat_list(path)
+            except Exception as e:
+                warning(f"Failed to access {path_name} at '{path}': {e}")
+                continue
+
+    def get_daemon_files(self, path_name: Optional[str] = None) -> list[str]:
+        """Get all daemon/agent plist files from specified or all paths.
+
+        Args:
+            path_name: Specific path name to search in. If None, searches all paths.
+
+        Returns:
+            list[str]: List of plist file paths.
+
+        Raises:
+            ValueError: If path_name is invalid.
+            RuntimeError: If file listing fails.
+        """
+        debug(f"Getting daemon files from path: {path_name or 'all'}")
+
+        all_files = []
+
+        if path_name:
+            if path_name not in self.daemon_paths:
+                raise ValueError(f"Invalid path name '{path_name}'. Available paths: {list(self.daemon_paths.keys())}")
+            paths_to_search = {path_name: self.daemon_paths[path_name]}
+        else:
+            paths_to_search = self.daemon_paths
+
+        for path_name, path in paths_to_search.items():
+            try:
+                if os.path.exists(path):
+                    plist_files = glob.glob(os.path.join(path, "*.plist"))
+                    all_files.extend(plist_files)
+                    debug(f"Found {len(plist_files)} plist files in {path_name}")
+                else:
+                    warning(f"Path does not exist: {path}")
+            except Exception as e:
+                warning(f"Failed to list files in {path_name} at '{path}': {e}")
+
+        return sorted(all_files)
+
+    def search_daemons(self, pattern: str, path_name: Optional[str] = None) -> list[str]:
+        """Search for daemons/agents matching a pattern.
+
+        Args:
+            pattern: Search pattern to match against plist filenames.
+            path_name: Specific path name to search in. If None, searches all paths.
+
+        Returns:
+            list[str]: List of matching plist file paths.
+
+        Raises:
+            ValueError: If pattern is empty or path_name is invalid.
+        """
+        pattern = validate_string_input(pattern, "pattern")
+        debug(f"Searching for daemons matching pattern: '{pattern}'")
+
+        all_files = self.get_daemon_files(path_name)
+        matching_files = [f for f in all_files if pattern.lower() in os.path.basename(f).lower()]
+
+        debug(f"Found {len(matching_files)} matching files")
+        return matching_files
+
+    def get_daemon_info(self, plist_path: str) -> dict[str, str | bool | int | float | None]:
+        """Get detailed information about a daemon/agent from its plist file.
+
+        Args:
+            plist_path: Path to the plist file.
+
+        Returns:
+            dict containing daemon information including:
+            - name: Daemon name
+            - path: Full path to plist
+            - exists: Whether the file exists
+            - size: File size in bytes
+            - modified: Last modification time
+
+        Raises:
+            ValueError: If plist_path is invalid.
+        """
+        plist_path = validate_string_input(plist_path, "plist_path")
+        debug(f"Getting daemon info for: {plist_path}")
+
+        info: dict[str, str | bool | int | float | None] = {
+            "name": os.path.basename(plist_path),
+            "path": plist_path,
+            "exists": False,
+            "size": 0,
+            "modified": None,
+        }
+
+        try:
+            if os.path.exists(plist_path):
+                stat_info = os.stat(plist_path)
+                info.update({"exists": True, "size": stat_info.st_size, "modified": stat_info.st_mtime})
+        except OSError as e:
+            warning(f"Failed to get info for {plist_path}: {e}")
+
+        return info
+
+    def get_daemon_status(self, daemon_name: str) -> dict[str, str | bool]:
+        """Get the current status of a daemon/agent.
+
+        Args:
+            daemon_name: Name of the daemon (without .plist extension).
+
+        Returns:
+            dict containing status information:
+            - loaded: Whether the daemon is currently loaded
+            - status: Human-readable status string
+
+        Raises:
+            ValueError: If daemon_name is invalid.
+        """
+        daemon_name = validate_string_input(daemon_name, "daemon_name")
+        debug(f"Getting status for daemon: {daemon_name}")
+
+        # Remove .plist extension if present
+        if daemon_name.endswith(".plist"):
+            daemon_name = daemon_name[:-6]
+
+        try:
+            # Use launchctl to check if daemon is loaded
+            result = CommandRunner.run(["launchctl", "list", daemon_name], check=False)
+            loaded = result.returncode == 0 and daemon_name in result.stdout
+
+            status = "Loaded" if loaded else "Not loaded"
+
+            return {"loaded": loaded, "status": status, "name": daemon_name}
+        except Exception as e:
+            warning(f"Failed to get status for daemon {daemon_name}: {e}")
+            return {"loaded": False, "status": f"Error: {e}", "name": daemon_name}
+
+    def load_daemon(self, plist_path: str) -> bool:
+        """Load a daemon/agent using launchctl.
+
+        Args:
+            plist_path: Path to the plist file.
+
+        Returns:
+            bool: True if successful, False otherwise.
+
+        Raises:
+            ValueError: If plist_path is invalid.
+        """
+        plist_path = validate_string_input(plist_path, "plist_path")
+        debug(f"Loading daemon from: {plist_path}")
+
+        if not os.path.exists(plist_path):
+            warning(f"Plist file does not exist: {plist_path}")
+            return False
+
+        try:
+            CommandRunner.run(["launchctl", "load", plist_path])
+            notice(f"Successfully loaded daemon: {os.path.basename(plist_path)}")
+            return True
+        except Exception as e:
+            warning(f"Failed to load daemon {plist_path}: {e}")
+            return False
+
+    def unload_daemon(self, plist_path: str) -> bool:
+        """Unload a daemon/agent using launchctl.
+
+        Args:
+            plist_path: Path to the plist file.
+
+        Returns:
+            bool: True if successful, False otherwise.
+
+        Raises:
+            ValueError: If plist_path is invalid.
+        """
+        plist_path = validate_string_input(plist_path, "plist_path")
+        debug(f"Unloading daemon from: {plist_path}")
+
+        try:
+            CommandRunner.run(["launchctl", "unload", plist_path])
+            notice(f"Successfully unloaded daemon: {os.path.basename(plist_path)}")
+            return True
+        except Exception as e:
+            warning(f"Failed to unload daemon {plist_path}: {e}")
+            return False
+
+    def get_daemon_summary(self) -> dict[str, int]:
+        """Get a summary count of daemons and agents by path.
+
+        Returns:
+            dict[str, int]: Dictionary mapping path names to file counts.
+        """
+        debug("Generating daemon summary")
+        summary = {}
+
+        for path_name, path in self.daemon_paths.items():
+            try:
+                if os.path.exists(path):
+                    plist_files = glob.glob(os.path.join(path, "*.plist"))
+                    summary[path_name] = len(plist_files)
+                else:
+                    summary[path_name] = 0
+            except Exception as e:
+                warning(f"Failed to count files in {path_name}: {e}")
+                summary[path_name] = 0
+
+        return summary
+
+    def print_summary(self) -> None:
+        """Print a summary of all daemons and agents by path."""
+        debug("Printing daemon summary")
+        summary = self.get_daemon_summary()
+
+        notice("=== Daemon and Agent Summary ===")
+        indent()
+        total = 0
+        for path_name, count in summary.items():
+            notice(f"{path_name.replace('_', ' ').title()}: {count} files")
+            total += count
+        unindent()
+        notice(f"Total: {total} daemon/agent files")