tasktree 0.0.20__py3-none-any.whl → 0.0.21__py3-none-any.whl

tasktree/__init__.py

@@ -1,4 +1,7 @@
-"""Task Tree - A task automation tool with intelligent incremental execution."""
+"""
+Task Tree - A task automation tool with intelligent incremental execution.
+@athena: 1b4a97c4bc42
+"""
 
 try:
     from importlib.metadata import version

tasktree/cli.py

@@ -1,3 +1,10 @@
+"""Command-line interface for Task Tree.
+
+Provides a Typer-based CLI with commands for listing, showing, executing,
+and managing task definitions. Supports task execution with incremental builds,
+dependency resolution, and rich terminal output via the Rich library.
+"""
+
 from __future__ import annotations
 
 import os
@@ -29,10 +36,12 @@ console = Console()
 
 
 def _supports_unicode() -> bool:
-    """Check if the terminal supports Unicode characters.
+    """
+    Check if the terminal supports Unicode characters.
 
     Returns:
-        True if terminal supports UTF-8, False otherwise
+    True if terminal supports UTF-8, False otherwise
+    @athena: 68f62a942a95
     """
     # Hard stop: classic Windows console (conhost)
     if os.name == "nt" and "WT_SESSION" not in os.environ:
@@ -51,37 +60,43 @@ def _supports_unicode() -> bool:
 
 
 def get_action_success_string() -> str:
-    """Get the appropriate success symbol based on terminal capabilities.
+    """
+    Get the appropriate success symbol based on terminal capabilities.
 
     Returns:
-        Unicode tick symbol (✓) if terminal supports UTF-8, otherwise "[ OK ]"
+    Unicode tick symbol (✓) if terminal supports UTF-8, otherwise "[ OK ]"
+    @athena: 39d9966ee6c8
     """
     return "✓" if _supports_unicode() else "[ OK ]"
 
 
 def get_action_failure_string() -> str:
-    """Get the appropriate failure symbol based on terminal capabilities.
+    """
+    Get the appropriate failure symbol based on terminal capabilities.
 
     Returns:
-        Unicode cross symbol (✗) if terminal supports UTF-8, otherwise "[ FAIL ]"
+    Unicode cross symbol (✗) if terminal supports UTF-8, otherwise "[ FAIL ]"
+    @athena: 5dd1111f8d74
     """
     return "✗" if _supports_unicode() else "[ FAIL ]"
 
 
 def _format_task_arguments(arg_specs: list[str | dict]) -> str:
-    """Format task arguments for display in list output.
+    """
+    Format task arguments for display in list output.
 
     Args:
-        arg_specs: List of argument specifications from task definition (strings or dicts)
+    arg_specs: List of argument specifications from task definition (strings or dicts)
 
     Returns:
-        Formatted string showing arguments with types and defaults
+    Formatted string showing arguments with types and defaults
 
     Examples:
-        ["mode", "target"] -> "mode:str target:str"
-        ["mode=debug", "target=x86_64"] -> "mode:str [=debug] target:str [=x86_64]"
-        ["port:int", "debug:bool=false"] -> "port:int debug:bool [=false]"
-        [{"timeout": {"type": "int", "default": 30}}] -> "timeout:int [=30]"
+    ["mode", "target"] -> "mode:str target:str"
+    ["mode=debug", "target=x86_64"] -> "mode:str [=debug] target:str [=x86_64]"
+    ["port:int", "debug:bool=false"] -> "port:int debug:bool [=false]"
+    [{"timeout": {"type": "int", "default": 30}}] -> "timeout:int [=30]"
+    @athena: fc3d6da90aeb
     """
     if not arg_specs:
         return ""
@@ -104,7 +119,10 @@ def _format_task_arguments(arg_specs: list[str | dict]) -> str:
 
 
 def _list_tasks(tasks_file: Optional[str] = None):
-    """List all available tasks with descriptions."""
+    """
+    List all available tasks with descriptions.
+    @athena: 778f231737a1
+    """
     recipe = _get_recipe(tasks_file)
     if recipe is None:
         console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
