Developer manual

Make your app pluggable

The easy way to make your app pluggable is to use the paster template:

$ easy_install DjangoPluggableApp PasteScript
$ paster create -t django_app django-myapp

This will create a directory named django-myapp with the packaging stuff (setup.py, MANIFEST.in, etc.) and a subdirectory myapp with a ready to go django’s app.

Here the generated tree:

django-myapp
django-myapp/bootstrap.py
django-myapp/buildout.cfg
django-myapp/MANIFEST.in
django-myapp/myapp
django-myapp/myapp/__init__.py
django-myapp/myapp/media
django-myapp/myapp/media/myapp
django-myapp/myapp/media/myapp/README.txt
django-myapp/myapp/models.py
django-myapp/myapp/templates
django-myapp/myapp/templates/myapp
django-myapp/myapp/templates/myapp/base.html
django-myapp/myapp/tests
django-myapp/myapp/tests/__init__.py
django-myapp/myapp/tests/functionnal.py
django-myapp/myapp/tests/test_index.py
django-myapp/myapp/tests/test_medias.py
django-myapp/myapp/urls.py
django-myapp/myapp/views.py
django-myapp/setup.cfg
django-myapp/setup.py
django-myapp/test_project
django-myapp/test_project/__init__.py
django-myapp/test_project/media
django-myapp/test_project/media/README.txt
django-myapp/test_project/settings.py
django-myapp/test_project/templates
django-myapp/test_project/templates/base.html
django-myapp/test_project/urls.py

As you can see the template contain a testing project. At this time you can run tests using buildout:

$ python2.5 bootstrap.py -d
$ ./bin/buildout
$ ./bin/django-test myapp
Creating test database 'default'...
...
No fixtures found.
.
----------------------------------------------------------------------
Ran 1 test in 0.170s

OK
Destroying test database 'default'...

Or launch a dev server inside the testing project:

$ ./bin/django-serve

Entry point

If you don’t use the template, you just need to add an entry point to your setup.py:

      ],
      entry_points="""
      # -*- Entry points: -*-
      [django.pluggable_app]
      myapp = myapp:pluggableapp
      """,
      )

And create the corresponding function in myapp.__init__.py:

# -*- coding: utf-8 -*-
import os

try:
    from pluggableapp import PluggableApp
except ImportError:
    # pluggableapp is not installed
    pass


def pluggableapp(**kw):
    app = PluggableApp('myapp', distribution='django-myapp', **kw)
    app.append_app()
    app.register_pattern('', r'^myapp/', 'myapp.urls')
    app.register_media(__file__)
    app.insert_templates(__file__)
    # app.initialize_settings(MYAPP_KEY='myappvalue', MYAPP_OTHER='other')
    return app

This function instantiate a PluggableApp. Update a few settings values in place (see API bellow) and return the app.

PluggableApp api

class pluggableapp.PluggableApp(name, **kw)

classmethod append(setting_key, *values, **kwargs)

Append values to setting_key

append_app(app_name=None)

Append app_name to INSTALLED_APPS

initialize_settings(**kwargs)

Initialize some settings values if not already defined

classmethod insert(setting_key, *values, **kwargs)

Insert values to setting_key

insert_app_templates()

Insert app_dir/templates to TEMPLATE_DIRS

insert_templates(template_dir)

Insert template_dir to TEMPLATE_DIRS

register_media(media_dir=None)

Register a media directory. PluggableApp while create a symlink in MEDIA_ROOT for each subdirectory found

register_pattern(app_prefix, prefix, module=None)

Register an url pattern