0
# Configuration
1

2
Configuration management system that parses pyproject.toml files and provides access to tasks, variables, and settings.
3

4
## Capabilities
5

6
### PyProject Class
7

8
Central configuration manager that loads and parses pyproject.toml files.
9

10
```python { .api }
11
class PyProject:
12
    def __init__(self, base_dir: Path):
13
        """
14
        Initialize PyProject with base directory.
15
        
16
        Searches for pyproject.toml in base_dir and parent directories.
17
        
18
        Args:
19
            base_dir: Starting directory for pyproject.toml search
20
        """
21
```
22

23
### Task Access
24

25
Access to all defined tasks with their configurations.
26

27
```python { .api }
28
@property
29
def tasks(self) -> Dict[str, Task]:
30
    """
31
    Dictionary of all defined tasks.
32
    
33
    Returns:
34
        Dict mapping task names to Task objects
35
        
36
    Raises:
37
        MissingTaskipyTasksSectionError: If [tool.taskipy.tasks] section missing
38
    """
39
```
40

41
### Variable Access
42

43
Access to all defined variables for task substitution.
44

45
```python { .api }
46
@property
47
def variables(self) -> Dict[str, Variable]:
48
    """
49
    Dictionary of all defined variables.
50
    
51
    Returns:
52
        Dict mapping variable names to Variable objects
53
        Empty dict if no variables section exists
54
    """
55
```
56

57
### Settings Access
58

59
Access to global taskipy settings.
60

61
```python { .api }
62
@property
63
def settings(self) -> dict:
64
    """
65
    Dictionary of taskipy settings.
66
    
67
    Returns:
68
        Dict containing settings from [tool.taskipy.settings]
69
        Empty dict if no settings section exists
70
    """
71
```
72

73
### Project Directory
74

75
Path to the directory containing the pyproject.toml file.
76

77
```python { .api }
78
@property
79
def dirpath(self) -> Path:
80
    """
81
    Path to directory containing pyproject.toml.
82
    
83
    Returns:
84
        Path object pointing to project root directory
85
    """
86
```
87

88
### Custom Runner
89

90
Access to configured custom task runner.
91

92
```python { .api }
93
@property
94
def runner(self) -> Optional[str]:
95
    """
96
    Custom runner command if configured.
97
    
98
    Returns:
99
        Runner command string or None if not configured
100
        
101
    Raises:
102
        InvalidRunnerTypeError: If runner setting is not a string
103
    """
104
```
105

106
## Usage Examples
107

108
### Basic Configuration Access
109

110
```python
111
from taskipy.pyproject import PyProject
112
from pathlib import Path
113

114
# Load project configuration
115
project = PyProject(Path('/path/to/project'))
116

117
# Access tasks
118
tasks = project.tasks
119
for name, task in tasks.items():
120
    print(f"Task: {name}, Command: {task.command}")
121

122
# Access variables
123
variables = project.variables
124
for name, var in variables.items():
125
    print(f"Variable: {name} = {var.value}")
126

127
# Access settings
128
settings = project.settings
129
print(f"Use vars globally: {settings.get('use_vars', False)}")
130
```
131

132
### Working with Different Project Structures
133

134
```python
135
# Nested project structure
136
# taskipy searches parent directories for pyproject.toml
137
project = PyProject(Path('/project/src/module'))  # Finds /project/pyproject.toml
138

139
# Multi-project monorepo
140
# Each subproject can have its own pyproject.toml
141
project = PyProject(Path('/monorepo/service-a'))  # Finds service-a/pyproject.toml
142
```
143

144
### Error Handling
145

146
```python
147
from taskipy.exceptions import (
148
    MissingPyProjectFileError,
149
    MalformedPyProjectError,
150
    MissingTaskipyTasksSectionError
151
)
152

153
try:
154
    project = PyProject(Path('/path/to/project'))
155
    tasks = project.tasks
156
except MissingPyProjectFileError:
157
    print("No pyproject.toml found in directory or parents")
158
except MalformedPyProjectError as e:
159
    print(f"Invalid TOML syntax: {e.reason}")
160
except MissingTaskipyTasksSectionError:
161
    print("No [tool.taskipy.tasks] section found")
162
```
163

164
## Configuration Format
165

166
### Task Definitions
167

168
Tasks can be defined in two formats:
169

170
#### Simple String Format
171
```toml
172
[tool.taskipy.tasks]
173
test = "python -m pytest"
174
lint = "pylint src tests"
175
```
176

177
#### Explicit Table Format
178
```toml
179
[tool.taskipy.tasks]
180
test = { cmd = "python -m pytest", help = "Run unit tests", cwd = ".", use_vars = true }
181
lint = { cmd = "pylint src tests", help = "Lint code with pylint" }
182
```
183

184
### Variable Definitions
185

186
Variables support both simple and recursive formats:
187

188
#### Simple Variables
189
```toml
190
[tool.taskipy.variables]
191
src_dir = "src"
192
test_dir = "tests"
193
```
194

195
#### Recursive Variables
196
```toml
197
[tool.taskipy.variables]
198
src_dir = "src"
199
package_dir = { var = "{src_dir}/mypackage", recursive = true }
200
test_path = { var = "{package_dir}/tests", recursive = true }
201
```
202

203
### Settings Configuration
204

205
Global settings that affect all tasks:
206

207
```toml
208
[tool.taskipy.settings]
209
use_vars = true          # Enable variables globally
210
cwd = "."               # Set global working directory
211
runner = "poetry run"    # Prefix all commands with runner
212
```
213

214
## Configuration Loading
215

216
### File Discovery
217

218
PyProject automatically searches for pyproject.toml:
219

220
1. Check provided base directory
221
2. Search parent directories recursively up to filesystem root
222
3. Raise MissingPyProjectFileError if not found
223

224
### TOML Parsing
225

226
- Uses `tomli` library for robust TOML parsing
227
- Handles malformed TOML files with descriptive errors
228
- Supports all TOML specification features
229

230
### Section Processing
231

232
#### Tasks Section
233
- Required: `[tool.taskipy.tasks]`
234
- Converts TOML values to Task objects
235
- Validates task structure and types
236

237
#### Variables Section
238
- Optional: `[tool.taskipy.variables]`
239
- Converts to Variable objects with recursion support
240
- Validates variable format and types
241

242
#### Settings Section
243
- Optional: `[tool.taskipy.settings]`
244
- Provides global configuration options
245
- Type validation for specific settings
246

247
## Advanced Configuration
248

249
### Project Structure Examples
250

251
#### Simple Project
252
```
253
project/
254
├── pyproject.toml
255
├── src/
256
└── tests/
257
```
258

259
#### Monorepo Structure
260
```
261
monorepo/
262
├── pyproject.toml          # Root configuration
263
├── service-a/
264
│   ├── pyproject.toml      # Service-specific tasks
265
│   └── src/
266
└── service-b/
267
    ├── pyproject.toml      # Service-specific tasks
268
    └── src/
269
```
270

271
#### Nested Development
272
```
273
project/
274
├── pyproject.toml
275
├── src/
276
│   └── mypackage/
277
│       └── submodule/      # taskipy works from any subdirectory
278
└── tests/
279
```
280

281
### Configuration Inheritance
282

283
Settings are applied with the following precedence:
284
1. Task-specific settings (highest priority)
285
2. Global taskipy settings
286
3. Default values (lowest priority)
287

288
### Validation Rules
289

290
- Task commands must be strings or valid table format
291
- Variable values must be strings or valid recursive format
292
- Settings values must match expected types
293
- Circular variable dependencies are detected and prevented