Ticket #16671: tutorial05.2.diff

File tutorial05.2.diff, 9.9 KB (added by stumbles, 13 years ago)
  • AUTHORS

    diff -r 548df236b2cc AUTHORS
    a b  
    357357    Christian Metts
    358358    michal@plovarna.cz
    359359    Slawek Mikula <slawek dot mikula at gmail dot com>
     360    Katie Miller <katie@sub50.com>
    360361    Shawn Milochik <shawn@milochik.com>
    361362    mitakummaa@gmail.com
    362363    mmarshall
     
    474475    Johan C. Stöver <johan@nilling.nl>
    475476    Nowell Strite <http://nowell.strite.org/>
    476477    Thomas Stromberg <tstromberg@google.com>
     478    Ben Sturmfels <ben@stumbles.id.au>
    477479    Pascal Varet
    478480    SuperJared
    479481    Radek Švarz <http://www.svarz.cz/translate/>
  • docs/intro/tutorial04.txt

    diff -r 548df236b2cc docs/intro/tutorial04.txt
    a b  
    322322For full details on generic views, see the :doc:`generic views documentation
    323323</topics/http/generic-views>`.
    324324
    325 Coming soon
    326 ===========
    327 
    328 The tutorial ends here for the time being. Future installments of the tutorial
    329 will cover:
    330 
    331     * Advanced form processing
    332     * Using the RSS framework
    333     * Using the cache framework
    334     * Using the comments framework
    335     * Advanced admin features: Permissions
    336     * Advanced admin features: Custom JavaScript
    337 
    338 In the meantime, you might want to check out some pointers on :doc:`where to go
    339 from here </intro/whatsnext>`
     325When you're comfortable, read :doc:`part 5 of this tutorial
     326</intro/tutorial05>` to learn about turning Polls into a reusable app.
  • new file docs/intro/tutorial05.txt

    diff -r 548df236b2cc docs/intro/tutorial05.txt
    - +  
     1=====================================
     2Writing your first Django app, part 5
     3=====================================
     4
     5This tutorial begins where :doc:`Tutorial 4 </intro/tutorial04>` left
     6off. We'll be turning our Web-poll into a stand-alone Python package.
     7
     8.. Outline:
     9
     10.. * motivation
     11..     * what is a python package?
     12..     * what is a django app?
     13..     * what is a reusable app?
     14
     15.. * preparing
     16..     * moving templates into your app
     17..     * parent directory
     18..     * adding package boilerplate
     19..     * link to packaging docs
     20..     * package builder
     21
     22.. * using the package
     23..     * how to install
     24
     25.. * publishing
     26..     * options for publishing
     27..     * link to docs on PyPI
     28
     29Python packages and reusable apps
     30==================================
     31
     32Django really is just Python. This means that you can make use of existing
     33Python packages in your project. You can also take parts of your projects and
     34reuse or share them.
     35
     36.. note::
     37
     38    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     39    is a way of grouping related Python code for easy reuse. A package contains
     40    one or more files of Python code (also known as "modules").
     41
     42    A Django *app* is nothing more than a Python package intended for use in a
     43    Django project. An app may also use common Django conventions, such as
     44    having a ``models.py`` file.
     45
     46One of Django's most powerful features is the concept of *reusable apps*. The
     47idea is that rather than rebuilding every new Django project from scratch, you
     48can make use of existing packages that you, and others, have written.
     49
     50In fact, we're already halfway to a reusable app. The Polls app we've been working on is
     51already a Python package. We know this because it can be imported with ``import
     52polls`` (since it contains an ``__init__.py`` file). In the previous tutorials,
     53we began making Polls reusable by decoupling it from the project-level URLconf.
     54
     55In this tutorial, we'll take further steps to make the app easily to use in new
     56projects and ready to publish for others to install and use.
     57
     58Completing your reusable app
     59============================
     60
     61Currently the
     62
     63Inside ``mysite/polls``, create the directory ``templates`` and *inside* that,
     64the directory ``polls``. Move the ``index.html`` and ``detail.html`` templates
     65into ``templates/polls``. This allows the app's templates to be distributed
     66with the app. Confirm that your poll Web site still works correctly.
     67
     68Your project should now look like this::
     69
     70    mysite/
     71        polls/
     72            admin.py
     73            templates/
     74                polls/
     75                    detail.html
     76                    index.html
     77            __init__.py
     78            models.py
     79            tests.py
     80            urls.py
     81            views.py
     82        __init__.py
     83        manage.py
     84        settings.py
     85        urls.py
     86
     87.. NOTE:: Why create a ``polls`` directory under templates when we're already
     88   inside the Polls app? This directory is needed to avoid conflicts because of
     89   how Django's ``app_directories`` template loader works.
     90
     91You now have a package that could be copied into new Django projects and
     92immediately reused. It's not yet ready to be published though. For that, we
     93need to package the app to make it easy for others to install.
     94
     95Packaging for external use
     96==========================
     97
     98Python packaging isn't as hard as it sounds, especially for such a small app.
     99
     100    * Firstly, create a parent directory for ``polls``, outside of your Django
     101      project. Call this directory ``django-polls``.
     102
     103    * Move the ``polls`` directory into the ``django-polls`` directory.
     104
     105    * Create a file ``django-polls/README.txt``::
     106
     107        =====
     108        Polls
     109        =====
     110
     111        Polls is a simple Django app to conduct Web-based polls. For each
     112        question, visitors can choose between a fixed number of answers.
     113
     114    * Create a file ``django-polls/setup.py`` with the following contents::
     115
     116          from distutils.core import setup
     117
     118          setup(
     119                name='django-polls',
     120                version='0.1',
     121                packages=['polls',],
     122                long_description=open('README.txt').read(),
     123                url='http://www.example.com/',
     124                author='Your Name',
     125                author_email='yourname@example.com',
     126          )
     127
     128    * Try building your package with ``python setup.py sdist`` (run from inside
     129      ``django-polls``. This creates a directory called ``dist`` and builds
     130      your new package, ``django-polls-0.1.tar.gz``.
     131
     132For more information on packaging, see `The Hitchhiker's Guide to Packaging
     133<http://guide.python-distribute.org/quickstart.html>`_.
     134
     135Using your own package
     136======================
     137
     138Since we moved the ``polls`` directory out of the project, it's no longer
     139working. We'll now fix this by installing our new ``django-polls`` package.
     140
     141.. NOTE:: The following steps install ``django-polls`` as a system library. In
     142   general, it's best to avoid messing with your system libraries to avoid
     143   breaking things. For this simple example though, the risk is low and it will
     144   help with understanding packaging. We'll explain how to uninstall in
     145   step 4.
     146
     147   For experienced users, a neater way to manage your packages is to use
     148   "virtualenv" (see below).
     149
     1501. Inside ``django-polls/dist``, untar the new package
     151   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     152   you're using Windows, you can download the command-line tool bsdtar_ to do
     153   this, or you can use a GUI-based tool such as 7-zip_.
     154
     1552. Change into the directory created in step 1 (e.g. ``cd django-polls``).
     156
     1573. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
     158   command ``sudo python setup.py install`` at the shell prompt.  If you're
     159   using Windows, start up a command shell with administrator privileges and
     160   run the command ``setup.py install``.
     161
     162   With luck, your Django project should now work correctly again. Run the
     163   server again to confirm this.
     164
     1654. To uninstall the package, delete the directory ``polls`` and the file
     166   ``django_polls-0.1.egg-info`` from your system libraries. On GNU/Linux and
     167   Mac OS these files live in ``/usr/local/lib/python2.X/dist-packages``, and
     168   on Windows, in ``C:\Python2X\Lib\site-packages`` (where *X* is the Python
     169   minor version number). You will need administrator privileges.
     170
     171.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
     172.. _7-zip: http://www.7-zip.org/
     173
     174Publishing your app
     175===================
     176
     177Now that we've packaged and tested ``django-polls``, it's ready to share with
     178the world! If this wasn't just an example, you might now want to:
     179
     180    * Email the package to a friend.
     181
     182    * Upload the package on your Web site.
     183
     184    * Post the package on a public repository, such as `The Python Package
     185      Index (PyPI)
     186      <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
     187
     188For more information on PyPI, see the `Quickstart
     189<http://guide.python-distribute.org/quickstart.html#register-your-package-with-the-python-package-index-pypi>`_
     190section of The Hitchhiker's Guide to Packaging.
     191
     192Installing Python packages with virtualenv
     193==========================================
     194
     195Earlier, we installed the Polls app as a system library. This has some
     196disadvantages:
     197
     198    * Modifying the system libraries can affect other Python software on your
     199      system.
     200   
     201    * You won't be able to run multiple version of this package (or others with
     202      the same name).
     203
     204Typically, these situations only arise once you're maintaining several Django
     205projects. When they do, the best solution is to use `virtualenv
     206<http://www.virtualenv.org/>`_. This tool allows you to maintain multiple
     207isolated Python environments, each with its own copy of the libraries and
     208package namespace.
     209
     210Further information
     211===================
     212
     213For more on writing reusable apps, see `What is a reusable app?
     214<http://ericholscher.com/projects/django-conventions/app/>`_ by Eric
     215Holsher. For a collection of reusable apps to use in your own projects, see the
     216`Pinax <http://pinaxproject.com/>`_ project.
     217
     218The tutorial ends here for the time being. In the meantime, you might want to
     219check out some pointers on :doc:`where to go from here </intro/whatsnext>`.
Back to Top