0
# Framework Integration
1

2
Specialized parsers for Django framework integration including database URLs, email configuration, and cache settings with automatic dependency management and comprehensive configuration support.
3

4
## Capabilities
5

6
### Django Database URL Parsing
7

8
Parse Django-compatible database URLs into configuration dictionaries using the dj-database-url library.
9

10
```python { .api }
11
def dj_db_url(self, name: str, default=..., **kwargs):
12
    """
13
    Parse environment variable as Django database URL.
14
    
15
    Parameters:
16
    - name: str, environment variable name
17
    - default: any, default value if variable not set (optional)
18
    - **kwargs: additional arguments passed to dj_database_url.parse()
19
    
20
    Returns:
21
    dj_database_url.DBConfig: Database configuration object
22
    
23
    Raises:
24
    RuntimeError: If dj-database-url package is not installed
25
    EnvValidationError: If URL is not a valid database URL
26
    
27
    Dependencies:
28
    Requires 'dj-database-url' package: pip install dj-database-url
29
    """
30
```
31

32
Usage examples:
33

34
```python
35
import os
36
from environs import env
37

38
# PostgreSQL database URL
39
os.environ["DATABASE_URL"] = "postgres://user:password@localhost:5432/mydb"
40
db_config = env.dj_db_url("DATABASE_URL")
41

42
print(f"Engine: {db_config['ENGINE']}")     # => 'django.db.backends.postgresql'
43
print(f"Name: {db_config['NAME']}")         # => 'mydb'
44
print(f"User: {db_config['USER']}")         # => 'user'
45
print(f"Password: {db_config['PASSWORD']}")  # => 'password'
46
print(f"Host: {db_config['HOST']}")         # => 'localhost'
47
print(f"Port: {db_config['PORT']}")         # => 5432
48

49
# MySQL database URL
50
os.environ["MYSQL_URL"] = "mysql://root:secret@db.example.com:3306/production"
51
mysql_config = env.dj_db_url("MYSQL_URL")
52

53
# SQLite database URL
54
os.environ["SQLITE_URL"] = "sqlite:///path/to/database.db"
55
sqlite_config = env.dj_db_url("SQLITE_URL")
56

57
# Database URL with additional options
58
os.environ["DB_URL"] = "postgres://user:pass@host:5432/db?conn_max_age=600&autocommit=true"
59
db_config = env.dj_db_url("DB_URL")
60
print(f"Options: {db_config.get('OPTIONS', {})}")
61

62
# Use in Django settings.py
63
DATABASES = {
64
    'default': env.dj_db_url("DATABASE_URL")
65
}
66

67
# With default value
68
default_db = env.dj_db_url("DATABASE_URL", "sqlite:///default.db")
69

70
# Multiple databases
71
os.environ["PRIMARY_DB"] = "postgres://user:pass@primary:5432/main"
72
os.environ["ANALYTICS_DB"] = "postgres://user:pass@analytics:5432/analytics"
73

74
DATABASES = {
75
    'default': env.dj_db_url("PRIMARY_DB"),
76
    'analytics': env.dj_db_url("ANALYTICS_DB")
77
}
78
```
79

80
### Django Email URL Parsing
81

82
Parse Django-compatible email URLs into email backend configurations using the dj-email-url library.
83

84
```python { .api }
85
def dj_email_url(self, name: str, default=..., **kwargs):
86
    """
87
    Parse environment variable as Django email URL.
88
    
89
    Parameters:
90
    - name: str, environment variable name
91
    - default: any, default value if variable not set (optional)
92
    - **kwargs: additional arguments passed to dj_email_url.parse()
93
    
94
    Returns:
95
    dict: Email backend configuration dictionary
96
    
97
    Raises:
98
    RuntimeError: If dj-email-url package is not installed
99
    EnvValidationError: If URL is not a valid email URL
100
    
101
    Dependencies:
102
    Requires 'dj-email-url' package: pip install dj-email-url
103
    """
104
```
105

106
Usage examples:
107

