0
# Honcho
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: honcho
7
- **Language**: Python
8
- **Installation**: `pip install honcho`
9
- **Export Dependencies**: `pip install honcho[export]` (for export functionality)
10

11
## Core Imports
12

13
```python
14
import honcho  # Only provides __version__
15
```
16

17
For programmatic usage:
18

19
```python
20
from honcho.manager import Manager
21
from honcho.printer import Printer
22
from honcho.environ import Env, parse_procfile, expand_processes
23
from honcho.process import Process
24
```
25

26
For CLI usage:
27

28
```python
29
from honcho.command import main
30
```
31

32
## Basic Usage
33

34
### Command Line Interface
35

36
```bash
37
# Start all processes from Procfile
38
honcho start
39

40
# Start specific processes
41
honcho start web worker
42

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

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

49
# Check Procfile validity
50
honcho check
51
```
52

53
### Programmatic Usage
54

55
```python
56
import sys
57
from honcho.manager import Manager
58
from honcho.printer import Printer
59

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

63
# Add processes
64
manager.add_process('web', 'python app.py')
65
manager.add_process('worker', 'python worker.py')
66

67
# Start all processes
68
manager.loop()
69

70
# Exit with appropriate code
71
sys.exit(manager.returncode)
72
```
73

74
## Architecture
75

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

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

84
## Capabilities
85

86
### Process Management
87

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

90
```python { .api }
91
class Manager:
92
    def __init__(self, printer=None): ...
93
    def add_process(self, name, cmd, quiet=False, env=None, cwd=None): ...
94
    def loop(self): ...
95
    def terminate(self): ...
96
    def kill(self): ...
97
```
98

99
[Process Management](./process-management.md)
100

101
### Environment and Configuration
102

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

105
```python { .api }
106
class Env:
107
    def __init__(self, config): ...
108
    def load_procfile(self): ...
109
    
110
def parse_procfile(contents): ...
111
def parse(content): ...
112
def expand_processes(processes, concurrency=None, env=None, quiet=None, port=None): ...
113
```
114

115
[Environment and Configuration](./environment-configuration.md)
116

117
### Output Formatting
118

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

121
```python { .api }
122
class Printer:
123
    def __init__(self, output=sys.stdout, time_format="%H:%M:%S", width=0, colour=True, prefix=True): ...
124
    def write(self, message): ...
125
```
126

127
[Output Formatting](./output-formatting.md)
128

129
### Export System
130

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

133
```python { .api }
134
class BaseExport:
135
    def __init__(self, template_dir=None, template_env=None): ...
136
    def render(self, processes, context): ...
137
```
138

139
[Export System](./export-system.md)
140

141
### Command Line Interface
142

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

145
```python { .api }
146
def main(argv=None): ...
147
def command_start(args): ...
148
def command_run(args): ...
149
def command_export(args): ...
150
def command_check(args): ...
151
```
152

153
[Command Line Interface](./command-line-interface.md)
154

155
## Types
156

157
```python { .api }
158
from collections import namedtuple
159
from typing import Dict, List, Optional, Union
160

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

164
class CommandError(Exception):
165
    """Exception raised for command execution errors."""
166
    pass
167
```