0
# Environment and File Sources
1

2
Load configuration from environment variables, .env files, and various configuration file formats including JSON, YAML, TOML, and Docker/Kubernetes secrets. These sources provide flexible configuration management for different deployment environments and use cases.
3

4
## Capabilities
5

6
### Environment Variables Source
7

8
Load settings from environment variables with support for prefixes, nested structures, and type conversion.
9

10
```python { .api }
11
class EnvSettingsSource(PydanticBaseEnvSettingsSource):
12
    """Source for environment variables."""
13
    
14
    def __init__(
15
        self,
16
        settings_cls: type[BaseSettings],
17
        case_sensitive: bool | None = None,
18
        env_prefix: str | None = None,
19
        env_nested_delimiter: str | None = None,
20
        env_nested_max_split: int | None = None,
21
        env_ignore_empty: bool | None = None,
22
        env_parse_none_str: str | None = None,
23
        env_parse_enums: bool | None = None,
24
    ):
25
        """
26
        Initialize environment settings source.
27
        
28
        Parameters:
29
        - settings_cls: The settings class
30
        - case_sensitive: Whether environment variable names are case-sensitive
31
        - env_prefix: Prefix for environment variable names
32
        - env_nested_delimiter: Delimiter for nested environment variables
33
        - env_nested_max_split: Maximum splits for nested variables
34
        - env_ignore_empty: Whether to ignore empty environment variables
35
        - env_parse_none_str: String value to parse as None
36
        - env_parse_enums: Whether to parse enum field names to values
37
        """
38
```
39

40
### DotEnv File Source
41

42
Load settings from .env files with support for multiple files, encodings, and environment variable processing.
43

44
```python { .api }
45
class DotEnvSettingsSource(EnvSettingsSource):
46
    """Source for .env file loading."""
47
    
48
    def __init__(
49
        self,
50
        settings_cls: type[BaseSettings],
51
        env_file: DotenvType | None = ENV_FILE_SENTINEL,
52
        env_file_encoding: str | None = None,
53
        case_sensitive: bool | None = None,
54
        env_prefix: str | None = None,
55
        env_nested_delimiter: str | None = None,
56
        env_nested_max_split: int | None = None,
57
        env_ignore_empty: bool | None = None,
58
        env_parse_none_str: str | None = None,
59
        env_parse_enums: bool | None = None,
60
    ):
61
        """
62
        Initialize .env file settings source.
63
        
64
        Parameters:
65
        - settings_cls: The settings class
66
        - env_file: Path(s) to .env file(s) to load
67
        - env_file_encoding: Encoding for .env files
68
        - Other parameters: Same as EnvSettingsSource
69
        """
70

71
def read_env_file(
72
    file_path: Path,
73
    *,
74
    encoding: str | None = None,
75
    case_sensitive: bool = False,
76
    ignore_empty: bool = False,
77
    parse_none_str: str | None = None,
78
) -> Mapping[str, str | None]:
79
    """
80
    Read and parse environment files.
81
    
82
    Note: This function is deprecated and will be removed in the next version.
83
    Use DotEnvSettingsSource._static_read_env_file if needed.
84
    
85
    Parameters:
86
    - file_path: Path to environment file
87
    - encoding: File encoding
88
    - case_sensitive: Whether keys are case-sensitive
89
    - ignore_empty: Whether to ignore empty values
90
    - parse_none_str: String value to parse as None
91
    
92
    Returns:
93
    Mapping of environment variables
94
    """
95
```
96

97
### JSON Configuration Source
98

99
Load settings from JSON configuration files with support for nested structures and file encoding options.
100

101
```python { .api }
102
class JsonConfigSettingsSource(InitSettingsSource, ConfigFileSourceMixin):
103
    """Source for JSON configuration files."""
104
    
105
    def __init__(
106
        self,
107
        settings_cls: type[BaseSettings],
108
        json_file: PathType | None = None,
109
        json_file_encoding: str | None = None,
110
    ):
111
        """
112
        Initialize JSON configuration source.
113
        
114
        Parameters:
115
        - settings_cls: The settings class
116
        - json_file: Path to JSON configuration file
117
        - json_file_encoding: Encoding for JSON file
118
        """
119
```
120

121
### YAML Configuration Source
122

