Simple Settings

Common errors

• ModuleNotFoundError: No module named 'your_settings_module'

  cause The Python interpreter cannot find the specified settings module. This usually means the module path provided via `--settings` or `SIMPLE_SETTINGS` is incorrect, or the directory containing the settings file is not in Python's `sys.path`.
  fix Verify the settings module path (e.g., `my_project.settings.development`). Ensure the directory containing `my_project` (or the top-level package) is in `PYTHONPATH` or added to `sys.path`.

• TypeError: 'NoneType' object is not iterable (or similar error related to empty config files)

  cause In versions prior to 1.1.0, loading an entirely empty settings file (e.g., an empty YAML or JSON file) could lead to a TypeError. This was fixed in 1.1.0 but could appear in older installations or specific edge cases.
  fix Upgrade to `simple-settings` version 1.1.0 or newer. Ensure configuration files are not entirely empty, or at least contain valid, minimal content if intended to be empty (e.g., `{}` for JSON/YAML).

Warnings

• deprecated The `SIMPLE_SETTINGS` environment variable for specifying the settings module is deprecated. While still functional, it's recommended to use the `--settings` command-line argument for explicit configuration or `LazySettings` for programmatic loading.
  Fix: Prefer using `python your_app.py --settings=your_module_path` or instantiate `LazySettings('your_module_path')`.
• gotcha Special settings, such as `SIMPLE_SETTINGS` for defining `required_settings` or `CONFIGURE_LOGGING`, are only recognized and applied when defined within a Python settings module (e.g., `settings.py`). They are ignored when settings are loaded from INI, YAML, JSON, or TOML files.
  Fix: Ensure all special settings are defined in a Python `.py` settings file.
• gotcha Loading dynamic settings from backends like AWS S3, Memcached, or a database requires installing the respective optional dependencies (e.g., `boto3`, `python-memcached`, `SQLAlchemy`). If these are missing, `ImportError` or similar runtime errors will occur when attempting to use those backends.
  Fix: Install `simple-settings` with the `[all]` extra (`pip install simple-settings[all]`) or install the specific dependency for the backend you intend to use (e.g., `pip install simple-settings[s3]`).

Install

• pip install simple-settings Basic Installation
• pip install simple-settings[all] Installation with all optional dependencies

Imports

• settings
  wrong:

  import simple_settings.settings

  correct:

  from simple_settings import settings

  The `settings` object is a singleton that gets populated when the settings module is identified.
• LazySettings

  from simple_settings import LazySettings

  Use `LazySettings` for explicit control over settings file loading, or when avoiding the global singleton.

Quickstart

This quickstart demonstrates how to define a Python settings file and load it using `LazySettings`. In a typical application, the settings module would be specified via a `--settings` command-line argument (e.g., `python your_app.py --settings=my_project_settings.development`) or the `SIMPLE_SETTINGS` environment variable, after which the global `simple_settings.settings` object becomes populated. Using `LazySettings` allows for explicit, programmatic control over which settings module to load.

import os
import sys
from simple_settings import settings

# --- Create a dummy settings file for demonstration ---
settings_content = """
FOO = 'bar'
BAZ = 123
SIMPLE_SETTINGS = {'required_settings': ['FOO']}
"""

settings_dir = 'my_project_settings'
os.makedirs(settings_dir, exist_ok=True)
with open(os.path.join(settings_dir, 'development.py'), 'w') as f:
    f.write(settings_content)

# Add the settings directory to Python's path so it can be imported
sys.path.insert(0, os.getcwd())

# Method 1: Set environment variable (deprecated but common in older setups)
# os.environ['SIMPLE_SETTINGS'] = 'my_project_settings.development'

# Method 2: Command line argument (preferred for non-programmatic loading)
# For programmatic loading, you'd typically use LazySettings or a custom loader
# For this quickstart, we'll demonstrate direct access after 'setting' the module path implicitly.
# In a real app, you would run like: python your_script.py --settings=my_project_settings.development

# As a workaround for a runnable quickstart, we'll manually set the internal _SETTINGS_MODULE
# This is NOT how you'd normally configure it in production for the 'settings' singleton
# Normally, the --settings CLI arg or SIMPLE_SETTINGS env var would handle this.
# Using LazySettings is the programmatic alternative.

# For this demonstration, we'll mimic the effect of `settings.configure()`
# if the env var or CLI was set.
# In a real application, you'd run `python your_app.py --settings=my_project_settings.development`
# and then `from simple_settings import settings` would automatically pick it up.
# To make this runnable without CLI args or env vars, we use LazySettings.

try:
    # Using LazySettings for a self-contained programmatic example
    app_settings = LazySettings('my_project_settings.development')
    print(f"FOO setting: {app_settings.FOO}")
    print(f"BAZ setting: {app_settings.BAZ}")

    # Demonstrate a missing required setting (this would raise an error)
    # with open(os.path.join(settings_dir, 'broken_settings.py'), 'w') as f:
    #     f.write("BAZ = 456")
    # broken_app_settings = LazySettings('my_project_settings.broken_settings')
    # print(f"Broken FOO: {broken_app_settings.FOO}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up dummy settings file and directory
    os.remove(os.path.join(settings_dir, 'development.py'))
    # if os.path.exists(os.path.join(settings_dir, 'broken_settings.py')):
    #     os.remove(os.path.join(settings_dir, 'broken_settings.py'))
    os.rmdir(settings_dir)
    sys.path.pop(0)