pysfi 0.1.11__py3-none-any.whl → 0.1.13__py3-none-any.whl

sfi/taskkill/taskkill.py

@@ -6,40 +6,66 @@ import logging
 import subprocess
 import sys
 from dataclasses import dataclass
+from typing import Final
 
+# Configure logging
 logging.basicConfig(level=logging.INFO, format="%(message)s")
 logger = logging.getLogger(__name__)
 
+# Constants
+DEFAULT_MATCH_THRESHOLD: Final[int] = 10
+FORCE_MATCH_THRESHOLD: Final[int] = 1000
+PROCESS_LIST_TIMEOUT: Final[int] = 10
+ENCODING_ATTEMPTS: Final[tuple[str, ...]] = ("gbk", "utf8")
+
+# Global state (consider refactoring to class-based approach in future)
 _cached_process_list: list[ProcessInfo] = []
 _processes_cached: bool = False
-_max_match_threshold: int = 10  # Maximum number of processes to match without confirmation
+_max_match_threshold: int = DEFAULT_MATCH_THRESHOLD
 
 
 @dataclass
 class ProcessInfo:
-    """Process information class."""
+    """Represents information about a system process.
+
+    Attributes:
+        name: The name of the process executable
+        pid: The process identifier as string
+    """
 
     name: str
     pid: str
 
 
 def get_matched_process(process_name: str) -> list[ProcessInfo]:
-    """Get the list of matching processes.
+    """Get processes matching the given pattern.
+
+    Performs case-insensitive wildcard matching against process names.
+
+    Args:
+        process_name: Pattern to match against process names (supports wildcards)
 
     Returns:
-        list[ProcessInfo]: List of matched processes
+        List of ProcessInfo objects that match the pattern
     """
-    return [p for p in _cached_process_list if fnmatch.fnmatch(p.name.lower(), process_name.lower())]
+    pattern = process_name.lower()
+    return [p for p in _cached_process_list if fnmatch.fnmatch(p.name.lower(), pattern)]
 
 
 def get_process_list(force_refresh: bool = False) -> None:
-    """Get the list of processes.
+    """Retrieve the current list of system processes.
+
+    Caches the process list to avoid repeated system calls. Use force_refresh=True
+    to bypass the cache when fresh data is required.
 
     Args:
-        force_refresh: Force refresh the process list even if cached.
+        force_refresh: If True, forces refreshing the process list even if cached.
+            Defaults to False.
     """
-    global _processes_cached
+    global _processes_cached, _cached_process_list
+
     if _processes_cached and not force_refresh:
+        logger.debug("Using cached process list")
         return
 
     _cached_process_list.clear()
@@ -48,9 +74,18 @@ def get_process_list(force_refresh: bool = False) -> None:
     else:
         _get_process_list_unix()
     _processes_cached = True
+    logger.debug(f"Retrieved {len(_cached_process_list)} processes")
 
 
 def _get_process_list_windows(encoding: str = "gbk") -> None:
+    """Retrieve process list on Windows using tasklist command.
+
+    Attempts to decode output with specified encoding, falling back to alternatives
+    if decoding fails.
+
+    Args:
+        encoding: Text encoding to try first. Defaults to "gbk".
+    """
     try:
         result = subprocess.run(
             ["tasklist", "/fo", "csv", "/nh"],
@@ -58,7 +93,7 @@ def _get_process_list_windows(encoding: str = "gbk") -> None:
             text=True,
             encoding=encoding,
             check=True,
-            timeout=10,  # Add timeout to prevent infinite wait
+            timeout=PROCESS_LIST_TIMEOUT,
         )
         logger.debug(f"Decoded using {encoding}")
         for line in result.stdout.strip().split("\n"):
@@ -69,37 +104,46 @@ def _get_process_list_windows(encoding: str = "gbk") -> None:
                     pid = parts[1].strip('"')
                     _cached_process_list.append(ProcessInfo(name, pid))
     except UnicodeDecodeError:
-        logger.warning(f"Failed to decode using {encoding} encoding, trying other encoding")
-        if encoding == "utf8":
+        logger.warning(
+            f"Failed to decode using {encoding} encoding, trying other encoding"
+        )
+        if encoding == ENCODING_ATTEMPTS[-1]:
             logger.error("All encoding attempts failed, unable to get process list")
             return
