Updated Jul 29, 2008 by loren.davie
Labels:	Featured

EnvironmentFiles

Environment Files are used to define your environment.

Introduction

Environment files are used to specify environment variables and generators that create values for them. An environment file is just a python file with an .env extension, that lives somewhere on the ENVPATH.

On startup, django-environment will build the environment based on each .env file that it finds on the ENVPATH. The final environment will be the composite of all the entries found in the files.

Environment File Format

An Environment File must contain a global variable called entries to which is assigned a dictionary object. The keys of the dictionary are the names of the variables to be placed in the environment, and to them are mapped the generators that will create the variable values.

Here's an example of an environment file:

# example.env
from environment.standard import RequestParameterGenerator, AuthProfileGenerator

entries = {
    'params':RequestParameterGenerator(),
    'avatar':AuthProfileGenerator(),
    'foo':'bar',
}

In the example above, there are three environment variables defined: 'params', 'avatar' and 'foo'. For each variable, a variable generator has been mapped. (Yes, 'bar' is just a string, but strings are automatically substituted with a StringGenerator, see below).

Variable Generators

django-environment comes with a number of variable generators out of the box.

StringGenerator

A string generator simply seeds the variable with the string defined in the environment file. String generators have special support by django-environment, so that it's not necessary to explicitly specify a string generator - you can simply place a string literal as the values in the entries dictionary. In other words:

'foo':'bar'

is the equivalent of

'foo':StringGenerator('bar')

StringDictGenerator

A string dictionary generator contains a dictionary of string mappings. It will use the variable name as the key, and return the value mapped to the variable name.

gen = StringDictGenerator({'Bert':'Ernie','BugBunny':'RoadRunner','Statler':'Waldorf'})

entries = {
    'Bert':gen,
    'BugsBunny',gen,
    'Statler',gen
}

URIGenerator

A URI generator will parse the incoming request and return the value returned by the request metadata 'PATH_INFO'. If there is a query string specified, it will append the '?' character and the query string to the path.

'path':URIGenerator()

In the above example the URL:

http://www.example.com/foo/bar.html?bannanna=ear

will return the value:

/foo/bar.html?bannanna=ear

FunctionGenerator

A function generator takes a no-arg function and executes it, returning the function output. This can combine nicely with lambdas.

from datetime import datetime
entries = {
    'current':FunctionGenerator(lambda:datetime.now())
}

The above entry would place the current time (a datetime object) under the variable "current".

ConditionalAttributeGenerator (CAG)

A conditional attribute generator (cag) returns the value of a specified attribute if it exists and has a value that evaluates to true. Otherwise it will return None or an alternate specified value.

from django.conf import settings
entries = {
   'foo':ConditionalAttributeGenerator(settings,'foo','bar'),
   'baz':ConditionalAttributeGenerator(settings,'baz')
}

In the above example, the "foo" variable would evaluate to whatever has been set in settings.py as "foo" (the equivalent of saying settings.foo) or if the attribute hasn't been set or isn't true, the literal value "bar".

For the "baz" variable, the it will be the value of the "baz" attribute in settings, or None.

CookieGenerator

A cookie generator returns the value found in the specified cookie. If the cookie name is not specified in the constructor, the variable name will be used as the name of the cookie.

entries = {
    'cookie':CookieGenerator('monster'),
    'oreo':CookieGenerator()
}

In the above example, the value of cookie "monster" is assigned to the variable "cookie", and the value of cookie "oreo" is assigned to variable "oreo".

RequestAttributeGenerator (RAG)

A Request Attribute Generator, or RAG, returns the specified attribute value from the request object.

    'files':RequestAttributeGenerator('FILES')

The above example will map the request.FILES to the "files" variable.

AuthProfileGenerator

An AuthProfileGenerator will retrieve the instance of the specified auth profile (defined in settings by the AUTH_PROFILE_MODULE setting) that corresponds to the current user.

# settings.py
AUTH_PROFILE_MODULE = 'environment_example.Avatar'

# example.env
entries = {
    'avatar':AuthProfileGenerator()
}

See more about auth profiles here: http://www.djangoproject.com/documentation/authentication/#storing-additional-information-about-users

RequestParameterGenerator

Takes the data from the request.POST or request.GET dictionaries.

    'entries':RequestParameterGenerator()

The above entry will map the request parameters to the "entries" variable. So for request: http://www.example.com?foo=bar, the value of "entries" will be {'foo':'bar'}.