tasktree 0.0.19__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
@@ -12,28 +14,36 @@ 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)\s*\.\s*([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\s*\.\s*([a-zA-Z_][a-zA-Z0-9_.-]*)\s*\.\s*outputs\s*\.\s*([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 }} 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_]*|[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
@@ -79,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()
@@ -128,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
 
@@ -168,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)
@@ -212,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.* }}
@@ -276,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)
@@ -304,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:
@@ -313,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)
@@ -372,3 +394,113 @@ def substitute_dependency_outputs(
         return dep_task._output_map[output_name]
 
     return DEP_OUTPUT_PATTERN.sub(replacer, text)
+
+
+def substitute_self_references(
+    text: str,
+    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.
+
+    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).
+
+    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
+    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
+
+    Raises:
+    ValueError: If referenced name doesn't exist or index is out of bounds
+
+    Example:
+    >>> 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"
+        identifier = match.group(2)  # name or numeric index
+
+        # 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"
+
+            # 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 SELF_REFERENCE_PATTERN.sub(replacer, text)

tasktree/types.py

@@ -10,7 +10,10 @@ import click
 
 
 class HostnameType(click.ParamType):
-    """Validates hostname format (not DNS resolution)."""
+    """
+    Validates hostname format (not DNS resolution).
+    @athena: 84a721c40458
+    """
 
     name = "hostname"
 
@@ -20,6 +23,9 @@ class HostnameType(click.ParamType):
     )
 
     def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
+        """
+        @athena: 8d921e52bcf2
+        """
         if isinstance(value, str):
             if self.HOSTNAME_PATTERN.match(value):
                 return value
@@ -27,7 +33,10 @@ class HostnameType(click.ParamType):
 
 
 class EmailType(click.ParamType):
-    """Validates email format (not deliverability)."""
+    """
+    Validates email format (not deliverability).
+    @athena: 95cfacc3f4cd
+    """
 
     name = "email"
 
@@ -37,6 +46,9 @@ class EmailType(click.ParamType):
     )
 
     def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
+        """
+        @athena: 25046aeb6e6f
+        """
         if isinstance(value, str):
             if self.EMAIL_PATTERN.match(value):
                 return value
@@ -44,11 +56,17 @@ class EmailType(click.ParamType):
 
 
 class IPType(click.ParamType):
-    """Validates IP address (IPv4 or IPv6)."""
+    """
+    Validates IP address (IPv4 or IPv6).
+    @athena: dac837bf4894
+    """
 
     name = "ip"
 
     def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
+        """
+        @athena: d57618e5ad89
+        """
         try:
             ip_address(value)
             return str(value)
@@ -57,11 +75,17 @@ class IPType(click.ParamType):
 
 
 class IPv4Type(click.ParamType):
-    """Validates IPv4 address."""
+    """
+    Validates IPv4 address.
+    @athena: ea5957643fe5
+    """
 
     name = "ipv4"
 
     def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
+        """
+        @athena: 7ed2d17d1f1a
+        """
         try:
             IPv4Address(value)
             return str(value)
@@ -70,11 +94,17 @@ class IPv4Type(click.ParamType):
 
 
 class IPv6Type(click.ParamType):
-    """Validates IPv6 address."""
+    """
+    Validates IPv6 address.
+    @athena: 9bc5b38d4f23
+    """
 
     name = "ipv6"
 
     def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
+        """
+        @athena: 4b101e4d54cf
+        """
         try:
             IPv6Address(value)
             return str(value)
@@ -83,11 +113,17 @@ class IPv6Type(click.ParamType):
 
 
 class DateTimeType(click.ParamType):
-    """Validates datetime in format YYYY-MM-DDTHH:MM:SS."""
+    """
+    Validates datetime in format YYYY-MM-DDTHH:MM:SS.
+    @athena: c3bafa3e22e3
+    """
 
     name = "datetime"
 
     def convert(self, value: Any, param: Optional[click.Parameter], ctx: Optional[click.Context]) -> str:
+        """
+        @athena: 13fa66adfe94
+        """
         if isinstance(value, str):
             try:
                 datetime.fromisoformat(value)
@@ -114,18 +150,20 @@ TYPE_MAPPING = {
 
 
 def get_click_type(type_name: str, min_val: int | float | None = None, max_val: int | float | None = None) -> click.ParamType:
-    """Get Click parameter type by name with optional range constraints.
+    """
+    Get Click parameter type by name with optional range constraints.
 
     Args:
-        type_name: Type name from task definition (e.g., 'str', 'int', 'hostname')
-        min_val: Optional minimum value for numeric types
-        max_val: Optional maximum value for numeric types
+    type_name: Type name from task definition (e.g., 'str', 'int', 'hostname')
+    min_val: Optional minimum value for numeric types
+    max_val: Optional maximum value for numeric types
 
     Returns:
-        Click parameter type instance
+    Click parameter type instance
 
     Raises:
-        ValueError: If type_name is not recognized
+    ValueError: If type_name is not recognized
+    @athena: d0912868676f
     """
     if type_name not in TYPE_MAPPING:
         raise ValueError(f"Unknown type: {type_name}")