evarify: Transform and Validate Environment Variables¶

Distribute & Pip¶

Installing Requests is simple with pip, just run this in your terminal:

$ pip install evarify

GitHub¶

evarify is developed on GitHub, where you can always retrieve the latest version of the code.

You can either clone the public repository:

$ git clone git://github.com/gtaylor/evarify.git

Download the tarball:

$ curl -OL https://github.com/gtaylor/evarify/tarball/master

Or, download the zipball:

$ curl -OL https://github.com/gtaylor/evarify/zipball/master

Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packages easily:

$ python setup.py install

ConfigStore and EnvironmentVariable¶

First, create a new module within your application that will hold your configuration. We suggest something like config.py.

Here’s a good starting point:

from evarify import ConfigStore, EnvironmentVariable
from evarify.filters.python_basics import value_to_python_log_level, \
    value_to_bool

settings = ConfigStore({
    'LOGLEVEL': EnvironmentVariable(
        name='LOGLEVEL',
        help_txt='The desired logging level (DEBUG|INFO|WARN|ERROR).',
        is_required=False,
        default_val='INFO',
        filters=[value_to_python_log_level],
    )
})

You’ll notice that the top-level container is the ConfigStore class. This will hold all of your EnvironmentVariable definitions, and eventually your loaded config values. See the API reference for each of those classes for more details on what the arguments mean.

Loading Config Values from Environment Variables¶

The next step is to go to the entrypoint module for your project and import and load our config values:

from mymodule.config import settings

settings.load_values()

This causes the magic to happen. We iterate through your EnvironmentVariable definitions, pull the values, run them through the filters, and set the corresponding dict key in your ConfigStore. You can then reference it with the dict API:

>>> import logging
>>> from mymodule.config import settings
>>> settings.load_values()
>>> assert settings['LOGGING'] == logging.INFO

Filters¶

An important part of our EnvironmentVariable definitions the filters param. This is a list of filter functions to pass the environment variable’s value through before storing the result in the ConfigStore. They fit the following signature:

def your_filter(config_val, evar):
    """
    :param str config_val: The env var value.
    :param EnvironmentVariable evar: The EVar object we are validating
        a value for.
    :raises: ValueError if there are any issues with the value.
    """
    # Your logic here. You can modify the config_val before returning.
    return config_val

The environment variable’s values will be passed through these filters in order, so be sure to arrange things accordingly.

You can easily write your own filters, or use any of our built-ins. See the evarify.filters.python_basics API reference for a list.

Gotchas¶

• If an EnvironmentVariable has been set to required=True (the default), you must define the environment variable when running your application (even if it’s an empty value).
• If EnvironmentVariable has been set to required=False, failing to define the environment variable will result in the default_val being used. If no default_val has been passed in, we default to None.

evarify.ConfigStore¶

class evarify.ConfigStore(evar_defs)[source]¶

This is the container for your EnvironmentVariable definitions, along with their eventual loaded config values. Once load_values() is ran on an instance of this class, the config values are addressable via the Python dict API.

__init__(evar_defs)[source]¶

Parameters:	evar_defs (dict) – Pass in a dict whose keys are config names and the values are EnvironmentVariable instances.

__weakref__¶

list of weak references to the object (if defined)

load_values()[source]¶

Go through the env var map, transferring the values to this object as attributes.

Raises:	RuntimeError if a required env var isn’t defined.

evarify.EnvironmentVariable¶

class evarify.EnvironmentVariable(name, is_required=True, default_val=None, filters=None, help_txt=None)[source]¶

Defines an Environment Variable to handle.

__init__(name, is_required=True, default_val=None, filters=None, help_txt=None)[source]¶

Parameters:

name (str) – The name of the environment variable. This is case-sensitive! is_required (bool) – If True, this variable must be defined when your Python process starts. If False, the default loaded value will match default_val. default_val – If is_required is False and this environment variable is not defined, this value will be loaded. filters (list) – A list of functions to pass the environment variable’s value (or default value) through. Order is significant! help_txt (str) – Optional help text describing the environment variable.

__weakref__¶

list of weak references to the object (if defined)

evarify.filters.python_basics¶

evarify.filters.python_basics.comma_separated_str_to_list(config_val, evar)[source]¶

Splits a comma-separated environment variable into a list of strings.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Return type:	list
Returns:	The equivalent list for a comma-separated string.

evarify.filters.python_basics.comma_separated_to_set(config_val, evar)[source]¶

Splits a comma-separated environment variable into a set of strings.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Return type:	set
Returns:	The equivalent set for a comma-separated string.

evarify.filters.python_basics.validate_is_boolean_true(config_val, evar)[source]¶

Make sure the value evaluates to boolean True.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Raises:	ValueError if the config value evaluates to boolean False.

evarify.filters.python_basics.validate_is_not_none(config_val, evar)[source]¶

If the value is None, fail validation.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Raises:	ValueError if the config value is None.

evarify.filters.python_basics.value_to_bool(config_val, evar)[source]¶

Massages the ‘true’ and ‘false’ strings to bool equivalents.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Return type:	bool
Returns:	True or False, depending on the value.

evarify.filters.python_basics.value_to_int(config_val, evar)[source]¶

Convert the value to int.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Return type:	int

evarify.filters.python_basics.value_to_none(config_val, evar)[source]¶

Given a value that evaluates to a boolean False, return None.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Return type:	str or None
Returns:	Either the non-False value or None.

evarify.filters.python_basics.value_to_python_log_level(config_val, evar)[source]¶

Convert an evar value into a Python logging level constant.

Parameters:	config_val (str) – The env var value. evar (EnvironmentVariable) – The EVar object we are validating a value for.
Returns:	A validated string.
Raises:	ValueError if the log level is invalid.

File an Issue¶

If you run into unexpected behavior or have ideas for new features, file an issue on on GitHub.

0.1.2 (In Development)¶

• Replace UserDict with dict in ConfigStore. (the_gigi)
• As a result of the previous, no longer require future as a dependency.

0.1.1 (2015-12-14)¶

• Use future module to make UserDict work across Python 2 + 3.

0.1.0 (2015-12-13)¶

• Initial release.