123
Load settings from YAML configuration files with support for configuration sections and file encoding.
124

125
```python { .api }
126
class YamlConfigSettingsSource(InitSettingsSource, ConfigFileSourceMixin):
127
    """Source for YAML configuration files."""
128
    
129
    def __init__(
130
        self,
131
        settings_cls: type[BaseSettings],
132
        yaml_file: PathType | None = None,
133
        yaml_file_encoding: str | None = None,
134
        yaml_config_section: str | None = None,
135
    ):
136
        """
137
        Initialize YAML configuration source.
138
        
139
        Parameters:
140
        - settings_cls: The settings class
141
        - yaml_file: Path to YAML configuration file
142
        - yaml_file_encoding: Encoding for YAML file
143
        - yaml_config_section: Top-level key to load from YAML file
144
        """
145
```
146

147
### TOML Configuration Source
148

149
Load settings from TOML configuration files with support for table headers and nested structures.
150

151
```python { .api }
152
class TomlConfigSettingsSource(InitSettingsSource, ConfigFileSourceMixin):
153
    """Source for TOML configuration files."""
154
    
155
    def __init__(
156
        self,
157
        settings_cls: type[BaseSettings],
158
        toml_file: PathType | None = None,
159
    ):
160
        """
161
        Initialize TOML configuration source.
162
        
163
        Parameters:
164
        - settings_cls: The settings class
165
        - toml_file: Path to TOML configuration file
166
        """
167

168
class PyprojectTomlConfigSettingsSource(TomlConfigSettingsSource):
169
    """Source for pyproject.toml configuration files."""
170
    
171
    def __init__(
172
        self,
173
        settings_cls: type[BaseSettings],
174
        pyproject_toml_depth: int = 0,
175
        pyproject_toml_table_header: tuple[str, ...] = (),
176
    ):
177
        """
178
        Initialize pyproject.toml configuration source.
179
        
180
        Parameters:
181
        - settings_cls: The settings class
182
        - pyproject_toml_depth: Directory levels up to search for pyproject.toml
183
        - pyproject_toml_table_header: TOML table header path
184
        """
185
```
186

187
### Secrets File Source
188

189
Load settings from Docker/Kubernetes secrets files with support for secrets directories and file-based configuration.
190

191
```python { .api }
192
class SecretsSettingsSource(PydanticBaseEnvSettingsSource):
193
    """Source for Docker/Kubernetes secrets files."""
194
    
195
    def __init__(
196
        self,
197
        settings_cls: type[BaseSettings],
198
        secrets_dir: PathType | None = None,
199
        case_sensitive: bool | None = None,
200
        env_prefix: str | None = None,
201
    ):
202
        """
203
        Initialize secrets file source.
204
        
205
        Parameters:
206
        - settings_cls: The settings class
207
        - secrets_dir: Directory containing secret files
208
        - case_sensitive: Whether secret names are case-sensitive
209
        - env_prefix: Prefix for secret names
210
        """
211
```
212

213
## Usage Examples
214

215
### Environment Variables
216

217
```python
218
import os
219
from pydantic_settings import BaseSettings
220

221
class AppSettings(BaseSettings):
222
    app_name: str = "MyApp"
223
    debug: bool = False
224
    max_connections: int = 100
225
    
226
    model_config = SettingsConfigDict(
227
        env_prefix='MYAPP_',
228
        case_sensitive=False
229
    )
230

231
# Set environment variables
232
os.environ['MYAPP_DEBUG'] = 'true'
233
os.environ['MYAPP_MAX_CONNECTIONS'] = '200'
234

235
settings = AppSettings()
236
print(f"Debug: {settings.debug}, Connections: {settings.max_connections}")
237
```
238

239
### Nested Environment Variables
240

241
```python
242
from pydantic import BaseModel
243

244
class DatabaseConfig(BaseModel):
245
    host: str = "localhost"
246
    port: int = 5432
247
    credentials: dict[str, str] = {}
248

249
class AppSettings(BaseSettings):
250
    database: DatabaseConfig = DatabaseConfig()
251
    
252
    model_config = SettingsConfigDict(
253
        env_nested_delimiter='__',
254
        case_sensitive=False
255
    )
256

257
# Environment variables: DATABASE__HOST, DATABASE__PORT, DATABASE__CREDENTIALS__USERNAME
258
os.environ['DATABASE__HOST'] = 'prod-db.company.com'
259
os.environ['DATABASE__PORT'] = '5432'
260
os.environ['DATABASE__CREDENTIALS__USERNAME'] = 'app_user'
261

262
settings = AppSettings()
263
```
264

