tasktree 0.0.22__py3-none-any.whl → 0.0.23__py3-none-any.whl

tasktree/logging.py

@@ -0,0 +1,112 @@
+"""Logging infrastructure for Task Tree.
+
+Provides a Logger interface for dependency injection of logging functionality.
+"""
+
+from __future__ import annotations
+
+import enum
+from abc import abstractmethod
+
+
+class LogLevel(enum.Enum):
+    """
+    Log verbosity levels for tasktree diagnostic messages.
+
+    Lower numeric values represent higher severity / less verbosity.
+    @athena: 3b2d8a378440
+    """
+
+    FATAL = 0  # Only unrecoverable errors (malformed task files, missing dependencies)
+    ERROR = 1  # Fatal errors plus task execution failures
+    WARN = 2  # Errors plus warnings about deprecated features, configuration issues
+    INFO = 3  # Warnings plus normal execution progress (default)
+    DEBUG = 4  # Info plus variable values, resolved paths, environment details
+    TRACE = 5  # Debug plus fine-grained execution tracing
+
+
+class Logger:
+    """
+    Abstract base class for logging implementations.
+
+    Provides a level-based logging interface with stack-based level management.
+    Concrete implementations must define how messages are output (e.g., to console, file, etc.).
+    @athena: fdcd08796011
+    """
+
+    @abstractmethod
+    def log(self, level: LogLevel, *args, **kwargs) -> None:
+        """
+        Log a message at the specified level.
+
+        Args:
+        level: The severity level of the message
+        *args: Positional arguments to log (strings, Rich objects, etc.)
+        **kwargs: Keyword arguments for formatting (e.g., style, justify)
+        @athena: 4563ae920ff4
+        """
+        pass
+
+    @abstractmethod
+    def push_level(self, level: LogLevel) -> None:
+        """
+        Push a new log level onto the level stack.
+
+        Messages below this level will be filtered out until pop_level() is called.
+        Useful for temporarily increasing verbosity in specific code sections.
+
+        Args:
+        level: The new log level to use
+        @athena: c73ac375d30a
+        """
+        pass
+
+    @abstractmethod
+    def pop_level(self) -> LogLevel:
+        """
+        Pop the current log level from the stack and return to the previous level.
+
+        Returns:
+        The log level that was popped
+
+        Raises:
+        RuntimeError: If attempting to pop the base (initial) log level
+        @athena: d4721a34516f
+        """
+        pass
+
+    def fatal(self, *args, **kwargs):
+        """
+        @athena: 951c9c5d4f3b
+        """
+        self.log(LogLevel.FATAL, *args, **kwargs)
+
+    def error(self, *args, **kwargs):
+        """
+        @athena: 7125264a8ce1
+        """
+        self.log(LogLevel.ERROR, *args, **kwargs)
+
+    def warn(self, *args, **kwargs):
+        """
+        @athena: 5a70af1bb5b4
+        """
+        self.log(LogLevel.WARN, *args, **kwargs)
+
+    def info(self, *args, **kwargs):
+        """
+        @athena: cdb5381023a6
+        """
+        self.log(LogLevel.INFO, *args, **kwargs)
+
+    def debug(self, *args, **kwargs):
+        """
+        @athena: ddfd0e359f09
+        """
+        self.log(LogLevel.DEBUG, *args, **kwargs)
+
+    def trace(self, *args, **kwargs):
+        """
+        @athena: 4f615a15562c
+        """
+        self.log(LogLevel.TRACE, *args, **kwargs)

tasktree/parser.py

@@ -16,6 +16,7 @@ from typing import Any, List
 import yaml
 
 from tasktree.types import get_click_type
+from tasktree.process_runner import TaskOutputTypes
 
 
 class CircularImportError(Exception):
@@ -69,7 +70,7 @@ class Environment:
 class Task:
     """
     Represents a task definition.
-    @athena: f516b5ae61c5
+    @athena: e2ea62ad15ba
     """
 
     name: str
