taskipy

Taskipy is a lightweight task runner for Python projects that turns pyproject.toml into a single source of truth for development commands. Instead of memorizing long shell invocations for testing, linting, or publishing, developers define named tasks under [tool.taskipy.tasks] and run them with a simple task <name> command, mirroring the ergonomics of npm’s run-script for the Python ecosystem.

Beyond simple aliases, taskipy supports composing tasks together, chaining pre- and post-task hooks, sharing reusable (optionally recursive) variables across commands, and running tasks from either a fixed working directory or the caller’s current directory. It integrates naturally with Poetry projects but works with any project that has a valid pyproject.toml file.

What You Get

• A [tool.taskipy.tasks] section in pyproject.toml as the single place to declare every project command
• Pre- and post-task hooks (pre_<task> / post_<task>) that run automatically around a task
• Reusable, optionally recursive variables shared across task commands via Python’s str.format
• Per-task or global working-directory control independent of where task is invoked from
• A task --list command that prints every declared task alongside its help text

Common Use Cases

• Running the test suite with task test instead of a long python -m unittest ... invocation
• Chaining lint checks automatically after tests via a post_test hook
• Standardizing release commands (publish_patch, publish_minor) across a team
• Sharing a common source-directory variable across lint, format, and type-check tasks

Under The Hood

Architecture Execution starts in cli.py’s argparse-based entry point, which builds a TaskRunner (task_runner.py) around the current working directory. TaskRunner loads a PyProject (pyproject.py) that parses pyproject.toml via tomli into typed Task and Variable model objects (task.py, variable.py). TaskRunner.run() resolves any pre_/post_ hook tasks by naming convention, performs variable substitution with cycle detection for recursive variables, then shells out via subprocess.Popen with per-argument shlex quoting, wiring SIGTERM forwarding through psutil so process trees terminate cleanly on both POSIX and Windows shells. Failures surface as a typed TaskipyError hierarchy (exceptions.py) with per-error exit codes, caught centrally in cli.py’s run(). The layering is clean: the TOML parsing/model layer is fully decoupled from the execution layer, and the CLI itself is a thin wrapper — extending a task’s schema touches only task.py and TaskRunner, never the CLI.

Tech Stack A pure Python 3.6+ package with a deliberately small runtime dependency set: tomli for TOML parsing (version-pinned differently per Python release), psutil for process-tree introspection during signal handling, colorama for cross-platform ANSI coloring in the task-list formatter, and mslex as a Windows-only shlex replacement. Packaging and its own development tasks are both driven by Poetry, with the project dogfooding taskipy for its own test/lint/release commands.

Code Quality Tests are written with the stdlib unittest framework plus parameterized for parametrized cases, spread across three files with an extensive tests/fixtures/ directory covering varied pyproject.toml configurations. Errors are modeled as explicit, typed exception classes with distinct exit codes rather than generic exceptions. Type hints are used consistently across the runner, model, and CLI layers, backed by a py.typed marker and enforced via mypy in CI, alongside pylint for style. GitHub Actions runs the test suite across a wide matrix of Python versions plus a dedicated Windows workflow, though no CONTRIBUTING guide is present.

What Makes It Unique The core concept — declarative named commands invoked through a short alias — closely mirrors npm’s run-script and is a well-established pattern rather than a novel one. Where taskipy distinguishes itself is in the careful engineering of the details: recursive variable resolution with explicit cycle detection, automatic pre/post hook chaining purely by naming convention, and platform-aware SIGTERM forwarding that correctly distinguishes shell-spawned child processes from direct subprocesses across operating systems.