265
### DotEnv Files
266

267
```python
268
# .env file content:
269
# DEBUG=true
270
# DATABASE_URL=postgresql://localhost/myapp
271
# API_KEY=secret-key-here
272

273
class AppSettings(BaseSettings):
274
    debug: bool = False
275
    database_url: str
276
    api_key: str
277
    
278
    model_config = SettingsConfigDict(
279
        env_file='.env',
280
        env_file_encoding='utf-8'
281
    )
282

283
settings = AppSettings()  # Loads from .env file
284
```
285

286
### Multiple DotEnv Files
287

288
```python
289
class AppSettings(BaseSettings):
290
    debug: bool = False
291
    database_url: str
292
    api_key: str
293
    
294
    model_config = SettingsConfigDict(
295
        env_file=['.env', '.env.local', '.env.production'],
296
        env_file_encoding='utf-8'
297
    )
298

299
# Files loaded in order, later files override earlier ones
300
settings = AppSettings()
301
```
302

303
### JSON Configuration
304

305
```python
306
# config.json:
307
# {
308
#   "app_name": "Production App",
309
#   "database": {
310
#     "host": "prod-db.company.com",
311
#     "port": 5432
312
#   },
313
#   "features": {
314
#     "enable_logging": true,
315
#     "max_retries": 3
316
#   }
317
# }
318

319
from pydantic import BaseModel
320

321
class DatabaseConfig(BaseModel):
322
    host: str
323
    port: int
324

325
class FeatureConfig(BaseModel):
326
    enable_logging: bool
327
    max_retries: int
328

329
class AppSettings(BaseSettings):
330
    app_name: str
331
    database: DatabaseConfig
332
    features: FeatureConfig
333
    
334
    model_config = SettingsConfigDict(
335
        json_file='config.json',
336
        json_file_encoding='utf-8'
337
    )
338

339
settings = AppSettings()
340
```
341

342
### YAML Configuration
343

344
```python
345
# config.yaml:
346
# production:
347
#   app_name: "Production App"
348
#   database:
349
#     host: "prod-db.company.com"
350
#     port: 5432
351
#   api:
352
#     timeout: 30
353
#     retries: 3
354

355
class AppSettings(BaseSettings):
356
    app_name: str
357
    database: dict
358
    api: dict
359
    
360
    model_config = SettingsConfigDict(
361
        yaml_file='config.yaml',
362
        yaml_config_section='production'  # Load from 'production' section
363
    )
364

365
settings = AppSettings()
366
```
367

368
### Docker Secrets
369

370
```python
371
# Docker secrets mounted at /run/secrets/
372
# Files: /run/secrets/db_password, /run/secrets/api_key
373

374
class AppSettings(BaseSettings):
375
    db_password: str
376
    api_key: str
377
    
378
    model_config = SettingsConfigDict(
379
        secrets_dir='/run/secrets'
380
    )
381

382
settings = AppSettings()  # Loads secrets from files
383
```
384

385
### Custom Source with Multiple Files
386

387
```python
388
from pydantic_settings import JsonConfigSettingsSource, YamlConfigSettingsSource
389

390
class AppSettings(BaseSettings):
391
    app_name: str = "MyApp"
392
    debug: bool = False
393
    
394
    @classmethod
395
    def settings_customise_sources(
396
        cls,
397
        settings_cls,
398
        init_settings,
399
        env_settings,
400
        dotenv_settings,
401
        file_secret_settings,
402
    ):
403
        return (
404
            init_settings,
405
            JsonConfigSettingsSource(settings_cls, json_file='config.json'),
406
            YamlConfigSettingsSource(settings_cls, yaml_file='config.yaml'),
407
            env_settings,
408
            dotenv_settings,
409
            file_secret_settings,
410
        )
411

412
settings = AppSettings()  # Loads from JSON, YAML, env vars, .env, and secrets
413
```