0
# Core API Functions
1
2
Primary programmatic interface for running tasks and accessing doit functionality directly from Python code without using the command line interface.
3
4
## Capabilities
5
6
### Task Execution
7
8
Execute doit tasks programmatically from Python code using task creators from modules or dictionaries.
9
10
```python { .api }
11
def run(task_creators):
12
"""
13
Run doit using task_creators from module or dict.
14
15
This function provides a shortcut to execute tasks without using the
16
command line interface. It will call sys.exit() with the appropriate
17
return code.
18
19
Args:
20
task_creators: module or dict containing task creator functions
21
22
Returns:
23
Does not return - calls sys.exit() with result code
24
25
Raises:
26
SystemExit: Always called with return code (0=success, 1=failure, 2=error, 3=user error)
27
"""
28
```
29
30
```python { .api }
31
def run_tasks(loader, tasks, extra_config=None):
32
"""
33
Run DoitMain instance with specified tasks and parameters.
34
35
More advanced API for running specific tasks with custom configuration
36
without command line parsing.
37
38
Args:
39
loader: Task loader instance
40
tasks (dict): Dictionary of task names and their options
41
extra_config (dict, optional): Extra configuration options
42
43
Returns:
44
int: Return code (0=success, 1=failure, 2=error, 3=user error)
45
46
Raises:
47
CmdParseError: Command parsing errors
48
InvalidDodoFile: Invalid dodo file errors
49
InvalidCommand: Invalid command errors
50
InvalidTask: Invalid task errors
51
"""
52
```
53
54
### Variable Access
55
56
Access command line variables and working directory information from within task functions.
57
58
```python { .api }
59
def get_var(name, default=None):
60
"""
61
Get command line variable values passed to doit.
62
63
Variables are set on command line as name=value pairs and can be
64
accessed within task functions using this function.
65
66
Args:
67
name (str): Variable name to retrieve
68
default: Default value if variable not found
69
70
Returns:
71
Variable value or default if not found, None if not initialized
72
"""
73
```
74
75
```python { .api }
76
def get_initial_workdir():
77
"""
78
Get working directory from where doit command was invoked.
79
80
Returns the directory path from where the doit command was originally
81
executed, before any directory changes during execution.
82
83
Returns:
84
str: Initial working directory path
85
"""
86
```
87
88
### Package Version
89
90
```python { .api }
91
__version__ = VERSION # Package version tuple (0, 36, 0)
92
```
93
94
### Usage Examples
95
96
#### Basic Task Execution
97
98
```python
99
from doit import run
100
101
def task_hello():
102
return {'actions': ['echo "Hello from API"']}
103
104
def task_build():
105
return {
106
'file_dep': ['src/main.py'],
107
'targets': ['dist/app'],
108
'actions': ['python setup.py build']
109
}
110
111
# Run all tasks in current module
112
if __name__ == '__main__':
113
run(globals())
114
```
115
116
#### Advanced Task Execution
117
118
```python
119
from doit.api import run_tasks
120
from doit.cmd_base import ModuleTaskLoader
121
122
# Define tasks
123
tasks = {
124
'build': {
125
'actions': ['python setup.py build'],
126
'file_dep': ['setup.py', 'src/main.py']
127
}
128
}
129
130
# Create loader and run specific tasks
131
loader = ModuleTaskLoader(tasks)
132
result = run_tasks(loader, ['build'])
133
print(f"Build result: {result}")
134
```
135
136
#### Variable Usage
137
138
```python
139
from doit import get_var
140
141
def task_deploy():
142
"""Deploy to environment specified by 'env' variable"""
143
environment = get_var('env', 'development')
144
return {
145
'actions': [f'deploy.sh --env {environment}'],
146
'verbosity': 2
147
}
148
149
# Run with: doit deploy env=production
150
```