Ticket #16671: tutorial05.5.diff

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

Reworded first section on reusable apps.

  • 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/index.txt

    diff -r 548df236b2cc docs/index.txt
    a b  
    4242      :doc:`Part 1 <intro/tutorial01>` |
    4343      :doc:`Part 2 <intro/tutorial02>` |
    4444      :doc:`Part 3 <intro/tutorial03>` |
    45       :doc:`Part 4 <intro/tutorial04>`
     45      :doc:`Part 4 <intro/tutorial04>` |
     46      :doc:`Part 5 <intro/tutorial05>`
    4647
    4748The model layer
    4849===============
  • docs/intro/index.txt

    diff -r 548df236b2cc docs/intro/index.txt
    a b  
    1313   tutorial02
    1414   tutorial03
    1515   tutorial04
     16   tutorial05
    1617   whatsnext
    1718   
    1819.. seealso::
     
    3334    .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
    3435    .. _dive into python: http://diveintopython.org/
    3536    .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
    36     .. _books about Python: http://wiki.python.org/moin/PythonBooks
    37  No newline at end of file
     37    .. _books about Python: http://wiki.python.org/moin/PythonBooks
  • 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 you can
     7reuse and share.
     8
     9.. Outline:
     10
     11.. * motivation
     12..     * what is a python package?
     13..     * what is a django app?
     14..     * what is a reusable app?
     15
     16.. * preparing
     17..     * moving templates into your app
     18..     * parent directory
     19..     * adding package boilerplate
     20..     * link to packaging docs
     21..     * package builder
     22
     23.. * using the package
     24..     * how to install
     25
     26.. * publishing
     27..     * options for publishing
     28..     * link to docs on PyPI
     29
     30Python packages and reusable apps
     31==================================
     32
     33Django really is just Python. This means that you can make use of existing
     34Python packages and Django apps in your project.
     35
     36The concept of piecing together projects out of *reusable apps* is one of
     37Django's most powerful features. Doing so, you avoid solving the same problems
     38over again. The only parts you need to write are those that make your project
     39unique.
     40
     41.. note::
     42
     43    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     44    is a way of grouping related Python code for easy reuse. A package contains
     45    one or more files of Python code (also known as "modules").
     46
     47    A package can be imported with ``import foo.bah`` or ``from foo import
     48    bar``. For a directory (like ``polls``) to be a package, it must contain a
     49    special file ``__init__.py``, even if the file is empty.
     50
     51    A Django *app* is just a Python package that is specifically intended for
     52    use in a Django project. An app may also use common Django conventions,
     53    such as having a ``models.py`` file.
     54
     55    Later on we use the term *packaging* to describe the process of making a
     56    Python package easy for others to install. It can be little confusing, we
     57    know.
     58
     59Let's say you had written a Polls app and wanted to use it in a brand new
     60project. How do you make it easily reusable? It just so happens that you're
     61well on the way already.
     62
     63In the previous tutorials, we began making Polls reusable by decoupling it from
     64the project-level URLconf. In this tutorial, we'll take further steps to make
     65the app easily to use in new projects and ready to publish for others to
     66install and use.
     67
     68Completing your reusable app
     69============================
     70
     71The Polls app we've been working on is already a Python package (thanks to the
     72``__init__.py`` inside ``polls``). That's a good start.
     73
     74We can't just pick up this package and drop it into a new project yet
     75though. The Polls templates are currently stored in the project-wide
     76``templates`` directory. To make the app self-contained, we need to store these
     77templates within the ``polls`` directory.
     78
     79Inside ``mysite/polls``, create the directory ``templates`` and *inside* that,
     80the directory ``polls``. Move the ``index.html`` and ``detail.html`` templates
     81into ``templates/polls``. This allows the app's templates to be distributed
     82with the app. Confirm that your poll Web site still works correctly.
     83
     84Your project should now look like this::
     85
     86    mysite/
     87        polls/
     88            admin.py
     89            templates/
     90                polls/
     91                    detail.html
     92                    index.html
     93            __init__.py
     94            models.py
     95            tests.py
     96            urls.py
     97            views.py
     98        __init__.py
     99        manage.py
     100        settings.py
     101        urls.py
     102
     103.. NOTE:: Why create a ``polls`` directory under templates when we're already
     104   inside the Polls app? This directory is needed to avoid conflicts because of
     105   how Django's ``app_directories`` template loader works.
     106
     107You now have a package that could be copied into new Django projects and
     108immediately reused. It's not yet ready to be published though. For that, we
     109need to package the app to make it easy for others to install.
     110
     111Packaging your app
     112==================
     113
     114Python packaging isn't as hard as it sounds, especially for such a small app.
     115
     1161. Firstly, create a parent directory for ``polls``, outside of your Django
     117   project. Call this directory ``django-polls``.
     118
     1192. Move the ``polls`` directory into the ``django-polls`` directory.
     120
     1213. Create a file ``django-polls/README.txt`` with the following contents::
     122
     123       =====
     124       Polls
     125       =====
     126
     127       Polls is a simple Django app to conduct Web-based polls. For each
     128       question, visitors can choose between a fixed number of answers.
     129
     130       Detailed documentation is in the "docs" directory.
     131
     132       Quick start
     133       -----------
     134
     135       1. Add "polls" to your INSTALLED_APPS setting like this::
     136
     137              INSTALLED_APPS = (
     138                  ...
     139                  'polls',
     140              )
     141
     142       2. Include the polls URLconf in your project urls.py like this::
     143
     144              (r'^polls/', include('polls.urls')),
     145
     146       3. Run `python manage.py syncdb` to create the polls models.
     147
     148       4. Start the development server and visit http://127.0.0.1:8000/admin/
     149          to create a poll (you'll need the Admin app enabled).
     150
     151       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
     152
     153
     1545. Create a file ``django-polls/setup.py`` with the following contents::
     155
     156    from distutils.core import setup
     157
     158    setup(
     159        name='django-polls',
     160        version='0.1',
     161        packages=['polls',],
     162        license='',
     163        long_description=open('README.txt').read(),
     164        url='http://www.example.com/',
     165        author='Your Name',
     166        author_email='yourname@example.com',
     167    )
     168
     1696. It's optional, but recommended, to include detailed documentation with
     170   your app. Create an empty directory ``django-polls/docs`` for future
     171   documentation. Create a file ``django-polls/MANIFEST.in`` with the following
     172   contents::
     173
     174       recursive-include docs *
     175
     176   This instruction ensures that the ``docs`` directory is included in the
     177   package.
     178
     1797. Try building your package with ``python setup.py sdist`` (run from inside
     180   ``django-polls``. This creates a directory called ``dist`` and builds your
     181   new package, ``django-polls-0.1.tar.gz``.
     182
     183For more information on packaging, see `The Hitchhiker's Guide to Packaging
     184<http://guide.python-distribute.org/quickstart.html>`_.
     185
     186Using your own package
     187======================
     188
     189Since we moved the ``polls`` directory out of the project, it's no longer
     190working. We'll now fix this by installing our new ``django-polls`` package.
     191
     192.. NOTE:: The following steps install ``django-polls`` as a system library. In
     193   general, it's best to avoid messing with your system libraries to avoid
     194   breaking things. For this simple example though, the risk is low and it will
     195   help with understanding packaging. We'll explain how to uninstall in
     196   step 4.
     197
     198   For experienced users, a neater way to manage your packages is to use
     199   "virtualenv" (see below).
     200
     2011. Inside ``django-polls/dist``, untar the new package
     202   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     203   you're using Windows, you can download the command-line tool bsdtar_ to do
     204   this, or you can use a GUI-based tool such as 7-zip_.
     205
     2062. Change into the directory created in step 1 (e.g. ``cd django-polls``).
     207
     2083. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
     209   command ``sudo python setup.py install`` at the shell prompt.  If you're
     210   using Windows, start up a command shell with administrator privileges and
     211   run the command ``setup.py install``.
     212
     213   With luck, your Django project should now work correctly again. Run the
     214   server again to confirm this.
     215
     2164. To uninstall the package, delete the directory ``polls`` and the file
     217   ``django_polls-0.1.egg-info`` from your system libraries. On GNU/Linux and
     218   Mac OS these files live in ``/usr/local/lib/python2.X/dist-packages``, and
     219   on Windows, in ``C:\Python2X\Lib\site-packages`` (where *X* is the Python
     220   minor version number). You will need administrator privileges.
     221
     222.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
     223.. _7-zip: http://www.7-zip.org/
     224
     225Publishing your app
     226===================
     227
     228Now that we've packaged and tested ``django-polls``, it's ready to share with
     229the world! If this wasn't just an example, you could now:
     230
     231    * Email the package to a friend.
     232
     233    * Upload the package on your Web site.
     234
     235    * Post the package on a public repository, such as `The Python Package
     236      Index (PyPI)
     237      <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
     238
     239For more information on PyPI, see the `Quickstart
     240<http://guide.python-distribute.org/quickstart.html#register-your-package-with-the-python-package-index-pypi>`_
     241section of The Hitchhiker's Guide to Packaging. One detail this guide mentions
     242is choosing the license under which your code is distributed.
     243
     244Installing Python packages with virtualenv
     245==========================================
     246
     247Earlier, we installed the Polls app as a system library. This has some
     248disadvantages:
     249
     250    * Modifying the system libraries can affect other Python software on your
     251      system.
     252
     253    * You won't be able to run multiple version of this package (or others with
     254      the same name).
     255
     256Typically, these situations only arise once you're maintaining several Django
     257projects. When they do, the best solution is to use `virtualenv
     258<http://www.virtualenv.org/>`_. This tool allows you to maintain multiple
     259isolated Python environments, each with its own copy of the libraries and
     260package namespace.
     261
     262Further information
     263===================
     264
     265For more on writing reusable apps, see `What is a reusable app?
     266<http://ericholscher.com/projects/django-conventions/app/>`_ by Eric
     267Holsher. For a collection of reusable apps to use in your own projects, see the
     268`Pinax <http://pinaxproject.com/>`_ project.
     269
     270The tutorial ends here for the time being. In the meantime, you might want to
     271check out some pointers on :doc:`where to go from here </intro/whatsnext>`.
Back to Top