or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcore-configuration.mderror-handling.mdframework-integration.mdindex.mdutilities.mdvalidation.md
tile.json

tessl/pypi-dynaconf

The dynamic configurator for your Python Project

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/dynaconf@3.2.x

To install, run

npx @tessl/cli install tessl/pypi-dynaconf@3.2.0

index.mddocs/

Dynaconf

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.

Package Information

  • Package Name: dynaconf
  • Package Type: pypi
  • Language: Python
  • Installation: pip install dynaconf

Core Imports

from dynaconf import Dynaconf

Alternative imports for specific functionality:

from dynaconf import Dynaconf, Validator, ValidationError
from dynaconf import FlaskDynaconf, DjangoDynaconf
from dynaconf import add_converter, inspect_settings, get_history

Basic Usage

from dynaconf import Dynaconf

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

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

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

# Use environment switching
with settings.using_env("production"):
    prod_db = settings.DATABASE_URL  # Different value for production

Architecture

Dynaconf's layered architecture provides flexible configuration management:

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

Capabilities

Core Configuration Management

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

class Dynaconf:
    def __init__(
        self,
        settings_files=None,
        environments=False,
        envvar_prefix=None,
        load_dotenv=False,
        **kwargs
    ): ...

def get(self, key, default=None, cast=None, fresh=False): ...
def get_fresh(self, key, default=None, cast=None): ...
def get_environ(self, key, default=None, cast=None): ...
def set(self, key, value, loader_identifier=None, merge=False): ...
def update(self, data=None, **kwargs): ...
def exists(self, key, fresh=False): ...
def as_bool(self, key): ...
def as_int(self, key): ...
def as_float(self, key): ...
def as_json(self, key): ...
def setenv(self, env=None, clean=True, silent=True): ...
def using_env(self, env, clean=True, silent=True): ...  # Context manager
def reload(self, env=None, silent=None): ...
def as_dict(self, env=None, internal=False): ...

Core Configuration

Validation System

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

class Validator:
    def __init__(
        self,
        *names,
        must_exist=False,
        condition=None,
        when=None,
        cast=None,
        default=None,
        **operations
    ): ...

def validate(self, settings, only=None, exclude=None): ...
def __or__(self, other): ...  # OR operation
def __and__(self, other): ... # AND operation

Validation System

Framework Integration

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

class FlaskDynaconf:
    def __init__(
        self,
        app=None,
        instance_relative_config=False,
        dynaconf_instance=None,
        **kwargs
    ): ...

def DjangoDynaconf(settings_module): ...

Framework Integration

Utility Functions

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

def add_converter(converter_key: str, func: callable): ...
def inspect_settings(
    settings,
    key=None,
    env=None,
    to_file=None,
    dumper="yaml"
): ...
def get_history(obj, key=None, include_internal=False): ...
def post_hook(func): ...  # Decorator

Utilities

Error Handling

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

class ValidationError(Exception):
    def __init__(self, message, details=None): ...

class DynaconfFormatError(Exception): ...
class DynaconfParseError(Exception): ...

Error Handling

Command Line Interface

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

# CLI Commands (accessed via 'dynaconf' command)
# dynaconf init [options]          - Initialize new project
# dynaconf get <key> [options]     - Get configuration value  
# dynaconf list [options]          - List all settings
# dynaconf write <to> [options]    - Export settings
# dynaconf validate [options]      - Run validation
# dynaconf inspect [options]       - Inspect loading history

Command Line Interface

Advanced Features

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