@@ -91,6 +92,7 @@ class Task:
     source_file: str = ""  # Track which file defined this task
     env: str = ""  # Environment name to use for execution
     private: bool = False  # If True, task is hidden from --list output
+    task_output: TaskOutputTypes | None = None
 
     # Internal fields for efficient output lookup (built in __post_init__)
     _output_map: dict[str, str] = field(
@@ -119,7 +121,7 @@ class Task:
     def __post_init__(self):
         """
         Ensure lists are always lists and build input/output maps and indexed lists.
-        @athena: a48b1eba81cd
+        @athena: 5c750d8b1ef7
         """
         if isinstance(self.deps, str):
             self.deps = [self.deps]
@@ -313,7 +315,7 @@ class ArgSpec:
 class Recipe:
     """
     Represents a parsed recipe file with all tasks.
-    @athena: 47f568c77013
+    @athena: 5d1881f292cc
     """
 
     tasks: dict[str, Task]
@@ -394,7 +396,7 @@ class Recipe:
         >>> recipe = parse_recipe(path)  # Variables not yet evaluated
         >>> recipe.evaluate_variables("build")  # Evaluate only reachable variables
         >>> # Now recipe.evaluated_variables contains only vars used by "build" task
-        @athena: d8de7b5f42b6
+        @athena: 108eb8ae4de1
         """
         if self._variables_evaluated:
             return  # Already evaluated, skip (idempotent)
@@ -665,7 +667,7 @@ def _validate_variable_name(name: str) -> None:
 
     Raises:
     ValueError: If name is not a valid identifier
-    @athena: 61f92f7ad278
+    @athena: b768b37686da
     """
     if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
         raise ValueError(
@@ -727,7 +729,7 @@ def _validate_env_variable_reference(
 
     Raises:
     ValueError: If reference is invalid
-    @athena: 9fc8b2333b54
+    @athena: 9738cec4b0b4
     """
     # Validate dict structure - allow 'env' and optionally 'default'
     valid_keys = {"env", "default"}
@@ -911,7 +913,7 @@ def _resolve_file_variable(var_name: str, filepath: str, resolved_path: Path) ->
 
     Raises:
     ValueError: If file doesn't exist, can't be read, or contains invalid UTF-8
-    @athena: cab84337f145
+    @athena: 211ae0e2493d
     """
     # Check file exists
     if not resolved_path.exists():
@@ -1036,7 +1038,7 @@ def _resolve_eval_variable(
 
     Raises:
     ValueError: If command fails or cannot be executed
-    @athena: 647d3a310c77
+    @athena: 0f912a7346fd
     """
     # Determine shell to use
     shell = None
@@ -1131,7 +1133,7 @@ def _resolve_variable_value(
 
     Raises:
     ValueError: If circular reference detected or validation fails
-    @athena: da94de106756
+    @athena: 2d87857c4e95
     """
     # Check for circular reference
     if name in resolution_stack:
@@ -1336,7 +1338,7 @@ def _expand_variable_dependencies(
     ... }
     >>> _expand_variable_dependencies({"a"}, raw_vars)
     {"a", "b", "c"}
-    @athena: 98e583b402aa
+    @athena: c7d55d26a3c2
     """
     expanded = set(variable_names)
     to_process = list(variable_names)
@@ -1470,7 +1472,7 @@ def _parse_file_with_env(
     Returns:
     Tuple of (tasks, environments, default_env_name, raw_variables, YAML_data)
     Note: Variables are NOT evaluated here - they're stored as raw specs for lazy evaluation
-    @athena: b2dced506787
+    @athena: 8b00183e612d
     """
     # Parse tasks normally
     tasks = _parse_file(file_path, namespace, project_root, import_stack)
@@ -1675,7 +1677,7 @@ def collect_reachable_variables(
     >>> task = Task("build", cmd="echo {{ var.version }}")
     >>> collect_reachable_variables({"build": task}, {"build"})
     {"version"}
-    @athena: e22e54537f8d
+    @athena: 84edaecf913a
     """
     import re
 
@@ -1824,7 +1826,7 @@ def parse_recipe(
     CircularImportError: If circular imports are detected
     yaml.YAMLError: If YAML is invalid
     ValueError: If recipe structure is invalid
-    @athena: 27326e37d5f3
+    @athena: c79c0f326180
     """
     if not recipe_path.exists():
         raise FileNotFoundError(f"Recipe file not found: {recipe_path}")
@@ -1883,7 +1885,7 @@ def _parse_file(
     CircularImportError: If a circular import is detected
     FileNotFoundError: If an imported file doesn't exist
     ValueError: If task structure is invalid
-    @athena: 8a903d791c2f
+    @athena: 225864160e55
     """
     # Initialize import stack if not provided
     if import_stack is None:
@@ -2065,6 +2067,7 @@ def _parse_file(
             source_file=str(file_path),
             env=task_data.get("env", ""),
             private=task_data.get("private", False),
+            task_output=task_data.get("task_output", None)
         )
 
         # Check for case-sensitive argument collisions
@@ -2090,7 +2093,7 @@ def _check_case_sensitive_arg_collisions(args: list[str], task_name: str) -> Non
     Args:
     args: List of argument specifications
     task_name: Name of the task (for warning message)
-    @athena: a3f0f3b184a8
+    @athena: 11ec810aa07b
     """
     import sys
 
@@ -2156,7 +2159,7 @@ def parse_arg_spec(arg_spec: str | dict) -> ArgSpec:
 
     Raises:
     ValueError: If argument specification is invalid
-    @athena: 2a4c7e804622
+    @athena: ef9805c194d7
     """
     # Handle dictionary format: { argname: { type: ..., default: ... } }
     if isinstance(arg_spec, dict):
@@ -2232,7 +2235,7 @@ def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
 
     Raises:
     ValueError: If dictionary format is invalid
-    @athena: 5b6b93a3612a
+    @athena: a6020b5b771c
     """
     # Validate dictionary keys
     valid_keys = {"type", "default", "min", "max", "choices"}

tasktree/process_runner.py

@@ -0,0 +1,411 @@
+"""Process execution abstraction layer.
+
+This module provides an interface for running subprocesses, allowing for
+better testability and dependency injection.
+"""
+
+import subprocess
+import sys
+from abc import ABC, abstractmethod
+from enum import Enum
+from subprocess import Popen
+from threading import Thread
+from typing import Any
+
+__all__ = [
+    "ProcessRunner",
+    "PassthroughProcessRunner",
+    "SilentProcessRunner",
+    "StdoutOnlyProcessRunner",
+    "StderrOnlyProcessRunner",
+    "StderrOnlyOnFailureProcessRunner",
+    "TaskOutputTypes",
+    "make_process_runner",
+    "stream_output"
+]
+
+from tasktree.logging import Logger
+
+
+class TaskOutputTypes(Enum):
+    """
+    Enum defining task output control modes.
+    @athena: TBD
+    """
+
+    ALL = "all"
+    NONE = "none"
+    OUT = "out"
+    ERR = "err"
+    ON_ERR = "on-err"
+
+
+class ProcessRunner(ABC):
+    """
+    Abstract interface for running subprocess commands.
+    @athena: 78720f594104
+    """
+
+    @abstractmethod
+    def run(self, *args: Any, **kwargs: Any) -> subprocess.CompletedProcess[Any]:
+        """
+        Run a subprocess command.
+
+        This method signature matches subprocess.run() to allow for direct
+        substitution in existing code.
+
+        Args:
+        *args: Positional arguments passed to subprocess.run
+        **kwargs: Keyword arguments passed to subprocess.run
+
+        Returns:
+        subprocess.CompletedProcess: The completed process result
+
+        Raises:
+        subprocess.CalledProcessError: If check=True and process exits non-zero
+        subprocess.TimeoutExpired: If timeout is exceeded
+        @athena: c056d217be2e
+        """
+        ...
+
+
+class PassthroughProcessRunner(ProcessRunner):
+    """
+    Process runner that directly delegates to subprocess.run.
+    @athena: 470e2ca46355
+    """
+
+    def __init__(self, logger: Logger) -> None:
+        self._logger = logger
+
+    def run(self, *args: Any, **kwargs: Any) -> subprocess.CompletedProcess[Any]:
+        """
+        Run a subprocess command via subprocess.run.
+
+        Args:
+        *args: Positional arguments passed to subprocess.run
+        **kwargs: Keyword arguments passed to subprocess.run
+
+        Returns:
+        subprocess.CompletedProcess: The completed process result
+
+        Raises:
+        subprocess.CalledProcessError: If check=True and process exits non-zero
+        subprocess.TimeoutExpired: If timeout is exceeded
+        @athena: 9f6363a621f2
+        """
+        return subprocess.run(*args, **kwargs)
+
+
+class SilentProcessRunner(ProcessRunner):
+    """
+    Process runner that suppresses all subprocess output by redirecting to DEVNULL.
+    @athena: TBD
+    """
+
+    def __init__(self, logger: Logger) -> None:
+        self._logger = logger
+
+    def run(self, *args: Any, **kwargs: Any) -> subprocess.CompletedProcess[Any]:
+        """
+        Run a subprocess command with stdout and stderr suppressed.
+
+        This implementation forces stdout=DEVNULL and stderr=DEVNULL to discard
+        all subprocess output, regardless of what the caller requests.
+
+        Args:
+        *args: Positional arguments passed to subprocess.run
+        **kwargs: Keyword arguments passed to subprocess.run
+
+        Returns:
+        subprocess.CompletedProcess: The completed process result
+
+        Raises:
+        subprocess.CalledProcessError: If check=True and process exits non-zero
+        subprocess.TimeoutExpired: If timeout is exceeded
+        @athena: TBD
+        """
+        kwargs["stdout"] = subprocess.DEVNULL
+        kwargs["stderr"] = subprocess.DEVNULL
+        return subprocess.run(*args, **kwargs)
+
+
+def stream_output(pipe: Any, target: Any) -> None:
+    """
+    Stream output from a pipe to a target stream.
+
+    Handles exceptions gracefully to avoid silent thread failures.
+    If the pipe is closed or an error occurs during reading/writing,
+    the function returns without raising an exception.
+
+    Args:
+        pipe: Input pipe to read from
+        target: Output stream to write to
+    @athena: TBD
+    """
+    if pipe:
+        try:
+            for line in pipe:
+                target.write(line)
+                target.flush()
+        except (OSError, ValueError):
+            # Pipe closed or other I/O error - this is expected when
+            # process is killed or stdout is closed
+            pass
+
+
+def _start_thread_and_wait_to_complete(process: Popen[str], stream: Any, thread: Thread, process_allowed_runtime: float | None, logger: Logger) -> int:
+    join_timeout_secs = 1.0
+
+    thread.start()
+
+    try:
+        process_return_code = process.wait(timeout=process_allowed_runtime)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+        if stream:
+            stream.close()
+            stream = None
+        thread.join(timeout=join_timeout_secs)
+        raise
+    finally:
+        if stream:
+            stream.close()
+            stream = None
+
+    thread.join(timeout=join_timeout_secs)
+    if thread.is_alive():
+        logger.warn(f"Stream thread did not complete within timeout of {join_timeout_secs} seconds")
+
+    return process_return_code
+
+
+def _check_result_if_necessary(raise_on_failure: bool, proc_ret_code: int, *args, **kwargs) -> subprocess.CompletedProcess[Any]:
+    if raise_on_failure and proc_ret_code != 0:
+        raise subprocess.CalledProcessError(
+            proc_ret_code, args[0] if args else kwargs.get("args", [])
+        )
+
+    # Return a CompletedProcess object for interface compatibility
+    return subprocess.CompletedProcess(
+        args=args[0] if args else kwargs.get("args", []),
+        returncode=proc_ret_code,
+        stdout=None,
+        stderr=None,  # We streamed it, so don't capture it
+    )
+
+
+class StdoutOnlyProcessRunner(ProcessRunner):
+    """
+    Process runner that streams stdout while suppressing stderr.
+
+    This implementation uses threading to asynchronously stream stdout from the
+    subprocess while discarding stderr output.
+    @athena: TBD
+    """
+
+    def __init__(self, logger: Logger) -> None:
+        self._logger = logger
+
+    def run(self, *args: Any, **kwargs: Any) -> subprocess.CompletedProcess[Any]:
+        """
+        Run a subprocess command with stdout streamed and stderr suppressed.
+
+        This implementation uses subprocess.Popen with threading to stream stdout
+        in real-time while discarding stderr. The interface remains synchronous
+        from the caller's perspective.
+
+        Buffering strategy: Uses line buffering (bufsize=1) to ensure output
+        appears promptly while maintaining reasonable performance.
+
+        Args:
+            *args: Positional arguments passed to subprocess.Popen
+            **kwargs: Keyword arguments passed to subprocess.Popen
+
+        Returns:
+            subprocess.CompletedProcess: The completed process result
+
+        Raises:
+            subprocess.CalledProcessError: If check=True and process exits non-zero
+            subprocess.TimeoutExpired: If timeout is exceeded
+        @athena: TBD
+        """
+        # Extract parameters that need special handling
+        check = kwargs.pop("check", False)
+        timeout = kwargs.pop("timeout", None)
+        # Remove capture_output if present - not supported by Popen
+        kwargs.pop("capture_output", None)
+
+        # Force stdout/stderr handling
+        kwargs["stdout"] = subprocess.PIPE
+        kwargs["stderr"] = subprocess.DEVNULL
+        kwargs["text"] = True
+        kwargs["bufsize"] = 1
+
+        # Start the process
+        process = subprocess.Popen(*args, **kwargs)
+
+        # Start thread to stream stdout with a descriptive name for debugging
+        thread = Thread(
+            target=stream_output,
+            args=(process.stdout, sys.stdout),
+            name="stdout-streamer",
+            daemon=True,
+        )
+
+        process_return_code = _start_thread_and_wait_to_complete(process, process.stdout, thread, timeout, self._logger)
+        return _check_result_if_necessary(check, process_return_code, *args, **kwargs)
+
+
+class StderrOnlyProcessRunner(ProcessRunner):
+    """
+    Process runner that streams stderr while suppressing stdout.
+
+    This implementation uses threading to asynchronously stream stderr from the
+    subprocess while discarding stdout output.
+    @athena: TBD
+    """
+
+    def __init__(self, logger: Logger) -> None:
+        self._logger = logger
+
+    def run(self, *args: Any, **kwargs: Any) -> subprocess.CompletedProcess[Any]:
+        """
+        Run a subprocess command with stderr streamed and stdout suppressed.
+
+        This implementation uses subprocess.Popen with threading to stream stderr
+        in real-time while discarding stdout. The interface remains synchronous
+        from the caller's perspective.
+
+        Buffering strategy: Uses line buffering (bufsize=1) to ensure output
+        appears promptly while maintaining reasonable performance.
+
+        Args:
+            *args: Positional arguments passed to subprocess.Popen
+            **kwargs: Keyword arguments passed to subprocess.Popen
+
+        Returns:
+            subprocess.CompletedProcess: The completed process result
+
+        Raises:
+            subprocess.CalledProcessError: If check=True and process exits non-zero
+            subprocess.TimeoutExpired: If timeout is exceeded
+        @athena: TBD
+        """
+        # Extract parameters that need special handling
+        check = kwargs.pop("check", False)
+        timeout = kwargs.pop("timeout", None)
+        # Remove capture_output if present - not supported by Popen
+        kwargs.pop("capture_output", None)
+
+        # Force stdout/stderr handling
+        kwargs["stdout"] = subprocess.DEVNULL
+        kwargs["stderr"] = subprocess.PIPE
+        kwargs["text"] = True
+        kwargs["bufsize"] = 1
+
+        # Start the process
+        process = subprocess.Popen(*args, **kwargs)
+
+        # Start thread to stream stderr with a descriptive name for debugging
+        thread = Thread(
+            target=stream_output,
+            args=(process.stderr, sys.stderr),
+            name="stderr-streamer",
+            daemon=True,
+        )
+
+        process_return_code = _start_thread_and_wait_to_complete(process, process.stderr, thread, timeout, self._logger)
+        return _check_result_if_necessary(check, process_return_code, *args, **kwargs)
+
+
+class StderrOnlyOnFailureProcessRunner(ProcessRunner):
+    """
+    Process runner that buffers stderr and only outputs it on failure.
+
+    This implementation ignores stdout completely (sends to DEVNULL) and captures
+    stderr. The buffered stderr is only output if the process exits with a non-zero
+    code.
+    """
+
+    def __init__(self, logger: Logger) -> None:
+        self._logger = logger
+
+    def run(self, *args: Any, **kwargs: Any) -> subprocess.CompletedProcess[Any]:
+        """
+        Run a subprocess command, buffering stderr and outputting only on failure.
+
+        Stdout is completely ignored (sent to DEVNULL). Stderr is collected in a
+        buffer during execution. If the process exits with non-zero code, the
+        buffered stderr is written to sys.stderr before returning/raising.
+
+        Args:
+            *args: Positional arguments passed to subprocess.run
+            **kwargs: Keyword arguments passed to subprocess.run
+
+        Returns:
+            subprocess.CompletedProcess: The completed process result
+
+        Raises:
+            subprocess.CalledProcessError: If check=True and process exits non-zero
+            subprocess.TimeoutExpired: If timeout is exceeded
+        """
+        check = kwargs.pop("check", False)
+        timeout = kwargs.pop("timeout", None)
+        kwargs.pop("capture_output", None)  # Remove if present
+        kwargs.pop("stdout", None)  # Remove if present
+        kwargs.pop("stderr", None)  # Remove if present
+
+        result = subprocess.run(
+            *args,
+            **kwargs,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+
+        if result.returncode != 0 and result.stderr:
+            sys.stderr.write(result.stderr)
+            sys.stderr.flush()
+
+        if check and result.returncode != 0:
+            raise subprocess.CalledProcessError(
+                result.returncode,
+                result.args,
+                output=result.stdout,
+                stderr=result.stderr,
+            )
+
+        return result
+
+
+def make_process_runner(output_type: TaskOutputTypes, logger: Logger) -> ProcessRunner:
+    """
+    Factory function for creating ProcessRunner instances.
+
+    Args:
+    output_type: The type of output control to use
+
+    Returns:
+    ProcessRunner: A new ProcessRunner instance
+
+    Raises:
+    ValueError: If an invalid TaskOutputTypes value is provided
+    @athena: ba1d2e048716
+    """
+    match output_type:
+        case TaskOutputTypes.ALL:
+            return PassthroughProcessRunner(logger)
+        case TaskOutputTypes.NONE:
+            return SilentProcessRunner(logger)
+        case TaskOutputTypes.OUT:
+            return StdoutOnlyProcessRunner(logger)
+        case TaskOutputTypes.ERR:
+            return StderrOnlyProcessRunner(logger)
+        case TaskOutputTypes.ON_ERR:
+            return StderrOnlyOnFailureProcessRunner(logger)
+        case _:
+            raise ValueError(f"Invalid TaskOutputTypes: {output_type}")