dynaconf package

Submodules

dynaconf.base module

class dynaconf.base.LazySettings(**kwargs)[source]

Bases: dynaconf.utils.functional.LazyObject

When you do:

>>> from dynaconf import settings

a LazySettings is imported and is initialized with only default_settings.

Then when you first access a value, this will be set up and loaders will be executes looking for default config files or the file defined in SETTINGS_MODULE_FOR_DYNACONF variable:

>>> settings.SETTINGS_MODULE

Or when you call:

>>> settings.configure(settings_module='/tmp/settings.py')

You can define in your settings module a list of loaders to get values from different stores. By default it will try environment variables starting with GLOBAL_ENV_FOR_DYNACONF (by defaulf DYNACONF_)

You can also import this directly and customize it. in a file proj/conf.py:

>>> from dynaconf import LazySettings
>>> config = LazySettings(ENV_FOR_DYNACONF='PROJ',
...                       LOADERS_FOR_DYNACONF=[
...                             'dynaconf.loaders.env_loader',
...                             'dynaconf.loaders.redis_loader'
...                       ])

save common values in a settings file:

$ echo "SERVER_IP = '10.10.10.10'" > proj/settings.py

or use .toml|.yaml|.ini|.json

save sensitive values in .secrets.{py|toml|yaml|ini|json} or export as DYNACONF global environment variable:

$ export DYNACONF_SERVER_PASSWD='super_secret'

>>> # from proj.conf import config
>>> print config.SERVER_IP
>>> print config.SERVER_PASSWD

and now it reads all variables starting with DYNACONF_ from envvars and all values in a hash called DYNACONF_PROJ in redis

configure(settings_module=None, **kwargs)[source]

Allows user to reconfigure settings object passing a new settings module or separated kwargs

Parameters:
  • settings_module – defines the setttings file
  • kwargs – override default settings
configured

If wrapped is configured

class dynaconf.base.Settings(settings_module=None, **kwargs)[source]

Bases: object

Common logic for settings whether set by a module or by the user.

as_bool(key)[source]

Partial method for get with bool cast

as_float(key)[source]

Partial method for get with float cast

as_int(key)[source]

Partial method for get with int cast

as_json(key)[source]

Partial method for get with json cast

clean(*args, **kwargs)[source]

Clean all loaded values to reload when switching envs

current_env

Return the current active env

current_namespace

Return the current active env

dynaconf_banner = '\n██████╗ ██╗ ██╗███╗ ██╗ █████╗ ██████╗ ██████╗ ███╗ ██╗███████╗\n██╔══██╗╚██╗ ██╔╝████╗ ██║██╔══██╗██╔════╝██╔═══██╗████╗ ██║██╔════╝\n██║ ██║ ╚████╔╝ ██╔██╗ ██║███████║██║ ██║ ██║██╔██╗ ██║█████╗\n██║ ██║ ╚██╔╝ ██║╚██╗██║██╔══██║██║ ██║ ██║██║╚██╗██║██╔══╝\n██████╔╝ ██║ ██║ ╚████║██║ ██║╚██████╗╚██████╔╝██║ ╚████║██║\n╚═════╝ ╚═╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝\n'
execute_loaders(env=None, silent=None, key=None, filename=None)[source]

Execute all internal and registered loaders

Parameters:
  • env – The environment to load
  • silent – If loading erros is silenced
  • key – if provided load a single key
  • filename – optinal custom filename to load
exists(key, fresh=False)[source]

Check if key exists

Parameters:
  • key – the name of setting variable
  • fresh – if key should be taken from source direclty
Returns:

Boolean

exists_in_environ(key)[source]

Return True if env variable is exported

flag(key, env=None)[source]

Feature flagging system write flags to redis $ dynaconf write redis -s DASHBOARD=1 -e premiumuser meaning: Any premium user has DASHBOARD feature enabled

In your program do:

# premium user has access to dashboard?
>>> if settings.flag('dashboard', 'premiumuser'):
...     activate_dashboard()

The value is ensured to be loaded fresh from redis server

It also works with file settings but the recommended is redis as the data can be loaded once it is updated.

Parameters:
  • key – The flag name
  • env – The env to look for
fresh()[source]

this context manager force the load of a key direct from the store:

$ export DYNACONF_VALUE='Original'
>>> from dynaconf import settings
>>> print settings.VALUE
'Original'
$ export DYNACONF_VALUE='Changed Value'
>>> print settings.VALUE  # will not be reloaded from env vars
'Original
>>> with settings.fresh(): # inside this context all is reloaded
...    print settings.VALUE
'Changed Value'

