dynaconf

When using pytest, it is recommended to use the FORCE_ENV_FOR_DYNACONF environment variable (or configuration option) instead of ENV_FOR_DYNACONF because it has higher precedence. This ensures your test environment settings are strictly applied.

You can use a pytest fixture with autouse=True to force the global settings object into the testing environment for the entire session.

import pytest
from dynaconf import settings

@pytest.fixture(scope="session", autouse=True)
def set_test_settings():
    settings.configure(FORCE_ENV_FOR_DYNACONF="testing")

Dynaconf prioritizes environment variables. By default, it looks for variables prefixed with DYNACONF_. You can customize this prefix using the envvar_prefix argument in the Dynaconf constructor.

Key features:

• Automatic Type Casting: Variables like DYNACONF_NUMBER=123 are automatically cast to int. Booleans (e.g., true) and lists (e.g., "['a', 'b']") are also supported.
• Nested Settings: Use double underscores (__) to denote nesting. For example, DYNACONF_NESTED__LEVEL__KEY=1 creates {'nested': {'level': {'key': 1}}}.
• Framework Prefixes: If using extensions, DJANGO_ and FLASK_ prefixes are automatically recognized.
• Custom Prefixes: If you initialize with Dynaconf(envvar_prefix="custom"), use CUSTOM_NAME=value.

The @insert token allows you to insert a value at a specific index in a list.

Syntax: KEY = '@insert [index] value'

Details:

• If the index is omitted, the value is inserted at index 0.
• Supports signed indexes (e.g., -1 to insert at the end of the list).
• For inserting dictionaries into a list of dictionaries, use TOML format or the @json token.

The Django Extension gives Dynaconf full control over django.conf.settings. By using DjangoDynaconf, every time you import django.conf.settings anywhere in your project, you are interacting with a Dynaconf instance. This grants you access to all advanced Dynaconf features.

Setup: Append the DjangoDynaconf initialization to the very bottom of your settings.py file.

# ... standard Django settings (DEBUG, etc.) ...

# AT THE VERY BOTTOM of settings.py
import dynaconf

validators = [
    dynaconf.Validator("INSTALLED_APPS", cont="mynew.app"),
    dynaconf.Validator("DEBUG", ne=True, env="production"),
]

settings = dynaconf.DjangoDynaconf(
    __name__,
    settings_files=["/etc/myapp/settings.toml"],
    validators=validators,
)

To use layered environments (e.g., [default], [development], [production]), you must set environments=True when instantiating Dynaconf.

Without this flag, Dynaconf treats sections as normal first-level keys.

To switch between environments, set the ENV_FOR_DYNACONF environment variable. For Flask/Django extensions, use FLASK_ENV or DJANGO_ENV respectively. You can also pass env="environment_name" directly to the Dynaconf constructor.

# config.py
settings = Dynaconf(environments=True)

# settings.toml
[default]
name = ""
[development]
name = "developer"
[production]
name = "admin"

# Switch to development
export ENV_FOR_DYNACONF=development
# settings.name will be "developer"

When you pass a list of validators to the Dynaconf constructor, they are not run immediately. They are triggered lazily when you first attempt to access a setting, call settings.validators, or call settings.as_dict(). Only the first ValidationError encountered will be raised.

from dynaconf import Dynaconf, Validator

settings = Dynaconf(
    settings_file=["settings.toml"],
    environments=True,
    validators=[
        Validator("AGE", lte=30, gte=10),
        Validator("NAME", eq="John"),
    ],
)

# Accessing settings triggers validation
print(settings.age)

Dynaconf provides a drop-in replacement for Flask's app.config. You can initialize the FlaskDynaconf extension by passing your Flask app instance to it. This turns app.config into a dynaconf instance.

from flask import Flask
from dynaconf import FlaskDynaconf

app = Flask(__name__)
FlaskDynaconf(app)

Place settings.toml and .secrets.toml in your project root (where you run flask run). Define environments using TOML sections like [default], [development], and [production].

Use the FLASK_ENV environment variable to switch between environments:

• FLASK_ENV=development
• FLASK_ENV=production

Note: If using the dynaconf CLI, the FLASK_APP environment variable must be defined.

When running dynaconf init, you can specify the file format, the project path, and pre-populate settings and secrets.

Options:

• -f, --format [ini|toml|yaml|json|py|env]: Set the file format.
• -p, --path TEXT: Specify the project root directory (defaults to current directory).
• -v, --vars TEXT: Key-value pairs to write to settings.toml (e.g., NAME=foo).
• -s, --secrets TEXT: Key-value pairs to write to .secrets.toml (e.g., TOKEN=1234).
• --django TEXT: Django-specific initialization.