tessl/pypi-poethepoet

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

—

Pending

Overview

Eval results

Files

Plugin Integration

Name: tessl/pypi-poethepoet
Author: tessl

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

Capabilities

Poetry Plugin

The Poetry plugin enables poethepoet tasks to be executed directly through Poetry commands, providing unified environment management and configuration sharing.

class PoetryPlugin:
    def activate(self, application: Application) -> None:
        """
        Activate the poethepoet plugin within Poetry.
        
        Args:
            application: Poetry application instance
            
        Registers the 'poe' command with Poetry's command system,
        enabling 'poetry poe task_name' execution.
        """

Poetry Command Integration

The PoeCommand class provides the Poetry command interface for executing poethepoet tasks.

class PoeCommand:
    def handle(self) -> int:
        """
        Handle Poetry poe command execution.
        
        Returns:
            Exit code (0 for success)
            
        Processes Poetry command arguments and delegates to
        poethepoet for task execution within Poetry's environment.
        """
    
    def get_poe(self, application, io, poe_config) -> PoeThePoet:
        """
        Create PoeThePoet instance configured for Poetry integration.
        
        Args:
            application: Poetry application instance
            io: Poetry IO handler
            poe_config: Poethepoet configuration
            
        Returns:
            Configured PoeThePoet instance
        """

Plugin Installation

The plugin can be installed and managed through Poetry's plugin system.

Installation Methods

# Install poethepoet with plugin support
pip install poethepoet[poetry_plugin]

# Or install as Poetry plugin directly
poetry self add poethepoet[poetry_plugin]

# Verify plugin installation
poetry --plugins

Plugin Entry Point

The plugin is registered through the Poetry entry point system:

# Entry point configuration (in pyproject.toml)
[project.entry-points."poetry.application.plugin"]
poethepoet = "poethepoet.plugin:PoetryPlugin"

Plugin Usage

Once installed, poethepoet tasks can be executed through Poetry commands.

Basic Plugin Usage

# Execute poethepoet task through Poetry
poetry poe test

# Pass arguments to tasks
poetry poe serve --port 8080

# Use Poetry's environment management
poetry poe build  # Runs in Poetry's virtual environment

Comparison with Standalone Usage

# Standalone poethepoet (requires separate installation)
poe test

# Poetry plugin (uses Poetry's environment)
poetry poe test

# Both execute the same tasks but with different environment contexts

Environment Integration

The plugin provides seamless integration with Poetry's virtual environment and dependency management.

# Environment integration features
class PoetryIntegration:
    # Automatic virtual environment detection
    virtual_env_path: str
    
    # Poetry configuration sharing
    poetry_config: dict
    
    # Dependency resolution integration
    dependencies: dict
    
    # Build system integration
    build_backend: str

Shared Configuration

The plugin shares configuration and environment settings between Poetry and poethepoet:

Virtual Environment: Uses Poetry's activated virtual environment
Dependencies: Access to Poetry's installed dependencies
Configuration: Inherits Poetry's project configuration
Working Directory: Operates in Poetry's project root

Plugin Configuration

The plugin can be configured through Poetry's configuration system and poethepoet's own configuration.

Poetry Configuration Integration

# pyproject.toml - Shared configuration
[tool.poetry]
name = "my-project"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.25.0"

# Poethepoet tasks available to both standalone and plugin usage
[tool.poe.tasks]
test = "pytest"
lint = "flake8 ."
build = {script = "build:main"}

Plugin-Specific Options

# Optional plugin-specific configuration
[tool.poe.poetry_hooks]
# Hooks to run before/after Poetry commands
pre_install = "poe clean"
post_install = "poe setup"

Advanced Plugin Features

Environment Variable Sharing

# Environment variables available in plugin context
POETRY_ACTIVE = "1"           # Indicates Poetry environment
POETRY_VIRTUAL_ENV = "path"   # Virtual environment path  
POETRY_PROJECT_ROOT = "path"  # Project root directory
POETRY_PYPROJECT_TOML = "path" # pyproject.toml location

Dependency Integration

The plugin can access Poetry's dependency information:

# Dependency integration capabilities
class PoetryDependencyIntegration:
    def get_installed_packages(self) -> dict[str, str]:
        """Get Poetry's installed packages."""
    
    def get_project_dependencies(self) -> dict[str, str]:
        """Get project dependencies from pyproject.toml."""
    
    def get_dev_dependencies(self) -> dict[str, str]:
        """Get development dependencies."""

Error Handling and Compatibility

The plugin handles various Poetry versions and configuration scenarios.

# Compatibility and error handling
class PluginCompatibility:
    min_poetry_version: str = "1.2.0"
    max_poetry_version: str = "3.0.0"
    
    def check_compatibility(self) -> bool:
        """Check Poetry version compatibility."""
    
    def handle_config_conflicts(self) -> None:
        """Resolve configuration conflicts."""
    
    def migrate_legacy_config(self) -> None:
        """Migrate from legacy configuration formats."""

Common Plugin Issues

Version Conflicts: Poetry and poethepoet version mismatches
Environment Issues: Virtual environment activation problems
Configuration Conflicts: Conflicting task definitions
Plugin Loading: Plugin registration and discovery issues

Usage Examples

Basic Plugin Workflow

# Install project with Poetry
poetry install

# Install poethepoet plugin
poetry self add poethepoet[poetry_plugin]

# Run tasks through Poetry
poetry poe test
poetry poe lint
poetry poe build

Development Workflow Integration

# Poetry + poethepoet integrated workflow
poetry install                    # Install dependencies
poetry poe format                # Format code
poetry poe lint                  # Lint code  
poetry poe test                  # Run tests
poetry build                     # Build package
poetry poe deploy                # Deploy application

CI/CD Integration

# GitHub Actions example with Poetry plugin
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      
      - name: Install Poetry
        run: pip install poetry
      
      - name: Install dependencies and plugin
        run: |
          poetry install
          poetry self add poethepoet[poetry_plugin]
      
      - name: Run tasks via plugin
        run: |
          poetry poe lint
          poetry poe test
          poetry poe build

Mixed Usage Patterns

# Developers can use both approaches
poe test                    # Standalone poethepoet
poetry poe test            # Through Poetry plugin

# Environment differences
poe --executor simple test   # Custom executor
poetry poe test             # Poetry's virtual environment

# Configuration sharing
poe -C other_project test   # Different project
poetry poe test             # Current Poetry project only

Plugin Development and Customization

# Custom plugin extension example
from poethepoet.plugin import PoetryPlugin

class CustomPoetryPlugin(PoetryPlugin):
    def activate(self, application):
        super().activate(application)
        # Add custom Poetry integration features
        self.add_custom_commands()
    
    def add_custom_commands(self):
        # Extend plugin functionality
        pass

Install with Tessl CLI

npx tessl i tessl/pypi-poethepoet

docs

cli-usage.md

index.md

plugin-integration.md

programmatic-api.md

task-configuration.md

tile.json

tessl/pypi-poethepoet