Ticket #16671: tutorial05.18.diff

File tutorial05.18.diff, 19.3 KB (added by Tim Graham, 12 years ago)

  • AUTHORS 

    diff --git a/AUTHORS b/AUTHORS
index 5799b94..6f9b410 100644
    a b answer newbie questions, and generally made Django that much better:  
    380380    Christian Metts
    381381    michal@plovarna.cz
    382382    Slawek Mikula <slawek dot mikula at gmail dot com>
     383    Katie Miller <katie@sub50.com>
    383384    Shawn Milochik <shawn@milochik.com>
    384385    mitakummaa@gmail.com
    385386    Taylor Mitchell <taylor.mitchell@gmail.com>
    … … answer newbie questions, and generally made Django that much better:  
    510511    Johan C. Stöver <johan@nilling.nl>
    511512    Nowell Strite <http://nowell.strite.org/>
    512513    Thomas Stromberg <tstromberg@google.com>
     514    Ben Sturmfels <ben@sturm.com.au>
    513515    Travis Swicegood <travis@domain51.com>
    514516    Pascal Varet
    515517    SuperJared

  • docs/index.txt 

    diff --git a/docs/index.txt b/docs/index.txt
index 5055edf..a6d9ed2 100644
    a b Are you new to Django or to programming? This is the place to start!  
    4646  :doc:`Part 3 <intro/tutorial03>` |
    4747  :doc:`Part 4 <intro/tutorial04>`
    4848
     49* **Advanced Tutorials:**
     50  :doc:`How to write reusable apps <intro/reusable-apps>`
     51
    4952The model layer
    5053===============
    5154

  • docs/intro/index.txt 

    diff --git a/docs/intro/index.txt b/docs/intro/index.txt
index 19290a5..afb1825 100644
    a b place: read this material to quickly get up and running.  
    66
    77.. toctree::
    88   :maxdepth: 1
    9    
     9
    1010   overview
    1111   install
    1212   tutorial01
    1313   tutorial02
    1414   tutorial03
    1515   tutorial04
     16   reusable-apps
    1617   whatsnext
    17    
     18
    1819.. seealso::
    1920
    2021    If you're new to Python_, you might want to start by getting an idea of what
    2122    the language is like. Django is 100% Python, so if you've got minimal
    2223    comfort with Python you'll probably get a lot more out of Django.
    23    
     24
    2425    If you're new to programming entirely, you might want to start with this
    2526    `list of Python resources for non-programmers`_
    26    
     27
    2728    If you already know a few other languages and want to get up to speed with
    2829    Python quickly, we recommend `Dive Into Python`_ (also available in a
    2930    `dead-tree version`_). If that's not quite your style, there are quite
    3031    a few other `books about Python`_.
    31    
     32
    3233    .. _python: http://python.org/
    3334    .. _list of Python resources for non-programmers: http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
    3435    .. _dive into python: http://diveintopython.net/
    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

  • new file docs/intro/reusable-apps.txt 

    diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
