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

tasktree/state.py

@@ -10,13 +10,19 @@ from typing import Any
 
 @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: 44713c70e04e
+    """
 
     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,7 +62,10 @@ class StateManager:
         self._loaded = False
 
     def load(self) -> None:
-        """Load state from file if it exists."""
+        """
+        Load state from file if it exists.
+        @athena: 11748af0886c
+        """
         if self.state_path.exists():
             try:
                 with open(self.state_path, "r") as f:
@@ -63,40 +80,49 @@ class StateManager:
         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.
+        """
+        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: ce21bb523d49
         """
         if not self._loaded:
             self.load()
@@ -114,6 +140,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,7 +1,9 @@
-"""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
@@ -21,25 +23,27 @@ DEP_OUTPUT_PATTERN = re.compile(
     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.
+    """
+    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
@@ -85,18 +89,20 @@ def substitute_variables(text: str | dict[str, Any], variables: dict[str, str])
 
 
 def substitute_arguments(text: str, args: dict[str, Any], exported_args: set[str] | None = None) -> str:
-    """Substitute {{ arg.name }} placeholders with argument values.
+    """
+    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 +140,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
 
@@ -174,24 +182,26 @@ 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)
@@ -218,27 +228,29 @@ def substitute_dependency_args(
     parent_args: dict[str, Any],
     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 +294,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 +324,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,27 +334,28 @@ 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)
@@ -385,63 +401,106 @@ 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)