108
```python
109
import os
110
from environs import env
111

112
# SMTP email configuration
113
os.environ["EMAIL_URL"] = "smtp://user:password@smtp.gmail.com:587?tls=true"
114
email_config = env.dj_email_url("EMAIL_URL")
115

116
print(f"Backend: {email_config['EMAIL_BACKEND']}")       # Email backend class
117
print(f"Host: {email_config['EMAIL_HOST']}")             # => 'smtp.gmail.com'
118
print(f"Port: {email_config['EMAIL_PORT']}")             # => 587
119
print(f"User: {email_config['EMAIL_HOST_USER']}")        # => 'user'
120
print(f"Password: {email_config['EMAIL_HOST_PASSWORD']}")# => 'password'
121
print(f"Use TLS: {email_config['EMAIL_USE_TLS']}")       # => True
122

123
# Console backend for development
124
os.environ["DEV_EMAIL_URL"] = "console:"
125
dev_email_config = env.dj_email_url("DEV_EMAIL_URL")
126

127
# File backend
128
os.environ["FILE_EMAIL_URL"] = "file:///tmp/emails"
129
file_email_config = env.dj_email_url("FILE_EMAIL_URL")
130

131
# SendGrid configuration
132
os.environ["SENDGRID_URL"] = "smtp://apikey:SG.xyz123@smtp.sendgrid.net:587?tls=true"
133
sendgrid_config = env.dj_email_url("SENDGRID_URL")
134

135
# Mailgun configuration
136
os.environ["MAILGUN_URL"] = "smtp://postmaster@mg.example.com:key123@smtp.mailgun.org:587?tls=true"
137
mailgun_config = env.dj_email_url("MAILGUN_URL")
138

139
# Use in Django settings.py
140
email_config = env.dj_email_url("EMAIL_URL", "console:")
141

142
EMAIL_BACKEND = email_config['EMAIL_BACKEND']
143
EMAIL_HOST = email_config.get('EMAIL_HOST', '')
144
EMAIL_PORT = email_config.get('EMAIL_PORT', 25)
145
EMAIL_HOST_USER = email_config.get('EMAIL_HOST_USER', '')
146
EMAIL_HOST_PASSWORD = email_config.get('EMAIL_HOST_PASSWORD', '')
147
EMAIL_USE_TLS = email_config.get('EMAIL_USE_TLS', False)
148
EMAIL_USE_SSL = email_config.get('EMAIL_USE_SSL', False)
149

150
# Simplified Django settings integration
151
locals().update(env.dj_email_url("EMAIL_URL", "console:"))
152
```
153

154
### Django Cache URL Parsing
155

156
Parse Django-compatible cache URLs into cache backend configurations using the django-cache-url library.
157

158
```python { .api }
159
def dj_cache_url(self, name: str, default=..., **kwargs):
160
    """
161
    Parse environment variable as Django cache URL.
162
    
163
    Parameters:
164
    - name: str, environment variable name
165
    - default: any, default value if variable not set (optional)
166
    - **kwargs: additional arguments passed to django_cache_url.parse()
167
    
168
    Returns:
169
    dict: Cache backend configuration dictionary
170
    
171
    Raises:
172
    RuntimeError: If django-cache-url package is not installed
173
    EnvValidationError: If URL is not a valid cache URL or backend is unknown
174
    
175
    Dependencies:
176
    Requires 'django-cache-url' package: pip install django-cache-url
177
    """
178
```
179

180
Usage examples:
181

182
```python
183
import os
184
from environs import env
185

186
# Redis cache configuration
187
os.environ["CACHE_URL"] = "redis://localhost:6379/1?client_class=django_redis.client.DefaultClient"
188
cache_config = env.dj_cache_url("CACHE_URL")
189

190
print(f"Backend: {cache_config['BACKEND']}")           # Redis backend class
191
print(f"Location: {cache_config['LOCATION']}")         # => 'redis://localhost:6379/1'
192
print(f"Options: {cache_config.get('OPTIONS', {})}")   # Client options
193

194
# Memcached configuration
195
os.environ["MEMCACHE_URL"] = "memcache://127.0.0.1:11211"
196
memcache_config = env.dj_cache_url("MEMCACHE_URL")
197

198
# Database cache backend
199
os.environ["DB_CACHE_URL"] = "db://cache_table"
200
db_cache_config = env.dj_cache_url("DB_CACHE_URL")
201

202
# File-based cache
203
os.environ["FILE_CACHE_URL"] = "file:///tmp/django_cache"
204
file_cache_config = env.dj_cache_url("FILE_CACHE_URL")
205

206
# Dummy cache for development
207
os.environ["DUMMY_CACHE_URL"] = "dummy:"
208
dummy_cache_config = env.dj_cache_url("DUMMY_CACHE_URL")
209

210
# Local memory cache
211
os.environ["LOCMEM_CACHE_URL"] = "locmem:unique-snowflake"
212
locmem_config = env.dj_cache_url("LOCMEM_CACHE_URL")
213

214
# Redis with additional options
215
os.environ["REDIS_CACHE_URL"] = "redis://redis.example.com:6379/0?client_class=django_redis.client.DefaultClient&connection_pool_kwargs={'max_connections':50}"
216
redis_config = env.dj_cache_url("REDIS_CACHE_URL")
217

218
# Use in Django settings.py
219
CACHES = {
220
    'default': env.dj_cache_url("CACHE_URL", "locmem:")
221
}
222

223
# Multiple cache configurations
224
os.environ["DEFAULT_CACHE"] = "redis://localhost:6379/0"
225
os.environ["SESSION_CACHE"] = "redis://localhost:6379/1"
226
os.environ["TEMPLATE_CACHE"] = "memcache://localhost:11211"
227

228
CACHES = {
229
    'default': env.dj_cache_url("DEFAULT_CACHE"),
230
    'sessions': env.dj_cache_url("SESSION_CACHE"),
231
    'templates': env.dj_cache_url("TEMPLATE_CACHE", "dummy:")
232
}
233

234
# Cache with timeout and versioning
235
os.environ["CACHE_WITH_OPTIONS"] = "redis://localhost:6379/0?timeout=300&version=2"
236
cache_with_options = env.dj_cache_url("CACHE_WITH_OPTIONS")
237
```
238

