Installation

Install GDAPS in your Python virtual environment using your favourite package manager. If you want to create plugins, install cookiecutter too. We'll use pip here, but you can use any other too.

python -m pip install gdaps
python -m pip install cookiecutter

Create a Django application as usual: django-admin startproject myproject.

Project name

First, set a variable named PROJECT_NAME in your settings.py:

PROJECT_NAME = "myproject"

This is a (machine) name for your project. Django itself does not provide such a name. It will be used in various places, and must be a valid python identifier.

Note

PROJECT_NAME is roughly what Django means with ROOT_URLCONF[0], but GDAPS requires it to be set explicitly.

Project title

Same goes for the title of the project. You will often need this in various places, so GDAPS requires it too:

PROJECT_TITLE = "My cool project"

Making INSTALLED_APPS more dynamic

INSTALLED_APPS is fixed within Django, but we want plugins to change that, and inject dependencies dynamically. Add "gdaps" to the INSTALLED_APPS section, and call PluginManager.alter_installed_apps() right below it:

from gdaps.pluginmanager import PluginManager

PROJECT_NAME = "myproject"
INSTALLED_APPS = [
    # ... standard Django apps and GDAPS
    "gdaps",
]
# The following line is important: It loads all plugins from setuptools
# entry points and from the directory named 'myproject.plugins':
INSTALLED_APPS += PluginManager.alter_installed_apps(INSTALLED_APPS, f"{PROJECT_NAME}.plugins")

This allows each installed plugin to alter the INSTALLED_APPS list, and e.g. insert their own dependencies into it at the correct position.

The second argument is the "plugin path". You can use whatever you want, but we recommend that you use {PROJECT_NAME}.plugins here. Basically, this is all you really need so far, for a minimal working GDAPS-enabled Django application. See usage for how to use GDAPS.

URL handling

Now add the URL path for GDAPS, so it can add plugins' URLs automatically to the global urlpattern.

# urls.py
from gdaps.pluginmanager import PluginManager

urlpatterns = PluginManager.urlpatterns() + [
    # ... add your fixed URL patterns here, like "admin/", etc.
]

This way each plugin can have an urlpatterns variable in urls.py, and all are merged together. However, by now, the plugin order is not determined, so urlpatterns too are not in a deterministically determined order. This could lead to problems, depending on your application design, so keep that in mind when designing plugins.

Logging

Django does not write loggings to the command line automatically. GDAPS uses various levels of logging. It is recommended that you create a LOGGING section in settings.py for GDAPS:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "gdaps": {"handlers": ["console"], "level": "INFO", "propagate": True},
    },
}

This will output all GDAPS log messages to the console.