-        # If GBK encoding fails, try UTF-8
-        try:
-            _get_process_list_windows(encoding="utf8")
-            logger.debug("Decoded using utf8")
-        except (
-            subprocess.SubprocessError,
-            OSError,
-            ValueError,
-            UnicodeDecodeError,
-        ):
-            logger.error("Failed to get process list")
-            return
+        # Try next encoding in sequence
+        next_encoding_idx = ENCODING_ATTEMPTS.index(encoding) + 1
+        if next_encoding_idx < len(ENCODING_ATTEMPTS):
+            next_encoding = ENCODING_ATTEMPTS[next_encoding_idx]
+            try:
+                _get_process_list_windows(encoding=next_encoding)
+                logger.debug(f"Decoded using {next_encoding}")
+            except (
+                subprocess.SubprocessError,
+                OSError,
+                ValueError,
+                UnicodeDecodeError,
+            ):
+                logger.error("Failed to get process list after encoding fallback")
+                return
     except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
         logger.error(f"Failed to execute tasklist command: {e.__class__.__name__}")
         return
     except Exception as e:
-        logger.error(f"Unknown error occurred while getting process list: {e.__class__.__name__}")
+        logger.error(
+            f"Unknown error occurred while getting process list: {e.__class__.__name__}"
+        )
         return
 
 
 def _get_process_list_unix() -> None:
+    """Retrieve process list on Unix-like systems using ps command."""
     try:
         result = subprocess.run(
             ["ps", "-eo", "pid,comm", "--no-headers"],
             capture_output=True,
             text=True,
             check=True,
+            timeout=PROCESS_LIST_TIMEOUT,
         )
         for line in result.stdout.strip().split("\n"):
             if line:
@@ -108,17 +152,26 @@ def _get_process_list_unix() -> None:
                     pid = parts[0]
                     name = parts[1]
                     _cached_process_list.append(ProcessInfo(name, pid))
-    except (subprocess.SubprocessError, OSError, ValueError):
-        logger.error("Failed to get process list")
+    except (
+        subprocess.SubprocessError,
+        OSError,
+        ValueError,
+        subprocess.TimeoutExpired,
+    ) as e:
+        logger.error(f"Failed to get process list: {e.__class__.__name__}")
         return
 
 
 def kill_process(process_name: str, force_refresh: bool = True) -> None:
-    """Terminate process.
+    """Terminate processes matching the given name or pattern.
+
+    Implements safety mechanisms including match threshold limits to prevent
+    accidental mass termination of processes.
 
     Args:
-        process_name: Process name
-        force_refresh: Force refresh process list before killing (default True)
+        process_name: Process name or pattern to match (supports wildcards)
+        force_refresh: Whether to refresh the process list before matching.
+            Defaults to True.
     """
     get_process_list(force_refresh=force_refresh)
     matched_processes = get_matched_process(process_name)
@@ -142,19 +195,27 @@ def kill_process(process_name: str, force_refresh: bool = True) -> None:
     logger.info(
         f"Found {match_count} process(es) matching '{process_name}': {[m.name for m in matched_processes]}",
     )
-    try:
-        success_count = 0
-        for process in matched_processes:
-            if _kill_process_by_pid(process.pid):
-                logger.info(f"Successfully terminated process {process.name} (PID: {process.pid})")
-                success_count += 1
-            else:
-                logger.info(f"Failed to terminate process {process.name} (PID: {process.pid})")
-    except (subprocess.SubprocessError, OSError, ValueError):
-        logger.error("Failed to terminate process")
-        return
-    else:
-        logger.info(f"Successfully terminated {success_count} process(es) matching '{process_name}'")
+
+    success_count = 0
+    failure_count = 0
+
+    for process in matched_processes:
+        if _kill_process_by_pid(process.pid):
+            logger.info(
+                f"Successfully terminated process {process.name} (PID: {process.pid})"
+            )
+            success_count += 1
+        else:
+            logger.info(
+                f"Failed to terminate process {process.name} (PID: {process.pid})"
+            )
+            failure_count += 1
+
+    logger.info(
+        f"Successfully terminated {success_count} process(es) matching '{process_name}'"
+    )
+    if failure_count > 0:
+        logger.warning(f"Failed to terminate {failure_count} process(es)")
 
 
 def _kill_process_by_pid(pid: str) -> bool:
@@ -165,70 +226,118 @@ def _kill_process_by_pid(pid: str) -> bool:
 
 
 def _kill_process_by_pid_windows(pid: str) -> bool:
-    """Terminate process by PID on Windows.
+    """Terminate process by PID on Windows using taskkill command.
+
+    Args:
+        pid: Process identifier as string
 
     Returns:
-        bool: Whether the process was successfully terminated.
+        True if process was successfully terminated, False otherwise
     """
     try:
