tasktree 0.0.2__tar.gz → 0.0.4__tar.gz

{tasktree-0.0.2 → tasktree-0.0.4}/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
         python-version: ['3.11', '3.12']
 
     steps:

{tasktree-0.0.2 → tasktree-0.0.4}/.gitignore

@@ -80,9 +80,6 @@ target/
 profile_default/
 ipython_config.py
 
-# pyenv
-.python-version
-
 # pipenv
 Pipfile.lock
 

tasktree-0.0.4/.python-version

@@ -0,0 +1 @@
+3.12

{tasktree-0.0.2 → tasktree-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktree
-Version: 0.0.2
+Version: 0.0.4
 Summary: A task automation tool with incremental execution
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
@@ -18,6 +18,95 @@ Description-Content-Type: text/markdown
 
 A task automation tool that combines simple command execution with dependency tracking and incremental execution.
 
+## Motivation
+In any project of even moderate size, various scripts inevitably come into being along the way. These scripts often must be run in a particular order, or at a particular time. For historical reasons, this almost certainly a problem if your project is developed in a Linux environment; in Windows, an IDE like Visual Studio may be taking care of a significant proportion of your build, packaging and deployment tasks. Then again, it may not...
+
+The various incantations that have to be issued to build, package, test and deploy a project can build up and then all of a sudden there's only a few people that remember which to invoke and when and then people start making helpful readme guides on what to do with the scripts and then those become out of date and start telling lies about things and so on.
+
+Then there's the scripts themselves. In Linux, they're probably a big pile of Bash and Python, or something (Ruby, Perl, you name it). You can bet the house on people solving the problem of passing parameters to their scripts in a whole bunch of different and inconsistent ways.
+
+```bash
+#!/usr/bin/env bash
+# It's an environment variable defined.... somewhere?
+echo "FOO is: $FOO"
+```
+```bash
+#!/usr/bin/env bash
+# Using simple positional arguments... guess what means what when you're invoking it!
+echo "First: $1, Second: $2"
+```
+```bash
+#!/usr/bin/env bash
+# Oooooh fancy "make me look like a proper app" named option parsing... don't try and do --foo=bar though!
+FOO=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --foo) FOO=$2; shift ;;
+        --)    break ;;
+        *)     echo "Unknown: $1";;
+    esac
+    shift
+done
+```
+```bash
+#!/usr/bin/env bash
+# This thing...
+ARGS=$(getopt -o f:b --long foo:,bar: -n 'myscript' -- "$@")
+eval set -- "$ARGS"
+while true; do
+    case "$1" in
+        -b|--bar) echo "Bar: $2"; shift 2 ;;
+        -f|--foo) echo "Foo: $2"; shift 2 ;;
+        --) shift; break ;;
+        *) break ;;
+    esac
+done
+```
+
+What about help info? Who has time to wire that in?
+
+### The point
+Is this just whining and moaning? Should we just man up and revel in our own ability to memorize all the right incantations like some kind of scripting shaman?
+
+... No. That's **a dumb idea**.
+
+Task Tree allows you to pile all the knowledge of **what** to run, **when** to run it, **where** to run it and **how** to run it into a single, readable place. Then you can delete all the scripts that no-one knows how to use and all the readme docs that lie to the few people that actually waste their time reading them. 
+
+The tasks you need to perform to deliver your project become summarised in an executable file that looks like:
+```yaml
+build:
+  desc: Compile stuff
+  outputs: [target/release/bin]
+  cmd: cargo build --release
+
+package:
+   desc: build installers
+   deps: [build]
+   outputs: [awesome.deb]
+   cmd: |
+      for bin in target/release/*; do
+          if [[ -x "$bin" && ! -d "$bin" ]]; then
+              install -Dm755 "$bin" "debian/awesome/usr/bin/$(basename "$bin")"
+          fi
+      done
+      
+      dpkg-buildpackage -us -uc
+
+test:
+  desc: Run tests
+  deps: [package]
+  inputs: [tests/**/*.py]
+  cmd: PYTHONPATH=src python3 -m pytest tests/ -v
+```
+
+If you want to run the tests then:
+```bash
+tt test
+```
+Boom! Done. `build` will always run, because there's no sensible way to know what Cargo did. However, if Cargo decided that nothing needed to be done and didn't touch the binaries, then `package` will realize that and not do anything. Then `test` will just run with the new tests that you just wrote. If you then immediately run `test` again, then `test` will figure out that none of the dependencies did anything and that none of the test files have changed and then just _do nothing_ - as it should.
+
+This is a toy example, but you can image how it plays out on a more complex project.
+
 ## Installation
 
 ### From PyPI (Recommended)
@@ -26,6 +115,16 @@ A task automation tool that combines simple command execution with dependency tr
 pipx install tasktree
 ```
 
+If you have multiple Python interpreter versions installed, and the _default_ interpreter is a version <3.11, then you can use `pipx`'s `--python` option to specify an interpreter with a version >=3.11:
+
+```bash
+# If the target version is on the PATH
+pipx install --python python3.12 tasktree
+
+# With a path to an interpreter
+pipx install --python /path/to/python3.12 tasktree
+```
+
 ### From Source
 
 For the latest unreleased version from GitHub:
@@ -61,9 +160,11 @@ test:
 Run tasks:
 
 ```bash
-tt build          # Build the application
-tt test           # Run tests (builds first if needed)
+tt                # Print the help
+tt --help         # ...also print the help
 tt --list         # Show all available tasks
+tt build          # Build the application (assuming this is in your tasktree.yaml)
+tt test           # Run tests (builds first if needed)
 ```
 
 ## Core Concepts
@@ -72,11 +173,12 @@ tt --list         # Show all available tasks
 
 Task Tree only runs tasks when necessary. A task executes if:
 
-- Its definition (command, outputs, working directory) has changed
+- Its definition (command, outputs, working directory, environment) has changed
 - Any input files have changed since the last run
 - Any dependencies have re-run
 - It has never been executed before
 - It has no inputs or outputs (always runs)
+- The execution environment has changed (CLI override or environment config change)
 
 ### Automatic Input Inheritance
 
@@ -105,17 +207,25 @@ All state lives in `.tasktree-state` at your project root. Stale entries are aut
 ```yaml
 task-name:
   desc: Human-readable description (optional)
-  deps: [other-task]              # Task dependencies
-  inputs: [src/**/*.go]            # Explicit input files (glob patterns)
-  outputs: [dist/binary]           # Output files (glob patterns)
-  working_dir: subproject/         # Execution directory (default: project root)
-  args: [param1, param2:path=default]   # Task parameters
-  cmd: go build -o dist/binary     # Command to execute
+  deps: [other-task]                     # Task dependencies
+  inputs: [src/**/*.go]                  # Explicit input files (glob patterns)
+  outputs: [dist/binary]                 # Output files (glob patterns)
+  working_dir: subproject/               # Execution directory (default: project root)
+  env: bash-strict                       # Execution environment (optional)
+  args: [param1, param2:path=default]    # Task parameters
+  cmd: go build -o dist/binary           # Command to execute
 ```
 
 ### Commands
 
-Multi-line commands using YAML literal blocks:
+**Single-line commands** are executed directly via the configured shell:
+
+```yaml
+build:
+  cmd: cargo build --release
+```
+
+**Multi-line commands** are written to temporary script files for proper execution:
 
 ```yaml
 deploy:
@@ -125,7 +235,9 @@ deploy:
     rsync -av dist/ server:/opt/app/
 ```
 
-Or folded blocks for long single-line commands:
+Multi-line commands preserve shell syntax (line continuations, heredocs, etc.) and support shebangs on Unix/macOS.
+
+Or use folded blocks for long single-line commands:
 
 ```yaml
 compile:
@@ -136,6 +248,58 @@ compile:
     -L lib -lm
 ```
 
+### Execution Environments
+
+Configure custom shell environments for task execution:
+
+```yaml
+environments:
+  default: bash-strict
+
+  bash-strict:
+    shell: bash
+    args: ['-c']              # For single-line: bash -c "command"
+    preamble: |               # For multi-line: prepended to script
+      set -euo pipefail
+
+  python:
+    shell: python
+    args: ['-c']
+
+  powershell:
+    shell: powershell
+    args: ['-ExecutionPolicy', 'Bypass', '-Command']
+    preamble: |
+      $ErrorActionPreference = 'Stop'
+
+tasks:
+  build:
+    # Uses 'default' environment (bash-strict)
+    cmd: cargo build --release
+
+  analyze:
+    env: python
+    cmd: |
+      import sys
+      print(f"Analyzing with Python {sys.version}")
+      # ... analysis code ...
+
+  windows-task:
+    env: powershell
+    cmd: |
+      Compress-Archive -Path dist/* -DestinationPath package.zip
+```
+
+**Environment resolution priority:**
+1. CLI override: `tt --env python build`
+2. Task's `env` field
+3. Recipe's `default` environment
+4. Platform default (bash on Unix, cmd on Windows)
+
+**Platform defaults** when no environments are configured:
+- **Unix/macOS**: bash with `-c` args
+- **Windows**: cmd with `/c` args
+
 ### Parameterised Tasks
 
 Tasks can accept arguments with optional defaults:
@@ -202,12 +366,19 @@ Input and output patterns support standard glob syntax:
 
 ### How State Works
 
-Each task is identified by a hash of its definition (command, outputs, working directory). State tracks:
+Each task is identified by a hash of its definition. The hash includes:
+
+- Command to execute
+- Output patterns
+- Working directory
+- Argument definitions
+- Execution environment
 
+State tracks:
 - When the task last ran
 - Timestamps of input files at that time
 
-Tasks are re-run when their definition changes or inputs are newer than the last run.
+Tasks are re-run when their definition changes, inputs are newer than the last run, or the environment changes.
 
 ### What's Not In The Hash
 
@@ -222,6 +393,72 @@ Changes to these don't invalidate cached state:
 
 At the start of each invocation, state is checked for invalid task hashes and non-existent ones are automatically removed. Delete a task from your recipe file and its state disappears the next time you run `tt <cmd>`
 
+## Command-Line Options
+
+Task Tree provides several command-line options for controlling task execution:
+
+### Execution Control
+
+```bash
+# Force re-run (ignore freshness checks)
+tt --force build
+tt -f build
+
+# Run only the specified task, skip dependencies (implies --force)
+tt --only deploy
+tt -o deploy
+
+# Override environment for all tasks
+tt --env python analyze
+tt -e powershell build
+```
+
+### Information Commands
+
+```bash
+# List all available tasks
+tt --list
+tt -l
+
+# Show detailed task definition
+tt --show build
+
+# Show dependency tree (without execution)
+tt --tree deploy
+
+# Show version
+tt --version
+tt -v
+
+# Create a blank recipe file
+tt --init
+```
+
+### State Management
+
+```bash
+# Remove state file (reset task cache)
+tt --clean
+tt --clean-state
+tt --reset
+```
+
+### Common Workflows
+
+```bash
+# Fresh build of everything
+tt --force build
+
+# Run a task without rebuilding dependencies
+tt --only test
+
+# Test with a different shell/environment
+tt --env python test
+
+# Force rebuild and deploy
+tt --force deploy production
+```
+
 ## Example: Full Build Pipeline
 
 ```yaml