an alternative is using settings.get_fresh(key)

Returns:context
get(key, default=None, cast=None, fresh=False)[source]

Get a value from settings store, this is the prefered way to access:

>>> from dynaconf import settings
>>> settings.get('KEY')
Parameters:
  • key – The name of the setting value, will always be upper case
  • default – In case of not found it will be returned
  • cast – Should cast in to @int, @float, @bool or @json ?
  • fresh – Should reload from loaders store before access?
Returns:

The value if found, default or None

get_environ(key, default=None, cast=None)[source]

Get value from environment variable using os.environ.get

Parameters:
  • key – The name of the setting value, will always be upper case
  • default – In case of not found it will be returned
  • cast – Should cast in to @int, @float, @bool or @json ? or cast must be true to use cast inference
Returns:

The value if found, default or None

get_fresh(key, default=None, cast=None)[source]

This is a shortcut to get(key, fresh=True). always reload from loaders store before getting the var.

Parameters:
  • key – The name of the setting value, will always be upper case
  • default – In case of not found it will be returned
  • cast – Should cast in to @int, @float, @bool or @json ?
Returns:

The value if found, default or None

keys()[source]

Redirects to store object

load_extra_yaml(env, silent, key)[source]

This is deprecated, kept for compat

Deprecated since version 1.0.0: Use multiple settings files instead.

loaded_by_loaders

Gets the internal mapping of LOADER -> values

loaded_envs

Get or create internal loaded envs list

loaded_namespaces

Get or create internal loaded envs list

loaders

Return available loaders

logger

Get or create inner logger

namespace(env=None, clean=True, silent=True, filename=None)

Used to interactively change the env Example of settings.toml:

[development]
message = 'This is in dev'
[other]
message = 'this is in other env'

Program:

>>> from dynaconf import settings
>>> print settings.MESSAGE
'This is in dev'
>>> with settings.using_env('OTHER'):
...    print settings.MESSAGE
'this is in other env'
Parameters:
  • env – Upper case name of env without any _
  • clean – If preloaded vars should be cleaned
  • silent – Silence errors
  • filename – Custom filename to load (optional)
Returns:

context

path_for(*args)[source]

Path containing PROJECT_ROOT_FOR_DYNACONF

reload(env=None, silent=None)[source]

Clean end Execute all loaders

set(key, value, loader_identifier=None, tomlfy=False)[source]

Set a value storing references for the loader

Parameters:
  • key – The key to store
  • value – The value to store
  • loader_identifier – Optional loader name e.g: toml, yaml etc.
  • tomlfy – Bool define if value is parsed by toml (defaults False)
setenv(env=None, clean=True, silent=True, filename=None)[source]

Used to interactively change the env Example of settings.toml:

[development]
message = 'This is in dev'
[other]
message = 'this is in other env'

Program:

>>> from dynaconf import settings
>>> print settings.MESSAGE
'This is in dev'
>>> with settings.using_env('OTHER'):
...    print settings.MESSAGE
'this is in other env'
Parameters:
  • env – Upper case name of env without any _
  • clean – If preloaded vars should be cleaned
  • silent – Silence errors
  • filename – Custom filename to load (optional)
Returns:

context

settings_module

Gets SETTINGS_MODULE variable

store

Gets internal storage

unset(key)[source]

Unset on all references

Parameters:key – The key to be unset
unset_all(keys)[source]

Unset based on a list of keys

Parameters:keys – a list of keys
update(data=None, loader_identifier=None, tomlfy=False, **kwargs)[source]

Update values in the current settings object without saving in stores:

>>> from dynaconf import settings
>>> print settings.NAME
'Bruno'
>>> settings.update({'NAME': 'John'}, other_value=1)
>>> print settings.NAME
'John'
>>> print settings.OTHER_VALUE
1
Parameters:
  • data – Data to be updated
  • loader_identifier – Only to be used by custom loaders
  • tomlfy – Bool define if value is parsed by toml (defaults False)
  • kwargs – extra values to update
Returns:

None

using_env(env, clean=True, silent=True, filename=None)[source]

This context manager allows the contextual use of a different env Example of settings.toml:

[development]
message = 'This is in dev'
[other]
message = 'this is in other env'

Program:

>>> from dynaconf import settings
>>> print settings.MESSAGE
'This is in dev'
>>> with settings.using_env('OTHER'):
...    print settings.MESSAGE
'this is in other env'
Parameters:
  • env – Upper case name of env without any _
  • clean – If preloaded vars should be cleaned
  • silent – Silence errors
  • filename – Custom filename to load (optional)
