Installation & Setup

Prerequisites

To install Avocado and it's dependencies, it is assumed you have the latest versions of distribute (or setuptools) and Pip installed.

Install

pip install avocado

The hard dependencies which will auto-install include:

• Django 1.4+
• modeltree 1.1+
• django-jsonfield 0.9+
• South 0.7.6+

Optional Dependencies

For a bare-bones Avocado installation the following dependencies may be skipped, but peruse through to understand the purpose of each one listed.

Have a suggestion for additional metadata integration? File an issue on Avocado's GitHub repo.

Django "sites" Framework

Having this installed enables associating DataFields and/or DataConcepts to specific sites, or more specifically, deployments. For example, an internal and external deployment may exist for the same application, but only the internal deployment provides access to certain restricted fields for operational use.

Install by adding django.contrib.sites to INSTALLED_APPS.

django-guardian

This enables fine-grain control over who has permissions for various DataFields. Permissions can be defined at a user or group level.

Install by doing pip install django-guardian and adding guardian to INSTALLED_APPS.

django-haystack

What's having all this great descriptive data if no one can find it? Haystack provides search engine facilities for the metadata.

Install by doing pip install django-haystack and installing one of the supported search engine backends. The easiest to setup is Whoosh which is implemented in pure Python. Install it by doing pip install whoosh, then update your settings file with the following:

# Add haystack
INSTALLED_APPS = (
    ...
    'haystack',
)

# Specify Haystack's siteconf module. This is generally project-specific,
# but Avocado provides one to get started.
HAYSTACK_SITECONF = 'avocado.search_sites'

# Specify the engine
HAYSTACK_SEARCH_ENGINE = 'whoosh'

# Add engine-specific config. Whoosh uses a binary file to store it's data.
# Specify the path where the whoosh index should live. This should generally
# be ignored by version control
HAYSTACK_WHOOSH_PATH = '/path/to/whoosh.index'

SciPy

Avocado comes with a stats package for performing some rudimentary statistical, aggregation and clustering operations on the data. This is certainly not necessary for all data, but if there is a heavy emphasis on numerical data or the amount of data is quite large, the stats may come in handy.

Install by doing pip install numpy first (a dependency of SciPy), followed by pip install scipy. Note, there are a few dependencies for compilation, so review SciPy's installation instructions for more details.

openpyxl

Avocado comes with an export package for supporting various means of exporting data into different formats. One of those formats is the native Microsoft Excel 2007 .xlsx format. To support that, the openpyxl library is used.

Install by doing pip install openpyxl.

Read more about exporting in Avocado.

Configure

At a minimum, your INSTALLED_APPS should contain the following apps:

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.messages',
    'django.contrib.sessions',

    'modeltree',
    'avocado',
    'avocado.export',
    ...
)

ModelTree Setup

Avocado heavily relies on ModelTree for dynamically setting up joins between models. For consistency of joins, a default root model must be defined which acts as a reference point for constructing joins.

In addition to adding modeltree to the INSTALLED_APPS above, add the following to your project settings:

MODELTREES = {
    'default': {
        'model': 'myapp.SomeModel',
    },
}

Confirm that it works by running the preview subcommand that comes with ModelTree:

python manage.py modeltree preview

All of the models related to myapp.SomeModel will be printed to the console with various indentation levels. This represents the traversal depth. There should not be any surprises, but if there are models you would like to exclude, simply add the excluded_models key to the settings dict:

MODELTREES = {
    'default': {
        'model': 'myapp.SomeModel',
        'excluded_models': ['auth.User'],
    },
}

For greater control over how ModelTree traverses paths, read the docs.

Next: Getting Started