Registry / devops / simple-settings

simple-settings

JSON →
library1.2.0pypypi✓ verified 85d ago

Simple Settings is a Python library designed to provide a flexible and straightforward way to manage project configurations, inspired by Django's settings system. It allows loading settings from various file formats (Python modules, CFG, YAML, JSON, TOML) and supports dynamic settings backends like AWS S3, Memcached, and SQL databases. The current version is 1.2.0, and it maintains an active, though irregular, release cadence.

pip install simple-settings
INSTALL
IMPORT
SIG · SIMPLE-SETTINGS
S
simple-settings
devopspythonv1.2.0
Install
4.2s avg
Import
120ms
Disk
72MB
Pass rate
3/ 10
Env Coverage3 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
4/8 runs
✓ 3.76s
py 3.11
4/8 runs
✓ 4.46s
py 3.12
4/8 runs
4/8 runs
py 3.13
4/8 runs
4/8 runs
py 3.9
4/8 runs
✓ 4.39s
72MB installed
● package 72MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

settings
from simple_settings import settings
import simple_settings.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.

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)
simple_settings --version
Debug
Known issues
deprecatedThe `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')`.
affects: <=1.2.0
gotchaSpecial 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.
affects: All versions
gotchaLoading 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]`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'your_settings_module'
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)
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).
Upgrade
Version history
1.2.0latest on PyPI · released Dec 30, 2021
Audit
Dependencies
PyYAMLoptionalRequired for loading settings from YAML files.
tomloptionalRequired for loading settings from TOML files.
boto3optionalRequired for using AWS S3 as a dynamic settings backend.
python-memcachedoptionalRequired for using Memcached as a dynamic settings backend.
SQLAlchemyoptionalRequired for using a database (via SQLAlchemy) as a dynamic settings backend.
Agent activity
39 hits · last 30 days
node
36
OpenAI (training)
1
Resources
simple-settings — pip install simple-settings · libregistry