0
# Configuration System
1
2
Comprehensive configuration system supporting file-based configuration, class overrides, project customization, and post-generation hooks. The configuration system allows fine-grained control over code generation behavior and output structure.
3
4
## Capabilities
5
6
### Configuration File Loading
7
8
Load configuration from YAML or JSON files for repeatable builds and complex setups.
9
10
```python { .api }
11
class ConfigFile(BaseModel):
12
class_overrides: Optional[dict[str, ClassOverride]] = None
13
content_type_overrides: Optional[dict[str, str]] = None
14
project_name_override: Optional[str] = None
15
package_name_override: Optional[str] = None
16
package_version_override: Optional[str] = None
17
use_path_prefixes_for_title_model_names: bool = True
18
post_hooks: Optional[list[str]] = None
19
docstrings_on_attributes: bool = False
20
field_prefix: str = "field_"
21
generate_all_tags: bool = False
22
http_timeout: int = 5
23
literal_enums: bool = False
24
25
@staticmethod
26
def load_from_path(path: Path) -> "ConfigFile":
27
"""
28
Load configuration from JSON or YAML file.
29
30
Parameters:
31
- path: Path to configuration file
32
33
Returns:
34
ConfigFile object with loaded settings
35
"""
36
```
37
38
### Class Override Configuration
39
40
Control the names and organization of generated model classes.
41
42
```python { .api }
43
class ClassOverride(BaseModel):
44
class_name: Optional[str] = None
45
module_name: Optional[str] = None
46
47
"""
48
Configuration for overriding generated class names.
49
50
Attributes:
51
- class_name: Override the generated class name
52
- module_name: Override the generated module name
53
"""
54
```
55
56
### Metadata Type Configuration
57
58
Control the type of project metadata generated (pyproject.toml, setup.py, etc.).
59
60
```python { .api }
61
class MetaType(str, Enum):
62
NONE = "none" # No project metadata files
63
POETRY = "poetry" # Poetry-compatible pyproject.toml
64
SETUP = "setup" # setup.py file
65
PDM = "pdm" # PDM-compatible pyproject.toml
66
UV = "uv" # uv-compatible pyproject.toml
67
```
68
69
### Runtime Configuration
70
71
The main configuration object used during generation, combining file-based and runtime settings.
72
73
```python { .api }
74
class Config:
75
meta_type: MetaType
76
class_overrides: dict[str, ClassOverride]
77
project_name_override: Optional[str]
78
package_name_override: Optional[str]
79
package_version_override: Optional[str]
80
use_path_prefixes_for_title_model_names: bool
81
post_hooks: list[str]
82
docstrings_on_attributes: bool
83
field_prefix: str
84
generate_all_tags: bool
85
http_timeout: int
86
literal_enums: bool
87
document_source: Union[Path, str]
88
file_encoding: str
89
content_type_overrides: dict[str, str]
90
overwrite: bool
91
output_path: Optional[Path]
92
93
@staticmethod
94
def from_sources(
95
config_file: ConfigFile,
96
meta_type: MetaType,
97
document_source: Union[Path, str],
98
file_encoding: str,
99
overwrite: bool,
100
output_path: Optional[Path],
101
) -> "Config":
102
"""
103
Create a Config from various sources.
104
105
Parameters:
106
- config_file: File-based configuration settings
107
- meta_type: Project metadata type
108
- document_source: OpenAPI document URL or file path
109
- file_encoding: Text encoding for generated files
110
- overwrite: Whether to overwrite existing output
111
- output_path: Custom output directory
112
113
Returns:
114
Combined configuration object
115
"""
116
```
117
118
## Configuration Options
119
120
### Project Customization
121
122
Control the names and structure of generated projects:
123
124
```yaml
125
# Project and package names
126
project_name_override: "my-awesome-api-client"
127
package_name_override: "my_awesome_api_client"
128
package_version_override: "1.0.0"
129
130
# Use path prefixes in model names for disambiguation
131
use_path_prefixes_for_title_model_names: true
132
```
133
134
### Class and Module Overrides
135
136
Rename generated classes and control their module organization:
137
138
```yaml
139
class_overrides:
140
VeryLongGeneratedModelName:
141
class_name: ShortName
142
module_name: short_name
143
AnotherLongName:
144
class_name: Better
145
# module_name defaults to snake_case of class_name
146
```
147
148
### Code Generation Options
149
150
Control aspects of the generated code:
151
152
```yaml
153
# Add docstrings to model attributes
154
docstrings_on_attributes: true
155
156
# Prefix for fields that conflict with Python keywords
157
field_prefix: "field_"
158
159
# Generate all tags even if they have no operations
160
generate_all_tags: false
161
162
# Use literal types instead of enums for string enums
163
literal_enums: true
164
```
165
166
### Content Type Handling
167
168
Override content type detection for specific MIME types:
169
170
```yaml
171
content_type_overrides:
172
"application/vnd.api+json": "application/json"
173
"text/csv": "text/plain"
174
```
175
176
### Post-Generation Hooks
177
178
Run commands after code generation for formatting and validation:
179
180
```yaml
181
post_hooks:
182
- "ruff check --fix ."
183
- "ruff format ."
184
- "mypy ."
185
- "pytest tests/"
186
```
187
188
### Network Configuration
189
190
Control HTTP behavior when fetching OpenAPI documents:
191
192
```yaml
193
# Timeout in seconds for HTTP requests
194
http_timeout: 30
195
```
196
197
## Usage Examples
198
199
### Basic YAML Configuration
200
201
```yaml
202
# config.yaml
203
project_name_override: "weather-api-client"
204
package_name_override: "weather_api_client"
205
206
class_overrides:
207
WeatherDataResponseModel:
208
class_name: WeatherData
209
module_name: weather_data
210
211
post_hooks:
212
- "ruff check --fix ."
213
- "ruff format ."
214
215
field_prefix: "attr_"
216
docstrings_on_attributes: true
217
http_timeout: 10
218
```
219
220
### JSON Configuration
221
222
```json
223
{
224
"project_name_override": "weather-api-client",
225
"package_name_override": "weather_api_client",
226
"class_overrides": {
227
"WeatherDataResponseModel": {
228
"class_name": "WeatherData",
229
"module_name": "weather_data"
230
}
231
},
232
"post_hooks": [
233
"ruff check --fix .",
234
"ruff format ."
235
],
236
"field_prefix": "attr_",
237
"docstrings_on_attributes": true,
238
"http_timeout": 10
239
}
240
```
241
242
### Loading Configuration Programmatically
243
244
```python
245
from pathlib import Path
246
from openapi_python_client.config import ConfigFile, MetaType, ClassOverride
247
248
# Load from file
249
config_file = ConfigFile.load_from_path(Path("config.yaml"))
250
251
# Or create programmatically
252
config_file = ConfigFile(
253
project_name_override="my-client",
254
class_overrides={
255
"LongModelName": ClassOverride(
256
class_name="ShortName",
257
module_name="short_name"
258
)
259
},
260
post_hooks=["ruff check --fix .", "ruff format ."],
261
docstrings_on_attributes=True,
262
field_prefix="field_",
263
http_timeout=30
264
)
265
```
266
267
### Different Metadata Types
268
269
```python
270
from openapi_python_client.config import MetaType
271
272
# Poetry (default) - generates pyproject.toml with Poetry metadata
273
meta_type = MetaType.POETRY
274
275
# PDM - generates pyproject.toml with PDM metadata
276
meta_type = MetaType.PDM
277
278
# Setup.py - generates traditional setup.py file
279
meta_type = MetaType.SETUP
280
281
# UV - generates pyproject.toml with uv metadata
282
meta_type = MetaType.UV
283
284
# None - generates only Python code, no project metadata
285
meta_type = MetaType.NONE
286
```
287
288
### Advanced Hook Configuration
289
290
```yaml
291
# Advanced post-hooks for different environments
292
post_hooks:
293
# Code formatting
294
- "ruff check --fix ."
295
- "ruff format ."
296
297
# Type checking
298
- "mypy ."
299
300
# Testing
301
- "pytest --cov=. --cov-report=html"
302
303
# Documentation
304
- "sphinx-build -b html docs docs/_build"
305
306
# Security scanning
307
- "bandit -r ."
308
```
309
310
## Default Behavior
311
312
When no configuration file is provided, the system uses these defaults:
313
314
- **meta_type**: `MetaType.POETRY`
315
- **field_prefix**: `"field_"`
316
- **http_timeout**: `5` seconds
317
- **file_encoding**: `"utf-8"`
318
- **post_hooks**: Ruff formatting and linting commands
319
- **use_path_prefixes_for_title_model_names**: `true`
320
- **docstrings_on_attributes**: `false`
321
- **generate_all_tags**: `false`
322
- **literal_enums**: `false`