Packaging Stand-Alone Django Apps

Directory structure

The app goes in a directory outside of any Django web project. If the app is addresses, structure it littled-addresses/addresses/.

Try to avoid naming conflicts, of course. (Check resources like PyPI.)

• Create README.rst
  • In the package root, e.g. littled-addresses/README.rst.
  • Sample contents at How to Write Reusable Apps—Packaging your app
• Create LICENSE file in the package root.
  • Django itself uses the BSD license.
• Create setup.py in the project root.
  • Sample at How to Write Reusable Apps—Packaging your app
  • More complete documentation at setuptools docs.
• Create MANIFEST.in in the project root.
  • This includes files other than Python modules and packages.
• Create a docs directory
  • Include it in MANIFEST.in with recursive-include docs *

Building the package

$ python setup.py sdist

• Run from the package root directory.
• Creates a dist directory which contains the (zipped) package.

Using the package

Installing the package

$ pip install --user django-addresses/dist/django-addresses-0.1.tar.gz

This installs the package on a system as a user library.

Or, using littled-addresses as an example, and installing from within the project directory:
N.B. user site-packages are not visible in virtualenvs. Also, the .tar.gz vs.zip extension just depends on however it was compressed.

$ sudo pip install dist/addresses-0.1.zip

It can now be referenced in other Django projects.

On Windows, when the package is installed for a specific user, the files are placed in ~/AppData/Roaming/Python[version]/site-packages/.

Upgrading the package

$ pip install --user --upgrade django-addresses/dist/django-addresses-0.2.tar.gz

This is essential if the models in the app change. Uninstalling the app will remove the migrations, causing any Django projects that use the app to not be capable of syncing up their database structure with the changes to the models.

Using the package in a project

Assuming that the package is

|
 +-- django-addresses
      |
      +-- addresses
      |    |
      |    +- [...]
      |
      [...]

In the project's settings.py:

INSTALLED_APPS = (
        ...
        'addresses',
    )

Then from the web project root:

$ python manage.py makemigrations addresses
$ python manage.py migrate addresses

To reference the objects in a model within the web project:

class Person(models.Model):
    address = models.ForeignKey('addresses.Address')
    # ...

Resetting migrations

In the case that migrations have been made, and you want to rebuild the database objects from scratch:

$ python manage.py migrate --fake addresses zero
$ python manage.py migrate addresses

• The first command sets the migration counter to before the initial (0001) migration.
• The 2nd command migrates the models at the state of the latest migration.

Uninstalling the package

$ pip uninstall django-addresses

Uninstalling a stand-along package will remove the migrations for that package. Without the migrations, Django projects won't be able to sync to any changes to the app's models. It's better to upgrade than to uninstall and install.