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

Before committing changes to the package, make sure to update the version if needed.

|
 +- [package_root]
      |
      +- [package_dir]
      |    |
      |    +- __init__.py > __version__
      | 
      +- [...]
      |
      +- setup.py > setup.version

Command to build the package:

$ python setup.py sdist

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

Using the package

Follow the instructions for upgrading the package if the package has already been installed.

Installing the package

Push the package distribution to GitHub.

Add the package and version to requirements.txt in the project's root directory:

-e git://github.com/account_name/package_repo.git#egg=package_name

Replacing account_name, package_repo, and package_name in the URL with the appropriate values.

Install the package with pip. (Make sure that the project's virtual environment has been activated first.)

$ pip install -r requirements.txt

Upgrading the package

Update the version number in requirements.txt.

Run pip install -r requirements.txt

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.