or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

command-line-interface.mdenvironment-configuration.mdexport-system.mdindex.mdoutput-formatting.mdprocess-management.md
tile.json

tessl/pypi-honcho

A Python clone of Foreman for managing Procfile-based applications with process management and export capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/honcho@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-honcho@2.0.0

index.mddocs/

Honcho

A Python clone of Foreman for managing Procfile-based applications. Honcho enables developers to run multiple processes concurrently from a single Procfile configuration, making it ideal for development environments where applications need to coordinate multiple services. It provides process management capabilities, environment variable management through .env files, and export functionality to various process management systems.

Package Information

  • Package Name: honcho
  • Language: Python
  • Installation: pip install honcho
  • Export Dependencies: pip install honcho[export] (for export functionality)

Core Imports

import honcho  # Only provides __version__

For programmatic usage:

from honcho.manager import Manager
from honcho.printer import Printer
from honcho.environ import Env, parse_procfile, expand_processes
from honcho.process import Process

For CLI usage:

from honcho.command import main

Basic Usage

Command Line Interface

# Start all processes from Procfile
honcho start

# Start specific processes
honcho start web worker

# Run a single command with environment
honcho run python manage.py migrate

# Export to systemd
honcho export systemd /etc/systemd/system --app myapp

# Check Procfile validity
honcho check

Programmatic Usage

import sys
from honcho.manager import Manager
from honcho.printer import Printer

# Create a manager with default printer
manager = Manager(Printer(sys.stdout))

# Add processes
manager.add_process('web', 'python app.py')
manager.add_process('worker', 'python worker.py')

# Start all processes
manager.loop()

# Exit with appropriate code
sys.exit(manager.returncode)

Architecture

Honcho follows an event-driven architecture with process management at its core:

  • Manager: Orchestrates multiple processes, handles signals, and manages process lifecycle events
  • Process: Wraps subprocess execution with event forwarding and output handling
  • Printer: Formats and colorizes process output with timestamps and process identification
  • Environment System: Manages Procfile parsing, environment variable loading, and process expansion
  • Export System: Pluggable architecture for generating process management configurations

Capabilities

Process Management

Core functionality for managing and orchestrating multiple concurrent processes with lifecycle management, output handling, and signal forwarding.

class Manager:
    def __init__(self, printer=None): ...
    def add_process(self, name, cmd, quiet=False, env=None, cwd=None): ...
    def loop(self): ...
    def terminate(self): ...
    def kill(self): ...

Process Management

Environment and Configuration

System for parsing Procfiles, managing environment variables, and expanding process configurations with concurrency and port assignment.

class Env:
    def __init__(self, config): ...
    def load_procfile(self): ...
    
def parse_procfile(contents): ...
def parse(content): ...
def expand_processes(processes, concurrency=None, env=None, quiet=None, port=None): ...

Environment and Configuration

Output Formatting

Handles formatted, colorized output with timestamps, process identification, and cross-platform terminal compatibility.

class Printer:
    def __init__(self, output=sys.stdout, time_format="%H:%M:%S", width=0, colour=True, prefix=True): ...
    def write(self, message): ...

Output Formatting

Export System

Pluggable architecture for exporting Procfile-based applications to various process management systems including systemd, supervisord, upstart, and runit.

class BaseExport:
    def __init__(self, template_dir=None, template_env=None): ...
    def render(self, processes, context): ...

Export System

Command Line Interface

Complete command-line interface for managing Procfile-based applications with commands for starting, running, checking, and exporting processes.

def main(argv=None): ...
def command_start(args): ...
def command_run(args): ...
def command_export(args): ...
def command_check(args): ...

Command Line Interface

Types

from collections import namedtuple
from typing import Dict, List, Optional, Union

ProcessParams = namedtuple("ProcessParams", "name cmd quiet env")
Message = namedtuple("Message", "type data time name colour")

class CommandError(Exception):
    """Exception raised for command execution errors."""
    pass