Ticket #16671: tutorial05.diff

File tutorial05.diff, 9.9 KB (added by stumbles, 9 years ago)

First draft of tutorial 5

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