Returns:

context

using_namespace(env, clean=True, silent=True, filename=None)

This context manager allows the contextual use of a different env Example of settings.toml:

[development]
message = 'This is in dev'
[other]
message = 'this is in other env'

Program:

>>> from dynaconf import settings
>>> print settings.MESSAGE
'This is in dev'
>>> with settings.using_env('OTHER'):
...    print settings.MESSAGE
'this is in other env'
Parameters:
  • env – Upper case name of env without any _
  • clean – If preloaded vars should be cleaned
  • silent – Silence errors
  • filename – Custom filename to load (optional)
Returns:

context

validators

Gets or creates validator wrapper

values()[source]

Redirects to store object

dynaconf.cli module

dynaconf.cli.open_docs(ctx, param, value)[source]
dynaconf.cli.print_version(ctx, param, value)[source]
dynaconf.cli.read_file_in_root_directory(*names, **kwargs)[source]

Read a file.

dynaconf.cli.show_banner(ctx, param, value)[source]

Shows dynaconf awesome banner

dynaconf.cli.split_vars(_vars)[source]

Splits values like foo=bar=zaz in {‘foo’: ‘bar=zaz’}

dynaconf.default_settings module

dynaconf.default_settings.get(key, default=None)[source]
dynaconf.default_settings.start_dotenv(obj=None)[source]
dynaconf.default_settings.try_renamed(key, value, current_key, older_key)[source]

dynaconf.constants module

dynaconf.test_settings module

dynaconf.validator module

exception dynaconf.validator.ValidationError[source]

Bases: Exception

class dynaconf.validator.Validator(*names, must_exist=None, condition=None, when=None, env=None, **operations)[source]

Bases: object

Validators are conditions attached to settings variables names or patterns:

Validator('MESSAGE', defined=True, eq='Hello World')

The above ensure MESSAGE is available in default env and is equal to ‘Hello World’

names are a one (or more) names or patterns:

Validator('NAME')
Validator('NAME', 'OTHER_NAME', 'EVEN_OTHER')
Validator(r'^NAME', r'OTHER./*')

The operations are:

eq: value == other
ne: value != other
gt: value > other
lt: value < other
gte: value >= other
lte: value <= other
is_type_of: isinstance(value, type)
is_in:  value in sequence
is_not_in: value not in sequence
identity: value is other

env is which env to be checked, can be a list or default is used.

when holds a validator and its return decides if validator runs or not:

Validator('NAME', defined=True, when=Validator('OTHER', eq=2))
# NAME is required only if OTHER eq to 2
# When the very first thing to be performed when passed.
# if no env is passed to `when` it is inherited

must_exist is exists requirement. (executed after when):

settings.exists(value)

condition is a callable to be executed and return boolean:

Validator('NAME', condition=lambda x: x == 1)
# it is executed before operations.
validate(settings)[source]

Raise ValidationError if invalid

class dynaconf.validator.ValidatorList(settings, *args, **kwargs)[source]

Bases: list

register(*args)[source]
validate()[source]

dynaconf.validator_conditions module

Implement basic assertions to be used in assertion action

dynaconf.validator_conditions.eq(value, other)[source]

Equal

dynaconf.validator_conditions.gt(value, other)[source]

Greater than

dynaconf.validator_conditions.gte(value, other)[source]

Greater than or equal

dynaconf.validator_conditions.identity(value, other)[source]

Identity check using ID

dynaconf.validator_conditions.is_in(value, other)[source]

Existence

dynaconf.validator_conditions.is_not_in(value, other)[source]

Inexistence

dynaconf.validator_conditions.is_type_of(value, other)[source]

Type check

dynaconf.validator_conditions.lt(value, other)[source]

Lower than

dynaconf.validator_conditions.lte(value, other)[source]

Lower than or equal

dynaconf.validator_conditions.ne(value, other)[source]

Not equal

Module contents

class dynaconf.LazySettings(**kwargs)[source]

Bases: dynaconf.utils.functional.LazyObject

When you do:

>>> from dynaconf import settings

a LazySettings is imported and is initialized with only default_settings.

Then when you first access a value, this will be set up and loaders will be executes looking for default config files or the file defined in SETTINGS_MODULE_FOR_DYNACONF variable:

>>> settings.SETTINGS_MODULE

Or when you call:

>>> settings.configure(settings_module='/tmp/settings.py')

You can define in your settings module a list of loaders to get values from different stores. By default it will try environment variables starting with GLOBAL_ENV_FOR_DYNACONF (by defaulf DYNACONF_)