@@ -144,7 +162,10 @@ def _list_tasks(tasks_file: Optional[str] = None):
 
 
 def _show_task(task_name: str, tasks_file: Optional[str] = None):
-    """Show task definition with syntax highlighting."""
+    """
+    Show task definition with syntax highlighting.
+    @athena: 79ae3e330662
+    """
     # Pass task_name as root_task for lazy variable evaluation
     recipe = _get_recipe(tasks_file, root_task=task_name)
     if recipe is None:
@@ -194,7 +215,10 @@ def _show_task(task_name: str, tasks_file: Optional[str] = None):
 
 
 def _show_tree(task_name: str, tasks_file: Optional[str] = None):
-    """Show dependency tree structure."""
+    """
+    Show dependency tree structure.
+    @athena: a906cef99324
+    """
     # Pass task_name as root_task for lazy variable evaluation
     recipe = _get_recipe(tasks_file, root_task=task_name)
     if recipe is None:
@@ -219,7 +243,10 @@ def _show_tree(task_name: str, tasks_file: Optional[str] = None):
 
 
 def _init_recipe():
-    """Create a blank recipe file with commented examples."""
+    """
+    Create a blank recipe file with commented examples.
+    @athena: 189726c9b6c0
+    """
     recipe_path = Path("tasktree.yaml")
     if recipe_path.exists():
         console.print("[red]tasktree.yaml already exists[/red]")
@@ -260,7 +287,10 @@ tasks:
 
 
 def _version_callback(value: bool):
-    """Show version and exit."""
+    """
+    Show version and exit.
+    @athena: abaed96ac23b
+    """
     if value:
         console.print(f"task-tree version {__version__}")
         raise typer.Exit()
@@ -306,17 +336,19 @@ def main(
         None, help="Task name and arguments"
     ),
 ):
-    """Task Tree - A task automation tool with incremental execution.
+    """
+    Task Tree - A task automation tool with incremental execution.
 
     Run tasks defined in tasktree.yaml with dependency tracking
     and incremental execution.
 
     Examples:
 
-      tt build                     # Run the 'build' task
-      tt deploy prod region=us-1   # Run 'deploy' with arguments
-      tt --list                    # List all tasks
-      tt --tree test               # Show dependency tree for 'test'
+    tt build                     # Run the 'build' task
+    tt deploy prod region=us-1   # Run 'deploy' with arguments
+    tt --list                    # List all tasks
+    tt --tree test               # Show dependency tree for 'test'
+    @athena: f76c75c12d10
     """
 
     if list_opt:
@@ -360,7 +392,10 @@ def main(
 
 
 def _clean_state(tasks_file: Optional[str] = None) -> None:
-    """Remove the .tasktree-state file to reset task execution state."""
+    """
+    Remove the .tasktree-state file to reset task execution state.
+    @athena: a0ddf4b333d4
+    """
     if tasks_file:
         recipe_path = Path(tasks_file)
         if not recipe_path.exists():
@@ -385,12 +420,14 @@ def _clean_state(tasks_file: Optional[str] = None) -> None:
 
 
 def _get_recipe(recipe_file: Optional[str] = None, root_task: Optional[str] = None) -> Optional[Recipe]:
-    """Get parsed recipe or None if not found.
+    """
+    Get parsed recipe or None if not found.
 
     Args:
-        recipe_file: Optional path to recipe file. If not provided, searches for recipe file.
-        root_task: Optional root task for lazy variable evaluation. If provided, only variables
-                  reachable from this task will be evaluated (performance optimization).
+    recipe_file: Optional path to recipe file. If not provided, searches for recipe file.
+    root_task: Optional root task for lazy variable evaluation. If provided, only variables
+    reachable from this task will be evaluated (performance optimization).
+    @athena: 0ee00c67df25
     """
     if recipe_file:
         recipe_path = Path(recipe_file)
@@ -419,6 +456,18 @@ def _get_recipe(recipe_file: Optional[str] = None, root_task: Optional[str] = No
 
 
 def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = False, env: Optional[str] = None, tasks_file: Optional[str] = None) -> None:
