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

tasktree/state.py

@@ -5,18 +5,24 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, Set
 
 
 @dataclass
 class TaskState:
-    """State for a single task execution."""
+    """
+    State for a single task execution.
+    @athena: b08a937b7f2f
+    """
 
     last_run: float
     input_state: dict[str, float | str] = field(default_factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for JSON serialization."""
+        """
+        Convert to dictionary for JSON serialization.
+        @athena: 5f42efc35e77
+        """
         return {
             "last_run": self.last_run,
             "input_state": self.input_state,
@@ -24,7 +30,10 @@ class TaskState:
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "TaskState":
-        """Create from dictionary loaded from JSON."""
+        """
+        Create from dictionary loaded from JSON.
+        @athena: d9237db7e7e7
+        """
         return cls(
             last_run=data["last_run"],
             input_state=data.get("input_state", {}),
@@ -32,15 +41,20 @@ class TaskState:
 
 
 class StateManager:
-    """Manages the .tasktree-state file."""
+    """
+    Manages the .tasktree-state file.
+    @athena: 3dd3447bb53b
+    """
 
     STATE_FILE = ".tasktree-state"
 
     def __init__(self, project_root: Path):
-        """Initialize state manager.
+        """
+        Initialize state manager.
 
         Args:
-            project_root: Root directory of the project
+        project_root: Root directory of the project
+        @athena: a0afbd8ae591
         """
         self.project_root = project_root
         self.state_path = project_root / self.STATE_FILE
@@ -48,55 +62,66 @@ class StateManager:
         self._loaded = False
 
     def load(self) -> None:
-        """Load state from file if it exists."""
+        """
+        Load state from file if it exists.
+        @athena: e0cf9097c590
+        """
         if self.state_path.exists():
             try:
                 with open(self.state_path, "r") as f:
                     data = json.load(f)
                     self._state = {
-                        key: TaskState.from_dict(value)
-                        for key, value in data.items()
+                        key: TaskState.from_dict(value) for key, value in data.items()
                     }
-            except (json.JSONDecodeError, KeyError) as e:
+            except (json.JSONDecodeError, KeyError):
                 # If state file is corrupted, start fresh
                 self._state = {}
         self._loaded = True
 
     def save(self) -> None:
-        """Save state to file."""
+        """
+        Save state to file.
+        @athena: 11e4a9761e4d
+        """
         data = {key: value.to_dict() for key, value in self._state.items()}
         with open(self.state_path, "w") as f:
             json.dump(data, f, indent=2)
 
     def get(self, cache_key: str) -> TaskState | None:
-        """Get state for a task.
+        """
+        Get state for a task.
 
         Args:
-            cache_key: Cache key (task_hash or task_hash__args_hash)
+        cache_key: Cache key (task_hash or task_hash__args_hash)
 
         Returns:
-            TaskState if found, None otherwise
+        TaskState if found, None otherwise
+        @athena: fe5b27e855eb
         """
         if not self._loaded:
             self.load()
         return self._state.get(cache_key)
 
     def set(self, cache_key: str, state: TaskState) -> None:
-        """Set state for a task.
+        """
+        Set state for a task.
 
         Args:
-            cache_key: Cache key (task_hash or task_hash__args_hash)
-            state: TaskState to store
+        cache_key: Cache key (task_hash or task_hash__args_hash)
+        state: TaskState to store
+        @athena: 244f16ea0ebc
         """
         if not self._loaded:
             self.load()
         self._state[cache_key] = state
 
-    def prune(self, valid_task_hashes: set[str]) -> None:
-        """Remove state entries for tasks that no longer exist.
+    def prune(self, valid_task_hashes: Set[str]) -> None:
+        """
+        Remove state entries for tasks that no longer exist.
 
         Args:
-            valid_task_hashes: Set of valid task hashes from current recipe
+        valid_task_hashes: Set of valid task hashes from current recipe
+        @athena: 2717c6c244d3
         """
         if not self._loaded:
             self.load()
@@ -114,6 +139,9 @@ class StateManager:
             del self._state[key]
 
     def clear(self) -> None:
-        """Clear all state (useful for testing)."""
+        """
+        Clear all state (useful for testing).
+        @athena: 3a92e36d9f83
+        """
         self._state = {}
         self._loaded = True

tasktree/substitution.py

@@ -1,45 +1,49 @@
-"""Placeholder substitution for variables, arguments, and environment variables.
+"""
+Placeholder substitution for variables, arguments, and environment variables.
 
 This module provides functions to substitute {{ var.name }}, {{ arg.name }},
 and {{ env.NAME }} placeholders with their corresponding values.
+@athena: f92441b6fff5
 """
 
 import re
-from random import choice
 from typing import Any
 
-
 # Pattern matches: {{ prefix.name }} with optional whitespace
 # Groups: (1) prefix (var|arg|env|tt), (2) name (identifier)
 PLACEHOLDER_PATTERN = re.compile(
-    r'\{\{\s*(var|arg|env|tt)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}'
+    r"\{\{\s*(var|arg|env|tt)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*}}"
 )
 
 # Pattern matches: {{ dep.task_name.outputs.output_name }} with optional whitespace
 # Groups: (1) task_name (can include dots for namespacing), (2) output_name (identifier)
 DEP_OUTPUT_PATTERN = re.compile(
-    r'\{\{\s*dep\.([a-zA-Z_][a-zA-Z0-9_.-]*)\.outputs\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}'
+    r"\{\{\s*dep\.([a-zA-Z_][a-zA-Z0-9_.-]*)\.outputs\.([a-zA-Z_][a-zA-Z0-9_]*)\s*}}"
 )
 
-# Pattern matches: {{ self.(inputs|outputs).name }} with optional whitespace
-# Groups: (1) field (inputs|outputs), (2) name (identifier)
+# Pattern matches: {{ self.(inputs|outputs).name }} or {{ self.(inputs|outputs).0 }} with optional whitespace
+# Groups: (1) field (inputs|outputs), (2) name (identifier) or index (numeric)
 SELF_REFERENCE_PATTERN = re.compile(
-    r'\{\{\s*self\.(inputs|outputs)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}'
+    r"\{\{\s*self\.(inputs|outputs)\.([a-zA-Z_][a-zA-Z0-9_]*|[0-9]+)\s*}}"
 )
 
 
-def substitute_variables(text: str | dict[str, Any], variables: dict[str, str]) -> str | dict[str, Any]:
-    """Substitute {{ var.name }} placeholders with variable values.
+def substitute_variables(
+    text: str | dict[str, Any], variables: dict[str, str]
+) -> str | dict[str, Any]:
+    """
+    Substitute {{ var.name }} placeholders with variable values.
 
     Args:
-        text: Text containing {{ var.name }} placeholders, or an argument dict with elements to be substituted
-        variables: Dictionary mapping variable names to their string values
+    text: Text containing {{ var.name }} placeholders, or an argument dict with elements to be substituted
+    variables: Dictionary mapping variable names to their string values
 
     Returns:
-        Text with all {{ var.name }} placeholders replaced
+    Text with all {{ var.name }} placeholders replaced
 
     Raises:
-        ValueError: If a referenced variable is not defined
+    ValueError: If a referenced variable is not defined
+    @athena: 93e0fbbe447c
     """
     if isinstance(text, dict):
         # The dict will only contain a single key, the value of this key should also be a dictionary, which contains
@@ -48,13 +52,18 @@ def substitute_variables(text: str | dict[str, Any], variables: dict[str, str])
 
         for arg_name in text.keys():
             # Pull out and substitute the individual fields of an argument one at a time
-            for field in  [ "default", "min", "max" ]:
+            for field in ["default", "min", "max"]:
                 if field in text[arg_name]:
-                    text[arg_name][field] = substitute_variables(text[arg_name][field], variables)
+                    text[arg_name][field] = substitute_variables(
+                        text[arg_name][field], variables
+                    )
 
             # choices is a list of things
             if "choices" in text[arg_name]:
-                text[arg_name]["choices"] = [substitute_variables(c, variables) for c in text[arg_name]["choices"]]
+                text[arg_name]["choices"] = [
+                    substitute_variables(c, variables)
+                    for c in text[arg_name]["choices"]
+                ]
 
             return text
         else:
@@ -84,19 +93,23 @@ def substitute_variables(text: str | dict[str, Any], variables: dict[str, str])
         return PLACEHOLDER_PATTERN.sub(replace_match, text)
 
 
-def substitute_arguments(text: str, args: dict[str, Any], exported_args: set[str] | None = None) -> str:
-    """Substitute {{ arg.name }} placeholders with argument values.
+def substitute_arguments(
+    text: str, args: dict[str, Any], exported_args: set[str] | None = None
+) -> str:
+    """
+    Substitute {{ arg.name }} placeholders with argument values.
 
     Args:
-        text: Text containing {{ arg.name }} placeholders
-        args: Dictionary mapping argument names to their values
-        exported_args: Set of argument names that are exported (not available for substitution)
+    text: Text containing {{ arg.name }} placeholders
+    args: Dictionary mapping argument names to their values
+    exported_args: Set of argument names that are exported (not available for substitution)
 
     Returns:
-        Text with all {{ arg.name }} placeholders replaced
+    Text with all {{ arg.name }} placeholders replaced
 
     Raises:
-        ValueError: If a referenced argument is not provided or is exported
+    ValueError: If a referenced argument is not provided or is exported
+    @athena: 39577c2b74a6
     """
     # Use empty set if None for cleaner handling
     exported_args = exported_args or set()
@@ -134,23 +147,25 @@ def substitute_arguments(text: str, args: dict[str, Any], exported_args: set[str
 
 
 def substitute_environment(text: str) -> str:
-    """Substitute {{ env.NAME }} placeholders with environment variable values.
+    """
+    Substitute {{ env.NAME }} placeholders with environment variable values.
 
     Environment variables are read from os.environ at substitution time.
 
     Args:
-        text: Text containing {{ env.NAME }} placeholders
+    text: Text containing {{ env.NAME }} placeholders
 
     Returns:
-        Text with all {{ env.NAME }} placeholders replaced
+    Text with all {{ env.NAME }} placeholders replaced
 
     Raises:
-        ValueError: If a referenced environment variable is not set
+    ValueError: If a referenced environment variable is not set
 
     Example:
-        >>> os.environ['USER'] = 'alice'
-        >>> substitute_environment("Hello {{ env.USER }}")
-        'Hello alice'
+    >>> os.environ['USER'] = 'alice'
+    >>> substitute_environment("Hello {{ env.USER }}")
+    'Hello alice'
+    @athena: 4f2afd2e0da2
     """
     import os
 
@@ -164,9 +179,7 @@ def substitute_environment(text: str) -> str:
 
         value = os.environ.get(name)
         if value is None:
-            raise ValueError(
-                f"Environment variable '{name}' is not set"
-            )
+            raise ValueError(f"Environment variable '{name}' is not set")
 
         return value
 
@@ -174,25 +187,28 @@ def substitute_environment(text: str) -> str:
 
 
 def substitute_builtin_variables(text: str, builtin_vars: dict[str, str]) -> str:
-    """Substitute {{ tt.name }} placeholders with built-in variable values.
+    """
+    Substitute {{ tt.name }} placeholders with built-in variable values.
 
     Built-in variables are system-provided values that tasks can reference.
 
     Args:
-        text: Text containing {{ tt.name }} placeholders
-        builtin_vars: Dictionary mapping built-in variable names to their string values
+    text: Text containing {{ tt.name }} placeholders
+    builtin_vars: Dictionary mapping built-in variable names to their string values
 
     Returns:
-        Text with all {{ tt.name }} placeholders replaced
+    Text with all {{ tt.name }} placeholders replaced
 
     Raises:
-        ValueError: If a referenced built-in variable is not defined
+    ValueError: If a referenced built-in variable is not defined
 
     Example:
-        >>> builtin_vars = {'project_root': '/home/user/project', 'task_name': 'build'}
-        >>> substitute_builtin_variables("Root: {{ tt.project_root }}", builtin_vars)
-        'Root: /home/user/project'
+    >>> builtin_vars = {'project_root': '/home/user/project', 'task_name': 'build'}
+    >>> substitute_builtin_variables("Root: {{ tt.project_root }}", builtin_vars)
+    'Root: /home/user/project'
+    @athena: 716250e3a71f
     """
+
     def replace_match(match: re.Match) -> str:
         prefix = match.group(1)
         name = match.group(2)
@@ -216,29 +232,31 @@ def substitute_dependency_args(
     template_value: str,
     parent_task_name: str,
     parent_args: dict[str, Any],
-    exported_args: set[str] | None = None
+    exported_args: set[str] | None = None,
 ) -> str:
-    """Substitute {{ arg.* }} templates in dependency argument values.
+    """
+    Substitute {{ arg.* }} templates in dependency argument values.
 
     This function substitutes parent task's arguments into dependency argument
     templates. Only {{ arg.* }} placeholders are allowed in dependency arguments.
 
     Args:
-        template_value: String that may contain {{ arg.* }} placeholders
-        parent_task_name: Name of parent task (for error messages)
-        parent_args: Parent task's argument values
-        exported_args: Set of parent's exported argument names
+    template_value: String that may contain {{ arg.* }} placeholders
+    parent_task_name: Name of parent task (for error messages)
+    parent_args: Parent task's argument values
+    exported_args: Set of parent's exported argument names
 
     Returns:
-        String with {{ arg.* }} placeholders substituted
+    String with {{ arg.* }} placeholders substituted
 
     Raises:
-        ValueError: If template references undefined arg, uses exported arg,
-                   or contains non-arg placeholders ({{ var.* }}, {{ env.* }}, {{ tt.* }})
+    ValueError: If template references undefined arg, uses exported arg,
+    or contains non-arg placeholders ({{ var.* }}, {{ env.* }}, {{ tt.* }})
 
     Example:
-        >>> substitute_dependency_args("{{ arg.mode }}", "build", {"mode": "debug"})
-        'debug'
+    >>> substitute_dependency_args("{{ arg.mode }}", "build", {"mode": "debug"})
+    'debug'
+    @athena: 3d07a1b4e6bc
     """
     # Check for disallowed placeholder types in dependency args
     # Only {{ arg.* }} is allowed, not {{ var.* }}, {{ env.* }}, or {{ tt.* }}
@@ -282,21 +300,23 @@ def substitute_dependency_args(
 
 
 def substitute_all(text: str, variables: dict[str, str], args: dict[str, Any]) -> str:
-    """Substitute all placeholder types: variables, arguments, environment.
+    """
+    Substitute all placeholder types: variables, arguments, environment.
 
     Substitution order: variables → arguments → environment.
     This allows variables to contain arg/env placeholders.
 
     Args:
-        text: Text containing placeholders
-        variables: Dictionary mapping variable names to their string values
-        args: Dictionary mapping argument names to their values
+    text: Text containing placeholders
+    variables: Dictionary mapping variable names to their string values
+    args: Dictionary mapping argument names to their values
 
     Returns:
-        Text with all placeholders replaced
+    Text with all placeholders replaced
 
     Raises:
-        ValueError: If any referenced variable, argument, or environment variable is not defined
+    ValueError: If any referenced variable, argument, or environment variable is not defined
+    @athena: c3fe48d3df5a
     """
     text = substitute_variables(text, variables)
     text = substitute_arguments(text, args)
@@ -310,7 +330,8 @@ def substitute_dependency_outputs(
     current_task_deps: list[str],
     resolved_tasks: dict[str, Any],
 ) -> str:
-    """Substitute {{ dep.<task>.outputs.<name> }} placeholders with dependency output paths.
+    """
+    Substitute {{ dep.<task>.outputs.<name> }} placeholders with dependency output paths.
 
     This function resolves references to named outputs from dependency tasks.
     It validates that:
@@ -319,28 +340,30 @@ def substitute_dependency_outputs(
     - The referenced output name exists in the dependency task
 
     Args:
-        text: Text containing {{ dep.*.outputs.* }} placeholders
-        current_task_name: Name of task being resolved (for error messages)
-        current_task_deps: List of dependency task names for the current task
-        resolved_tasks: Dictionary mapping task names to Task objects (already resolved)
+    text: Text containing {{ dep.*.outputs.* }} placeholders
+    current_task_name: Name of task being resolved (for error messages)
+    current_task_deps: List of dependency task names for the current task
+    resolved_tasks: Dictionary mapping task names to Task objects (already resolved)
 
     Returns:
-        Text with all {{ dep.*.outputs.* }} placeholders replaced with output paths
+    Text with all {{ dep.*.outputs.* }} placeholders replaced with output paths
 
     Raises:
-        ValueError: If referenced task doesn't exist, isn't a dependency,
-                   or doesn't have the named output
+    ValueError: If referenced task doesn't exist, isn't a dependency,
+    or doesn't have the named output
 
     Example:
-        >>> # Assuming build task has output { bundle: "dist/app.js" }
-        >>> substitute_dependency_outputs(
-        ...     "Deploy {{ dep.build.outputs.bundle }}",
-        ...     "deploy",
-        ...     ["build"],
-        ...     {"build": build_task}
-        ... )
-        'Deploy dist/app.js'
+    >>> # Assuming build task has output { bundle: "dist/app.js" }
+    >>> substitute_dependency_outputs(
+    ...     "Deploy {{ dep.build.outputs.bundle }}",
+    ...     "deploy",
+    ...     ["build"],
+    ...     {"build": build_task}
+    ... )
+    'Deploy dist/app.js'
+    @athena: 1e537c8d579c
     """
+
     def replacer(match: re.Match) -> str:
         dep_task_name = match.group(1)
         output_name = match.group(2)
@@ -367,7 +390,11 @@ def substitute_dependency_outputs(
         # Look up the named output
         if output_name not in dep_task._output_map:
             available = list(dep_task._output_map.keys())
-            available_msg = ", ".join(available) if available else "(none - all outputs are anonymous)"
+            available_msg = (
+                ", ".join(available)
+                if available
+                else "(none - all outputs are anonymous)"
+            )
             raise ValueError(
                 f"Task '{current_task_name}' references output '{output_name}' "
                 f"from task '{dep_task_name}', but '{dep_task_name}' has no output named '{output_name}'.\n"
@@ -385,63 +412,107 @@ def substitute_self_references(
     task_name: str,
     input_map: dict[str, str],
     output_map: dict[str, str],
+    indexed_inputs: list[str],
+    indexed_outputs: list[str],
 ) -> str:
-    """Substitute {{ self.inputs.name }} and {{ self.outputs.name }} placeholders.
+    """
+    Substitute {{ self.inputs.name }} and {{ self.outputs.name }} placeholders.
+
+    This function resolves references to the task's own inputs and outputs.
+    Supports both named access ({{ self.inputs.name }}) and positional access
+    ({{ self.inputs.0 }}, {{ self.inputs.1 }}, etc.).
+
+    Named entries use the input_map/output_map dictionaries.
+    Positional entries use indexed_inputs/indexed_outputs lists (0-based indexing,
+    following YAML declaration order).
 
-    This function resolves references to the task's own named inputs and outputs.
-    Only named entries are accessible; anonymous inputs/outputs cannot be referenced.
     The substitution is literal string replacement - no glob expansion or path resolution.
 
     Args:
-        text: Text containing {{ self.* }} placeholders
-        task_name: Name of current task (for error messages)
-        input_map: Dictionary mapping input names to path strings
-        output_map: Dictionary mapping output names to path strings
+    text: Text containing {{ self.* }} placeholders
+    task_name: Name of current task (for error messages)
+    input_map: Dictionary mapping input names to path strings
+    output_map: Dictionary mapping output names to path strings
+    indexed_inputs: List of all inputs in YAML order
+    indexed_outputs: List of all outputs in YAML order
 
     Returns:
-        Text with all {{ self.* }} placeholders replaced with literal path strings
+    Text with all {{ self.* }} placeholders replaced with literal path strings
 
     Raises:
-        ValueError: If referenced name doesn't exist in input_map or output_map
+    ValueError: If referenced name doesn't exist or index is out of bounds
 
     Example:
-        >>> input_map = {"src": "*.txt"}
-        >>> output_map = {"dest": "out/result.txt"}
-        >>> substitute_self_references(
-        ...     "cp {{ self.inputs.src }} {{ self.outputs.dest }}",
-        ...     "copy",
-        ...     input_map,
-        ...     output_map
-        ... )
-        'cp *.txt out/result.txt'
+    >>> input_map = {"src": "*.txt"}
+    >>> output_map = {"dest": "out/result.txt"}
+    >>> indexed_inputs = ["*.txt"]
+    >>> indexed_outputs = ["out/result.txt"]
+    >>> substitute_self_references(
+    ...     "cp {{ self.inputs.src }} {{ self.outputs.0 }}",
+    ...     "copy",
+    ...     input_map,
+    ...     output_map,
+    ...     indexed_inputs,
+    ...     indexed_outputs
+    ... )
+    'cp *.txt out/result.txt'
+    @athena: 9d997ff08eef
     """
+
     def replacer(match: re.Match) -> str:
         field = match.group(1)  # "inputs" or "outputs"
-        name = match.group(2)
+        identifier = match.group(2)  # name or numeric index
 
-        # Select appropriate map
-        if field == "inputs":
-            name_map = input_map
-            field_display = "input"
-        else:  # field == "outputs"
-            name_map = output_map
-            field_display = "output"
-
-        # Check if name exists in map
-        if name not in name_map:
-            available = list(name_map.keys())
-            if available:
-                available_msg = ", ".join(available)
-            else:
-                available_msg = f"(none - all {field} are anonymous)"
+        # Check if identifier is a numeric index
+        if identifier.isdigit():
+            # Positional access
+            index = int(identifier)
+            indexed_list = indexed_inputs if field == "inputs" else indexed_outputs
+            field_display = "input" if field == "inputs" else "output"
 
-            raise ValueError(
-                f"Task '{task_name}' references {field_display} '{name}' "
-                f"but has no {field_display} named '{name}'.\n"
-                f"Available named {field}: {available_msg}\n"
-                f"Hint: Define named {field} like: {field}: [{{ {name}: 'path/to/file' }}]"
-            )
+            # Check if list is empty
+            if len(indexed_list) == 0:
+                raise ValueError(
+                    f"Task '{task_name}' references {field_display} index '{index}' "
+                    f"but has no {field} defined"
+                )
+
+            # Check bounds
+            if index >= len(indexed_list):
+                max_index = len(indexed_list) - 1
+                raise ValueError(
+                    f"Task '{task_name}' references {field_display} index '{index}' "
+                    f"but only has {len(indexed_list)} {field} (indices 0-{max_index})"
+                )
+
+            return indexed_list[index]
+        else:
+            # Named access (existing logic)
+            name = identifier
+
+            # Select appropriate map
+            if field == "inputs":
+                name_map = input_map
+                field_display = "input"
+            else:  # field == "outputs"
+                name_map = output_map
+                field_display = "output"
+
+            # Check if name exists in map
+            if name not in name_map:
+                available = list(name_map.keys())
+                if available:
+                    available_msg = ", ".join(available)
+                else:
+                    available_msg = f"(none - all {field} are anonymous)"
+
+                raise ValueError(
+                    f"Task '{task_name}' references {field_display} '{name}' "
+                    f"but has no {field_display} named '{name}'.\n"
+                    f"Available named {field}: {available_msg}\n"
+                    f"Hint: Define named {field} like: {field}: [{{ {name}: 'path/to/file' }}]"
+                )
 
-        return name_map[name]
+            return name_map[name]
 
     return SELF_REFERENCE_PATTERN.sub(replacer, text)