You can also import this directly and customize it. in a file proj/conf.py:

>>> from dynaconf import LazySettings
>>> config = LazySettings(ENV_FOR_DYNACONF='PROJ',
...                       LOADERS_FOR_DYNACONF=[
...                             'dynaconf.loaders.env_loader',
...                             'dynaconf.loaders.redis_loader'
...                       ])

save common values in a settings file:

$ echo "SERVER_IP = '10.10.10.10'" > proj/settings.py

or use .toml|.yaml|.ini|.json

save sensitive values in .secrets.{py|toml|yaml|ini|json} or export as DYNACONF global environment variable:

$ export DYNACONF_SERVER_PASSWD='super_secret'

>>> # from proj.conf import config
>>> print config.SERVER_IP
>>> print config.SERVER_PASSWD

and now it reads all variables starting with DYNACONF_ from envvars and all values in a hash called DYNACONF_PROJ in redis

configure(settings_module=None, **kwargs)[source]

Allows user to reconfigure settings object passing a new settings module or separated kwargs

Parameters:
  • settings_module – defines the setttings file
  • kwargs – override default settings
configured

If wrapped is configured

class dynaconf.Validator(*names, must_exist=None, condition=None, when=None, env=None, **operations)[source]

Bases: object

Validators are conditions attached to settings variables names or patterns:

Validator('MESSAGE', defined=True, eq='Hello World')

The above ensure MESSAGE is available in default env and is equal to ‘Hello World’

names are a one (or more) names or patterns:

Validator('NAME')
Validator('NAME', 'OTHER_NAME', 'EVEN_OTHER')
Validator(r'^NAME', r'OTHER./*')

The operations are:

eq: value == other
ne: value != other
gt: value > other
lt: value < other
gte: value >= other
lte: value <= other
is_type_of: isinstance(value, type)
is_in:  value in sequence
is_not_in: value not in sequence
identity: value is other

env is which env to be checked, can be a list or default is used.

when holds a validator and its return decides if validator runs or not:

Validator('NAME', defined=True, when=Validator('OTHER', eq=2))
# NAME is required only if OTHER eq to 2
# When the very first thing to be performed when passed.
# if no env is passed to `when` it is inherited

must_exist is exists requirement. (executed after when):

settings.exists(value)

condition is a callable to be executed and return boolean:

Validator('NAME', condition=lambda x: x == 1)
# it is executed before operations.
validate(settings)[source]

Raise ValidationError if invalid

class dynaconf.FlaskDynaconf(app=None, instance_relative_config=False, dynaconf_instance=None, **kwargs)[source]

Bases: object

The arguments are. app = The created app dynaconf_args = Extra args to be passed to Dynaconf (validator for example)

All other values are stored as config vars specially:

ENV_FOR_DYNACONF = env prefix for your envvars to become settings
                    example:
                        export MYSITE_SQL_PORT='@int 5445'

                    with that exported to env you access using:
                        app.config.SQL_PORT
                        app.config.get('SQL_PORT')
                        app.config.get('sql_port')
                        # get is case insensitive
                        app.config['SQL_PORT']

                    Dynaconf uses `@int, @bool, @float, @json` to cast
                    env vars

SETTINGS_MODULE_FOR_DYNACONF = The name of the module or file to use as
                            default to load settings. If nothing is
                            passed it will be `settings.*` or value
                            found in `ENVVAR_FOR_DYNACONF`
                            Dynaconf supports
                            .py, .yml, .toml, ini, json
ATTENTION: Take a look at settings.yml and .secrets.yml to know the
required settings format.

Settings load order in Dynaconf:

  • Load all defaults and Flask defaults
  • Load all passed variables when applying FlaskDynaconf
  • Update with data in settings files
  • Update with data in environmente vars ENV_FOR_DYNACONF_

TOML files are very useful to have envd settings, lets say, production and development.

You can also achieve the same using multiple .py files naming as settings.py, production_settings.py and development_settings.py (see examples/validator)

Example:

app = Flask(__name__)
FlaskDynaconf(
    app,
    ENV_FOR_DYNACONF='MYSITE',
    SETTINGS_MODULE_FOR_DYNACONF='settings.yml',
    EXTRA_VALUE='You can add aditional config vars here'
)

Take a look at examples/flask in Dynaconf repository

init_app(app, **kwargs)[source]

kwargs holds initial dynaconf configuration

make_config(app)[source]
exception dynaconf.ValidationError[source]

Bases: Exception