0
# Taskipy
1

2
A complementary task runner for Python projects that enables defining and executing development pipeline tasks through pyproject.toml configuration. Taskipy provides an npm run-script inspired interface for Python, supporting task composition, pre/post hooks, variable substitution, and working directory configuration.
3

4
## Package Information
5

6
- **Package Name**: taskipy
7
- **Language**: Python
8
- **Installation**: `pip install taskipy` or `poetry add --dev taskipy`
9
- **Requirements**: Python 3.6+, valid pyproject.toml file
10

11
## Core Imports
12

13
```python
14
from taskipy.cli import run, main
15
from taskipy.task_runner import TaskRunner
16
from taskipy.list import TasksListFormatter
17
```
18

19
## Basic Usage
20

21
### Configuration
22
Define tasks in `pyproject.toml`:
23

24
```toml
25
[tool.taskipy.tasks]
26
test = "python -m unittest tests/test_*.py"
27
lint = { cmd = "pylint tests taskipy", help = "lint code with pylint" }
28
```
29

30
### Command Line Usage
31
```bash
32
# Run a task
33
task test
34

35
# List available tasks
36
task --list
37

38
# Pass arguments to tasks
39
task test --verbose
40
```
41

42
### Programmatic Usage
43
```python
44
from taskipy.cli import run
45
from pathlib import Path
46

47
# Run task programmatically
48
exit_code = run(['test', '--verbose'], cwd='/path/to/project')
49

50
# Direct TaskRunner usage
51
from taskipy.task_runner import TaskRunner
52

53
runner = TaskRunner(Path('/path/to/project'))
54
runner.list()  # Show available tasks
55
exit_code = runner.run('test', ['--verbose'])
56
```
57

58
## Architecture
59

60
Taskipy consists of several key components:
61

62
- **CLI Interface** (`taskipy.cli`): Command-line entry point and programmatic API
63
- **TaskRunner** (`taskipy.task_runner`): Core task execution engine with pre/post hook support
64
- **PyProject** (`taskipy.pyproject`): Configuration parser for pyproject.toml files
65
- **Task** (`taskipy.task`): Individual task representation with metadata
66
- **Variable** (`taskipy.variable`): Variable substitution system with recursive support
67
- **TasksListFormatter** (`taskipy.list`): Task display and formatting utilities
68

69
## Capabilities
70

71
### Command Line Interface
72

73
Primary interface for running tasks, listing available tasks, and passing arguments. Supports both direct execution and programmatic usage.
74

75
```python { .api }
76
def main(): ...
77
def run(args: List[str], cwd: Union[str, Path, None] = None) -> int: ...
78
```
79

80
[Command Line Interface](./cli.md)
81

82
### Task Execution and Management
83

84
Core task execution engine that handles task discovery, pre/post hooks, variable substitution, and process management.
85

86
```python { .api }
87
class TaskRunner:
88
    def __init__(self, cwd: Union[str, Path]): ...
89
    def list(self): ...
90
    def run(self, task_name: str, args: List[str]) -> int: ...
91
```
92

93
[Task Execution](./task-execution.md)
94

95
### Configuration Management
96

97
Manages pyproject.toml configuration parsing, task definitions, variables, and settings.
98

99
```python { .api }
100
class PyProject:
101
    def __init__(self, base_dir: Path): ...
102
    @property
103
    def tasks(self) -> Dict[str, Task]: ...
104
    @property
105
    def variables(self) -> Dict[str, Variable]: ...
106
    @property
107
    def settings(self) -> dict: ...
108
```
109

110
[Configuration](./configuration.md)
111

112
### Task Composition and Hooks
113

114
Support for task composition through pre/post hooks, task chaining, and complex workflow orchestration.
115

116
```python { .api }
117
class Task:
118
    def __init__(self, task_name: str, task_toml_contents: object): ...
119
    @property
120
    def name(self) -> str: ...
121
    @property
122
    def command(self) -> str: ...
123
    @property
124
    def description(self) -> str: ...
125
```
126

127
[Task Composition](./task-composition.md)
128

129
### Variable Substitution
130

131
Template variable system with recursive variable support for DRY task configuration.
132

133
```python { .api }
134
class Variable:
135
    def __init__(self, name: str, value: str, recursive: bool): ...
136
    @property
137
    def name(self) -> str: ...
138
    @property
139
    def value(self) -> str: ...
140
    @property
141
    def recursive(self) -> bool: ...
142
```
143

144
[Variables](./variables.md)
145

146
### Task List Formatting
147

148
Utilities for formatting and displaying task lists with colored output and automatic terminal width handling.
149

150
```python { .api }
151
class TasksListFormatter:
152
    def __init__(self, tasks: Iterable[Task]): ...
153
    def print(self, line_width: Optional[int] = None): ...
154
```
155

156
### Error Handling
157

158
Comprehensive exception hierarchy for handling various error conditions with specific exit codes.
159

160
```python { .api }
161
class TaskipyError(Exception):
162
    exit_code = 1
163

164
class TaskNotFoundError(TaskipyError):
165
    exit_code = 127
166
    def __init__(self, task_name: str, suggestion: Optional[str] = None): ...
167
```
168

169
[Error Handling](./error-handling.md)
170

171
## Types
172

173
```python { .api }
174
from typing import List, Dict, Optional, Union, Iterable
175
from pathlib import Path
176

177
TaskDict = Dict[str, Task]
178
VariableDict = Dict[str, Variable]
179
SettingsDict = dict
180
```