+    """
+    Execute a task with its dependencies and handle argument parsing.
+
+    Args:
+        args: Task name followed by optional task arguments
+        force: Force re-execution even if task is up-to-date
+        only: Execute only the specified task, skip dependencies
+        env: Override environment for task execution
+        tasks_file: Path to recipe file (optional)
+
+    @athena: 207f7635a60d
+    """
     if not args:
         return
 
@@ -511,6 +560,21 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
 
 
 def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, Any]:
+    """
+    Parse and validate task arguments from command line values.
+
+    Args:
+        arg_specs: Task argument specifications with types and defaults
+        arg_values: Raw argument values from command line (positional or named)
+
+    Returns:
+        Dictionary mapping argument names to typed, validated values
+
+    Raises:
+        typer.Exit: If arguments are invalid, missing, or unknown
+
+    @athena: 2072a35f9d11
+    """
     if not arg_specs:
         if arg_values:
             console.print(f"[red]Task does not accept arguments[/red]")
@@ -579,6 +643,17 @@ def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, A
 
 
 def _build_rich_tree(dep_tree: dict) -> Tree:
+    """
+    Build a Rich Tree visualization from a dependency tree structure.
+
+    Args:
+        dep_tree: Nested dictionary representing task dependencies
+
+    Returns:
+        Rich Tree object for terminal display
+
+    @athena: 62472c8ca729
+    """
     task_name = dep_tree["name"]
     tree = Tree(task_name)
 
@@ -591,7 +666,10 @@ def _build_rich_tree(dep_tree: dict) -> Tree:
 
 
 def cli():
-    """Entry point for the CLI."""
+    """
+    Entry point for the CLI.
+    @athena: 3b3cccd1ff6f
+    """
     app()
 
 

tasktree/docker.py

@@ -23,31 +23,41 @@ if TYPE_CHECKING:
 
 
 class DockerError(Exception):
-    """Raised when Docker operations fail."""
+    """
+    Raised when Docker operations fail.
+    @athena: 876629e35765
+    """
 
     pass
 
 
 class DockerManager:
-    """Manages Docker image building and container execution."""
+    """
+    Manages Docker image building and container execution.
+    @athena: ef3cc3d7bcbe
+    """
 
     def __init__(self, project_root: Path):
-        """Initialize Docker manager.
+        """
+        Initialize Docker manager.
 
         Args:
-            project_root: Root directory of the project (where tasktree.yaml is located)
+        project_root: Root directory of the project (where tasktree.yaml is located)
+        @athena: eb7d4c5a27aa
         """
         self._project_root = project_root
         self._built_images: dict[str, tuple[str, str]] = {}  # env_name -> (image_tag, image_id) cache
 
     def _should_add_user_flag(self) -> bool:
-        """Check if --user flag should be added to docker run.
+        """
+        Check if --user flag should be added to docker run.
 
         Returns False on Windows (where Docker Desktop handles UID mapping automatically).
         Returns True on Linux/macOS where os.getuid() and os.getgid() are available.
 
         Returns:
-            True if --user flag should be added, False otherwise
+        True if --user flag should be added, False otherwise
+        @athena: 6a872eea6a10
         """
         # Skip on Windows - Docker Desktop handles UID mapping differently
         if platform.system() == "Windows":
@@ -57,18 +67,20 @@ class DockerManager:
         return hasattr(os, "getuid") and hasattr(os, "getgid")
 
     def ensure_image_built(self, env: Environment) -> tuple[str, str]:
-        """Build Docker image if not already built this invocation.
+        """
+        Build Docker image if not already built this invocation.
 
         Args:
-            env: Environment definition with dockerfile and context
+        env: Environment definition with dockerfile and context
 
         Returns:
-            Tuple of (image_tag, image_id)
-            - image_tag: Tag like "tt-env-builder"
-            - image_id: Full image ID like "sha256:abc123..."
+        Tuple of (image_tag, image_id)
+        - image_tag: Tag like "tt-env-builder"
+        - image_id: Full image ID like "sha256:abc123..."
 
         Raises:
