or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-usage.mdindex.mdplugin-integration.mdprogrammatic-api.mdtask-configuration.md
tile.json

tessl/pypi-poethepoet

A batteries included task runner that works well with poetry and uv

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/poethepoet@0.37.x

To install, run

npx @tessl/cli install tessl/pypi-poethepoet@0.37.0

index.mddocs/

Poethepoet

A batteries included task runner that works well with Poetry and UV package managers. Poethepoet enables developers to define and execute project tasks directly from pyproject.toml configuration files, offering multiple task execution modes and comprehensive CLI features.

Package Information

  • Package Name: poethepoet
  • Version: 0.37.0
  • Language: Python
  • Installation: pip install poethepoet
  • Python Version: >= 3.9
  • CLI Command: poe

Core Imports

from poethepoet import main

For programmatic usage:

from poethepoet.app import PoeThePoet
from poethepoet.config import PoeConfig
from poethepoet.io import PoeIO

Basic Usage

CLI Usage

# Install poethepoet globally
pip install poethepoet

# Run a task defined in pyproject.toml
poe test

# List available tasks
poe

# Run with verbose output
poe -v task_name

# Run with dry-run mode
poe -d task_name

Programmatic Usage

from poethepoet.app import PoeThePoet
from pathlib import Path

# Create application instance
app = PoeThePoet(cwd=Path("."))

# Execute task with CLI arguments
result = app(cli_args=["test", "--verbose"])

# Or resolve and run specific task
task = app.resolve_task()
if task:
    result = app.run_task(task)

Configuration in pyproject.toml

[tool.poe.tasks]
# Command task
test = "pytest tests/"

# Script task with arguments
format.script = "black:main"
format.args = ["."]

# Sequence task
check.sequence = ["format", "test"]

# Task with help text
serve.cmd = "python -m http.server 8000"
serve.help = "Start development server"

# Complex task with environment variables
build.script = "scripts:build_project"
build.env = {DEBUG = "false"}

Architecture

Poethepoet's design centers around these key components:

  • PoeThePoet: Main application class handling task resolution and execution
  • PoeConfig: Configuration loader supporting multiple file formats (TOML, YAML, JSON)
  • Task Types: Pluggable task execution modes (cmd, script, expression, sequence, etc.)
  • Executors: Environment-aware execution engines (Poetry, UV, virtualenv, simple)
  • PoeIO: Verbosity-controlled input/output management

This architecture enables poethepoet to integrate seamlessly with various Python project tools while maintaining flexibility for different task execution needs.

Capabilities

Programmatic API

Core classes and functions for embedding poethepoet functionality into other applications. Provides full control over task execution, configuration management, and environment setup.

class PoeThePoet:
    def __init__(
        self,
        cwd: Path | str | None = None,
        config: Mapping[str, Any] | PoeConfig | None = None,
        output: PoeIO | IO = None,
        **kwargs
    ): ...
    
    def __call__(self, cli_args: Sequence[str], internal: bool = False) -> int: ...
    def run_task(self, task: PoeTask, context: RunContext | None = None) -> int | None: ...

Programmatic API

CLI Interface

Command-line interface providing task execution, help system, shell completion, and comprehensive argument handling for interactive and scripted usage.

def main() -> None: ...

# CLI arguments
# poe [options] task [task_args]
# -h, --help [TASK]    Show help
# -v, --verbose        Increase verbosity  
# -q, --quiet          Decrease verbosity
# -d, --dry-run        Print task without executing

CLI Usage

Task Configuration

Multiple task types supporting different execution modes: shell commands, Python expressions, script references, and complex task composition with sequences and DAGs.

# Task types available in configuration
task_types = ["cmd", "shell", "script", "expr", "sequence", "ref", "switch"]

# Configuration options
class TaskOptions:
    help: str
    env: dict[str, str] 
    cwd: str
    deps: list[str]
    args: list[str]

Task Configuration

Poetry Plugin Integration

Seamless integration with Poetry's plugin system, enabling poethepoet tasks to be executed through Poetry commands with shared environment and configuration.

class PoetryPlugin:
    def activate(self, application: Application) -> None: ...

class PoeCommand:
    def handle(self) -> int: ...

Plugin Integration

Exception Handling

# Base exception class
class PoeException(Exception): ...

# Specific exception types
class ConfigValidationError(PoeException): ...
class ExecutionError(PoeException): ...
class CyclicDependencyError(PoeException): ...
class ExpressionParseError(PoeException): ...

Common error scenarios:

  • Invalid task configuration
  • Cyclic task dependencies
  • Missing task executables
  • Environment setup failures
  • Task execution errors