Test & distribute

Running tests

In the terminal, we can run our test:

$ python manage.py test polls

Your project and your reusable app

After the previous tutorials, our project should look like this:

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    polls/
        __init__.py
        admin.py
        models.py
        static/
            polls/
                images/
                    background.gif
                style.css
        templates/
            polls/
                detail.html
                index.html
                results.html
        tests.py
        urls.py
        views.py
    templates/
        admin/
            base_site.html

Installing some prerequisites

The current state of Python packaging is a bit muddled with various tools. For this tutorial, we’re going to use setuptools to build our package. It’s the recommended packaging tool (merged with thedistribute fork). We’ll also be using pip to install and uninstall it. You should install these two packages now. If you need help, you can refer to how to install Django with pip. You can install setuptools the same way.

Packaging your app

1. First, create a parent directory for polls, outside of your Django project. Call this directory django-polls.

2. Move the polls directory into the django-polls directory.
3. Create a file django-polls/README.rst with the following contents:

   =====
   Polls
   =====
   
   Polls is a simple Django app to conduct Web-based polls. For each
   question, visitors can choose between a fixed number of answers.
   
   Detailed documentation is in the "docs" directory.
   
   Quick start
   -----------
   
   1. Add "polls" to your INSTALLED_APPS setting like this::
   
         INSTALLED_APPS = (
             ...
             'polls',
         )
   
   2. Include the polls URLconf in your project urls.py like this::
   
         url(r'^polls/', include('polls.urls')),
   
   3. Run `python manage.py syncdb` to create the polls models.
   
   4. Start the development server and visit http://127.0.0.1:8000/admin/
      to create a poll (you'll need the Admin app enabled).
   
   5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.

4. Create a django-polls/LICENSE file. Choosing a license is beyond the scope of this tutorial, but suffice it to say that code released publicly without a license is useless. Django and many Django-compatible apps are distributed under the BSD license; however, you’re free to pick your own license. Just be aware that your licensing choice will affect who is able to use your code.
5. Next we’ll create a setup.py file which provides details about how to build and install the app. A full explanation of this file is beyond the scope of this tutorial, but the setuptools docs have a good explanation. Create a file django-polls/setup.py with the following contents:

   import os
   from setuptools import setup
   
   README = open(os.path.join(os.path.dirname(__file__), 'README.rst')).read()
   
   # allow setup.py to be run from any path
   os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
   
   setup(
       name='django-polls',
       version='0.1',
       packages=['polls'],
       include_package_data=True,
       license='BSD License',  # example license
       description='A simple Django app to conduct Web-based polls.',
       long_description=README,
       url='http://www.example.com/',
       author='Your Name',
       author_email='yourname@example.com',
       classifiers=[
           'Environment :: Web Environment',
           'Framework :: Django',
           'Intended Audience :: Developers',
           'License :: OSI Approved :: BSD License', # example license
           'Operating System :: OS Independent',
           'Programming Language :: Python',
           'Programming Language :: Python :: 2.6',
           'Programming Language :: Python :: 2.7',
           'Topic :: Internet :: WWW/HTTP',
           'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
       ],
   )
   

6. Only Python modules and packages are included in the package by default. To include additional files, we’ll need to create a MANIFEST.in file. The setuptools docs referred to in the previous step discuss this file in more details. To include the templates, the README.rst and our LICENSE file, create a file django-polls/MANIFEST.in with the following contents:

   include LICENSE
   include README.rst
   recursive-include polls/static *
   recursive-include polls/templates *

7. It’s optional, but recommended, to include detailed documentation with your app. Create an empty directory django-polls/docs for future documentation. Add an additional line todjango-polls/MANIFEST.in:

   recursive-include docs *

   Note that the docs directory won’t be included in your package unless you add some files to it. Many Django apps also provide their documentation online through sites like readthedocs.org.
8. Try building your package with python setup.py sdist (run from inside django-polls). This creates a directory called dist and builds your new package, django-polls-0.1.tar.gz.

Using your own package

1. To install the package, use pip

   pip install --user django-polls/dist/django-polls-0.1.tar.gz

2. To uninstall the package, use pip:

   pip uninstall django-polls