====================================
Reusable Django apps with setuptools
====================================

.. contents::
    :backlinks: none

This is yet another approach on enabling Django to load reusable, pluggable,
egg-based applications without changing the Django sourcecode. Think of
plugins or components, e.g. django-registration, django-threadedcomments or
django-tagging.

It uses setuptools for finding, handling and loading egg-based Python modules
with a specific `entry point`_, e.g. ``'django.apps'``.

`Egg-based Python modules`_ (a.k.a. eggs) are compressed packaged Python modules
like Django apps. Every Django app can be converted to an egg distribution by
using a special setup.py file.

Installation
============

Get the source from the application site at::

    http://code.google.com/p/django-reusableapps/

To install *reusableapps*, follow these steps:

1. Follow the instructions in the `INSTALL file`_.
2. Add ``import reusableapps`` to the top of your `settings file`_.
3. Add a new setting to your `settings file`_, a list of locations of
   reusable apps, in search order. Note that these paths should use
   Unix-style forward slashes, even on Windows.
   
   For example::
   
     REUSABLE_APPS_DIRS = (
         '/home/jannis/.local',
         '/Users/Jannis/Code/eggs',
         '/usr/share/django/apps',
         'C:/www/django/apps',
     )
   
4. Add to the last line of your settings file (after the INSTALLED_APPS_ 
   and REUSABLE_APPS_DIRS setting)::
   
     INSTALLED_APPS = reusableapps.search(REUSABLE_APPS_DIRS, INSTALLED_APPS)

Putting it together
-------------------

Once you finished with above installation instructions, your `settings file`_
should look something like this::

    import reusableapps
    
    # ...
    
    REUSABLE_APPS_DIRS = (
        '/home/jannis/.local',
        '/Users/Jannis/Code/eggs',
        '/usr/share/django/apps',
        'C:/www/django/apps',
    )

    INSTALLED_APPS = (
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.sites',
        'myproject.myapp',
    )

    INSTALLED_APPS = reusableapps.search(REUSABLE_APPS_DIRS, INSTALLED_APPS)

You can then put reusable, pluggable, egg-based Django apps in one of the
directories in ``REUSABLE_APPS_DIRS``.

Using templates from egg-based Django apps
------------------------------------------

If you want to use templates from a egg-based Django app please add
``'django.template.loaders.eggs.load_template_source'`` to the TEMPLATE_LOADERS_
setting.

.. _INSTALL file: http://django-reusableapps.googlecode.com/svn/trunk/INSTALL.rst
.. _settings file: http://docs.djangoproject.com/en/dev/ref/settings/
.. _INSTALLED_APPS: http://docs.djangoproject.com/en/dev/ref/settings/#installed-apps
.. _TEMPLATE_LOADERS: http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders
.. _entry point: http://peak.telecommunity.com/DevCenter/setuptools#dynamic-discovery-of-services-and-plugins
.. _Egg-based Python modules: http://peak.telecommunity.com/DevCenter/PythonEggs

Adding support for *django-reusableapps* to your own Django app
===============================================================

If you want to support django-reusableapps in your own Django app, you need
to modify your existing setup.py to import the setup function from the
setuptools instead the from the distutils::

    from setuptools import setup

Furthermore you need to add an 'entry point' to the setup keywords::

    entry_points={'django.apps': 'myapp = myapp'},

where my ``myapp`` is the name of your Django app, e.g. ``registration``.
A full example can be found at setup-example.py_ and should be copied to
the parent directory of your app as ``setup.py``. You are then able to create
an egg file with of this app.

.. _setup-example.py: http://django-reusableapps.googlecode.com/svn/trunk/docs/setup-example.py

Creating egg files of reuasable Django apps
===========================================

Once you have a proper setup.py in the parent directory of your Django app,
you can run::

    python setup.py bdist_egg

to build a egg file of it. It will be created in the ``dist`` directory and
have a filename like ``dummyapp-0.1-py2.5.egg``. You can then distribute it
and use it by placing it in one of the ``REUSABLE_APPS_DIRS`` of your Django
project.

Support
=======

Please leave your `questions and problems`_ on the `designated Google Code site`_.

.. _designated Google Code site: http://code.google.com/p/django-reusableapps/
.. _questions and problems: http://code.google.com/p/django-reusableapps/issues/
