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

tasktree/graph.py

@@ -1,7 +1,9 @@
-"""Dependency resolution using topological sorting."""
+"""
+Dependency resolution using topological sorting.
+@athena: bc19c5dc0cca
+"""
 
 from graphlib import TopologicalSorter
-from pathlib import Path
 from typing import Any
 
 from tasktree.hasher import hash_args
@@ -10,25 +12,26 @@ from tasktree.parser import (
     Task,
     DependencyInvocation,
     parse_dependency_spec,
-    parse_arg_spec,
 )
 from tasktree.substitution import substitute_dependency_args
 
 
 def _get_exported_arg_names(task: Task) -> set[str]:
-    """Extract names of exported arguments from a task.
+    """
+    Extract names of exported arguments from a task.
 
     Exported arguments are identified by the '$' prefix in their definition.
 
     Args:
-        task: Task to extract exported arg names from
+    task: Task to extract exported arg names from
 
     Returns:
-        Set of exported argument names (without the '$' prefix)
+    Set of exported argument names (without the '$' prefix)
 
     Example:
-        Task with args: ["$server", "port"]
-        Returns: {"server"}
+    Task with args: ["$server", "port"]
+    Returns: {"server"}
+    @athena: 706576271735
     """
     if not task.args:
         return set()
@@ -53,9 +56,10 @@ def resolve_dependency_invocation(
     parent_task_name: str,
     parent_args: dict[str, Any],
     parent_exported_args: set[str],
-    recipe: Recipe
+    recipe: Recipe,
 ) -> DependencyInvocation:
-    """Parse dependency specification and substitute parent argument templates.
+    """
+    Parse dependency specification and substitute parent argument templates.
 
     This function handles template substitution in dependency arguments. It:
     1. Checks if dependency arguments contain {{ arg.* }} templates
@@ -63,37 +67,38 @@ def resolve_dependency_invocation(
     3. Delegates to parse_dependency_spec for type conversion and validation
 
     Args:
-        dep_spec: Dependency specification (str or dict with task name and args)
-        parent_task_name: Name of the parent task (for error messages)
-        parent_args: Parent task's argument values (for template substitution)
-        parent_exported_args: Set of parent's exported argument names
-        recipe: Recipe containing task definitions
+    dep_spec: Dependency specification (str or dict with task name and args)
+    parent_task_name: Name of the parent task (for error messages)
+    parent_args: Parent task's argument values (for template substitution)
+    parent_exported_args: Set of parent's exported argument names
+    recipe: Recipe containing task definitions
 
     Returns:
-        DependencyInvocation with typed, validated arguments
+    DependencyInvocation with typed, validated arguments
 
     Raises:
-        ValueError: If template substitution fails, argument validation fails,
-                   or dependency task doesn't exist
+    ValueError: If template substitution fails, argument validation fails,
+    or dependency task doesn't exist
 
     Examples:
-        Simple string (no templates):
-        >>> resolve_dependency_invocation("build", "test", {}, set(), recipe)
-        DependencyInvocation("build", None)
-
-        Literal arguments (no templates):
-        >>> resolve_dependency_invocation({"build": ["debug"]}, "test", {}, set(), recipe)
-        DependencyInvocation("build", {"mode": "debug"})
-
-        Template substitution:
-        >>> resolve_dependency_invocation(
-        ...     {"build": ["{{ arg.env }}"]},
-        ...     "test",
-        ...     {"env": "production"},
-        ...     set(),
-        ...     recipe
-        ... )
-        DependencyInvocation("build", {"mode": "production"})
+    Simple string (no templates):
+    >>> resolve_dependency_invocation("build", "test", {}, set(), recipe)
+    DependencyInvocation("build", None)
+
+    Literal arguments (no templates):
+    >>> resolve_dependency_invocation({"build": ["debug"]}, "test", {}, set(), recipe)
+    DependencyInvocation("build", {"mode": "debug"})
+
+    Template substitution:
+    >>> resolve_dependency_invocation(
+    ...     {"build": ["{{ arg.env }}"]},
+    ...     "test",
+    ...     {"env": "production"},
+    ...     set(),
+    ...     recipe
+    ... )
+    DependencyInvocation("build", {"mode": "production"})
+    @athena: 968bae796809
     """
     # Simple string case - no args to substitute
     if isinstance(dep_spec, str):
