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:

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

Changed in Avocado 2.3

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==2.0.0 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==2.4.1, then update your settings file with the following:

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

HAYSTACK_CONNECTIONS = {
    'default': {
        'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
        'PATH': '/path/to/whoosh.index',
    }
}

# For real-time updates of the search indexes. If real-time is too process
# heavy, check out a queue-based version:
# http://django-haystack.readthedocs.org/en/latest/best_practices.html#use-of-a-queue-for-a-better-user-experience
HAYSTACK_SIGNAL_PROCESSOR = 'haystack.signals.RealtimeSignalProcessor'

For migrations from 1.x to 2.x, view the Haystack migration guide.

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',
    ...
)

ModelTree Setup

Avocado heavily relies on ModelTree for dynamically query generation. 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