0
# Task Definition and Loading
1

2
Functions and decorators for defining tasks, managing delayed task creation, parameterizing task generators, and loading task definitions from modules.
3

4
## Capabilities
5

6
### Task Creator Decorators
7

8
Decorators for enhancing task creator functions with parameter definitions and delayed execution capabilities.
9

10
```python { .api }
11
def create_after(executed=None, target_regex=None, creates=None):
12
    """
13
    Decorator to annotate a task-creator function with delayed loader info.
14
    
15
    Allows tasks to be created after other tasks have been executed, enabling
16
    dynamic task creation based on execution results.
17
    
18
    Args:
19
        executed (str, optional): Name of task that should be executed before
20
                                calling the creator function
21
        target_regex (str, optional): Regex for all targets this loader will create
22
        creates (list, optional): List of explicit task basenames this creator will generate
23
        
24
    Returns:
25
        function: Decorated task creator function
26
    """
27
```
28

29
```python { .api }
30
def task_params(param_def):
31
    """
32
    Decorator to annotate a task-creator function with parameter definitions.
33
    
34
    Enables task creators to accept command line arguments and configuration
35
    parameters with proper parsing and validation.
36
    
37
    Args:
38
        param_def (list): List of parameter definition dictionaries with keys:
39
                         - name: parameter name
40
                         - type: parameter type (str, int, bool, etc.)
41
                         - default: default value
42
                         - help: help text
43
    
44
    Returns:
45
        function: Decorated task creator function
46
        
47
    Raises:
48
        ValueError: If param_def is not a valid parameter definition list
49
    """
50
```
51

52
### Task Loading and Generation
53

54
Functions for discovering task creators, loading tasks from namespaces, and generating task objects.
55

56
```python { .api }
57
def load_tasks(namespace, command_names=(), allow_delayed=False, args=(), config=None, task_opts=None):
58
    """
59
    Find task-creators and create tasks from a namespace dictionary.
60
    
61
    Discovers functions with names starting with 'task_' or objects with
62
    'create_doit_tasks' method and converts them to Task objects.
63
    
64
    Args:
65
        namespace (dict): Dictionary containing task creators and other objects
66
        command_names (tuple): Blacklist of command names that can't be task names
67
        allow_delayed (bool): Whether to ignore delayed task execution dependencies
68
        args (list): Command line arguments for task parameter parsing
69
        config (dict): Configuration from TOML/INI files
70
        task_opts (dict): Task options passed through API
71
        
72
    Returns:
73
        list: List of Task objects in definition order
74
        
75
    Raises:
76
        InvalidTask: If task definition is invalid
77
        InvalidDodoFile: If task names conflict with command names
78
    """
79
```
80

81
```python { .api }
82
def generate_tasks(func_name, gen_result, gen_doc=None):
83
    """
84
    Create tasks from a task generator result.
85
    
86
    Processes the return value from a task creator function and converts
87
    it into Task objects, handling dictionaries, generators, and Task instances.
88
    
89
    Args:
90
        func_name (str): Name of the task generator function
91
        gen_result: Value returned by task generator (dict, generator, or Task)
92
        gen_doc (str, optional): Docstring from task generator function
93
        
94
    Returns:
95
        tuple: Tuple of Task objects
96
        
97
    Raises:
98
        InvalidTask: If generator result is invalid format
99
    """
100
```
101

102
### Module and Configuration Loading
103

104
Functions for loading dodo modules and configuration from Python files and TOML/INI files.
105

106
```python { .api }
107
def get_module(dodo_file, cwd=None, seek_parent=False):
108
    """
109
    Find and import Python module defining tasks (dodo file).
110
    
111
    Locates and imports the dodo file, setting up the proper Python path
112
    and working directory for task execution.
113
    
114
    Args:
115
        dodo_file (str): Path to file containing task definitions
116
        cwd (str, optional): Working directory to use, defaults to dodo file directory
117
        seek_parent (bool): Search for dodo file in parent directories if not found
118
        
119
    Returns:
120
        module: Imported Python module containing task definitions
121
        
122
    Raises:
123
        InvalidDodoFile: If dodo file cannot be found or imported
124
        InvalidCommand: If specified cwd is not a directory
125
    """
126
```
127

128
```python { .api }
129
def load_doit_config(dodo_module):
130
    """
131
    Load DOIT_CONFIG dictionary from dodo module.
132
    
133
    Extracts configuration settings from the DOIT_CONFIG variable in
134
    the dodo module, providing default configuration options.
135
    
136
    Args:
137
        dodo_module (dict): Dictionary with module members
138
        
139
    Returns:
140
        dict: Configuration dictionary
141
        
142
    Raises:
143
        InvalidDodoFile: If DOIT_CONFIG is not a dictionary
144
    """
145
```
146

147
### Constants and Variables
148

149
```python { .api }
150
TASK_STRING = "task_"  # Prefix used to identify task generator functions
151

152
initial_workdir = None  # Directory path from where doit was executed (set by loader)
153
```
154

155
### Usage Examples
156

157
#### Basic Task Creator with Parameters
158

159
```python
160
from doit import task_params
161

162
@task_params([
163
    {'name': 'env', 'type': str, 'default': 'dev', 'help': 'Environment to deploy to'},
164
    {'name': 'verbose', 'type': bool, 'default': False, 'help': 'Enable verbose output'}
165
])
166
def task_deploy(env, verbose):
167
    """Deploy application to specified environment"""
168
    cmd = f'deploy.sh --env {env}'
169
    if verbose:
170
        cmd += ' --verbose'
171
    
172
    return {
173
        'actions': [cmd],
174
        'verbosity': 2 if verbose else 1
175
    }
176

177
# Run with: doit deploy --env production --verbose
178
```
179

180
#### Delayed Task Creation
181

182
```python
183
from doit import create_after
184

185
@create_after(executed='setup')
186
def task_dynamic_tests():
187
    """Create test tasks based on setup results"""
188
    # This will only run after 'setup' task completes
189
    test_files = discover_test_files_from_setup()
190
    
191
    for test_file in test_files:
192
        yield {
193
            'name': f'test_{test_file}',
194
            'actions': [f'python -m pytest {test_file}'],
195
            'file_dep': [test_file]
196
        }
197
```
198

199
#### Task Generator with Subtasks
200

201
```python
202
def task_process_files():
203
    """Process all data files"""
204
    for filename in glob.glob('data/*.txt'):
205
        yield {
206
            'name': filename,
207
            'file_dep': [filename],
208
            'targets': [filename.replace('.txt', '.processed')],
209
            'actions': [f'process_data.py {filename}']
210
        }
211
```
212

213
#### Configuration Loading
214

215
```python
216
# In dodo.py
217
DOIT_CONFIG = {
218
    'default_tasks': ['build', 'test'],
219
    'continue': True,
220
    'verbosity': 2,
221
}
222

223
def task_build():
224
    return {'actions': ['python setup.py build']}
225
```