simple-settings 0.14.0

project_settings.py

In this example we just store a simple string but any python type is accepted.

SIMPLE_CONF = 'simple'

app.py

You don’t need specify which setting simple-settings must load, you can do this with command line or environment.

from simple_settings import settings

print(settings.SIMPLE_CONF)

Run

You can specify your settings module with command line:

$ python app.py --settings=project_settings
simple

Or environment:

$ export SIMPLE_SETTINGS=project_settings
$ python app.py
simple

Check examples, in project repository for more usage samples.

Configure logging

If you set the special setting CONFIGURE_LOGGING with True, simple-settings will configure the python logging to you. You just need to define your logging configuration with Python dictConfig format and place in LOGGING setting, e.g.

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'default': {
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
        },
    },
    'handlers': {
        'logfile': {
            'level': 'DEBUG',
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': 'my_log.log',
            'maxBytes': 50 * 1024 * 1024,
            'backupCount': 10,
            'formatter': 'default'
        },
    },
    'loggers': {
        '': {
            'handlers': ['logfile'],
            'level': 'ERROR'
        },
        'my_project': {
            'level': 'INFO',
            'propagate': True,
        },
    }
}

To use just get logger with logging.getLogger(), e.g.

import logging
logger = logging.getLogger('my_project')


logger.info('Hello')

Don’t forget, simple-settings is lazy and it only configures logging after runs setup() method or after reads some setting.

Override settings value

You can override the values of your settings module with environment variables. You just need set the special setting OVERRIDE_BY_ENV with True as value.

$ export SIMPLE_CONF="simple from env"
$ python app.py --settings=project_settings
simple from env

This is not a dynamic behavior, because settings are only overriden at “settings setup” time; see dynamic settings for a real dynamic behavior.

Required Settings

You can determine a list of mandatory settings, i.e. settings that require a valid value. For this, set the special setting REQUIRED_SETTINGS to a list (or any iterable) of your required settings. If any setting in this list has an invalid value (or is not present in setting file) then a ValueError is raised with a list of required settings not satified in the settings file.

Required Not None Settings

You can also determine a list of settings that must have a not none value, i.e. settings that cannot be set as none. For this, set the special setting REQUIRED_NOT_NONE_SETTINGS to a list (or any iterable) of the settings that you require to not be none. If any setting in this list has a value of none, then a ValueError is raised with a list of settings that must be set to not none.

Required Settings Types

You can enforce that settings must have a particular type. For this, set the special setting REQUIRED_SETTINGS_TYPES to a dictionary with the keys being the name of the setting and the value being the type of the setting (see list below for supported values).

If any of these settings has a value that is not of the type specified, or is a string that cannot be parsed to the type specified, a ValueError is raised with a list of settings that are of the wrong type. If there are no errors, the setting value will be converted into that type. If any of the values are none, their type is not evaluated.

The supported types are listed below. If you attempt to set a type that is not one of these types, then a ValueError will be raised with any unsupported types.

• "bool" - python’s native boolean type, parsed from a string as true if the value is "True" or "true"; and as false if the value if "False" or "false"

• "int" - python’s native integer type, parsed from a string using int(value)

• "float" - python’s native float type, parsed from a string using float(value)

• "str" - python’s native string type, not parsed from a string

Dynamic Settings

simple-settings has a list of dynamic settings mechanisms that change a value of setting dynamically. If dynamic setting is activate, for all setting the dynamic reader is called. The current dynamic mechanisms suported is:

SIMPLE_SETTINGS = {
    'DYNAMIC_SETTINGS': {
        'backend': 'redis',
        'host': 'locahost',
        'port': 6379,
    }
}

SIMPLE_SETTINGS = {
    'DYNAMIC_SETTINGS': {
        'backend': 'consul',
        'host': 'locahost',
        'port': 8500,
        'prefix': 'mynamespace/'
    }
}

SIMPLE_SETTINGS = {
    'DYNAMIC_SETTINGS': {
        'backend': 'database',
        'sqlalchemy.url': 'sqlite:///:memory:',
        ...
    }
}

SIMPLE_SETTINGS = {
    'DYNAMIC_SETTINGS': {
        'backend': 's3',
        'bucket_name': 'simple-settings',
        'region': 'us-east-1'
        ...
    }
}

Context Manager example

from simple_settings import settings
from simple_settings.utils import settings_stub


with settings_stub(SOME_SETTING='foo'):
    assert settings.SOME_SETTING == 'foo'
assert settings.SOME_SETTING == 'bar'

Decorator example

from simple_settings import settings
from simple_settings.utils import settings_stub


@settings_stub(SOME_SETTING='foo')
def get_some_setting():
    return settings.SOME_SETTING

assert get_some_setting() == 'foo'
assert settings.SOME_SETTING == 'bar'

[0.14.0] - 2019-01-31

• Required not none special setting

• Required types special setting and type conversion

[0.13.0] - 2018-03-28

• Dynamic settings behaviors with AWS S3.

[0.12.1] - 2017-10-27

• Fix dynamic settings read behavior to ignore only None values and not zeros values ( #68)

[0.12.0] - 2017-03-07

• Load settings from toml files.

[0.11.0] - 2017-02-17

• Autoconfigure python logging with CONFIGURE_LOGGING special setting.

[0.10.0] - 2016-10-28

• Support configuring dynamic backends with an optional prefix.

[0.9.1] - 2016-09-15

• configure method now works even called before the LazySettings setup.

[0.9.0] - 2016-08-12

• configure method now update settings in dynamic settings.

• On get setting value in dynamic setting update local settings with this value.

• Auto casting value in dynamic storage to using complex types.

[0.8.1] - 2016-06-04

• Fix instalation with database extra requires.

[0.8.0] - 2016-06-04

• Better ImportError message if using a dynamic reader without your lib dependencies.

• Refactor in Settings Stub.

• Dynamic settings behaviors with SQLAlchemy (database backend).

• Load settings of json files.

[0.7.0] - 2016-06-02

• Nice python REPR for LazySettings objects.

• Dynamic settings behaviors with Redis.

• Dynamic settings behaviors with Consul.

• Generate package with python wheel.

[0.6.0] - 2016-05-17

• Some refactors.

• Determine settings files and modules directly in LazySettings object (to avoid use env or command line argument).

• configure method to update settings.

• Use safe_load instead load in yaml strategy.

[0.5.0] - 2016-02-03

• Some refactors.

• Load settings of yaml files.

• New SIMPLE_SETTINGS environment variable.

• New --simple-settings command line arg.

[0.4.0] - 2016-01-03

• Lazy settings load.

[0.3.1] - 2015-07-23

• Avoid to load python modules (as settings) in python files (with this, fix deepcopy bug in as_dict() method).

[0.3.0] - 2015-07-19

• Deepcopy in as_dict method to anticipate unexpected changes.

• Special Settings Behaviors.

  • Override settings values by environment.

  • Required settings validation.

• Remove default behavior of override settings values by environment (now it’s a special settings).

• Settings Stub (useful for tests)

• Change bahavior of settings __getattr__ (before may raise KeyError if simple-settings do not locate the setting, now raise AttributeError)

[0.2.0] - 2015-06-19

• Load multiple settings separated by comma (like a pipeline).

• Load settings of cfg files.

• Filter python module attributes to read only user settings.

[0.1.1] - 2015-05-19

• Fix parser_args error if using simple-settings with others command line arguments.

[0.1.0] - 2015-05-14

• First release.