Ticket #16671: tutorial05.10.diff

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

Update tutorial to include templates directory via MANIFEST.in.


    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>`
    4748The model layer
  • docs/intro/index.txt

    diff -r 548df236b2cc docs/intro/index.txt
    a b  
    1313   tutorial02
    1414   tutorial03
    1515   tutorial04
     16   tutorial05
    1617   whatsnext
    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
    325 Coming soon
    326 ===========
    328 The tutorial ends here for the time being. Future installments of the tutorial
    329 will cover:
    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
    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
    - +  
     2Writing your first Django app, part 5
     5This 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.
     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.
     12.. Outline:
     14.. * motivation
     15..     * what is a python package?
     16..     * what is a django app?
     17..     * what is a reusable app?
     19.. * preparing
     20..     * moving templates into your app
     21..     * parent directory
     22..     * adding package boilerplate
     23..     * link to packaging docs
     24..     * package builder
     26.. * using the package
     27..     * how to install
     29.. * publishing
     30..     * options for publishing
     31..     * link to docs on PyPI
     33Reusability matters
     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?
     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. Django itself is
     43also just Python. This means that you can take existing Python packages or
     44Django apps and compose them into your own web project. You only need to write
     45the parts that make your project unique.
     47Let's say you were starting a new project that needed a polls app like the one
     48we've been working on. How do you make this app reusable? Luckily, you're well
     49on the way already. In the :doc:`Tutorial 3 </intro/tutorial03>`, we began by
     50decoupling polls from the project-level URLconf. In this tutorial, we'll take
     51further steps to make the app easy to use in new projects and ready to publish
     52for others to install and use.
     54.. admonition:: Package? App?
     56    A Python `package <http://docs.python.org/tutorial/modules.html#packages>`_
     57    provides a way of grouping related Python code for easy reuse. A package contains
     58    one or more files of Python code (also known as "modules").
     60    A package can be imported with ``import foo.bar`` or ``from foo import
     61    bar``. For a directory (like ``polls``) to form a package, it must contain a
     62    special file ``__init__.py``, even if this file is empty.
     64    A Django *app* is just a Python package that is specifically intended for
     65    use in a Django project. An app may also use common Django conventions,
     66    such as having a ``models.py`` file.
     68    Later on we use the term *packaging* to describe the process of making a
     69    Python package easy for others to install. It can be a little confusing, we
     70    know.
     72Completing your reusable app
     75After the previous tutorials, our project should look like this::
     77    mysite/
     78        manage.py
     79        mysite/
     80            __init__.py
     81            settings.py
     82            urls.py
     83            wsgi.py
     84        polls/
     85            admin.py
     86            __init__.py
     87            models.py
     88            tests.py
     89            urls.py
     90            views.py
     92You also have a directory somewhere called ``mytemplates`` which you created in
     93:doc:`Tutorial 2 </intro/tutorial02>`. You specified its location in the
     94TEMPLATE_DIRS setting. This directory should look like this::
     96    mytemplates/
     97        admin/
     98            base_site.html
     99        polls/
     100            detail.html
     101            index.html
     102            results.html
     104The polls app is already a Python package, thanks to the ``polls/__init__.py``
     105file. That's a great start, but we can't just pick up this package and drop it
     106into a new project. The polls templates are currently stored in the
     107project-wide ``mytemplates`` directory. To make the app self-contained, it should also contain the necessary templates.
     109Inside the ``polls`` app, create a new ``templates`` directory. Now move the
     110``polls`` template directory from ``mytemplates`` into the new
     111``templates``. Your project should now look like this::
     113    mysite/
     114        manage.py
     115        mysite/
     116            __init__.py
     117            settings.py
     118            urls.py
     119            wsgi.py
     120        polls/
     121            admin.py
     122            __init__.py
     123            models.py
     124            templates/
     125                polls/
     126                    detail.html
     127                    index.html
     128                    results.html
     129            tests.py
     130            urls.py
     131            views.py
     133Your project-wide templates directory should now look like this::
     135    mytemplates/
     136        admin/
     137            base_site.html
     139Looking good! Now would be a good time to confirm that your polls application
     140still works correctly.
     142The ``polls`` directory could now be copied into a new Django project and
     143immediately reused. It's not quite ready to be published though. For that, we
     144need to package the app to make it easy for others to install.
     146.. admonition:: Why nested?
     148   Why create a ``polls`` directory under ``templates`` when we're
     149   already inside the polls app? This directory is needed to avoid conflicts in
     150   Django's ``app_directories`` template loader.
     152Packaging your app
     155Python *packaging* refers to preparing your app in a specific format that can
     156be easily installed and used. Django itself is packaged very much like
     157this. For a small app like polls, this process isn't too difficult.
     1591. Firstly, create a parent directory for ``polls``, outside of your Django
     160   project. Call this directory ``django-polls``.
     1622. Move the ``polls`` directory into the ``django-polls`` directory.
     1643. Create a file ``django-polls/README.txt`` with the following contents::
     166       =====
     167       Polls
     168       =====
     170       Polls is a simple Django app to conduct Web-based polls. For each
     171       question, visitors can choose between a fixed number of answers.
     173       Detailed documentation is in the "docs" directory.
     175       Quick start
     176       -----------
     178       1. Add "polls" to your INSTALLED_APPS setting like this::
     180              INSTALLED_APPS = (
     181                  ...
     182                  'polls',
     183              )
     185       2. Include the polls URLconf in your project urls.py like this::
     187              (r'^polls/', include('polls.urls')),
     189       3. Run `python manage.py syncdb` to create the polls models.
     191       4. Start the development server and visit
     192          to create a poll (you'll need the Admin app enabled).
     194       5. Visit to participate in the poll.
     1975. Create a file ``django-polls/setup.py`` with the following contents::
     199    from distutils.core import setup
     201    setup(
     202        name='django-polls',
     203        version='0.1',
     204        packages=['polls',],
     205        license='',
     206        long_description=open('README.txt').read(),
     207        url='http://www.example.com/',
     208        author='Your Name',
     209        author_email='yourname@example.com',
     210    )
     2126. Only a limited set of files are included in the package by default. To also
     213   include the templates, create a file ``django-polls/MANIFEST.in`` with
     214   the following contents::
     216       recursive-include polls/templates *
     2187. It's optional, but recommended, to include detailed documentation with your
     219   app. Create an empty directory ``django-polls/docs`` for future
     220   documentation. Add an additional line to ``django-polls/MANIFEST.in``::
     222       recursive-include docs *
     2248. Try building your package with ``python setup.py sdist`` (run from inside
     225   ``django-polls``). This creates a directory called ``dist`` and builds your
     226   new package, ``django-polls-0.1.tar.gz``.
     228For more information on packaging, see `The Hitchhiker's Guide to Packaging
     231Using your own package
     234Since we moved the ``polls`` directory out of the project, it's no longer
     235working. We'll now fix this by installing our new ``django-polls`` package.
     237.. admonition:: Installing as a system library
     239   The following steps install ``django-polls`` as a system library. In
     240   general, it's best to avoid messing with your system libraries to avoid
     241   breaking things. For this simple example though, the risk is low and it will
     242   help with understanding packaging. We'll explain how to uninstall in
     243   step 4.
     245   For experienced users, a neater way to manage your packages is to use
     246   "virtualenv" (see below).
     2481. Inside ``django-polls/dist``, untar the new package
     249   ``django-polls-0.1.tar.gz`` (e.g. ``tar xzvf django-polls-0.1.tar.gz``). If
     250   you're using Windows, you can download the command-line tool bsdtar_ to do
     251   this, or you can use a GUI-based tool such as 7-zip_.
     2532. Change into the directory created in step 1 (e.g. ``cd django-polls``).
     2553. If you're using GNU/Linux, Mac OS X or some other flavor of Unix, enter the
     256   command ``sudo python setup.py install`` at the shell prompt.  If you're
     257   using Windows, start up a command shell with administrator privileges and
     258   run the command ``setup.py install``.
     260   With luck, your Django project should now work correctly again. Run the
     261   server again to confirm this.
     2634. To uninstall the package, delete the directory ``polls`` and the file
     264   ``django_polls-0.1.egg-info`` from your system libraries. On GNU/Linux and
     265   Mac OS X these files live in ``/usr/local/lib/python2.X/dist-packages``, and
     266   on Windows, in ``C:\Python2X\Lib\site-packages`` (where *X* is the Python
     267   minor version number). You will need administrator privileges.
     269.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
     270.. _7-zip: http://www.7-zip.org/
     272Publishing your app
     275Now that we've packaged and tested ``django-polls``, it's ready to share with
     276the world! If this wasn't just an example, you could now:
     278    * Email the package to a friend.
     280    * Upload the package on your Web site.
     282    * Post the package on a public repository, such as `The Python Package
     283      Index (PyPI)
     284      <http://guide.python-distribute.org/contributing.html#pypi-info>`_.
     286For more information on PyPI, see the `Quickstart
     288section of The Hitchhiker's Guide to Packaging. One detail this guide mentions
     289is choosing the license under which your code is distributed.
     291Installing Python packages with virtualenv
     294Earlier, we installed the polls app as a system library. This has some
     297    * Modifying the system libraries can affect other Python software on your
     298      system.
     300    * You won't be able to run multiple versions of this package (or others with
     301      the same name).
     303Typically, these situations only arise once you're maintaining several Django
     304projects. When they do, the best solution is to use *virtualenv*. This tool
     305allows you to maintain multiple isolated Python environments, each with its own
     306copy of the libraries and package namespace.
     308Learn more on the `virtualenv <http://www.virtualenv.org/>`_ Web site.
     310More about reusable apps
     313For more on writing reusable apps, see `What is a reusable app?
     314<http://ericholscher.com/projects/django-conventions/app/>`_ by Eric
     315Holsher. For a collection of reusable apps to use in your own projects, see the
     316`Pinax <http://pinaxproject.com/>`_ project.
     318The tutorial ends here for the time being. In the meantime, you might want to
     319check out some pointers on :doc:`where to go from here </intro/whatsnext>`.
Back to Top