0
# doit
1
2
A powerful automation tool that brings the concept of build tools to execute any kind of task. doit scales from simple task runners for organizing project-related tasks to efficient build-tool execution with DAG (Direct Acyclic Graph) creation and task result caching, ensuring only required tasks are executed in the correct order for incremental builds.
3
4
## Package Information
5
6
- **Package Name**: doit
7
- **Language**: Python
8
- **Installation**: `pip install doit`
9
- **Dependencies**: `cloudpickle`, `importlib-metadata>=4.4`
10
- **Optional**: `tomli` for TOML config support (Python < 3.11)
11
12
## Core Imports
13
14
```python
15
import doit
16
```
17
18
For programmatic API usage:
19
20
```python
21
from doit import run, get_var, create_after, task_params, Globals
22
from doit.api import run_tasks
23
from doit.tools import config_changed, timeout, LongRunning, Interactive
24
```
25
26
## Basic Usage
27
28
### Simple Task Definition (dodo.py)
29
30
```python
31
def task_hello():
32
"""Say hello"""
33
return {
34
'actions': ['echo "Hello World!"'],
35
'verbosity': 2,
36
}
37
38
def task_compile():
39
"""Compile source files"""
40
return {
41
'file_dep': ['src/main.c'],
42
'targets': ['build/main.o'],
43
'actions': ['gcc -c src/main.c -o build/main.o'],
44
}
45
```
46
47
### Running Tasks
48
49
```bash
50
# List available tasks
51
doit list
52
53
# Run all tasks
54
doit
55
56
# Run specific task
57
doit hello
58
```
59
60
### Programmatic Usage
61
62
```python
63
from doit import run
64
65
# Define tasks in current module
66
def task_example():
67
return {'actions': ['echo "Running example"']}
68
69
# Run tasks programmatically
70
if __name__ == '__main__':
71
run(globals())
72
```
73
74
## Architecture
75
76
doit follows a plugin-based architecture with several key components:
77
78
- **Task Loaders**: Discover and load task definitions from dodo files or modules
79
- **Dependency Manager**: Track file dependencies and task execution state using persistent storage
80
- **Runner**: Execute tasks with support for parallel execution and incremental builds
81
- **Commands**: Extensible command system (run, list, clean, info, etc.)
82
- **Reporters**: Customizable output formatting and progress reporting
83
- **Actions**: Pluggable execution engines for shell commands and Python functions
84
85
This design enables doit to serve both as a simple task runner and as a framework for building complex automation workflows and pipelines.
86
87
## Capabilities
88
89
### Core API Functions
90
91
Primary programmatic interface for running tasks and accessing doit functionality directly from Python code.
92
93
```python { .api }
94
def run(task_creators):
95
"""Run doit using task_creators from module or dict"""
96
97
def get_var(name, default=None):
98
"""Get command line variable values"""
99
100
def get_initial_workdir():
101
"""Get working directory from where doit command was invoked"""
102
```
103
104
[Core API](./core-api.md)
105
106
### Task Definition and Loading
107
108
Functions and decorators for defining tasks, managing delayed task creation, and parameterizing task generators.
109
110
```python { .api }
111
@create_after(executed=None, target_regex=None, creates=None)
112
def task_creator_func():
113
"""Decorator for delayed task creation"""
114
115
@task_params(param_def)
116
def task_creator_func():
117
"""Decorator for task parameter definitions"""
118
119
def load_tasks(namespace, command_names=(), allow_delayed=False, args=(), config=None, task_opts=None):
120
"""Find task-creators and create tasks from namespace"""
121
```
122
123
[Task Definition](./task-definition.md)
124
125
### Actions and Execution
126
127
Classes and utilities for defining task actions, including shell commands, Python functions, and specialized interactive actions.
128
129
```python { .api }
130
class LongRunning(CmdAction):
131
"""Handle long running shell processes (servers/services)"""
132
133
class Interactive(CmdAction):
134
"""Handle interactive shell processes"""
135
136
class PythonInteractiveAction(PythonAction):
137
"""Handle interactive Python actions"""
138
```
139
140
[Actions](./actions.md)
141
142
### Utility Tools and Helpers
143
144
Helper functions and classes for common task patterns, uptodate checkers, and development utilities.
145
146
```python { .api }
147
def create_folder(dir_path):
148
"""Create folder if it doesn't exist"""
149
150
class config_changed:
151
"""Check if configuration was modified (uptodate checker)"""
152
153
class timeout:
154
"""Add timeout to task (uptodate checker)"""
155
156
def set_trace():
157
"""Start debugger with proper stdout"""
158
```
159
160
[Tools and Utilities](./tools.md)
161
162
### Command Line Interface
163
164
Complete command-line interface with extensible commands, configuration management, and plugin system.
165
166
```python { .api }
167
class DoitMain:
168
"""Main CLI application class"""
169
170
class DoitConfig:
171
"""Parse and store INI/TOML configuration"""
172
173
# Available commands: run, list, clean, info, help, forget, ignore, dumpdb, strace, completion, resetdep
174
```
175
176
[Command Line Interface](./cli.md)
177
178
### Exception Handling
179
180
Comprehensive exception hierarchy for task failures, configuration errors, and execution problems.
181
182
```python { .api }
183
class InvalidTask(Exception):
184
"""Invalid task instance"""
185
186
class TaskFailed(BaseFail):
187
"""Task execution was not successful"""
188
189
class TaskError(BaseFail):
190
"""Error while trying to execute task"""
191
```
192
193
[Exceptions](./exceptions.md)
194
195
## Types
196
197
### Core Types
198
199
```python { .api }
200
class Task:
201
"""Main task abstraction with actions, dependencies, targets"""
202
203
class DelayedLoader:
204
"""Contains info for delayed creation of tasks from task-creator"""
205
206
class Globals:
207
"""Registry of singletons for accessing dep_manager"""
208
dep_manager = None # Dependency manager instance
209
```