0
# Dynaconf
1

2
A comprehensive Python configuration management system that enables developers to handle settings through multiple file formats (TOML, YAML, JSON, INI, PY), environment variables, and external services. It offers layered configuration support for different environments, built-in protection for sensitive information, and seamless integration with popular web frameworks like Django and Flask.
3

4
## Package Information
5

6
- **Package Name**: dynaconf
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install dynaconf`
10

11
## Core Imports
12

13
```python
14
from dynaconf import Dynaconf
15
```
16

17
Alternative imports for specific functionality:
18

19
```python
20
from dynaconf import Dynaconf, Validator, ValidationError
21
from dynaconf import FlaskDynaconf, DjangoDynaconf
22
from dynaconf import add_converter, inspect_settings, get_history
23
```
24

25
## Basic Usage
26

27
```python
28
from dynaconf import Dynaconf
29

30
# Create settings instance with multiple sources
31
settings = Dynaconf(
32
    envvar_prefix="MYAPP",                    # Environment variable prefix
33
    settings_files=["settings.toml", "*.yaml"],  # Configuration files
34
    environments=True,                        # Enable environment layers
35
    load_dotenv=True,                        # Load .env files
36
)
37

38
# Access configuration values
39
database_url = settings.DATABASE_URL
40
debug_mode = settings.get("DEBUG", default=False, cast=bool)
41
port = settings.as_int("PORT", 8000)
42

43
# Set values programmatically
44
settings.set("CACHE_TTL", 3600)
45
settings.update({"API_VERSION": "v2", "TIMEOUT": 30})
46

47
# Use environment switching
48
with settings.using_env("production"):
49
    prod_db = settings.DATABASE_URL  # Different value for production
50
```
51

52
## Architecture
53

54
Dynaconf's layered architecture provides flexible configuration management:
55

56
- **LazySettings**: Defers loading until first access, enabling dynamic reconfiguration
57
- **Settings**: Core functionality with 100+ methods for configuration management
58
- **Multi-source Loading**: Supports files, environment variables, and external services
59
- **Environment Layering**: Automatic switching between development, testing, production
60
- **Validation System**: Comprehensive validation with type checking and custom rules
61
- **Framework Integration**: Native support for Flask and Django applications
62

63
## Capabilities
64

65
### Core Configuration Management
66

67
Fundamental configuration functionality including settings creation, value access, type casting, environment management, and multi-source data loading.
68

69
```python { .api }
70
class Dynaconf:
71
    def __init__(
72
        self,
73
        settings_files=None,
74
        environments=False,
75
        envvar_prefix=None,
76
        load_dotenv=False,
77
        **kwargs
78
    ): ...
79

80
def get(self, key, default=None, cast=None, fresh=False): ...
81
def get_fresh(self, key, default=None, cast=None): ...
82
def get_environ(self, key, default=None, cast=None): ...
83
def set(self, key, value, loader_identifier=None, merge=False): ...
84
def update(self, data=None, **kwargs): ...
85
def exists(self, key, fresh=False): ...
86
def as_bool(self, key): ...
87
def as_int(self, key): ...
88
def as_float(self, key): ...
89
def as_json(self, key): ...
90
def setenv(self, env=None, clean=True, silent=True): ...
91
def using_env(self, env, clean=True, silent=True): ...  # Context manager
92
def reload(self, env=None, silent=None): ...
93
def as_dict(self, env=None, internal=False): ...
94
```
95

96
[Core Configuration](./core-configuration.md)
97

98
### Validation System
99

100
Comprehensive validation framework with required field checking, type validation, range constraints, custom conditions, and combinatorial validators for ensuring configuration integrity.
101

102
```python { .api }
103
class Validator:
104
    def __init__(
105
        self,
106
        *names,
107
        must_exist=False,
108
        condition=None,
109
        when=None,
110
        cast=None,
111
        default=None,
112
        **operations
113
    ): ...
114

115
def validate(self, settings, only=None, exclude=None): ...
116
def __or__(self, other): ...  # OR operation
117
def __and__(self, other): ... # AND operation
118
```
119

120
[Validation System](./validation.md)
121

122
### Framework Integration
123

124
Native integration with Flask and Django frameworks providing seamless configuration management for web applications with automatic settings binding and framework-specific optimizations.
125

126
```python { .api }
127
class FlaskDynaconf:
128
    def __init__(
129
        self,
130
        app=None,
131
        instance_relative_config=False,
132
        dynaconf_instance=None,
133
        **kwargs
134
    ): ...
135

136
def DjangoDynaconf(settings_module): ...
137
```
138

139
[Framework Integration](./framework-integration.md)
140

141
### Utility Functions
142

143
Configuration inspection, debugging, and extension capabilities including custom type converters, settings history tracking, and hook system for extending functionality.
144

145
```python { .api }
146
def add_converter(converter_key: str, func: callable): ...
147
def inspect_settings(
148
    settings,
149
    key=None,
150
    env=None,
151
    to_file=None,
152
    dumper="yaml"
153
): ...
154
def get_history(obj, key=None, include_internal=False): ...
155
def post_hook(func): ...  # Decorator
156
```
157

158
[Utilities](./utilities.md)
159

160
### Error Handling
161

162
Exception classes and error handling patterns for configuration parsing, validation failures, and format errors with detailed error reporting and debugging information.
163

164
```python { .api }
165
class ValidationError(Exception):
166
    def __init__(self, message, details=None): ...
167

168
class DynaconfFormatError(Exception): ...
169
class DynaconfParseError(Exception): ...
170
```
171

172
[Error Handling](./error-handling.md)
173

174
### Command Line Interface
175

176
Comprehensive CLI for project initialization, configuration management, validation, and debugging with support for multiple file formats and environments.
177

178
```python { .api }
179
# CLI Commands (accessed via 'dynaconf' command)
180
# dynaconf init [options]          - Initialize new project
181
# dynaconf get <key> [options]     - Get configuration value  
182
# dynaconf list [options]          - List all settings
183
# dynaconf write <to> [options]    - Export settings
184
# dynaconf validate [options]      - Run validation
185
# dynaconf inspect [options]       - Inspect loading history
186
```
187

188
[Command Line Interface](./cli.md)
189

190
## Advanced Features
191

192
- **Lazy Loading**: Deferred configuration loading with lazy evaluation
193
- **Template Support**: Jinja2 and string formatting in configuration values
194
- **Multi-Environment**: Automatic environment detection and switching
195
- **External Services**: Redis and HashiCorp Vault integration
196
- **Type Casting**: Built-in converters with custom extension support
197
- **Configuration Merging**: Sophisticated merging strategies for complex configurations