dj_settings: Project Settings the UNIX Way

dj_settings provides a robust, UNIX-inspired approach to managing application configuration. It reads settings from multiple locations with a clear priority order, supporting environment variables, .d directory overrides, and multiple configuration formats.

Originally designed for Django projects, it has evolved into a versatile configuration management solution suitable for any Python application.

Key Features

• UNIX-style configuration hierarchy: Read from /etc/, ~/.config/, project directory, and environment variables
• .d directory overrides: Override configuration files with drop-in directories (e.g., config.yml.d/*.yml)
• Multiple format support: YAML, TOML, JSON, INI, and environment files
• Type-safe settings classes: Create typed configuration objects with decorators
• Environment variable integration: Seamlessly blend file-based and environment-based configuration
• Array merging: Optionally merge arrays instead of overwriting them

Quick Start

from dj_settings import ConfigParser

parser = ConfigParser("/path/to/project/config.yml")

# Get a setting with the full fallback chain
database_url = parser.get_setting(
    "url",
    sections=["database"],
    default="sqlite:///db.sqlite3",
)

Or use type-safe settings classes:

from dj_settings import config_value, settings_class


@settings_class("/path/to/project/config.yml", merge_arrays=True)
class Settings:
    debug: bool = config_value("DEBUG", default=False)
    database_url: str = config_value("url", sections=["database"])
    allowed_hosts: list[str] = config_value(
        "allowed_hosts", sections=["server"], default=["localhost"]
    )


settings = Settings()
print(settings.debug)  # Type-safe access

Documentation

• Installation Guide - How to install dj_settings
• Usage Guide - Comprehensive usage documentation
  • Config Parsers - Using ConfigParser and get_setting
  • Settings Classes - Type-safe settings with decorators
• Changelog - Version history and changes
• License - BSD-3-Clause license
• Code of Conduct - Community guidelines

Why dj_settings?

Managing configuration across different environments (development, staging, production) is challenging. dj_settings solves this by:

1. Following UNIX conventions: Uses the well-understood pattern of system-wide (/etc/), user-specific (~/.config/), and project-local configuration
2. Supporting overrides: The .d directory pattern allows incremental configuration without modifying base files
3. Being format-agnostic: Works with YAML, TOML, JSON, INI, and environment variables
4. Providing type safety: Modern Python type hints and dataclasses for better IDE support and error detection