-            DockerError: If docker command not available or build fails
+        DockerError: If docker command not available or build fails
+        @athena: 9b3c11c29fbb
         """
         # Check if already built this invocation
         if env.name in self._built_images:
@@ -132,19 +144,21 @@ class DockerManager:
         working_dir: Path,
         container_working_dir: str,
     ) -> subprocess.CompletedProcess:
-        """Execute command inside Docker container.
+        """
+        Execute command inside Docker container.
 
         Args:
-            env: Environment definition
-            cmd: Command to execute
-            working_dir: Host working directory (for resolving relative volume paths)
-            container_working_dir: Working directory inside container
+        env: Environment definition
+        cmd: Command to execute
+        working_dir: Host working directory (for resolving relative volume paths)
+        container_working_dir: Working directory inside container
 
         Returns:
-            CompletedProcess from subprocess.run
+        CompletedProcess from subprocess.run
 
         Raises:
-            DockerError: If docker run fails
+        DockerError: If docker run fails
+        @athena: 2c963babb5ca
         """
         # Ensure image is built (returns tag and ID)
         image_tag, image_id = self.ensure_image_built(env)
@@ -200,7 +214,8 @@ class DockerManager:
             ) from e
 
     def _resolve_volume_mount(self, volume: str) -> str:
-        """Resolve volume mount specification.
+        """
+        Resolve volume mount specification.
 
         Handles:
         - Relative paths (resolved relative to project_root)
@@ -208,10 +223,11 @@ class DockerManager:
         - Absolute paths (used as-is)
 
         Args:
-            volume: Volume specification (e.g., "./src:/workspace/src" or "~/.cargo:/root/.cargo")
+        volume: Volume specification (e.g., "./src:/workspace/src" or "~/.cargo:/root/.cargo")
 
         Returns:
-            Resolved volume specification with absolute host path
+        Resolved volume specification with absolute host path
+        @athena: c7661050443e
         """
         if ":" not in volume:
             raise ValueError(
@@ -235,10 +251,12 @@ class DockerManager:
         return f"{resolved_host_path}:{container_path}"
 
     def _check_docker_available(self) -> None:
-        """Check if docker command is available.
+        """
+        Check if docker command is available.
 
         Raises:
-            DockerError: If docker is not available
+        DockerError: If docker is not available
+        @athena: 16ba713e3962
         """
         try:
             subprocess.run(
@@ -254,16 +272,18 @@ class DockerManager:
             )
 
     def _get_image_id(self, image_tag: str) -> str:
-        """Get the full image ID for a given tag.
+        """
+        Get the full image ID for a given tag.
 
         Args:
-            image_tag: Docker image tag (e.g., "tt-env-builder")
+        image_tag: Docker image tag (e.g., "tt-env-builder")
 
         Returns:
-            Full image ID (e.g., "sha256:abc123def456...")
+        Full image ID (e.g., "sha256:abc123def456...")
 
         Raises:
-            DockerError: If cannot inspect image
+        DockerError: If cannot inspect image
+        @athena: e4bc075fe857
         """
         try:
             result = subprocess.run(
@@ -279,13 +299,15 @@ class DockerManager:
 
 
 def is_docker_environment(env: Environment) -> bool:
-    """Check if environment is Docker-based.
+    """
+    Check if environment is Docker-based.
 
     Args:
-        env: Environment to check
+    env: Environment to check
 
     Returns:
-        True if environment has a dockerfile field, False otherwise
+    True if environment has a dockerfile field, False otherwise
+    @athena: 1ffd255a4e90
     """
     return bool(env.dockerfile)
 
@@ -293,7 +315,8 @@ def is_docker_environment(env: Environment) -> bool:
 def resolve_container_working_dir(
     env_working_dir: str, task_working_dir: str
 ) -> str:
-    """Resolve working directory inside container.
+    """
+    Resolve working directory inside container.
 
     Combines environment's working_dir with task's working_dir:
     - If task specifies working_dir: container_dir = env_working_dir / task_working_dir