239
## Complete Django Settings Example
240

241
Here's how to use all Django integration parsers together in a typical Django settings.py file:
242

243
```python
244
# settings.py
245
import os
246
from environs import env
247

248
# Initialize environs
249
env.read_env()  # Load .env file
250

251
# Database configuration
252
DATABASES = {
253
    'default': env.dj_db_url("DATABASE_URL", "sqlite:///db.sqlite3")
254
}
255

256
# Cache configuration  
257
CACHES = {
258
    'default': env.dj_cache_url("CACHE_URL", "locmem:")
259
}
260

261
# Email configuration
262
email_config = env.dj_email_url("EMAIL_URL", "console:")
263
EMAIL_BACKEND = email_config['EMAIL_BACKEND']
264
EMAIL_HOST = email_config.get('EMAIL_HOST', '')
265
EMAIL_PORT = email_config.get('EMAIL_PORT', 25)
266
EMAIL_HOST_USER = email_config.get('EMAIL_HOST_USER', '')
267
EMAIL_HOST_PASSWORD = email_config.get('EMAIL_HOST_PASSWORD', '')
268
EMAIL_USE_TLS = email_config.get('EMAIL_USE_TLS', False)
269
EMAIL_USE_SSL = email_config.get('EMAIL_USE_SSL', False)
270

271
# Other environment-based settings
272
DEBUG = env.bool("DEBUG", False)
273
SECRET_KEY = env.str("SECRET_KEY")
274
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", ["localhost", "127.0.0.1"])
275

276
# Static and media files
277
STATIC_URL = env.str("STATIC_URL", "/static/")
278
STATIC_ROOT = env.path("STATIC_ROOT", None)
279
MEDIA_URL = env.str("MEDIA_URL", "/media/")
280
MEDIA_ROOT = env.path("MEDIA_ROOT", None)
281

282
# Logging
283
LOGGING = {
284
    'version': 1,
285
    'disable_existing_loggers': False,
286
    'handlers': {
287
        'console': {
288
            'class': 'logging.StreamHandler',
289
            'level': env.log_level("LOG_LEVEL", "INFO"),
290
        },
291
    },
292
    'root': {
293
        'handlers': ['console'],
294
        'level': env.log_level("ROOT_LOG_LEVEL", "INFO"),
295
    },
296
}
297
```
298

299
## Environment File Example
300

301
Corresponding .env file for the Django settings:
302

303
```bash
304
# .env file
305
DEBUG=true
306
SECRET_KEY=your-secret-key-here
307
ALLOWED_HOSTS=localhost,127.0.0.1,yoursite.com
308

309
# Database
310
DATABASE_URL=postgres://user:password@localhost:5432/myproject
311

312
# Cache
313
CACHE_URL=redis://localhost:6379/0
314

315
# Email
316
EMAIL_URL=smtp://username:password@smtp.gmail.com:587?tls=true
317

318
# Logging
319
LOG_LEVEL=DEBUG
320
ROOT_LOG_LEVEL=INFO
321

322
# Static files
323
STATIC_URL=/static/
324
STATIC_ROOT=/var/www/static/
325
MEDIA_URL=/media/
326
MEDIA_ROOT=/var/www/media/
327
```
328

329
## Error Handling
330

331
Handle missing dependencies and invalid configurations appropriately:
332

333
```python
334
from environs import env, EnvValidationError
335
import os
336

337
# Handle missing dj-database-url
338
try:
339
    db_config = env.dj_db_url("DATABASE_URL")
340
except RuntimeError as e:
341
    print(f"Missing dependency: {e}")
342
    # Fallback to manual configuration or default
343
    db_config = {
344
        'ENGINE': 'django.db.backends.sqlite3',
345
        'NAME': 'db.sqlite3'
346
    }
347

348
# Handle invalid URLs
349
os.environ["INVALID_DB_URL"] = "not-a-valid-url"
350
try:
351
    db_config = env.dj_db_url("INVALID_DB_URL")
352
except EnvValidationError as e:
353
    print(f"Invalid database URL: {e}")
354
    # Use default configuration
355
    db_config = env.dj_db_url("DATABASE_URL", "sqlite:///default.db")
356
```
357

358
## Types
359

360
```python { .api }
361
from typing import Dict, Any, Optional
362

363
try:
364
    from dj_database_url import DBConfig
365
except ImportError:
366
    DBConfig = Dict[str, Any]
367

368
EmailConfig = Dict[str, Any]
369
CacheConfig = Dict[str, Any]
370
```