new file mode 100644
index 0000000..90e91c8
    - +  
     1=============================================
     2Advanced tutorial: How to write reusable apps
     3=============================================
     4
     5This advanced tutorial begins where :doc:`Tutorial 4 </intro/tutorial04>` left
     6off. We'll be turning our Web-poll into a standalone Python package you can
     7reuse in new projects and share with other people.
     8
     9If you haven't recently completed Tutorials 1–4, we encourage you to review
     10these so that your example project matches the one described below.
     11
     12.. Outline:
     13
     14.. * motivation
     15..     * what is a python package?
     16..     * what is a django app?
     17..     * what is a reusable app?
     18
     19.. * preparing
     20..     * moving templates into your app
     21..     * parent directory
     22..     * adding package boilerplate
     23..     * link to packaging docs
     24..     * package builder
     25
     26.. * using the package
     27..     * how to install
     28
     29.. * publishing
     30..     * options for publishing
     31..     * link to docs on PyPI
     32
     33Reusability matters
     34===================
     35
     36It's a lot of work to design, build, test and maintain a web application. Many
     37Python and Django projects share common problems. Wouldn't it be great if we
     38could save some of this repeated work?
     39
     40Reusability is the way of life in Python. `The Python Package Index (PyPI)
     41<http://guide.python-distribute.org/contributing.html#pypi-info>`_ has a vast
     42range of packages you can use in your own Python programs. Check out `Django
     43Packages <http://www.djangopackages.com>`_ for existing reusable apps you could
     44incorporate in your project. Django itself is also just a Python package. This
     45means that you can take existing Python packages or Django apps and compose
     46them into your own web project. You only need to write the parts that make
     47your project unique.
     48
     49Let's say you were starting a new project that needed a polls app like the one
     50we've been working on. How do you make this app reusable? Luckily, you're well
     51on the way already. In :doc:`Tutorial 3 </intro/tutorial03>`, we saw how we
     52could decouple polls from the project-level URLconf using an ``include``.
     53In this tutorial, we'll take further steps to make the app easy to use in new
     54projects and ready to publish for others to install and use.
     55
     56.. admonition:: Package? App?
     57
     58    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     59    provides a way of grouping related Python code for easy reuse. A package
     60    contains one or more files of Python code (also known as "modules").
     61
     62    A package can be imported with ``import foo.bar`` or ``from foo import
     63    bar``. For a directory (like ``polls``) to form a package, it must contain
     64    a special file ``__init__.py``, even if this file is empty.
     65
     66    A Django *app* is just a Python package that is specifically intended for
     67    use in a Django project. An app may also use common Django conventions,
     68    such as having a ``models.py`` file.
     69
     70    Later on we use the term *packaging* to describe the process of making a
     71    Python package easy for others to install. It can be a little confusing, we
     72    know.
     73
     74Completing your reusable app
     75============================
     76
     77After the previous tutorials, our project should look like this::
     78
     79    mysite/
     80        manage.py
     81        mysite/
     82            __init__.py
     83            settings.py
     84            urls.py
     85            wsgi.py
     86        polls/
     87            admin.py
     88            __init__.py
     89            models.py
     90            tests.py
     91            urls.py
     92            views.py
     93
     94You also have a directory somewhere called ``mytemplates`` which you created in
     95:doc:`Tutorial 2 </intro/tutorial02>`. You specified its location in the
     96TEMPLATE_DIRS setting. This directory should look like this::
     97
     98    mytemplates/
     99        admin/
     100            base_site.html
     101        polls/
     102            detail.html
     103            index.html
     104            results.html
     105
     106The polls app is already a Python package, thanks to the ``polls/__init__.py``
     107file. That's a great start, but we can't just pick up this package and drop it
     108into a new project. The polls templates are currently stored in the
     109project-wide ``mytemplates`` directory. To make the app self-contained, it
     110should also contain the necessary templates.
     111
     112Inside the ``polls`` app, create a new ``templates`` directory. Now move the
     113``polls`` template directory from ``mytemplates`` into the new
     114``templates``. Your project should now look like this::
     115
     116    mysite/
     117        manage.py
     118        mysite/
     119            __init__.py
     120            settings.py
     121            urls.py
     122            wsgi.py
     123        polls/
     124            admin.py
     125            __init__.py
     126            models.py
     127            templates/
     128                polls/
     129                    detail.html
     130                    index.html
     131                    results.html
     132            tests.py
     133            urls.py
     134            views.py
     135
     136Your project-wide templates directory should now look like this::
     137
     138    mytemplates/
     139        admin/
     140            base_site.html
     141
     142Looking good! Now would be a good time to confirm that your polls application
     143still works correctly.  How does Django know how to find the new location of
     144the polls templates even though we didn't modify :setting:`TEMPLATE_DIRS`?
     145Django has a :setting:`TEMPLATE_LOADERS` setting which contains a list
     146of callables that know how to import templates from various sources.  One of
     147the defaults is :class:`django.template.loaders.app_directories.Loader` which
     148looks for a "templates" subdirectory in each of the :setting:`INSTALLED_APPS`.
     149
     150The ``polls`` directory could now be copied into a new Django project and
     151immediately reused. It's not quite ready to be published though. For that, we
     152need to package the app to make it easy for others to install.
     153
     154.. admonition:: Why nested?
     155
     156   Why create a ``polls`` directory under ``templates`` when we're
     157   already inside the polls app? This directory is needed to avoid conflicts in
     158   Django's ``app_directories`` template loader.  For example, if two
     159   apps had a template called ``base.html``, without the extra directory, it
     160   wouldn't be possible to distinguish between the two. It's a good convention
     161   to use the name of your app for this directory.
     162
     163.. _installing-reuseable-apps-prerequisites:
     164
     165Installing some prerequisites
     166=============================
     167
     168The current state of Python packaging is a bit muddled with various tools. For
     169this tutorial, we're going to use distribute_ to build our package. It's a
     170community-maintained fork of the older ``setuptools`` project. We'll also be
     171using `pip`_ to uninstall it after we're finished. You should install these
     172two packages now. If you need help, you can refer to :ref:`how to install
     173Django with pip<installing-official-release>`. You can install ``distribute``
     174the same way.
     175
     176.. _distribute: http://pypi.python.org/pypi/distribute
     177.. _pip: http://pypi.python.org/pypi/pip
     178
     179Packaging your app
     180==================
     181
     182Python *packaging* refers to preparing your app in a specific format that can
     183be easily installed and used. Django itself is packaged very much like
     184this. For a small app like polls, this process isn't too difficult.
     185
     1861. First, create a parent directory for ``polls``, outside of your Django
     187   project. Call this directory ``django-polls``.
     188
     189.. admonition::  Choosing a name for your app
     190
     191   When choosing a name for your package, check resources like PyPI to avoid
     192   naming conflicts with existing packages. It's often useful to prepend
     193   ``django-`` to your module name when creating a package to distribute.
     194   This helps others looking for Django apps identify your app as Django
     195   specific.
     196
     1972. Move the ``polls`` directory into the ``django-polls`` directory.
     198
     1993. Create a file ``django-polls/README.txt`` with the following contents::
     200
     201    =====
     202    Polls
     203    =====
     204
     205    Polls is a simple Django app to conduct Web-based polls. For each
     206    question, visitors can choose between a fixed number of answers.
     207
     208    Detailed documentation is in the "docs" directory.
     209
     210    Quick start
     211    -----------
     212
     213    1. Add "polls" to your INSTALLED_APPS setting like this::
     214
     215          INSTALLED_APPS = (
     216              ...
     217              'polls',
     218          )
     219
     220    2. Include the polls URLconf in your project urls.py like this::
     221
     222          url(r'^polls/', include('polls.urls')),
     223
     224    3. Run `python manage.py syncdb` to create the polls models.
     225
     226    4. Start the development server and visit http://127.0.0.1:8000/admin/
     227      to create a poll (you'll need the Admin app enabled).
     228
     229    5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
     230
     2314. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the
     232scope of this tutorial, but suffice it to say that code released publicly
     233without a license is *useless*. Django and many Django-compatible apps are
     234distributed under the BSD license; however, you're free to pick your own
     235license. Just be aware that your licensing choice will affect who is able
     236to use your code.
     237
     2385. Next we'll create a ``setup.py`` file which provides details about how to
     239build and install the app.  A full explanation of this file is beyond the
     240scope of this tutorial, but the `distribute docs
     241<http://packages.python.org/distribute/setuptools.html>`_ have a good explanation.
     242Create a file ``django-polls/setup.py`` with the following contents::
     243
     244    import os
     245    from setuptools import setup
     246
     247    README = open(os.path.join(os.path.dirname(__file__), 'README.txt')).read()
     248
     249    # allow setup.py to be run from any path
     250    os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))
     251
     252    setup(
     253        name = 'django-polls',
     254        version = '0.1',
     255        packages = ['polls'],
     256        include_package_data = True,
     257        license = 'BSD License', # example license
     258        description = 'A simple Django app to conduct Web-based polls.',
     259        long_description = README,
     260        url = 'http://www.example.com/',
     261        author = 'Your Name',
     262        author_email = 'yourname@example.com',
     263        classifiers = [
     264            'Environment :: Web Environment',
     265            'Framework :: Django',
     266            'Intended Audience :: Developers',
     267            'License :: OSI Approved :: BSD License', # example license
     268            'Operating System :: OS Independent',
     269            'Programming Language :: Python',
     270            'Programming Language :: Python :: 2.6',
     271            'Programming Language :: Python :: 2.7',
     272            'Topic :: Internet :: WWW/HTTP',
     273            'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
     274        ],
     275    )
     276
     277.. admonition:: I thought you said we were going to use ``distibute``?
     278
     279    Distribute is a drop-in replacement for ``setuptools``. Even though we
     280    appear to import from ``setuptools``, since we have ``distribute``
     281    installed, it will override the import.
     282
     2836. Only Python modules and packages are included in the package by default. To
     284   include additional files, we'll need to create a ``MANIFEST.in`` file. The
     285   distribute docs referred to in the previous step discuss this file in more
     286   details. To include the templates and our LICENSE file, create a file
     287   ``django-polls/MANIFEST.in`` with the following contents::
     288
     289    include LICENSE
     290    recursive-include polls/templates *
     291
     2927. It's optional, but recommended, to include detailed documentation with your
     293   app. Create an empty directory ``django-polls/docs`` for future
     294   documentation. Add an additional line to ``django-polls/MANIFEST.in``::
     295
     296    recursive-include docs *
     297
     298   Note that the ``docs`` directory won't be included in your package unless
     299   you add some files to it. Many Django apps also provide their documentation
     300   online through sites like `readthedocs.org <http://readthedocs.org>`_.
     301
     3028. Try building your package with ``python setup.py sdist`` (run from inside
     303   ``django-polls``). This creates a directory called ``dist`` and builds your
     304   new package, ``django-polls-0.1.tar.gz``.
     305
     306For more information on packaging, see `The Hitchhiker's Guide to Packaging
     307<http://guide.python-distribute.org/quickstart.html>`_.
     308
     309Using your own package
     310======================
     311
     312Since we moved the ``polls`` directory out of the project, it's no longer
     313working. We'll now fix this by installing our new ``django-polls`` package.
     314
     315.. admonition:: Installing as a system library
     316
     317   The following steps install ``django-polls`` as a system library. In
     318   general, it's best to avoid messing with your system libraries to avoid
     319   breaking things. For this simple example though, the risk is low and it will
     320   help with understanding packaging. We'll explain how to uninstall in
     321   step 4.
     322
     323   For experienced users, a neater way to manage your packages is to use
     324   "virtualenv" (see below).
     325
     3261. Inside ``django-polls/dist``, untar the new package
     327   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     328   you're using Windows, you can download the command-line tool bsdtar_ to do
     329   this, or you can use a GUI-based tool such as 7-zip_.
     330
     3312. Change into the directory created in step 1 (e.g. ``cd django-polls-0.1``).
     332
     3333. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
     334   command ``sudo python setup.py install`` at the shell prompt.  If you're
     335   using Windows, start up a command shell with administrator privileges and
     336   run the command ``setup.py install``.
     337
     338   With luck, your Django project should now work correctly again. Run the
     339   server again to confirm this.
     340
     3414. To uninstall the package, use pip (you already :ref:`installed it
     342   <installing-reuseable-apps-prerequisites>`, right?)::
     343
     344    sudo pip uninstall django-polls
     345
     346.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
     347.. _7-zip: http://www.7-zip.org/
     348.. _pip: http://pypi.python.org/pypi/pip
     349
     350Publishing your app
     351===================
     352
     353Now that we've packaged and tested ``django-polls``, it's ready to share with
     354the world! If this wasn't just an example, you could now:
     355
     356* Email the package to a friend.
     357
     358* Upload the package on your Web site.
     359
     360* Post the package on a public repository, such as `The Python Package Index
     361  (PyPI) <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
     362
     363For more information on PyPI, see the `Quickstart
     364<http://guide.python-distribute.org/quickstart.html#register-your-package-with-the-python-package-index-pypi>`_
     365section of The Hitchhiker's Guide to Packaging. One detail this guide mentions
     366is choosing the license under which your code is distributed.
     367
     368Installing Python packages with virtualenv
     369==========================================
     370
     371Earlier, we installed the polls app as a system library. This has some
     372disadvantages:
     373
     374* Modifying the system libraries can affect other Python software on your
     375  system.
     376
     377* You won't be able to run multiple versions of this package (or others with
     378  the same name).
     379
     380Typically, these situations only arise once you're maintaining several Django
     381projects. When they do, the best solution is to use `virtualenv
     382<http://www.virtualenv.org/>`_. This tool allows you to maintain multiple
     383isolated Python environments, each with its own copy of the libraries and
     384package namespace.

  • docs/intro/tutorial03.txt 

    diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt
index 169e6cd..a6c730a 100644
    a b Load the page in your Web browser, and you should see a bulleted-list  
    315315containing the "What's up" poll from Tutorial 1. The link points to the poll's
    316316detail page.
    317317
     318.. admonition:: Organizing Templates
     319
     320    Rather than one big templates directory, you can also store templates
     321    within each app. We'll discuss this in more detail in the `reuseable apps
     322    tutorial</intro/reuseable-apps>`.
     323
    318324A shortcut: :func:`~django.shortcuts.render`
    319325--------------------------------------------
    320326

  • docs/intro/tutorial04.txt 

    diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt
index 8909caf..dfee827 100644
    a b For full details on generic views, see the :doc:`generic views documentation  
    278278What's next?
    279279============
    280280
    281 The tutorial ends here for the time being. In the meantime, you might want to
    282 check out some pointers on :doc:`where to go from here </intro/whatsnext>`.
     281The beginner tutorial ends here for the time being. In the meantime, you might
     282want to check out some pointers on :doc:`where to go from here
     283</intro/whatsnext>`.
     284
     285If you are familiar with Python packaging and interested in learning how to
     286turn polls into a "reusable app", check out :doc:`Advanced tutorial: How to
     287write reusable apps</intro/reusable-apps>`.
Back to Top