tasktree 0.0.20__py3-none-any.whl → 0.0.22__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
@@ -14,7 +21,12 @@ from rich.tree import Tree
 
 from tasktree import __version__
 from tasktree.executor import Executor
-from tasktree.graph import build_dependency_tree, resolve_execution_order, resolve_dependency_output_references, resolve_self_references
+from tasktree.graph import (
+    build_dependency_tree,
+    resolve_execution_order,
+    resolve_dependency_output_references,
+    resolve_self_references,
+)
 from tasktree.hasher import hash_task, hash_args
 from tasktree.parser import Recipe, find_recipe_file, parse_arg_spec, parse_recipe
 from tasktree.state import StateManager
@@ -29,10 +41,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 +65,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,10 +124,15 @@ 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]")
+        console.print(
+            "[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]"
+        )
         raise typer.Exit(1)
 
     # Calculate maximum task name length for fixed-width column (only visible tasks)
@@ -116,13 +141,17 @@ def _list_tasks(tasks_file: Optional[str] = None):
         task = recipe.get_task(name)
         if task and not task.private:
             visible_task_names.append(name)
-    max_task_name_len = max(len(name) for name in visible_task_names) if visible_task_names else 0
+    max_task_name_len = (
+        max(len(name) for name in visible_task_names) if visible_task_names else 0
+    )
 
     # Create borderless table with three columns
     table = Table(show_edge=False, show_header=False, box=None, padding=(0, 2))
 
-    # Command column: fixed width to accommodate longest task name
-    table.add_column("Command", style="bold cyan", no_wrap=True, width=max_task_name_len)
+    # Command column: fixed width to accommodate the longest task name
+    table.add_column(
+        "Command", style="bold cyan", no_wrap=True, width=max_task_name_len
+    )
 
     # Arguments column: allow wrapping with sensible max width
     table.add_column("Arguments", style="white", max_width=60)
@@ -144,11 +173,16 @@ 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:
-        console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
+        console.print(
+            "[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]"
+        )
         raise typer.Exit(1)
 
     task = recipe.get_task(task_name)
@@ -181,9 +215,9 @@ def _show_task(task_name: str, tasks_file: Optional[str] = None):
     # Configure YAML dumper to use literal block style for multiline strings
     def literal_presenter(dumper, data):
         """Use literal block style (|) for strings containing newlines."""
-        if '\n' in data:
-            return dumper.represent_scalar('tag:yaml.org,2002:str', data, style='|')
-        return dumper.represent_scalar('tag:yaml.org,2002:str', data)
+        if "\n" in data:
+            return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
+        return dumper.represent_scalar("tag:yaml.org,2002:str", data)
 
     yaml.add_representer(str, literal_presenter)
 
@@ -194,11 +228,16 @@ 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:
-        console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
+        console.print(
+            "[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]"
+        )
         raise typer.Exit(1)
 
     task = recipe.get_task(task_name)
@@ -219,7 +258,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 +302,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()
@@ -277,10 +322,18 @@ def main(
         is_eager=True,
         help="Show version and exit",
     ),
-    list_opt: Optional[bool] = typer.Option(None, "--list", "-l", help="List all available tasks"),
-    show: Optional[str] = typer.Option(None, "--show", "-s", help="Show task definition"),
-    tree: Optional[str] = typer.Option(None, "--tree", "-t", help="Show dependency tree"),
-    tasks_file: Optional[str] = typer.Option(None, "--tasks", "-T", help="Path to recipe file (tasktree.yaml, *.tasks, etc.)"),
+    list_opt: Optional[bool] = typer.Option(
+        None, "--list", "-l", help="List all available tasks"
+    ),
+    show: Optional[str] = typer.Option(
+        None, "--show", "-s", help="Show task definition"
+    ),
+    tree: Optional[str] = typer.Option(
+        None, "--tree", "-t", help="Show dependency tree"
+    ),
+    tasks_file: Optional[str] = typer.Option(
+        None, "--tasks", "-T", help="Path to recipe file (tasktree.yaml, *.tasks, etc.)"
+    ),
     init: Optional[bool] = typer.Option(
         None, "--init", "-i", help="Create a blank tasktree.yaml"
     ),
