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

{tasktree-0.0.19.dist-info → tasktree-0.0.21.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.19
+Version: 0.0.21
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -833,6 +833,369 @@ Hint: Define named outputs like: outputs: [{ missing: 'path/to/file' }]
 - **Deployment pipelines**: Reference exact artifacts to deploy
 - **Configuration propagation**: Pass generated config files through build stages
 
+### Self-References
+
+Tasks can reference their own inputs and outputs using `{{ self.inputs.name }}` (named access) or `{{ self.inputs.0 }}` (positional access) templates. This eliminates repetition when paths contain variables or when tasks have multiple inputs/outputs.
+
+**Named Inputs and Outputs:**
+
+Just like dependency output references, inputs and outputs can have names:
+
+```yaml
+tasks:
+  process:
+    inputs:
+      - src: "data/input.json"      # Named input
+      - config: "config.yaml"        # Named input
+    outputs:
+      - result: "output/result.json" # Named output
+      - log: "output/process.log"    # Named output
+    cmd: |
+      process-tool \
+        --input {{ self.inputs.src }} \
+        --config {{ self.inputs.config }} \
+        --output {{ self.outputs.result }} \
+        --log {{ self.outputs.log }}
+```
+
+**Syntax:**
+
+- **Defining named inputs**: `inputs: [{ name: "path/to/file" }]`
+- **Defining named outputs**: `outputs: [{ name: "path/to/file" }]`
+- **Defining anonymous inputs**: `inputs: ["path/to/file"]`
+- **Defining anonymous outputs**: `outputs: ["path/to/file"]`
+- **Referencing by name**: `{{ self.inputs.input_name }}` or `{{ self.outputs.output_name }}`
+- **Referencing by index**: `{{ self.inputs.0 }}` or `{{ self.outputs.1 }}` (0-based)
+- **Mixed format**: Can combine named and anonymous inputs/outputs in the same task
+
+**Why Use Self-References?**
+
+Self-references follow the DRY (Don't Repeat Yourself) principle:
+
+```yaml
+# Without self-references - repetitive
+tasks:
+  build:
+    inputs: [src/app-{{ var.version }}.c]
+    outputs: [build/app-{{ var.version }}.o]
+    cmd: gcc src/app-{{ var.version }}.c -o build/app-{{ var.version }}.o
+
+# With self-references - DRY
+tasks:
+  build:
+    inputs:
+      - source: src/app-{{ var.version }}.c
+    outputs:
+      - object: build/app-{{ var.version }}.o
+    cmd: gcc {{ self.inputs.source }} -o {{ self.outputs.object }}
+```
+
+**Working with Variables:**
+
+Self-references work seamlessly with variables:
+
+```yaml
+variables:
+  platform: linux
+  arch: x86_64
+
+tasks:
+  compile:
+    inputs:
+      - src: src/{{ var.platform }}/main.c
+      - header: include/{{ var.arch }}/defs.h
+    outputs:
+      - binary: build/{{ var.platform }}-{{ var.arch }}/app
+    cmd: |
+      gcc {{ self.inputs.src }} \
+        -include {{ self.inputs.header }} \
+        -o {{ self.outputs.binary }}
+```
+
+Variables are evaluated first, then self-references substitute the expanded paths.
+
+**Working with Arguments:**
+
+Self-references work with parameterized tasks:
+
+```yaml
+tasks:
+  deploy:
+    args: [environment]
+    inputs:
+      - config: configs/{{ arg.environment }}/app.yaml
+    outputs:
+      - deployed: deployed-{{ arg.environment }}.yaml
+    cmd: |
+      validate {{ self.inputs.config }}
+      deploy {{ self.inputs.config }} > {{ self.outputs.deployed }}
+```
+
+```bash
+tt deploy production  # Uses configs/production/app.yaml
+tt deploy staging     # Uses configs/staging/app.yaml
+```
+
+**Working with Dependency Outputs:**
+
+Self-references and dependency references can be used together:
+
+```yaml
+tasks:
+  build:
+    outputs:
+      - artifact: dist/app.js
+    cmd: webpack build
+
+  package:
+    deps: [build]
+    inputs:
+      - manifest: package.json
+    outputs:
+      - tarball: release.tar.gz
+    cmd: tar czf {{ self.outputs.tarball }} \
+           {{ self.inputs.manifest }} \
+           {{ dep.build.outputs.artifact }}
+```
+
+**Mixed Named and Anonymous:**
+
+Tasks can mix named and anonymous inputs/outputs:
+
+```yaml
+tasks:
+  build:
+    inputs:
+      - config: build.yaml  # Named - can reference
+      - src/**/*.c          # Anonymous - tracked but not referenceable
+    outputs:
+      - binary: bin/app     # Named - can reference
+      - bin/app.debug       # Anonymous - tracked but not referenceable
+    cmd: build-tool --config {{ self.inputs.config }} --output {{ self.outputs.binary }}
+```
+
+**Positional Index References:**
+
+In addition to named references, you can access inputs and outputs by their positional index using `{{ self.inputs.0 }}`, `{{ self.inputs.1 }}`, etc. This provides an alternative way to reference items, especially useful for:
+
+- **Anonymous inputs/outputs**: Reference items that don't have names
+- **Simple sequential access**: When order is more important than naming
+- **Mixed with named access**: Use both styles in the same task
+
+**Syntax:**
+
+```yaml
+tasks:
+  process:
+    inputs: ["file1.txt", "file2.txt", "file3.txt"]
+    outputs: ["output1.txt", "output2.txt"]
+    cmd: |
+      cat {{ self.inputs.0 }} {{ self.inputs.1 }} > {{ self.outputs.0 }}
+      cat {{ self.inputs.2 }} > {{ self.outputs.1 }}
+```
+
+Indices follow YAML declaration order, starting from 0 (zero-based indexing):
+- First input/output = index 0
+- Second input/output = index 1
+- Third input/output = index 2, etc.
+
+**Works with Both Named and Anonymous:**
+
+```yaml
+tasks:
+  build:
+    inputs:
+      - config: "build.yaml"  # Index 0, also accessible as {{ self.inputs.config }}
+      - "src/**/*.c"          # Index 1, ONLY accessible as {{ self.inputs.1 }}
+      - headers: "include/*.h" # Index 2, also accessible as {{ self.inputs.headers }}
+    outputs:
+      - "dist/app.js"         # Index 0
+      - bundle: "dist/bundle.js" # Index 1, also accessible as {{ self.outputs.bundle }}
+    cmd: |
+      # Mix positional and named references
+      build-tool \
+        --config {{ self.inputs.0 }} \
+        --sources {{ self.inputs.1 }} \
+        --headers {{ self.inputs.headers }} \
+        --output {{ self.outputs.bundle }}
+```
+
+**Same Item, Multiple Ways:**
+
+Named items can be accessed by both name and index:
+
+```yaml
+tasks:
+  copy:
+    inputs:
+      - source: data.txt
+    cmd: |
+      # These are equivalent:
+      cat {{ self.inputs.source }} > copy1.txt
+      cat {{ self.inputs.0 }} > copy2.txt
+```
+
+**With Variables and Arguments:**
+
+Positional references work with variable-expanded paths:
+
+```yaml
+variables:
+  version: "1.0"
+
+tasks:
+  package:
+    args: [platform]
+    inputs:
+      - "dist/app-{{ var.version }}.js"
+      - "dist/lib-{{ arg.platform }}.so"
+    outputs: ["release-{{ var.version }}-{{ arg.platform }}.tar.gz"]
+    cmd: tar czf {{ self.outputs.0 }} {{ self.inputs.0 }} {{ self.inputs.1 }}
+```
+
+**Index Boundaries:**
+
+Indices are validated before execution:
+
+```yaml
+tasks:
+  build:
+    inputs: ["file1.txt", "file2.txt"]
+    cmd: cat {{ self.inputs.5 }}  # Error: index 5 out of bounds!
+```
+
+Error message:
+```
+Task 'build' references input index '5' but only has 2 inputs (indices 0-1)
+```
+
+**Empty Lists:**
+
+Referencing an index when no inputs/outputs exist:
+
+```yaml
+tasks:
+  generate:
+    cmd: echo "test" > {{ self.outputs.0 }}  # Error: no outputs defined!
+```
+
+Error message:
+```
+Task 'generate' references output index '0' but has no outputs defined
+```
+
+**When to Use Index References:**
+
+- **Anonymous items**: Only way to reference inputs/outputs without names
+- **Order-based processing**: When the sequence matters more than naming
+- **Simple tasks**: Quick access without defining names
+- **Compatibility**: Accessing items in legacy YAML that uses anonymous format
+
+**When to Use Named References:**
+
+- **Clarity**: Names make commands more readable (`{{ self.inputs.config }}` vs `{{ self.inputs.2 }}`)
+- **Maintainability**: Adding/removing items doesn't break indices
+- **Complex tasks**: Many inputs/outputs are easier to manage with names
+
+**Error Messages:**
+
+If you reference a non-existent input or output:
+
+```yaml
+tasks:
+  build:
+    inputs:
+      - src: input.txt
+    cmd: cat {{ self.inputs.missing }}  # Error!
+```
+
+You'll get a clear error before execution:
+
+```
+Task 'build' references input 'missing' but has no input named 'missing'.
+Available named inputs: src
+Hint: Define named inputs like: inputs: [{ missing: 'path/to/file' }]
+```
+
+Similarly, if you try to reference an anonymous input:
+
+```yaml
+tasks:
+  build:
+    inputs: [file.txt]  # Anonymous input
+    cmd: cat {{ self.inputs.src }}  # Error!
+```
+
+You'll get:
+
+```
+Task 'build' references input 'src' but has no input named 'src'.
+Available named inputs: (none - all inputs are anonymous)
+Hint: Define named inputs like: inputs: [{ src: 'file.txt' }]
+```
+
+**Key Behaviors:**
+
+- **Two access methods**: Reference by name (`{{ self.inputs.name }}`) or by index (`{{ self.inputs.0 }}`)
+- **Template resolution**: Self-references are resolved during dependency graph planning
+- **Substitution order**: Variables → Dependency outputs → Self-references → Arguments/Environment
+- **Fail-fast validation**: Errors are caught before execution begins (missing names, out-of-bounds indices)
+- **Clear error messages**: Lists available names/indices if reference doesn't exist
+- **Backward compatible**: Existing anonymous inputs/outputs work unchanged
+- **State tracking**: Works correctly with incremental execution and freshness checks
+- **Index order**: Positional indices follow YAML declaration order (0-based)
+
+**Limitations:**
+
+- **Anonymous not referenceable by name**: Anonymous inputs/outputs cannot be referenced by name (use positional index instead: `{{ self.inputs.0 }}`)
+- **Case sensitive**: `{{ self.inputs.Src }}` and `{{ self.inputs.src }}` are different
+- **Argument defaults**: Self-references in argument defaults are not supported (arguments are evaluated before self-references)
+- **No negative indices**: Python-style negative indexing (`{{ self.inputs.-1 }}`) is not supported
+
+**Use Cases:**
+
+- **Eliminate repetition**: Define complex paths once, use them multiple times
+- **Variable composition**: Combine variables with self-references for clean commands
+- **Multiple inputs/outputs**: Reference specific files when tasks have many
+- **Complex build pipelines**: Keep commands readable with named artifacts
+- **Glob patterns**: Use self-references with glob patterns for dynamic inputs
+
+**Example: Multi-Stage Build:**
+
+```yaml
+variables:
+  version: "2.1.0"
+  platform: "linux"
+
+tasks:
+  prepare:
+    outputs:
+      - builddir: build/{{ var.platform }}-{{ var.version }}
+    cmd: mkdir -p {{ self.outputs.builddir }}
+
+  compile:
+    deps: [prepare]
+    inputs:
+      - source: src/main.c
+      - headers: include/*.h
+    outputs:
+      - object: build/{{ var.platform }}-{{ var.version }}/main.o
+    cmd: |
+      gcc -c {{ self.inputs.source }} \
+        -I include \
+        -o {{ self.outputs.object }}
+
+  link:
+    deps: [compile]
+    outputs:
+      - executable: build/{{ var.platform }}-{{ var.version }}/app
+      - symbols: build/{{ var.platform }}-{{ var.version }}/app.sym
+    cmd: |
+      gcc build/{{ var.platform }}-{{ var.version }}/main.o \
+        -o {{ self.outputs.executable }}
+      objcopy --only-keep-debug {{ self.outputs.executable }} {{ self.outputs.symbols }}
+```
+
 
 ### Private Tasks
 

tasktree-0.0.21.dist-info/RECORD

@@ -0,0 +1,14 @@
+tasktree/__init__.py,sha256=ZfI6vy-TxinN7eK0_XjfHUFq83pFV1XiHFrai_SHNqw,1251
+tasktree/cli.py,sha256=pyXMUENz1ldl8z9SPXBZ1zhOHzmvIRUGu2y5VwRUdgo,22960
+tasktree/docker.py,sha256=EeIUqptvDqSXbjWKXwWGhA4hWvsBjOk0Z-3cS3cqEOM,14857
+tasktree/executor.py,sha256=x0K-TIVRmiKuUlur1UTOpB2xOJOE_Cv3-3MlE7xUNEk,47271
+tasktree/graph.py,sha256=BjpLaa7EE2vmOcUlqhvp1KK7yT5VbXHQCbxljOhF84k,23603
+tasktree/hasher.py,sha256=UM-2dqRE-rspQUbhA-noGHc80-Hu-QaxCTPRb_UzPto,6661
+tasktree/parser.py,sha256=sXgotDdDQiNSmo7FaESFQ4j1OytaheyplJSdFrFXTYk,99286
+tasktree/state.py,sha256=0fxKbMNYbo-dCpCTTnKTmJhGRy72G5kLnh99FScMLGU,3985
+tasktree/substitution.py,sha256=2ubFn6jIX5qmtzyWSCxTut-_Cn0zew8KnwxMqDIPq1o,18545
+tasktree/types.py,sha256=2uHdUncfyfw4jNWbQTBUirew-frmTjuk1ZYNd15cyQQ,4908
+tasktree-0.0.21.dist-info/METADATA,sha256=nyjDhb1hdQMEiLx0t_qqonqPoyFZVMCrIg7xFIKxMs8,54353
+tasktree-0.0.21.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tasktree-0.0.21.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
+tasktree-0.0.21.dist-info/RECORD,,

tasktree-0.0.19.dist-info/RECORD

@@ -1,14 +0,0 @@
-tasktree/__init__.py,sha256=N-dZcggJDe4WaloC1MdEh0oMTHlUpBN9AEcAm6leDf4,1167
-tasktree/cli.py,sha256=_GzqQIk2z2Hz17bkTOWhtNW4X4_Ijxn-uEL-WZGt8LM,20858
-tasktree/docker.py,sha256=qvja8G63uAcC73YMVY739egda1_CcBtoqzm0qIJU_Q8,14443
-tasktree/executor.py,sha256=7pzcH2wLWMZPk3hwhzWgz18RVkIPFCKdu23MboWUQs4,45914
-tasktree/graph.py,sha256=9O5LByzMYa8ccedznqKBTb0Xe9N_aajSR1cAcb8zGQE,20366
-tasktree/hasher.py,sha256=o7Akd_AgGkAsnv9biK0AcbhlcqUQ9ne5y_6r4zoFaw0,5493
-tasktree/parser.py,sha256=PVgtGORCpnkb8wcXHFfsyVqDhJ3PwzwCqO3VWiuLQl4,94777
-tasktree/state.py,sha256=Cktl4D8iDZVd55aO2LqVyPrc-BnljkesxxkcMcdcfOY,3541
-tasktree/substitution.py,sha256=3-gdvHbBwPkQPflx3GVSpEEa0vTL_ivdcMIba77gtJc,14225
-tasktree/types.py,sha256=R_YAyO5bMLB6XZnkMRT7VAtlkA_Xx6xu0aIpzQjrBXs,4357
-tasktree-0.0.19.dist-info/METADATA,sha256=KTLp0p1Mkzzvah-Hy15KrXnTcKju5dlQyvDvEdnDOmg,43609
-tasktree-0.0.19.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tasktree-0.0.19.dist-info/entry_points.txt,sha256=lQINlvRYnimvteBbnhH84A9clTg8NnpEjCWqWkqg8KE,40
-tasktree-0.0.19.dist-info/RECORD,,