Welcome to easy_config’s documentation!¶
Parse configuration values from files, the environment, and elsewhere all in one place.
On this page:
Installation¶
Installation should be as easy as executing this command in your chosen terminal:
$ pip install easy_config
The source code for this project is hosted on Github. Downloading and installing from source goes like this:
$ git clone https://github.com/scolby33/easy_config
$ cd easy_config
$ pip install .
If you intend to install in a virtual environment, activate it before running
pip install
.
easy_config
officially supports Python 3.6 and later.
Example Usage¶
Here is a full working example of using easy_config. First, write your configuration class:
# config.py
from easy_config import EasyConfig
class MyProgramConfig(EasyConfig):
FILES = ['myprogram.ini']
NAME = 'MyProgram' # the name for the .ini file section and the namespace prefix for environment variables
# define the options like you would a dataclass
number: int
name: str
check_bounds: bool = True # options with defaults must all come after non-default options
A sample configuration file:
# myprogram.ini
[MyProgram]
# section name matches `NAME` from the configuration class
number = 3
And a sample program to illustrate the usage:
# test_config.py
import sys
from config import MyProgramConfig
print(MyProgramConfig.load(name=sys.argv[1])
Running this program with various options:
$ python test_config.py Scott
MyProgramConfig(number=3, name='Scott', check_bounds=True)
$ env MYPROGRAM_CHECK_BOUNDS=False python test_config.py Scott
# environment variable names are the all-uppercase transformation of the NAME concatenated with the option name and an underscore
MyProgramConfig(number=3, name='Scott', check_bounds=False)
$ env MYPROGRAM_NUMBER=10 MYPROGRAM_NAME=Charlie python test_config.py Scott
MyProgramConfig(number=10, name='Scott', check_bounds=True)
As you can see, values are taken in precedence, with arguments passed to load
overriding values from the environment which, in turn, override values from
configuration files.
Once you have the MyProgramConfig
instance, you can use it just like any dataclass.
Click Integration¶
easy_config
ships with a contrib module integrating with the Click command line interface package.
License¶
easy_config
is licensed under the MIT License, a permissive open-source license.
The full text of the license is available here and in the root of the source code repository.
Changelog¶
easy_config
adheres to the Semantic Versioning (“Semver”) 2.0.0 versioning standard.
Details about this versioning scheme can be found on the Semver website.
Versions postfixed with ‘-dev’ are currently under development and those without a
postfix are stable releases.
You are reading the documents for version 1.0.0 of easy_config
.
Full changelogs can be found on the Changelog page.