@@ -297,7 +350,10 @@ def main(
         None, "--force", "-f", help="Force re-run all tasks (ignore freshness)"
     ),
     only: Optional[bool] = typer.Option(
-        None, "--only", "-o", help="Run only the specified task, skip dependencies (implies --force)"
+        None,
+        "--only",
+        "-o",
+        help="Run only the specified task, skip dependencies (implies --force)",
     ),
     env: Optional[str] = typer.Option(
         None, "--env", "-e", help="Override environment for all tasks"
@@ -306,17 +362,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:
@@ -342,11 +400,19 @@ def main(
     if task_args:
         # --only implies --force
         force_execution = force or only or False
-        _execute_dynamic_task(task_args, force=force_execution, only=only or False, env=env, tasks_file=tasks_file)
+        _execute_dynamic_task(
+            task_args,
+            force=force_execution,
+            only=only or False,
+            env=env,
+            tasks_file=tasks_file,
+        )
     else:
         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]")
+            console.print(
+                "[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]"
+            )
             console.print("Run [cyan]tt --init[/cyan] to create a blank recipe file")
             raise typer.Exit(1)
 
@@ -360,7 +426,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():
@@ -378,19 +447,25 @@ def _clean_state(tasks_file: Optional[str] = None) -> None:
 
     if state_path.exists():
         state_path.unlink()
-        console.print(f"[green]{get_action_success_string()} Removed {state_path}[/green]")
+        console.print(
+            f"[green]{get_action_success_string()} Removed {state_path}[/green]"
+        )
         console.print("All tasks will run fresh on next execution")
     else:
         console.print(f"[yellow]No state file found at {state_path}[/yellow]")
 
 
-def _get_recipe(recipe_file: Optional[str] = None, root_task: Optional[str] = None) -> Optional[Recipe]:
-    """Get parsed recipe or None if not found.
+def _get_recipe(
+    recipe_file: Optional[str] = None, root_task: Optional[str] = None
+) -> Optional[Recipe]:
+    """
+    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)
@@ -418,7 +493,25 @@ def _get_recipe(recipe_file: Optional[str] = None, root_task: Optional[str] = No
         raise typer.Exit(1)
 
 
-def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = False, env: Optional[str] = None, tasks_file: Optional[str] = None) -> None:
+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
 
@@ -428,7 +521,9 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
     # Pass task_name as root_task for lazy variable evaluation
     recipe = _get_recipe(tasks_file, root_task=task_name)
     if recipe is None:
-        console.print("[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]")
+        console.print(
+            "[red]No recipe file found (tasktree.yaml, tasktree.yml, tt.yaml, or *.tasks)[/red]"
+        )
         raise typer.Exit(1)
 
     # Apply global environment override if provided
@@ -488,7 +583,7 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
             task.working_dir,
             task.args,
             executor._get_effective_env_name(task),
-            task.deps
+            task.deps,
         )
 
         # If task has arguments, append args hash to create unique cache key
@@ -504,16 +599,35 @@ def _execute_dynamic_task(args: list[str], force: bool = False, only: bool = Fal
     state.save()
     try:
         executor.execute_task(task_name, args_dict, force=force, only=only)
-        console.print(f"[green]{get_action_success_string()} Task '{task_name}' completed successfully[/green]")
+        console.print(
+            f"[green]{get_action_success_string()} Task '{task_name}' completed successfully[/green]"
+        )
     except Exception as e:
-        console.print(f"[red]{get_action_failure_string()} Task '{task_name}' failed: {e}[/red]")
+        console.print(
+            f"[red]{get_action_failure_string()} Task '{task_name}' failed: {e}[/red]"
+        )
         raise typer.Exit(1)
 
 
 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]")
+            console.print("[red]Task does not accept arguments[/red]")
             raise typer.Exit(1)
         return {}
 
@@ -537,7 +651,7 @@ def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, A
         else:
             # Positional argument
             if positional_index >= len(parsed_specs):
-                console.print(f"[red]Too many arguments[/red]")
+                console.print("[red]Too many arguments[/red]")
                 raise typer.Exit(1)
             spec = parsed_specs[positional_index]
             arg_value = value_str
@@ -545,13 +659,19 @@ def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, A
 
         # Convert value to appropriate type (exported args are always strings)
         try:
-            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            click_type = get_click_type(
+                spec.arg_type, min_val=spec.min_val, max_val=spec.max_val
+            )
             converted_value = click_type.convert(arg_value, None, None)
 
             # Validate choices after type conversion
             if spec.choices is not None and converted_value not in spec.choices:
-                console.print(f"[red]Invalid value for {spec.name}: {converted_value!r}[/red]")
-                console.print(f"Valid choices: {', '.join(repr(c) for c in spec.choices)}")
+                console.print(
+                    f"[red]Invalid value for {spec.name}: {converted_value!r}[/red]"
+                )
+                console.print(
+                    f"Valid choices: {', '.join(repr(c) for c in spec.choices)}"
+                )
                 raise typer.Exit(1)
 
             args_dict[spec.name] = converted_value
@@ -566,10 +686,14 @@ def _parse_task_args(arg_specs: list[str], arg_values: list[str]) -> dict[str, A
         if spec.name not in args_dict:
             if spec.default is not None:
                 try:
-                    click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+                    click_type = get_click_type(
+                        spec.arg_type, min_val=spec.min_val, max_val=spec.max_val
+                    )
                     args_dict[spec.name] = click_type.convert(spec.default, None, None)
                 except Exception as e:
-                    console.print(f"[red]Invalid default value for {spec.name}: {e}[/red]")
+                    console.print(
+                        f"[red]Invalid default value for {spec.name}: {e}[/red]"
+                    )
                     raise typer.Exit(1)
             else:
                 console.print(f"[red]Missing required argument: {spec.name}[/red]")
@@ -579,6 +703,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 +726,10 @@ def _build_rich_tree(dep_tree: dict) -> Tree:
 
 
 def cli():
-    """Entry point for the CLI."""
+    """
+    Entry point for the CLI.
+    @athena: 3b3cccd1ff6f
+    """
     app()