Implementation of key-value pair based configuration for Python applications.
Project description
Python configuration utilities
Implementation of key-value pair based configuration for Python applications.
Features:
- support for most common sources of application settings
- support for overriding settings in sequence
- support for nested structures and lists, using attribute notation
- strategy to use environment specific settings
This library is freely inspired by .NET Core Microsoft.Extensions.Configuration
namespace and its pleasant design (ref. MSDN documentation, Microsoft Extensions Configuration Deep Dive).
The main class is influenced by Luciano Ramalho`s example of JSON structure explorer using attribute notation, in his book Fluent Python.
Supported sources:
- yaml files
- json files
- ini files
- environmental variables
- dictionaries
- keys and values
Installation
pip install essentials-configuration
Alternatively, to install it with support for YAML
configuration files:
pip install essentials-configuration[yaml]
Examples
JSON file and environmental variables
In this example, configuration values will include the structure inside the
file settings.json
and environmental variables whose name starts with "APP_".
Settings are applied in order, so environmental variables with matching name
override values from the json
file.
from configuration import ConfigurationBuilder
from configuration.json import JSONFile
from configuration.env import EnvironmentalVariables
builder = ConfigurationBuilder()
builder.add_source(JSONFile("settings.json"))
builder.add_source(EnvironmentalVariables(prefix="APP_"))
config = builder.build()
For example, if the JSON file contains the following contents:
{
"logging": {
"level": "INFO"
},
"example": "Hello World",
"foo": "foo"
}
And the environment has a variable named APP_foo=AAA
:
>>> config
<Configuration {'logging': {'level': 'INFO'}, 'example': 'Hello World', 'foo': 'AAA'}>
>>> config.foo
'AAA'
>>> config.logging.level
'INFO'
YAML file and environmental variables
In this example, configuration will include anything inside a file
settings.yaml
and environmental variables. Settings are applied in order, so
environmental variables with matching name override values from the yaml
file
(using the yaml
source requires also PyYAML
package).
from configuration import ConfigurationBuilder
from configuration.env import EnvironmentalVariables
from configuration.yaml import YAMLFile
builder = ConfigurationBuilder()
builder.add_source(YAMLFile("settings.yaml"))
builder.add_source(EnvironmentalVariables())
config = builder.build()
YAML file, optional file by environment
In this example, if an environmental variable with name APP_ENVIRONMENT
and
value dev
exists, and a configuration file with name settings.dev.yaml
is
present, it is read to override values configured in settings.yaml
file.
import os
from configuration import ConfigurationBuilder
from configuration.env import EnvironmentalVariables
from configuration.yaml import YAMLFile
environment_name = os.environ["APP_ENVIRONMENT"]
builder = ConfigurationBuilder()
builder.add_source(YAMLFile("settings.yaml"))
builder.add_source(YAMLFile(f"settings.{environment_name}.yaml", optional=True))
builder.add_source(EnvironmentalVariables(prefix="APP_"))
config = builder.build()
Filtering environmental variables by prefix
from configuration import Configuration
config = Configuration()
# will read only environmental variables
# starting with "APP_", case insensitively, removing the "APP_" prefix by
# default
config.add_environmental_variables("APP_")
INI files
INI files are parsed using the built-in configparser
module, therefore
support [DEFAULT]
section; all values are kept as strings.
from configuration import ConfigurationBuilder
from configuration.ini import INIFile
builder = ConfigurationBuilder()
builder.add_source(INIFile("settings.ini"))
config = builder.build()
Dictionaries
from configuration import ConfigurationBuilder
builder = ConfigurationBuilder()
builder.add_map({"host": "localhost", "port": 8080})
builder.add_map({"hello": "world", "example": [{"id": 1}, {"id": 2}]})
config = builder.build()
assert config.host == "localhost"
assert config.port == 8080
assert config.hello == "world"
assert config.example[0].id == 1
assert config.example[1].id == 2
Keys and values
from configuration import ConfigurationBuilder
builder = ConfigurationBuilder()
builder.add_map({"host": "localhost", "port": 8080})
builder.add_value("port", 44555)
config = builder.build()
assert config.host == "localhost"
assert config.port == 44555
Overriding nested values
It is possible to override nested values by environmental variables or dictionary keys using the following notation for sub properties:
- keys separated by colon ":", such as
a:d:e
- keys separated by "__", such as
a__d__e
from configuration import ConfigurationBuilder, MapSource
builder = ConfigurationBuilder(
[
MapSource(
{
"a": {
"b": 1,
"c": 2,
"d": {
"e": 3,
"f": 4,
},
}
}
)
]
)
config = builder.build()
assert config.a.b == 1
assert config.a.d.e == 3
assert config.a.d.f == 4
builder.add_value("a:d:e", 5)
config = builder.build()
assert config.a.d.e == 5
assert config.a.d.f == 4
Overriding nested values using env variables
import os
builder = ConfigurationBuilder(
[
MapSource(
{
"a": {
"b": 1,
"c": 2,
"d": {
"e": 3,
"f": 4,
},
}
}
)
]
)
config = builder.build()
assert config.a.b == 1
assert config.a.d.e == 3
assert config.a.d.f == 4
# NB: if an env variable such as:
# a:d:e=5
# or...
# a__d__e=5
#
# is defined, it overrides the value from the dictionary
os.environ["a__d__e"] = "5"
builder.sources.append(EnvironmentalVariables())
config = builder.build()
assert config.a.d.e == "5"
Overriding values in list items using env variables
builder = ConfigurationBuilder(
[
MapSource(
{
"b2c": [
{"tenant": "1"},
{"tenant": "2"},
{"tenant": "3"},
]
}
)
]
)
builder.add_value("b2c:1:tenant", "4")
config = builder.build()
assert config.b2c[0].tenant == "1"
assert config.b2c[1].tenant == "4"
assert config.b2c[2].tenant == "3"
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for essentials-configuration-0.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 00301702270b6133abb749918b68dad35a4805dbd16d5502dcd365b5447e97e1 |
|
MD5 | 11bcf522738e53091d42f8b7ebceaaf1 |
|
BLAKE2b-256 | fbf79a68c5a80b30d1ef648ffff17d79a2e62a6cc5018ff1c1f2989d4c74c5e2 |
Hashes for essentials_configuration-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e4cc0f5894be9fa72c779dd62ea5ed2d671ee38bce461d73b6da2884aa83559a |
|
MD5 | 4a667e3da5d0f17de836cbb025ffec27 |
|
BLAKE2b-256 | 622319467bcfc9fae226f86670e6f655b392b7396be43dd8febff047e307af78 |