Configuration provider¶
Configuration
provider provides configuration options to the other providers.
import boto3
from dependency_injector import containers, providers
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
s3_client_factory = providers.Factory(
boto3.client,
's3',
aws_access_key_id=config.aws.access_key_id,
aws_secret_access_key=config.aws.secret_access_key,
)
if __name__ == '__main__':
container = Container()
container.config.from_dict(
{
'aws': {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
},
},
)
s3_client = container.s3_client_factory()
It implements the principle “use first, define later”.
Loading from an INI file¶
Configuration
provider can load configuration from an ini
file using the
Configuration.from_ini()
method:
from dependency_injector import containers, providers
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
container = Container()
container.config.from_ini('examples/providers/configuration/config.ini')
assert container.config() == {
'aws': {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
},
}
assert container.config.aws() == {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
}
assert container.config.aws.access_key_id() == 'KEY'
assert container.config.aws.secret_access_key() == 'SECRET'
where examples/providers/configuration/config.ini
is:
[aws]
access_key_id = KEY
secret_access_key = SECRET
Configuration.from_ini()
method supports environment variables interpolation. Use
${ENV_NAME}
format in the configuration file to substitute value of the environment
variable ENV_NAME
.
Loading from a YAML file¶
Configuration
provider can load configuration from a yaml
file using the
Configuration.from_yaml()
method:
from dependency_injector import containers, providers
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
container = Container()
container.config.from_yaml('examples/providers/configuration/config.yml')
assert container.config() == {
'aws': {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
},
}
assert container.config.aws() == {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
}
assert container.config.aws.access_key_id() == 'KEY'
assert container.config.aws.secret_access_key() == 'SECRET'
where examples/providers/configuration/config.yml
is:
aws:
access_key_id: "KEY"
secret_access_key: "SECRET"
Configuration.from_yaml()
method uses custom version of yaml.SafeLoader
.
The loader supports environment variables interpolation. Use ${ENV_NAME}
format
in the configuration file to substitute value of the environment variable ENV_NAME
.
You can also specify a YAML loader as an argument:
import yaml
container.config.from_yaml('config.yml', loader=yaml.UnsafeLoader)
Note
Loading of a yaml configuration requires PyYAML
package.
You can install the Dependency Injector
with an extra dependency:
pip install dependency-injector[yaml]
or install PyYAML
directly:
pip install pyyaml
Don’t forget to mirror the changes in the requirements file.
Loading from a Pydantic settings¶
Configuration
provider can load configuration from a pydantic
settings object using the
Configuration.from_pydantic()
method:
import os
from dependency_injector import containers, providers
from pydantic import BaseSettings, Field
# Emulate environment variables
os.environ['AWS_ACCESS_KEY_ID'] = 'KEY'
os.environ['AWS_SECRET_ACCESS_KEY'] = 'SECRET'
class AwsSettings(BaseSettings):
access_key_id: str = Field(env='aws_access_key_id')
secret_access_key: str = Field(env='aws_secret_access_key')
class Settings(BaseSettings):
aws: AwsSettings = AwsSettings()
optional: str = Field(default='default_value')
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
container = Container()
container.config.from_pydantic(Settings())
assert container.config.aws.access_key_id() == 'KEY'
assert container.config.aws.secret_access_key() == 'SECRET'
assert container.config.optional() == 'default_value'
To get the data from pydantic settings Configuration
provider calls Settings.dict()
method.
If you need to pass an argument to this call, use .from_pydantic()
keyword arguments.
container.config.from_pydantic(Settings(), exclude={'optional'})
Note
Dependency Injector
doesn’t install pydantic
by default.
You can install the Dependency Injector
with an extra dependency:
pip install dependency-injector[pydantic]
or install pydantic
directly:
pip install pydantic
Don’t forget to mirror the changes in the requirements file.
Loading from a dictionary¶
Configuration
provider can load configuration from a Python dict
using the
Configuration.from_dict()
method:
from dependency_injector import containers, providers
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
container = Container()
container.config.from_dict(
{
'aws': {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
},
},
)
assert container.config() == {
'aws': {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
},
}
assert container.config.aws() == {
'access_key_id': 'KEY',
'secret_access_key': 'SECRET',
}
assert container.config.aws.access_key_id() == 'KEY'
assert container.config.aws.secret_access_key() == 'SECRET'
Loading from an environment variable¶
Configuration
provider can load configuration from an environment variable using the
Configuration.from_env()
method:
import os
from dependency_injector import containers, providers
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
container = Container()
# Emulate environment variables
os.environ['AWS_ACCESS_KEY_ID'] = 'KEY'
os.environ['AWS_SECRET_ACCESS_KEY'] = 'SECRET'
container.config.aws.access_key_id.from_env('AWS_ACCESS_KEY_ID')
container.config.aws.secret_access_key.from_env('AWS_SECRET_ACCESS_KEY')
container.config.optional.from_env('UNDEFINED', 'default_value')
assert container.config.aws.access_key_id() == 'KEY'
assert container.config.aws.secret_access_key() == 'SECRET'
assert container.config.optional() == 'default_value'
Loading from the multiple sources¶
Configuration
provider can load configuration from the multiple sources. Loaded
configuration is merged recursively over the existing configuration.
from dependency_injector import containers, providers
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
container = Container()
container.config.from_yaml('examples/providers/configuration/config.yml')
container.config.from_yaml('examples/providers/configuration/config.local.yml')
assert container.config() == {
'aws': {
'access_key_id': 'LOCAL-KEY',
'secret_access_key': 'LOCAL-SECRET',
},
}
assert container.config.aws() == {
'access_key_id': 'LOCAL-KEY',
'secret_access_key': 'LOCAL-SECRET',
}
assert container.config.aws.access_key_id() == 'LOCAL-KEY'
assert container.config.aws.secret_access_key() == 'LOCAL-SECRET'
where examples/providers/configuration/config.local.yml
is:
aws:
access_key_id: "LOCAL-KEY"
secret_access_key: "LOCAL-SECRET"
Mandatory and optional sources¶
By default, methods .from_yaml()
and .from_ini()
ignore errors if configuration file does not exist.
You can use this to specify optional configuration files.
If configuration file is mandatory, use required
argument. Configuration provider will raise an error
if required file does not exist.
You can also use required
argument when loading configuration from dictionaries and environment variables.
Mandatory YAML file:
container.config.from_yaml('config.yaml', required=True)
Mandatory INI file:
container.config.from_ini('config.ini', required=True)
Mandatory dictionary:
container.config.from_dict(config_dict, required=True)
Mandatory environment variable:
container.config.api_key.from_env('API_KEY', required=True)
See also: Strict mode and required options.
Specifying the value type¶
You can specify the type of the injected configuration value explicitly.
This helps when you read the value from an ini file or an environment variable and need to
convert it into an int
or a float
.
import os
from dependency_injector import containers, providers
class ApiClient:
def __init__(self, api_key: str, timeout: int):
self.api_key = api_key
self.timeout = timeout
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
api_client_factory = providers.Factory(
ApiClient,
api_key=config.api.key,
timeout=config.api.timeout.as_int(),
)
if __name__ == '__main__':
container = Container()
# Emulate environment variables
os.environ['API_KEY'] = 'secret'
os.environ['API_TIMEOUT'] = '5'
container.config.api.key.from_env('API_KEY')
container.config.api.timeout.from_env('API_TIMEOUT')
api_client = container.api_client_factory()
assert api_client.api_key == 'secret'
assert api_client.timeout == 5
Configuration
provider has next helper methods:
.as_int()
.as_float()
.as_(callback, *args, **kwargs)
The last method .as_(callback, *args, **kwargs)
helps to implement other conversions.
import os
import decimal
from dependency_injector import containers, providers
class Calculator:
def __init__(self, pi: decimal.Decimal):
self.pi = pi
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
calculator_factory = providers.Factory(
Calculator,
pi=config.pi.as_(decimal.Decimal),
)
if __name__ == '__main__':
container = Container()
# Emulate environment variables
os.environ['PI'] = '3.1415926535897932384626433832'
container.config.pi.from_env('PI')
calculator = container.calculator_factory()
assert calculator.pi == decimal.Decimal('3.1415926535897932384626433832')
With the .as_(callback, *args, **kwargs)
you can specify a function that will be called
before the injection. The value from the config will be passed as a first argument. The returned
value will be injected. Parameters *args
and **kwargs
are handled as any other injections.
Strict mode and required options¶
You can use configuration provider in strict mode. In strict mode configuration provider raises an error on access to any undefined option.
from dependency_injector import containers, providers, errors
class ApiClient:
def __init__(self, api_key: str, timeout: int):
self.api_key = api_key
self.timeout = timeout
class Container(containers.DeclarativeContainer):
config = providers.Configuration(strict=True)
api_client_factory = providers.Factory(
ApiClient,
api_key=config.api.key,
timeout=config.api.timeout.as_int(),
)
if __name__ == '__main__':
container = Container()
try:
api_client = container.api_client_factory()
except errors.Error:
# raises error: Undefined configuration option "config.api.key"
...
Methods .from_*()
in strict mode raise an exception if configuration file does not exist or
configuration data is undefined:
class Container(containers.DeclarativeContainer):
config = providers.Configuration(strict=True)
if __name__ == '__main__':
container = Container()
try:
container.config.from_yaml('does-not_exist.yml') # raise exception
except FileNotFoundError:
...
try:
container.config.from_ini('does-not_exist.ini') # raise exception
except FileNotFoundError:
...
try:
container.config.from_pydantic(EmptySettings()) # raise exception
except ValueError:
...
try:
container.config.from_env('UNDEFINED_ENV_VAR') # raise exception
except ValueError:
...
try:
container.config.from_dict({}) # raise exception
except ValueError:
...
You can override .from_*()
methods behaviour in strict mode using required
argument:
class Container(containers.DeclarativeContainer):
config = providers.Configuration(strict=True)
if __name__ == '__main__':
container = Container()
container.config.from_yaml('config.yml')
container.config.from_yaml('config.local.yml', required=False)
You can also use .required()
option modifier when making an injection. It does not require to switch
configuration provider to strict mode.
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
api_client_factory = providers.Factory(
ApiClient,
api_key=config.api.key.required(),
timeout=config.api.timeout.required().as_int(),
)
Note
Modifier .required()
should be specified before type modifier .as_*()
.
Aliases¶
You can use Configuration
provider with a context manager to create aliases.
from dependency_injector import containers, providers
from environs import Env
class Container(containers.DeclarativeContainer):
config = providers.Configuration()
if __name__ == '__main__':
env = Env()
container = Container()
with container.config.some_plugin_name as plugin:
plugin.some_interval_ms.override(
env.int(
'SOME_INTERVAL_MS',
default=30000,
),
)
with plugin.kafka as kafka:
kafka.bootstrap_servers.override(
env.list(
'KAFKA_BOOTSTRAP_SERVERS',
default=['kafka1', 'kafka2'],
),
)
kafka.security_protocol.override(
env.str(
'KAFKA_SECURITY_PROTOCOL',
default='SASL_SSL',
),
)
Note
Library environs
is a 3rd party library. You need to install it
separately:
pip install environs
Documentation is available on GitHub: https://github.com/sloria/environs
Injecting invariants¶
You can inject invariant configuration options based on the value of the other configuration option.
To use that you should provide the switch-value as an item of the configuration option that
contains sections config.options[config.switch]
:
When the value of the
config.switch
isA
, theconfig.options.A
is injectedWhen the value of the
config.switch
isB
, theconfig.options.B
is injected
import dataclasses
from dependency_injector import containers, providers
@dataclasses.dataclass
class Foo:
option1: object
option2: object
class Container(containers.DeclarativeContainer):
config = providers.Configuration(default={
'target': 'A',
'items': {
'A': {
'option1': 60,
'option2': 80,
},
'B': {
'option1': 10,
'option2': 20,
},
},
})
foo_factory = providers.Factory(
Foo,
option1=config.items[config.target].option1,
option2=config.items[config.target].option2,
)
if __name__ == '__main__':
container = Container()
container.config.target.from_env('TARGET')
foo = container.foo_factory()
print(foo.option1, foo.option2)
# $ TARGET=A python configuration_itemselector.py
# 60 80
# $ TARGET=B python configuration_itemselector.py
# 10 20