-        subprocess.run(
+        result = subprocess.run(
             ["taskkill", "/F", "/PID", pid],
             capture_output=True,
             text=True,
             check=True,
+            timeout=PROCESS_LIST_TIMEOUT,
         )
+        logger.debug(f"taskkill output: {result.stdout.strip()}")
         return True
-    except subprocess.CalledProcessError:
-        logger.error(f"Failed to terminate process PID {pid}")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to terminate process PID {pid}: {e}")
+        if e.stdout:
+            logger.debug(f"taskkill stdout: {e.stdout.strip()}")
+        if e.stderr:
+            logger.debug(f"taskkill stderr: {e.stderr.strip()}")
+        return False
+    except subprocess.TimeoutExpired:
+        logger.error(f"Timeout while terminating process PID {pid}")
         return False
 
 
 def _kill_process_by_pid_unix(pid: str) -> bool:
-    """Terminate process by PID on Unix/Linux.
+    """Terminate process by PID on Unix/Linux using kill command.
+
+    Args:
+        pid: Process identifier as string
 
     Returns:
-        bool: Whether the process was successfully terminated.
+        True if process was successfully terminated, False otherwise
     """
     try:
-        subprocess.run(
+        result = subprocess.run(
             ["kill", "-9", pid],
             capture_output=True,
             text=True,
             check=True,
+            timeout=PROCESS_LIST_TIMEOUT,
         )
+        logger.debug(f"kill output: {result.stdout.strip()}")
         return True
-    except subprocess.CalledProcessError:
-        logger.error(f"Failed to terminate process PID {pid}")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to terminate process PID {pid}: {e}")
+        if e.stdout:
+            logger.debug(f"kill stdout: {e.stdout.strip()}")
+        if e.stderr:
+            logger.debug(f"kill stderr: {e.stderr.strip()}")
+        return False
+    except subprocess.TimeoutExpired:
+        logger.error(f"Timeout while terminating process PID {pid}")
         return False
 
 
 def main() -> None:
-    """Terminate process."""
-    parser = argparse.ArgumentParser()
-    parser.add_argument("processes", type=str, nargs="+", help="Process to terminate.")
-    parser.add_argument("--debug", "-d", action="store_true", help="Enable debug mode.")
+    """Main entry point for the taskkill command-line interface.
+
+    Terminates processes by name or pattern with cross-platform support.
+    """
+    parser = argparse.ArgumentParser(
+        description="Cross-platform process termination utility",
+        epilog="Examples:\n  taskk notepad.exe\n  taskk python*\n  taskk chrome.exe --debug\n  taskk temp* --force",
+    )
+    parser.add_argument(
+        "processes",
+        type=str,
+        nargs="+",
+        help="Process name or pattern to terminate (supports wildcards)",
+    )
+    parser.add_argument(
+        "--debug",
+        "-d",
+        action="store_true",
+        help="Enable debug logging for detailed output",
+    )
     parser.add_argument(
         "--force",
         "-f",
         action="store_true",
-        help="Force termination even if match count exceeds threshold.",
+        help="Force termination even if match count exceeds safety threshold",
     )
 
     args = parser.parse_args()
 
     if args.debug:
         logger.setLevel(logging.DEBUG)
+        logger.debug("Debug mode enabled")
 
     # Temporarily increase threshold if force flag is set
     global _max_match_threshold
     original_threshold = _max_match_threshold
     if args.force:
-        _max_match_threshold = 1000  # Large number to effectively disable the limit
+        _max_match_threshold = FORCE_MATCH_THRESHOLD
+        logger.debug(
+            f"Force mode enabled, threshold increased to {_max_match_threshold}"
+        )
 
-    # Fetch process list once for the first process, then reuse for remaining
+    # Process each target
     for i, process_name in enumerate(args.processes):
+        # Refresh process list only for the first process to avoid redundant calls
         force_refresh = i == 0
+        logger.info(f"Terminating processes matching: {process_name}")
         kill_process(process_name, force_refresh=force_refresh)
 
     # Restore original threshold
     _max_match_threshold = original_threshold
+    if args.force:
+        logger.debug("Restored original match threshold")

sfi/which/which.py

@@ -18,8 +18,12 @@ logger = logging.getLogger(__name__)
 def find_executable(name: str, *, fuzzy: bool) -> tuple[str, str | None]:
     """Find executable path for commands cross-platform.
 
+    Args:
+        name: Name of the command to find
+        fuzzy: Whether to use fuzzy matching
+
     Returns:
-        Tuple[str, Optional[str]]: Command name and path.
+        Tuple containing the command name and its path if found, None otherwise.
     """
     try:
         # Select command based on system
@@ -49,8 +53,12 @@ def find_executable(name: str, *, fuzzy: bool) -> tuple[str, str | None]:
 def main() -> None:
     parser = argparse.ArgumentParser(description="Find executable path for commands.")
     parser.add_argument("commands", type=str, nargs="+", help="Commands to query")
-    parser.add_argument("-f", "--fuzzy", action="store_true", help="Enable fuzzy matching")
-    parser.add_argument("-q", "--quiet", action="store_true", help="Only print paths, no status symbols")
+    parser.add_argument(
+        "-f", "--fuzzy", action="store_true", help="Enable fuzzy matching"
+    )
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="Only print paths, no status symbols"
+    )
 
     args = parser.parse_args()