Welcome to Concrete Settings¶
Concrete Settings is a Python library which facilitates configuration management in big and small programs.
The project was born out of necessity to manage a huge
decade-old Django-based SaaS solution with more than two hundred
different application settings scattered around settings.py.
What does this setting do?
What type is it?
Why does it have such a weird format?
Is this the final value, or it changes somewhere on the way?
Sometimes developers spent hours seeking answers to these
questions.
Concrete Settings tackles these problems altogether. It was designed to be developer and end-user friendly. The settings are defined via normal Python code with few tricks which significantly improve readability and maintainability.
Take a look at a small example of Settings class with one
boolean setting DEBUG. A developer defines the
settings in application code, while an end-user
chooses to store the configuration in a YAML file:
# settings.py
from concrete_settings import Settings
class AppSettings(Settings):
#: Turns debug mode on/off
DEBUG: bool = False
app_settings = AppSettings()
app_settings.update('/path/to/user/settings.yml')
app_settings.is_valid(raise_exception=True)
# settings.yml
DEBUG: true
Accessing settings:
>>> print(app_settings.DEBUG)
True
>>> print(AppSettings.DEBUG.__doc__)
Turns debug mode on/off
Settings are defined in classes. Python mechanism
of inheritance and composition apply here, so settings can be mixed (multiple inheritance)
and be nested (settings as class fields).
Settings are type-annotated and are validated.
Documentation matters! Each settings can be documented in Sphinx-style comments #: written
above its definition.
An instance of Settings can be updated i.e. read from any kind of source:
YAML, JSON or Python files, environmental variables, Python dicts, and you can add more!
Finally, Concrete Settings comes with batteries like Django 3.0 support out of the box.
In a nutshell:
This flow perfectly applies to
A web application backend. Think of Django or Flask application and all the settings required to start it up.
A rich feed-execute-output tools like Sphinx documentation.
Concrete Settings are here to improve configuration handling whether you are starting from scratch, or dealing with an old legacy Cthulhu. Are you ready to try it out? Then you are very welcome to Concrete Settings documentation!
Installation¶
Python Version
We recommend using the latest version of Python 3. Concrete Settings supports Python 3.6 and newer.
With pip:
pip install concrete-settings
Dependencies
These distributions will be installed automatically when installing Concrete Settings:
Typeguard provides runtime type checking and allows validating settings values types.
Sphinx allows documenting settings in developer-friendly way - in comments above settings definitions.
Typing Extensions provides typing hints backports to Python 3.6.
Optional dependencies
These distributions will not be installed automatically. Concrete Settings will detect and use them if you install them.
PyYAML allows reading settings from YAML sources.
Source
The source is available at https://github.com/basicwolf/concrete-settings.
Contributions are warmly welcomed!
Documentation¶
API Reference¶
If you are looking for information on a specific function, class or method, this part of the documentation is for you.