@@ -301,11 +324,12 @@ def resolve_container_working_dir(
     - If neither specify: container_dir = "/" (Docker default)
 
     Args:
-        env_working_dir: Working directory from environment definition
-        task_working_dir: Working directory from task definition
+    env_working_dir: Working directory from environment definition
+    task_working_dir: Working directory from task definition
 
     Returns:
-        Resolved working directory path
+    Resolved working directory path
+    @athena: bb13d00dd07d
     """
     if not env_working_dir and not task_working_dir:
         return "/"
@@ -322,13 +346,15 @@ def resolve_container_working_dir(
 
 
 def parse_dockerignore(dockerignore_path: Path) -> "pathspec.PathSpec | None":
-    """Parse .dockerignore file into pathspec matcher.
+    """
+    Parse .dockerignore file into pathspec matcher.
 
     Args:
-        dockerignore_path: Path to .dockerignore file
+    dockerignore_path: Path to .dockerignore file
 
     Returns:
-        PathSpec object for matching, or None if file doesn't exist or pathspec not available
+    PathSpec object for matching, or None if file doesn't exist or pathspec not available
+    @athena: 62bc07a3c6d0
     """
     if pathspec is None:
         # pathspec library not available - can't parse .dockerignore
@@ -351,17 +377,19 @@ def context_changed_since(
     dockerignore_path: Path | None,
     last_run_time: float,
 ) -> bool:
-    """Check if any file in Docker build context has changed since last run.
+    """
+    Check if any file in Docker build context has changed since last run.
 
     Uses early-exit optimization: stops on first changed file found.
 
     Args:
-        context_path: Path to Docker build context directory
-        dockerignore_path: Optional path to .dockerignore file
-        last_run_time: Unix timestamp of last task run
+    context_path: Path to Docker build context directory
+    dockerignore_path: Optional path to .dockerignore file
+    last_run_time: Unix timestamp of last task run
 
     Returns:
-        True if any file changed, False otherwise
+    True if any file changed, False otherwise
+    @athena: 556acb1ed6ca
     """
     # Parse .dockerignore
     dockerignore_spec = None
@@ -395,14 +423,16 @@ def context_changed_since(
 
 
 def extract_from_images(dockerfile_content: str) -> list[tuple[str, str | None]]:
-    """Extract image references from FROM lines in Dockerfile.
+    """
+    Extract image references from FROM lines in Dockerfile.
 
     Args:
-        dockerfile_content: Content of Dockerfile
+    dockerfile_content: Content of Dockerfile
 
     Returns:
-        List of (image_reference, digest) tuples where digest may be None for unpinned images
-        Example: [("rust:1.75", None), ("rust", "sha256:abc123...")]
+    List of (image_reference, digest) tuples where digest may be None for unpinned images
+    Example: [("rust:1.75", None), ("rust", "sha256:abc123...")]
+    @athena: ede7ed483bdd
     """
     # Regex pattern to match FROM lines
     # Handles: FROM [--platform=...] image[:tag][@digest] [AS alias]
@@ -421,26 +451,30 @@ def extract_from_images(dockerfile_content: str) -> list[tuple[str, str | None]]
 
 
 def check_unpinned_images(dockerfile_content: str) -> list[str]:
-    """Check for unpinned base images in Dockerfile.
+    """
+    Check for unpinned base images in Dockerfile.
 
     Args:
-        dockerfile_content: Content of Dockerfile
+    dockerfile_content: Content of Dockerfile
 
     Returns:
-        List of unpinned image references (images without @sha256:... digests)
+    List of unpinned image references (images without @sha256:... digests)
+    @athena: 58cc6de8fc96
     """
     images = extract_from_images(dockerfile_content)
     return [image for image, digest in images if digest is None]
 
 
 def parse_base_image_digests(dockerfile_content: str) -> list[str]:
-    """Parse pinned base image digests from Dockerfile.
+    """
+    Parse pinned base image digests from Dockerfile.
 
     Args:
-        dockerfile_content: Content of Dockerfile
+    dockerfile_content: Content of Dockerfile
 
     Returns:
-        List of digests (e.g., ["sha256:abc123...", "sha256:def456..."])
+    List of digests (e.g., ["sha256:abc123...", "sha256:def456..."])
+    @athena: c4d1da6b067c
     """
     images = extract_from_images(dockerfile_content)
     return [digest for _image, digest in images if digest is not None]