@@ -163,30 +168,44 @@ def resolve_dependency_invocation(
 
 
 class CycleError(Exception):
-    """Raised when a dependency cycle is detected."""
+    """
+    Raised when a dependency cycle is detected.
+    @athena: 80f584af9b92
+    """
 
     pass
 
 
 class TaskNotFoundError(Exception):
-    """Raised when a task dependency doesn't exist."""
+    """
+    Raised when a task dependency doesn't exist.
+    @athena: f838e39564ae
+    """
 
     pass
 
 
 class TaskNode:
-    """Represents a node in the dependency graph (task + arguments).
+    """
+    Represents a node in the dependency graph (task + arguments).
 
     Each node represents a unique invocation of a task with specific arguments.
     Tasks invoked with different arguments are considered different nodes.
+    @athena: b5ff009e2f60
     """
 
     def __init__(self, task_name: str, args: dict[str, Any] | None = None):
+        """
+        @athena: 24d686697ce3
+        """
         self.task_name = task_name
         self.args = args  # Keep None as None
 
     def __hash__(self):
-        """Hash based on task name and sorted args."""
+        """
+        Hash based on task name and sorted args.
+        @athena: 16615e007076
+        """
         # Treat None and {} as equivalent for hashing
         if not self.args:
             return hash(self.task_name)
@@ -194,7 +213,10 @@ class TaskNode:
         return hash((self.task_name, args_hash))
 
     def __eq__(self, other):
-        """Equality based on task name and args."""
+        """
+        Equality based on task name and args.
+        @athena: 139d5234448f
+        """
         if not isinstance(other, TaskNode):
             return False
         # Treat None and {} as equivalent
@@ -203,12 +225,18 @@ class TaskNode:
         return self.task_name == other.task_name and self_args == other_args
 
     def __repr__(self):
+        """
+        @athena: dd99b6a7835e
+        """
         if not self.args:
             return f"TaskNode({self.task_name})"
         args_str = ", ".join(f"{k}={v}" for k, v in sorted(self.args.items()))
         return f"TaskNode({self.task_name}, {{{args_str}}})"
 
     def __str__(self):
+        """
+        @athena: 2d82ca4b9d41
+        """
         if not self.args:
             return self.task_name
         args_str = ", ".join(f"{k}={v}" for k, v in sorted(self.args.items()))
@@ -216,23 +244,23 @@ class TaskNode:
 
 
 def resolve_execution_order(
-    recipe: Recipe,
-    target_task: str,
-    target_args: dict[str, Any] | None = None
+    recipe: Recipe, target_task: str, target_args: dict[str, Any] | None = None
 ) -> list[tuple[str, dict[str, Any]]]:
-    """Resolve execution order for a task and its dependencies.
+    """
+    Resolve execution order for a task and its dependencies.
 
     Args:
-        recipe: Parsed recipe containing all tasks
-        target_task: Name of the task to execute
-        target_args: Arguments for the target task (optional)
+    recipe: Parsed recipe containing all tasks
+    target_task: Name of the task to execute
+    target_args: Arguments for the target task (optional)
 
     Returns:
-        List of (task_name, args_dict) tuples in execution order (dependencies first)
+    List of (task_name, args_dict) tuples in execution order (dependencies first)
 
     Raises:
-        TaskNotFoundError: If target task or any dependency doesn't exist
-        CycleError: If a dependency cycle is detected
+    TaskNotFoundError: If target task or any dependency doesn't exist
+    CycleError: If a dependency cycle is detected
+    @athena: b4443e1cb45d
     """
     if target_task not in recipe.tasks:
         raise TaskNotFoundError(f"Task not found: {target_task}")
@@ -241,7 +269,9 @@ def resolve_execution_order(
     graph: dict[TaskNode, set[TaskNode]] = {}
 
     # Track seen nodes to detect duplicates
-    seen_invocations: dict[tuple[str, str], TaskNode] = {}  # (task_name, args_hash) -> node
+    seen_invocations: dict[
+        tuple[str, str], TaskNode
+    ] = {}  # (task_name, args_hash) -> node
 
     def get_or_create_node(task_name: str, args: dict[str, Any] | None) -> TaskNode:
         """Get existing node or create new one for this invocation."""
@@ -275,7 +305,7 @@ def resolve_execution_order(
                 parent_task_name=node.task_name,
                 parent_args=node.args or {},
                 parent_exported_args=parent_exported_args,
-                recipe=recipe
+                recipe=recipe,
             )
 
             # Create or get node for this dependency invocation
@@ -310,24 +340,26 @@ def resolve_dependency_output_references(
     recipe: Recipe,
     ordered_tasks: list[tuple[str, dict[str, Any]]],
 ) -> None:
-    """Resolve {{ dep.<task>.outputs.<name> }} references in topological order.
+    """
+    Resolve {{ dep.<task>.outputs.<name> }} references in topological order.
 
     This function walks through tasks in dependency order (dependencies first) and
     resolves any references to dependency outputs in task fields. Templates are
     resolved in place, modifying the Task objects in the recipe.
 
     Args:
-        recipe: Recipe containing task definitions
-        ordered_tasks: List of (task_name, args) tuples in topological order
+    recipe: Recipe containing task definitions
+    ordered_tasks: List of (task_name, args) tuples in topological order
 
     Raises:
-        ValueError: If template references cannot be resolved (missing task,
-                   missing output, task not in dependencies, etc.)
+    ValueError: If template references cannot be resolved (missing task,
+    missing output, task not in dependencies, etc.)
 
     Example:
-        Given tasks in topological order: [('build', {}), ('deploy', {})]
-        If deploy.cmd contains "{{ dep.build.outputs.bundle }}", it will be
-        resolved to the actual output path from the build task.
+    Given tasks in topological order: [('build', {}), ('deploy', {})]
+    If deploy.cmd contains "{{ dep.build.outputs.bundle }}", it will be
+    resolved to the actual output path from the build task.
+    @athena: 6dce9dbe6286
     """
     from tasktree.substitution import substitute_dependency_outputs
 
@@ -418,22 +450,29 @@ def resolve_self_references(
     recipe: Recipe,
     ordered_tasks: list[tuple[str, dict[str, Any]]],
 ) -> None:
-    """Resolve {{ self.inputs.name }} and {{ self.outputs.name }} references.
+    """
+    Resolve {{ self.inputs.name }} and {{ self.inputs.0 }} style references.
 
     This function walks through tasks and resolves self-references to task's own
-    inputs/outputs. Must be called AFTER resolve_dependency_output_references()
-    so that dependency outputs are already resolved in output paths.
+    inputs/outputs. Supports both named access ({{ self.inputs.name }}) and
+    positional access ({{ self.inputs.0 }}, {{ self.inputs.1 }}, etc.).
+
+    Must be called AFTER resolve_dependency_output_references() so that
+    dependency outputs are already resolved in output paths.
 
     Args:
-        recipe: Recipe containing task definitions
-        ordered_tasks: List of (task_name, args) tuples in topological order
+    recipe: Recipe containing task definitions
+    ordered_tasks: List of (task_name, args) tuples in topological order
 
     Raises:
-        ValueError: If self-reference cannot be resolved (missing name, etc.)
+    ValueError: If self-reference cannot be resolved (missing name, out of bounds index, etc.)
 
     Example:
-        If task.cmd contains "{{ self.inputs.src }}" and task has input {src: "*.txt"},
-        it will be resolved to "*.txt" (literal string, no glob expansion).
+    If task.cmd contains "{{ self.inputs.src }}" and task has input {src: "*.txt"},
+    it will be resolved to "*.txt" (literal string, no glob expansion).
+    If task.cmd contains "{{ self.inputs.0 }}" and task has inputs ["*.txt", "*.md"],
+    it will be resolved to "*.txt" (first input in YAML order).
+    @athena: 641e28567d1d
     """
     from tasktree.substitution import substitute_self_references
 
@@ -449,6 +488,8 @@ def resolve_self_references(
                 task_name,
                 task._input_map,
                 task._output_map,
+                task._indexed_inputs,
+                task._indexed_outputs,
             )
 
         # Resolve self-references in working_dir
@@ -458,6 +499,8 @@ def resolve_self_references(
                 task_name,
                 task._input_map,
                 task._output_map,
+                task._indexed_inputs,
+                task._indexed_outputs,
             )
 
         # Resolve self-references in argument defaults
@@ -472,26 +515,30 @@ def resolve_self_references(
                                     task_name,
                                     task._input_map,
                                     task._output_map,
+                                    task._indexed_inputs,
+                                    task._indexed_outputs,
                                 )
 
 
 def get_implicit_inputs(recipe: Recipe, task: Task) -> list[str]:
-    """Get implicit inputs for a task based on its dependencies.
+    """
+    Get implicit inputs for a task based on its dependencies.
 
     Tasks automatically inherit inputs from dependencies:
     1. All outputs from dependency tasks become implicit inputs
     2. All inputs from dependency tasks that don't declare outputs are inherited
     3. If task uses a Docker environment, Docker artifacts become implicit inputs:
-       - Dockerfile
-       - .dockerignore (if present)
-       - Special markers for context directory and base image digests
+    - Dockerfile
+    - .dockerignore (if present)
+    - Special markers for context directory and base image digests
 
     Args:
-        recipe: Parsed recipe containing all tasks
-        task: Task to get implicit inputs for
+    recipe: Parsed recipe containing all tasks
+    task: Task to get implicit inputs for
 
     Returns:
-        List of glob patterns for implicit inputs, including Docker-specific markers
+    List of glob patterns for implicit inputs, including Docker-specific markers
+    @athena: da25e64fbd2b
     """
     implicit_inputs = []
 
@@ -543,20 +590,24 @@ def get_implicit_inputs(recipe: Recipe, task: Task) -> list[str]:
     return implicit_inputs
 
 
-def build_dependency_tree(recipe: Recipe, target_task: str, target_args: dict[str, Any] | None = None) -> dict:
-    """Build a tree structure representing dependencies for visualization.
+def build_dependency_tree(
+    recipe: Recipe, target_task: str, target_args: dict[str, Any] | None = None
+) -> dict:
+    """
+    Build a tree structure representing dependencies for visualization.
 
     Note: This builds a true tree representation where shared dependencies may
     appear multiple times. Each dependency is shown in the context of its parent,
     allowing the full dependency path to be visible from any node.
 
     Args:
-        recipe: Parsed recipe containing all tasks
-        target_task: Name of the task to build tree for
-        target_args: Arguments for the target task (optional)
+    recipe: Parsed recipe containing all tasks
+    target_task: Name of the task to build tree for
+    target_args: Arguments for the target task (optional)
 
     Returns:
-        Nested dictionary representing the dependency tree
+    Nested dictionary representing the dependency tree
+    @athena: 570e5c663887
     """
     if target_task not in recipe.tasks:
         raise TaskNotFoundError(f"Task not found: {target_task}")
@@ -571,12 +622,17 @@ def build_dependency_tree(recipe: Recipe, target_task: str, target_args: dict[st
 
         # Create node identifier for cycle detection
         from tasktree.hasher import hash_args
+
         args_dict = args or {}
         node_id = (task_name, hash_args(args_dict) if args_dict else "")
 
         # Detect cycles in current recursion path
         if node_id in current_path:
-            display_name = task_name if not args_dict else f"{task_name}({', '.join(f'{k}={v}' for k, v in sorted(args_dict.items()))})"
+            display_name = (
+                task_name
+                if not args_dict
+                else f"{task_name}({', '.join(f'{k}={v}' for k, v in sorted(args_dict.items()))})"
+            )
             return {"name": display_name, "deps": [], "cycle": True}
 
         current_path.add(node_id)

tasktree/hasher.py

@@ -1,16 +1,25 @@
+"""Task and argument hashing for incremental execution.
+
+Provides functions to compute deterministic hashes of task definitions,
+arguments, and environment configurations. These hashes are used to detect
+changes that require task re-execution in the incremental build system.
+"""
+
 import hashlib
 import json
 from typing import Any, Optional
 
 
 def _arg_sort_key(arg: str | dict[str, Any]) -> str:
-    """Extract the sort key from an arg for deterministic hashing.
+    """
+    Extract the sort key from an arg for deterministic hashing.
 
     Args:
-        arg: Either a string arg or dict arg specification
+    arg: Either a string arg or dict arg specification
 
     Returns:
-        The argument name to use as a sort key
+    The argument name to use as a sort key
+    @athena: c88bb2cf696b
     """
     if isinstance(arg, dict):
         # Dict args have exactly one key - the argument name
@@ -19,15 +28,31 @@ def _arg_sort_key(arg: str | dict[str, Any]) -> str:
     return arg
 
 
-def _normalize_choices_lists(args: list[str | dict[str, Any]]) ->  list[str | dict[str, Any]]:
+def _normalize_choices_lists(
+    args: list[str | dict[str, Any]],
+) -> list[str | dict[str, Any]]:
+    """
+    Normalize argument choices lists by sorting them for deterministic hashing.
+
+    Args:
+        args: List of argument specifications (strings or dicts)
+
+    Returns:
+        List of argument specs with sorted choices lists
+
+    @athena: 7512379275e3
+    """
     normalized_args = []
     for arg in args:
         if isinstance(arg, dict):
             # Deep copy and sort choices if present
             normalized = {}
             for key, value in arg.items():
-                if isinstance(value, dict) and 'choices' in value:
-                    normalized[key] = {**value, 'choices': sorted(value['choices'], key=str)}
+                if isinstance(value, dict) and "choices" in value:
+                    normalized[key] = {
+                        **value,
+                        "choices": sorted(value["choices"], key=str),
+                    }
                 else:
                     normalized[key] = value
             normalized_args.append(normalized)
@@ -38,20 +63,22 @@ def _normalize_choices_lists(args: list[str | dict[str, Any]]) ->  list[str | di
 
 
 def _serialize_outputs_for_hash(outputs: list[str | dict[str, str]]) -> list[str]:
-    """Serialize outputs to consistent list of strings for hashing.
+    """
+    Serialize outputs to consistent list of strings for hashing.
 
     Converts both named outputs (dicts) and anonymous outputs (strings)
     into a consistent, sortable format.
 
     Args:
-        outputs: List of output specifications (strings or dicts)
+    outputs: List of output specifications (strings or dicts)
 
     Returns:
-        List of serialized output strings in sorted order
+    List of serialized output strings in sorted order
 
     Example:
-        >>> _serialize_outputs_for_hash(["file.txt", {"bundle": "app.js"}])
-        ['bundle:app.js', 'file.txt']
+    >>> _serialize_outputs_for_hash(["file.txt", {"bundle": "app.js"}])
+    ['bundle:app.js', 'file.txt']
+    @athena: 933995400691
     """
     serialized = []
     for output in outputs:
@@ -72,20 +99,22 @@ def hash_task(
     working_dir: str,
     args: list[str | dict[str, Any]],
     env: str = "",
-    deps: list[str | dict[str, Any]] | None = None
+    deps: list[str | dict[str, Any]] | None = None,
 ) -> str:
-    """Hash task definition including dependencies.
+    """
+    Hash task definition including dependencies.
 
     Args:
-        cmd: Task command
-        outputs: Task outputs (strings or named dicts)
-        working_dir: Working directory
-        args: Task argument specifications
-        env: Environment name
-        deps: Dependency specifications (optional, for dependency hash)
+    cmd: Task command
+    outputs: Task outputs (strings or named dicts)
+    working_dir: Working directory
+    args: Task argument specifications
+    env: Environment name
+    deps: Dependency specifications (optional, for dependency hash)
 
     Returns:
-        8-character hash of task definition
+    8-character hash of task definition
+    @athena: 7a461d51a8bb
     """
     data = {
         "cmd": cmd,
@@ -110,28 +139,43 @@ def hash_task(
             else:
                 normalized_deps.append(dep)
         # Sort using JSON serialization for consistent ordering
-        data["deps"] = sorted(normalized_deps, key=lambda x: json.dumps(x, sort_keys=True) if isinstance(x, dict) else x)
+        data["deps"] = sorted(
+            normalized_deps,
+            key=lambda x: json.dumps(x, sort_keys=True) if isinstance(x, dict) else x,
+        )
 
     serialized = json.dumps(data, sort_keys=True, separators=(",", ":"))
     return hashlib.sha256(serialized.encode()).hexdigest()[:8]
 
 
 def hash_args(args_dict: dict[str, Any]) -> str:
+    """
+    Hash task argument values for cache key generation.
+
+    Args:
+        args_dict: Dictionary mapping argument names to their values
+
+    Returns:
+        8-character hash of the argument dictionary
+
+    @athena: 768e562bff64
+    """
     serialized = json.dumps(args_dict, sort_keys=True, separators=(",", ":"))
     return hashlib.sha256(serialized.encode()).hexdigest()[:8]
 
 
 def hash_environment_definition(env) -> str:
-    """Hash environment definition fields that affect task execution.
+    """
+    Hash environment definition fields that affect task execution.
 
     Args:
-        env: Environment to hash
+    env: Environment to hash
 
     Returns:
-        16-character hash of environment definition
+    16-character hash of environment definition
+    @athena: 2de34f1a0b4a
     """
     # Import inside function to avoid circular dependency
-    from tasktree.parser import Environment
 
     # Handle args - can be list (shell args) or dict (docker build args)
     args_value = env.args
@@ -156,6 +200,18 @@ def hash_environment_definition(env) -> str:
 
 
 def make_cache_key(task_hash: str, args_hash: Optional[str] = None) -> str:
+    """
+    Combine task and argument hashes into a cache key.
+
+    Args:
+        task_hash: Hash of the task definition
+        args_hash: Optional hash of task arguments
+
+    Returns:
+        Combined cache key string in format "task_hash__args_hash" or just "task_hash"
+
+    @athena: c85093f485c7
+    """
     if args_hash:
         return f"{task_hash}__{args_hash}"
     return task_hash