[ { "path": "Python/DjangoBook/Makefile", "content": "# Makefile for Sphinx documentation\n#\n\n# You can set these variables from the command line.\nSPHINXOPTS =\nSPHINXBUILD = sphinx-build\nPAPER =\nBUILDDIR = _build\n\n# Internal variables.\nPAPEROPT_a4 = -D latex_paper_size=a4\nPAPEROPT_letter = -D latex_paper_size=letter\nALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .\n# the i18n builder cannot share the environment and doctrees with the others\nI18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .\n\n.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext\n\nhelp:\n\t@echo \"Please use \\`make ' where is one of\"\n\t@echo \" html to make standalone HTML files\"\n\t@echo \" dirhtml to make HTML files named index.html in directories\"\n\t@echo \" singlehtml to make a single large HTML file\"\n\t@echo \" pickle to make pickle files\"\n\t@echo \" json to make JSON files\"\n\t@echo \" htmlhelp to make HTML files and a HTML help project\"\n\t@echo \" qthelp to make HTML files and a qthelp project\"\n\t@echo \" devhelp to make HTML files and a Devhelp project\"\n\t@echo \" epub to make an epub\"\n\t@echo \" latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter\"\n\t@echo \" latexpdf to make LaTeX files and run them through pdflatex\"\n\t@echo \" text to make text files\"\n\t@echo \" man to make manual pages\"\n\t@echo \" texinfo to make Texinfo files\"\n\t@echo \" info to make Texinfo files and run them through makeinfo\"\n\t@echo \" gettext to make PO message catalogs\"\n\t@echo \" changes to make an overview of all changed/added/deprecated items\"\n\t@echo \" linkcheck to check all external links for integrity\"\n\t@echo \" doctest to run all doctests embedded in the documentation (if enabled)\"\n\nclean:\n\t-rm -rf $(BUILDDIR)/*\n\nhtml:\n\t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html\n\t@echo\n\t@echo \"Build finished. The HTML pages are in $(BUILDDIR)/html.\"\n\ndirhtml:\n\t$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml\n\t@echo\n\t@echo \"Build finished. The HTML pages are in $(BUILDDIR)/dirhtml.\"\n\nsinglehtml:\n\t$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml\n\t@echo\n\t@echo \"Build finished. The HTML page is in $(BUILDDIR)/singlehtml.\"\n\npickle:\n\t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle\n\t@echo\n\t@echo \"Build finished; now you can process the pickle files.\"\n\njson:\n\t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json\n\t@echo\n\t@echo \"Build finished; now you can process the JSON files.\"\n\nhtmlhelp:\n\t$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp\n\t@echo\n\t@echo \"Build finished; now you can run HTML Help Workshop with the\" \\\n\t \".hhp project file in $(BUILDDIR)/htmlhelp.\"\n\nqthelp:\n\t$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp\n\t@echo\n\t@echo \"Build finished; now you can run \"qcollectiongenerator\" with the\" \\\n\t \".qhcp project file in $(BUILDDIR)/qthelp, like this:\"\n\t@echo \"# qcollectiongenerator $(BUILDDIR)/qthelp/TheDjangoBook.qhcp\"\n\t@echo \"To view the help file:\"\n\t@echo \"# assistant -collectionFile $(BUILDDIR)/qthelp/TheDjangoBook.qhc\"\n\ndevhelp:\n\t$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp\n\t@echo\n\t@echo \"Build finished.\"\n\t@echo \"To view the help file:\"\n\t@echo \"# mkdir -p $$HOME/.local/share/devhelp/TheDjangoBook\"\n\t@echo \"# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/TheDjangoBook\"\n\t@echo \"# devhelp\"\n\nepub:\n\t$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub\n\t@echo\n\t@echo \"Build finished. The epub file is in $(BUILDDIR)/epub.\"\n\nlatex:\n\t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex\n\t@echo\n\t@echo \"Build finished; the LaTeX files are in $(BUILDDIR)/latex.\"\n\t@echo \"Run \\`make' in that directory to run these through (pdf)latex\" \\\n\t \"(use \\`make latexpdf' here to do that automatically).\"\n\nlatexpdf:\n\t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex\n\t@echo \"Running LaTeX files through pdflatex...\"\n\t$(MAKE) -C $(BUILDDIR)/latex all-pdf\n\t@echo \"pdflatex finished; the PDF files are in $(BUILDDIR)/latex.\"\n\ntext:\n\t$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text\n\t@echo\n\t@echo \"Build finished. The text files are in $(BUILDDIR)/text.\"\n\nman:\n\t$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man\n\t@echo\n\t@echo \"Build finished. The manual pages are in $(BUILDDIR)/man.\"\n\ntexinfo:\n\t$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo\n\t@echo\n\t@echo \"Build finished. The Texinfo files are in $(BUILDDIR)/texinfo.\"\n\t@echo \"Run \\`make' in that directory to run these through makeinfo\" \\\n\t \"(use \\`make info' here to do that automatically).\"\n\ninfo:\n\t$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo\n\t@echo \"Running Texinfo files through makeinfo...\"\n\tmake -C $(BUILDDIR)/texinfo info\n\t@echo \"makeinfo finished; the Info files are in $(BUILDDIR)/texinfo.\"\n\ngettext:\n\t$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale\n\t@echo\n\t@echo \"Build finished. The message catalogs are in $(BUILDDIR)/locale.\"\n\nchanges:\n\t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes\n\t@echo\n\t@echo \"The overview file is in $(BUILDDIR)/changes.\"\n\nlinkcheck:\n\t$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck\n\t@echo\n\t@echo \"Link check complete; look for any errors in the above output \" \\\n\t \"or in $(BUILDDIR)/linkcheck/output.txt.\"\n\ndoctest:\n\t$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest\n\t@echo \"Testing of doctests in the sources finished, look at the \" \\\n\t \"results in $(BUILDDIR)/doctest/output.txt.\"\n" }, { "path": "Python/DjangoBook/Procfile", "content": "web: gunicorn -kgevent -w4 -b0.0.0.0:$PORT app:app\n" }, { "path": "Python/DjangoBook/README.rst", "content": "===============\nThe Django Book\n===============\n\nWelcome to the community edition of the Django Book!\n\nThis book was originally published by Apress in 2009, and covered Django 1.0. Since then, it's languished. We're working on getting the book updated to cover Django 1.4, 1.5, and beyond. But **we need your help**, so we're making this book — warts and all — open source in the hopes that it'll find love as a community project.\n\nSo, if you'd like to help out, send us a pull request!\n" }, { "path": "Python/DjangoBook/app.py", "content": "\"\"\"\nThe simplest possible app that can serve these Sphinx docs and issue\nredirects for the previous URLs.\n\"\"\"\n\nimport static\nimport selector\nfrom unipath import FSPath as Path\n\napp = selector.Selector()\n\ndef redirect(to):\n \"\"\"\n Create a 301 redirect WSGI app.\n\n `to` may contain str.format-style formatting which'll be formatted against\n the routing arguments (wsgiorg.routing_args).\n \"\"\"\n def _redirect(environ, start_response):\n args, kwargs = environ['wsgiorg.routing_args']\n start_response('301 MOVED PERMANENTLY',\n [('Location', to.format(*args, **kwargs))])\n return []\n return _redirect\n\n# Redirects for old doc URLs, since Cool URIs Don't Change.\napp.add('/', GET=redirect('/en/2.0/index.html'))\napp.add('/license/', GET=redirect('/en/2.0/license.html'))\napp.add('/about/', GET=redirect('/en/2.0/frontmatter.html'))\napp.add('/en/1.0/', GET=redirect('/en/2.0/index.html'))\napp.add('/en/1.0/{doc:chunk}/', GET=redirect('/en/2.0/{doc}.html'))\napp.add('/en/2.0/{doc:chunk}/', GET=redirect('/en/2.0/{doc}.html'))\n\n# Serve docs at \"/en/2.0\" still, to leave room for the future.\n# One of these days I'll actually do this, not just talk about it!\ndocs = static.Cling(Path(__file__).parent.child('_build', 'html'))\napp.add(\"/en/2.0|\", GET=docs)\n" }, { "path": "Python/DjangoBook/appendixA.rst", "content": "======================================\nAppendix A: Model Definition Reference\n======================================\n\nChapter 5 explains the basics of defining models, and we use them throughout\nthe rest of the book. There is, however, a *huge* range of model options\navailable not covered elsewhere. This appendix explains each possible model\ndefinition option.\n\nNote that although these APIs are considered stable, the Django developers\nconsistently add new shortcuts and conveniences to the model definition. It's a\ngood idea to always check the latest documentation online at\nhttp://docs.djangoproject.com/.\n\nFields\n======\n\nThe most important part of a model -- and the only required part of a model --\nis the list of database fields it defines.\n\n.. admonition:: Field Name Restrictions\n\n Django places only two restrictions on model field names:\n\n 1. A field name cannot be a Python reserved word, because that would result\n in a Python syntax error. For example::\n\n class Example(models.Model):\n pass = models.IntegerField() # 'pass' is a reserved word!\n\n 2. A field name cannot contain more than one underscore in a row, due to\n the way Django's query lookup syntax works. For example::\n\n class Example(models.Model):\n foo__bar = models.IntegerField() # 'foo__bar' has two underscores!\n\n These limitations can be worked around, though, because your field name\n doesn't necessarily have to match your database column name. See\n \"db_column\", below.\n\n SQL reserved words, such as ``join``, ``where``, or ``select``, *are* allowed\n as model field names, because Django escapes all database table names and\n column names in every underlying SQL query. It uses the quoting syntax of your\n particular database engine.\n\nEach field in your model should be an instance of the appropriate ``Field``\nclass. Django uses the field class types to determine a few things:\n\n* The database column type (e.g., ``INTEGER``, ``VARCHAR``).\n\n* The widget to use in Django's forms and admin site, if you care to use it\n (e.g., ````, ``\n \n \n \n\nif the user enters ``\"John Smith\"`` in the ``your_name`` field and selects\nboth \"The Beatles\" and \"The Zombies\" in the multiple select box, here's what\nDjango's request object would have::\n\n >>> request.GET\n {}\n >>> request.POST\n {'your_name': ['John Smith'], 'bands': ['beatles', 'zombies']}\n >>> request.POST['your_name']\n 'John Smith'\n >>> request.POST['bands']\n 'zombies'\n >>> request.POST.getlist('bands')\n ['beatles', 'zombies']\n >>> request.POST.get('your_name', 'Adrian')\n 'John Smith'\n >>> request.POST.get('nonexistent_field', 'Nowhere Man')\n 'Nowhere Man'\n\n.. admonition:: Implementation Note:\n\n The ``GET``, ``POST``, ``COOKIES``, ``FILES``, ``META``, ``REQUEST``,\n ``raw_post_data``, and ``user`` attributes are all lazily loaded. That means\n Django doesn't spend resources calculating the values of those attributes until\n your code requests them.\n\nHttpResponse\n============\n\nIn contrast to ``HttpRequest`` objects, which are created automatically by\nDjango, ``HttpResponse`` objects are your responsibility. Each view you write\nis responsible for instantiating, populating, and returning an\n``HttpResponse``.\n\nThe ``HttpResponse`` class lives at ``django.http.HttpResponse``.\n\nConstruction HttpResponses\n--------------------------\n\nTypically, you'll construct an ``HttpResponse`` to pass the contents of the\npage, as a string, to the ``HttpResponse`` constructor::\n\n >>> response = HttpResponse(\"Here's the text of the Web page.\")\n >>> response = HttpResponse(\"Text only, please.\", mimetype=\"text/plain\")\n\nBut if you want to add content incrementally, you can use ``response`` as a\nfilelike object::\n\n >>> response = HttpResponse()\n >>> response.write(\"

Here's the text of the Web page.

\")\n >>> response.write(\"

Here's another paragraph.

\")\n\nYou can pass ``HttpResponse`` an iterator rather than passing it\nhard-coded strings. If you use this technique, follow these guidelines:\n\n* The iterator should return strings.\n\n* If an ``HttpResponse`` has been initialized with an iterator as its\n content, you can't use the ``HttpResponse`` instance as a filelike\n object. Doing so will raise ``Exception``.\n\nFinally, note that ``HttpResponse`` implements a ``write()`` method, which\nmakes is suitable for use anywhere that Python expects a filelike object. See\nChapter 8 for some examples of using this technique.\n\nSetting Headers\n---------------\n\nYou can add and delete headers using dictionary syntax::\n\n >>> response = HttpResponse()\n >>> response['X-DJANGO'] = \"It's the best.\"\n >>> del response['X-PHP']\n >>> response['X-DJANGO']\n \"It's the best.\"\n\nYou can also use ``has_header(header)`` to check for the existence of a header.\n\nAvoid setting ``Cookie`` headers by hand; instead, see Chapter 14 for\ninstructions on how cookies work in Django.\n\nHttpResponse Subclasses\n-----------------------\n\nDjango includes a number of ``HttpResponse`` subclasses that handle different\ntypes of HTTP responses (see Table G-5). Like ``HttpResponse``, these subclasses live in\n``django.http``.\n\n.. table:: Table G-5. HttpResponse Subclasses\n\n ================================== =======================================\n Class Description\n ================================== =======================================\n ``HttpResponseRedirect`` The constructor takes a single argument:\n the path to redirect to. This can\n be a fully qualified URL (e.g.,\n ``'http://search.yahoo.com/'``) or\n an absolute URL with no domain (e.g.,\n ``'/search/'``). Note that this\n returns an HTTP status code 302.\n\n ``HttpResponsePermanentRedirect`` Like ``HttpResponseRedirect``, but it\n returns a permanent redirect (HTTP\n status code 301) instead of a \"found\"\n redirect (status code 302).\n\n ``HttpResponseNotModified`` The constructor doesn't take any\n arguments. Use this to designate that\n a page hasn't been modified since the\n user's last request.\n\n ``HttpResponseBadRequest`` Acts just like ``HttpResponse`` but\n uses a 400 status code.\n\n ``HttpResponseNotFound`` Acts just like ``HttpResponse`` but\n uses a 404 status code.\n\n ``HttpResponseForbidden`` Acts just like ``HttpResponse`` but\n uses a 403 status code.\n\n ``HttpResponseNotAllowed`` Like ``HttpResponse``, but uses a 405\n status code. It takes a single, required\n argument: a list of permitted methods\n (e.g., ``['GET', 'POST']``).\n\n ``HttpResponseGone`` Acts just like ``HttpResponse`` but\n uses a 410 status code.\n\n ``HttpResponseServerError`` Acts just like ``HttpResponse`` but\n uses a 500 status code.\n ================================== =======================================\n\nYou can, of course, define your own ``HttpResponse`` subclass to support\ndifferent types of responses not supported out of the box.\n\nReturning Errors\n----------------\n\nReturning HTTP error codes in Django is easy. We've already mentioned the\n``HttpResponseNotFound``, ``HttpResponseForbidden``,\n``HttpResponseServerError``, and other subclasses. Just return an instance of one\nof those subclasses instead of a normal ``HttpResponse`` in order to signify\nan error, for example::\n\n def my_view(request):\n # ...\n if foo:\n return HttpResponseNotFound('

Page not found

')\n else:\n return HttpResponse('

Page was found

')\n\nBecause a 404 error is by far the most common HTTP error, there's an easier\nway to handle it.\n\nWhen you return an error such as ``HttpResponseNotFound``, you're responsible\nfor defining the HTML of the resulting error page::\n\n return HttpResponseNotFound('

Page not found

')\n\nFor convenience, and because it's a good idea to have a consistent 404 error page\nacross your site, Django provides an ``Http404`` exception. If you raise\n``Http404`` at any point in a view function, Django will catch it and return the\nstandard error page for your application, along with an HTTP error code 404.\n\nHere's an example::\n\n from django.http import Http404\n\n def detail(request, poll_id):\n try:\n p = Poll.objects.get(pk=poll_id)\n except Poll.DoesNotExist:\n raise Http404\n return render(request, 'polls/detail.html', {'poll': p})\n\nIn order to use the ``Http404`` exception to its fullest, you should create a\ntemplate that is displayed when a 404 error is raised. This template should be\ncalled ``404.html``, and it should be located in the top level of your template tree.\n\nCustomizing the 404 (Not Found) View\n------------------------------------\n\nWhen you raise an ``Http404`` exception, Django loads a special view devoted\nto handling 404 errors. By default, it's the view\n``django.views.defaults.page_not_found``, which loads and renders the template\n``404.html``.\n\nThis means you need to define a ``404.html`` template in your root template\ndirectory. This template will be used for all 404 errors.\n\nThis ``page_not_found`` view should suffice for 99% of Web applications, but\nif you want to override the 404 view, you can specify ``handler404`` in your\nURLconf, like so::\n\n from django.conf.urls.defaults import *\n\n urlpatterns = patterns('',\n ...\n )\n\n handler404 = 'mysite.views.my_custom_404_view'\n\nBehind the scenes, Django determines the 404 view by looking for\n``handler404``. By default, URLconfs contain the following line::\n\n from django.conf.urls.defaults import *\n\nThat takes care of setting ``handler404`` in the current module. As you can\nsee in ``django/conf/urls/defaults.py``, ``handler404`` is set to\n``'django.views.defaults.page_not_found'`` by default.\n\nThere are three things to note about 404 views:\n\n* The 404 view is also called if Django doesn't find a match after checking\n every regular expression in the URLconf.\n\n* If you don't define your own 404 view -- and simply use the default,\n which is recommended -- you still have one obligation: to create a\n ``404.html`` template in the root of your template directory. The default\n 404 view will use that template for all 404 errors.\n\n* If ``DEBUG`` is set to ``True`` (in your settings module), then your 404\n view will never be used, and the traceback will be displayed instead.\n\nCustomizing the 500 (Server Error) View\n---------------------------------------\n\nSimilarly, Django executes special-case behavior in the case of runtime errors\nin view code. If a view results in an exception, Django will, by default, call\nthe view ``django.views.defaults.server_error``, which loads and renders the\ntemplate ``500.html``.\n\nThis means you need to define a ``500.html`` template in your root template\ndirectory. This template will be used for all server errors.\n\nThis ``server_error`` view should suffice for 99% of Web applications, but if\nyou want to override the view, you can specify ``handler500`` in your\nURLconf, like so::\n\n from django.conf.urls.defaults import *\n\n urlpatterns = patterns('',\n ...\n )\n\n handler500 = 'mysite.views.my_custom_error_view'\n" }, { "path": "Python/DjangoBook/bin/post_compile", "content": "#!/bin/bash\n\nsphinx-build -q -b html -d _build/doctrees . _build/html\n" }, { "path": "Python/DjangoBook/chapter01.rst", "content": "=================================\nChapter 1: Introduction to Django\n=================================\n\nThis book is about Django, a Web development framework that saves you time\nand makes Web development a joy. Using Django, you can build and maintain\nhigh-quality Web applications with minimal fuss.\n\nAt its best, Web development is an exciting, creative act; at its worst,\nit can be a repetitive, frustrating nuisance. Django lets you focus on the fun\nstuff -- the crux of your Web application -- while easing the pain of the\nrepetitive bits. In doing so, it provides high-level abstractions of common\nWeb development patterns, shortcuts for frequent programming tasks, and\nclear conventions for how to solve problems. At the same time, Django tries to\nstay out of your way, letting you work outside the scope of the framework as\nneeded.\n\nThe goal of this book is to make you a Django expert. The focus is twofold.\nFirst, we explain, in depth, what Django does and how to build Web\napplications with it. Second, we discuss higher-level concepts where\nappropriate, answering the question \"How can I apply these tools effectively\nin my own projects?\" By reading this book, you'll learn the skills needed to\ndevelop powerful Web sites quickly, with code that is clean and easy to\nmaintain.\n\nWhat Is a Web Framework?\n========================\n\nDjango is a prominent member of a new generation of *Web frameworks* -- but\nwhat does that term mean, precisely?\n\nTo answer that question, let's consider the design of a Web application written\nin Python *without* a framework. Throughout this book, we'll take this approach\nof showing you basic ways of getting work done *without* shortcuts, in the hope\nthat you'll recognize why shortcuts are so helpful. (It's also valuable to know\nhow to get things done without shortcuts because shortcuts aren't always\navailable. And most importantly, knowing *why* things work the way they do\nmakes you a better Web developer.)\n\nOne of the simplest, most direct ways to build a Python Web app from scratch is\nto use the Common Gateway Interface (CGI) standard, which was a popular\ntechnique circa 1998. Here's a high-level explanation of how it works: just\ncreate a Python script that outputs HTML, then save the script to a Web server\nwith a \".cgi\" extension and visit the page in your Web browser. That's it.\n\nHere's an example Python CGI script that displays the ten most recently\npublished books from a database. Don't worry about syntax details; just get a\nfeel for the basic things it's doing::\n\n #!/usr/bin/env python\n\n import MySQLdb\n\n print \"Content-Type: text/html\\n\"\n print \"Books\"\n print \"\"\n print \"

Books

\"\n print \"\"\n print \"\"\n\n connection.close()\n\nFirst, to fulfill the requirements of CGI, this code prints a \"Content-Type\"\nline, followed by a blank line. It prints some introductory HTML, connects to a\ndatabase and runs a query to retrieve the names of the latest ten books.\nLooping over those books, it generates an HTML list of the titles. Finally, it\nprints the closing HTML and closes the database connection.\n\nWith a one-off page like this one, the write-it-from-scratch approach isn't\nnecessarily bad. For one thing, this code is simple to comprehend -- even a\nnovice developer can read these 16 lines of Python and understand everything it\ndoes, from start to finish. There's nothing else to learn, no other code to\nread. It's also simple to deploy: just save this code in a file that ends with\n\".cgi\", upload that file to a Web server, and visit that page with a browser.\n\nBut despite its simplicity, this approach has a number of problems and\nannoyances. Ask yourself these questions:\n\n* What happens when multiple parts of your application need to connect to\n the database? Surely that database-connecting code shouldn't need to be\n duplicated in each individual CGI script. The pragmatic thing to do would\n be to refactor it into a shared function.\n\n* Should a developer really have to worry about printing the\n \"Content-Type\" line and remembering to close the database connection?\n This sort of boilerplate reduces programmer productivity and introduces\n opportunities for mistakes. These setup- and teardown-related tasks would\n best be handled by some common infrastructure.\n\n* What happens when this code is reused in multiple environments, each with\n a separate database and password? At this point, some\n environment-specific configuration becomes essential.\n\n* What happens when a Web designer who has no experience coding Python\n wishes to redesign the page? One wrong character could crash the entire\n application. Ideally, the logic of the page -- the retrieval of book\n titles from the database -- would be separate from the HTML display of\n the page, so that a designer could edit the latter without affecting the\n former.\n\nThese problems are precisely what a Web framework intends to solve. A Web\nframework provides a programming infrastructure for your applications, so that\nyou can focus on writing clean, maintainable code without having to reinvent\nthe wheel. In a nutshell, that's what Django does.\n\nThe MVC Design Pattern\n======================\n\nLet's dive in with a quick example that demonstrates the difference between the\nprevious approach and a Web framework's approach. Here's how you might write\nthe previous CGI code using Django. The first thing to note is that that we\nsplit it over four Python files (``models.py``, ``views.py``, ``urls.py``) and\nan HTML template (``latest_books.html``)::\n\n # models.py (the database tables)\n\n from django.db import models\n\n class Book(models.Model):\n name = models.CharField(max_length=50)\n pub_date = models.DateField()\n\n\n # views.py (the business logic)\n\n from django.shortcuts import render\n from models import Book\n\n def latest_books(request):\n book_list = Book.objects.order_by('-pub_date')[:10]\n return render(request, 'latest_books.html', {'book_list': book_list})\n\n\n # urls.py (the URL configuration)\n\n from django.conf.urls.defaults import *\n import views\n\n urlpatterns = patterns('',\n (r'^latest/$', views.latest_books),\n )\n\n\n # latest_books.html (the template)\n\n Books\n \n

Books

\n \n \n\nAgain, don't worry about the particulars of syntax; just get a feel for the\noverall design. The main thing to note here is the *separation of concerns*:\n\n* The ``models.py`` file contains a description of the database table,\n represented by a Python class. This class is called a *model*. Using it,\n you can create, retrieve, update and delete records in your database\n using simple Python code rather than writing repetitive SQL statements.\n\n* The ``views.py`` file contains the business logic for the page. The\n ``latest_books()`` function is called a *view*.\n\n* The ``urls.py`` file specifies which view is called for a given URL\n pattern. In this case, the URL ``/latest/`` will be handled by the\n ``latest_books()`` function. In other words, if your domain is\n example.com, any visit to the URL http://example.com/latest/ will call\n the ``latest_books()`` function.\n\n* The ``latest_books.html`` file is an HTML template that describes the\n design of the page. It uses a template language with basic logic\n statements -- e.g., ``{% for book in book_list %}``.\n\nTaken together, these pieces loosely follow a pattern called\nModel-View-Controller (MVC). Simply put, MVC is way of developing software so\nthat the code for defining and accessing data (the model) is separate from\nrequest-routing logic (the controller), which in turn is separate from the user\ninterface (the view). (We'll discuss MVC in more depth in Chapter 5.)\n\nA key advantage of such an approach is that components are *loosely coupled*.\nEach distinct piece of a Django-powered Web application has a single key\npurpose and can be changed independently without affecting the other pieces.\nFor example, a developer can change the URL for a given part of the application\nwithout affecting the underlying implementation. A designer can change a page's\nHTML without having to touch the Python code that renders it. A database\nadministrator can rename a database table and specify the change in a single\nplace, rather than having to search and replace through a dozen files.\n\nIn this book, each component of MVC gets its own chapter. Chapter 3 covers\nviews, Chapter 4 covers templates, and Chapter 5 covers models.\n\nDjango's History\n================\n\nBefore we dive into more code, we should take a moment to explain Django's\nhistory. We noted above that we'll be showing you how to do things *without*\nshortcuts so that you more fully understand the shortcuts. Similarly, it's\nuseful to understand *why* Django was created, because knowledge of the history\nwill put into context why Django works the way it does.\n\nIf you've been building Web applications for a while, you're probably familiar\nwith the problems in the CGI example we presented earlier. The classic Web\ndeveloper's path goes something like this:\n\n1. Write a Web application from scratch.\n2. Write another Web application from scratch.\n3. Realize the application from step 1 shares much in common with the\n application from step 2.\n4. Refactor the code so that application 1 shares code with application 2.\n5. Repeat steps 2-4 several times.\n6. Realize you've invented a framework.\n\nThis is precisely how Django itself was created!\n\nDjango grew organically from real-world applications written by a Web\ndevelopment team in Lawrence, Kansas, USA. It was born in the fall of 2003,\nwhen the Web programmers at the *Lawrence Journal-World* newspaper, Adrian\nHolovaty and Simon Willison, began using Python to build applications.\n\nThe World Online team, responsible for the production and maintenance of\nseveral local news sites, thrived in a development environment dictated by\njournalism deadlines. For the sites -- including LJWorld.com, Lawrence.com and\nKUsports.com -- journalists (and management) demanded that features be added\nand entire applications be built on an intensely fast schedule, often with only\ndays' or hours' notice. Thus, Simon and Adrian developed a time-saving Web\ndevelopment framework out of necessity -- it was the only way they could build\nmaintainable applications under the extreme deadlines.\n\nIn summer 2005, after having developed this framework to a point where it was\nefficiently powering most of World Online's sites, the team, which now included\nJacob Kaplan-Moss, decided to release the framework as open source software.\nThey released it in July 2005 and named it Django, after the jazz guitarist\nDjango Reinhardt.\n\nNow, several years later, Django is a well-established open source project with\ntens of thousands of users and contributors spread across the planet. Two of\nthe original World Online developers (the \"Benevolent Dictators for Life,\"\nAdrian and Jacob) still provide central guidance for the framework's growth,\nbut it's much more of a collaborative team effort.\n\nThis history is relevant because it helps explain two key things. The first is\nDjango's \"sweet spot.\" Because Django was born in a news environment, it offers\nseveral features (such as its admin site, covered in Chapter 6) that are\nparticularly well suited for \"content\" sites -- sites like Amazon.com,\ncraigslist.org, and washingtonpost.com that offer dynamic, database-driven\ninformation. Don't let that turn you off, though -- although Django is\nparticularly good for developing those sorts of sites, that doesn't preclude it\nfrom being an effective tool for building any sort of dynamic Web site.\n(There's a difference between being *particularly effective* at something and\nbeing *ineffective* at other things.)\n\nThe second matter to note is how Django's origins have shaped the culture of\nits open source community. Because Django was extracted from real-world code,\nrather than being an academic exercise or commercial product, it is acutely\nfocused on solving Web development problems that Django's developers themselves\nhave faced -- and continue to face. As a result, Django itself is actively\nimproved on an almost daily basis. The framework's maintainers have a vested\ninterest in making sure Django saves developers time, produces applications\nthat are easy to maintain and performs well under load. If nothing else, the\ndevelopers are motivated by their own selfish desires to save themselves time\nand enjoy their jobs. (To put it bluntly, they eat their own dog food.)\n\n.. AH The following sections are the type of content that typically appears\n.. AH in a book's Introduction section, but we include it here because this\n.. AH chapter serves as an introduction.\n\nHow to Read This Book\n=====================\n\nIn writing this book, we tried to strike a balance between readability and\nreference, with a bias toward readability. Our goal with this book, as stated\nearlier, is to make you a Django expert, and we believe the best way to teach is\nthrough prose and plenty of examples, rather than providing an exhaustive\nbut bland catalog of Django features. (As the saying goes, you can't expect to\nteach somebody how to speak a language merely by teaching them the alphabet.)\n\nWith that in mind, we recommend that you read Chapters 1 through 12 in order.\nThey form the foundation of how to use Django; once you've read them, you'll be\nable to build and deploy Django-powered Web sites. Specifically, Chapters 1\nthrough 7 are the \"core curriculum,\" Chapters 8 through 11 cover more advanced\nDjango usage, and Chapter 12 covers deployment. The remaining chapters, 13\nthrough 20, focus on specific Django features and can be read in any order.\n\nThe appendixes are for reference. They, along with the free documentation at\nhttp://www.djangoproject.com/, are probably what you'll flip back to occasionally to\nrecall syntax or find quick synopses of what certain parts of Django do.\n\nRequired Programming Knowledge\n------------------------------\n\nReaders of this book should understand the basics of procedural and\nobject-oriented programming: control structures (e.g., ``if``, ``while``,\n``for``), data structures (lists, hashes/dictionaries), variables, classes and\nobjects.\n\nExperience in Web development is, as you may expect, very helpful, but it's\nnot required to understand this book. Throughout the book, we try to promote\nbest practices in Web development for readers who lack this experience.\n\nRequired Python Knowledge\n-------------------------\n\nAt its core, Django is simply a collection of libraries written in the Python\nprogramming language. To develop a site using Django, you write Python code\nthat uses these libraries. Learning Django, then, is a matter of learning how\nto program in Python and understanding how the Django libraries work.\n\nIf you have experience programming in Python, you should have no trouble diving\nin. By and large, the Django code doesn't perform a lot of \"magic\" (i.e.,\nprogramming trickery whose implementation is difficult to explain or\nunderstand). For you, learning Django will be a matter of learning Django's\nconventions and APIs.\n\nIf you don't have experience programming in Python, you're in for a treat.\nIt's easy to learn and a joy to use! Although this book doesn't include a full\nPython tutorial, it highlights Python features and functionality where\nappropriate, particularly when code doesn't immediately make sense. Still, we\nrecommend you read the official Python tutorial, available online at\nhttp://docs.python.org/tut/. We also recommend Mark Pilgrim's free book\n*Dive Into Python*, available at http://www.diveintopython.net/ and published in\nprint by Apress.\n\nRequired Django Version\n-----------------------\n\nThis book covers Django 1.4.\n\nDjango's developers maintain backwards compatibility as much as possible, but\noccasionally introduce some backwards incompatible changes. The changes in each\nrelease are always covered in the release notes, which you can find here:\nhttps://docs.djangoproject.com/en/dev/releases/1.X\n\n\nGetting Help\n------------\n\nOne of the greatest benefits of Django is its kind and helpful user community.\nFor help with any aspect of Django -- from installation, to application design,\nto database design, to deployment -- feel free to ask questions online.\n\n* The django-users mailing list is where thousands of Django users hang out\n to ask and answer questions. Sign up for free at http://www.djangoproject.com/r/django-users.\n\n* The Django IRC channel is where Django users hang out to chat and help\n each other in real time. Join the fun by logging on to #django on the\n Freenode IRC network.\n\nWhat's Next\n-----------\n\nIn :doc:`chapter02`, we'll get started with Django, covering installation and\ninitial setup.\n" }, { "path": "Python/DjangoBook/chapter02.rst", "content": "==========================\nChapter 2: Getting Started\n==========================\n\nInstalling Django is a multi-step process, due to the multiple moving parts in\nmodern Web development environments. In this chapter, we'll walk you through\nhow to install the framework and its few dependencies.\n\nBecause Django is \"just\" Python code, it runs anywhere Python does -- including\non some cell phones! But this chapter just covers the common scenarios for\nDjango installations. We'll assume you're installing it either on a\ndesktop/laptop machine or a server.\n\nLater, in Chapter 12, we'll cover how to deploy Django to a production site.\n\nInstalling Python\n=================\n\nDjango itself is written purely in Python, so the first step in installing the\nframework is to make sure you have Python installed.\n\nPython Versions\n---------------\n\nThe core Django framework (version 1.4+) works with any Python version from 2.5\nto 2.7, inclusive. Django's optional GIS (Geographic Information Systems)\nsupport requires Python 2.5 to 2.7.\n\nIf you're not sure which version of Python to install and you have complete\nfreedom over the decision, pick the latest one in the 2.x series: version 2.7.\nAlthough Django works equally well with any version from 2.5 to 2.7, the later\nversions of Python have performance improvements and additional language\nfeatures you might like to use in your applications. Plus, certain third-party\nDjango add-ons that you might want to use might require a version newer than\nPython 2.5, so using a later version of Python keeps your options open.\n\n.. admonition:: Django and Python 3.0\n\n At the time of writing, Python 3.0 had been released, but Django\n only supported it experimentally. Python 3.0 introduced a\n substantial number of backwards-incompatible changes to the\n language itself, and, as a result, many major Python libraries and\n frameworks, including Django, had not yet caught up.\n\n Django 1.5 will support Python 2.6, 2.7, and 3.2. However,\n support for Python 3.2 is considered a \"preview\", which means the\n Django developers are not yet confident enough to promise\n stability in production. For that, they suggest you wait until\n Django 1.6.\n\nInstallation\n------------\n\nIf you're on Linux or Mac OS X, you probably have Python already installed.\nType ``python`` at a command prompt (or in Applications/Utilities/Terminal, in\nOS X). If you see something like this, then Python is installed::\n\n Python 2.7.3rc2 (default, Apr 22 2012, 22:30:17)\n [GCC 4.6.3] on linux2\n Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n >>>\n\nOtherwise, you'll need to download and install Python. It's fast and easy, and\ndetailed instructions are available at http://www.python.org/download/\n\nInstalling Django\n=================\n\nAt any given time, two distinct versions of Django are available to you: the\nlatest official release and the bleeding-edge development version. The version you\ndecide to install depends on your priorities. Do you want a stable and tested\nversion of Django, or do you want a version containing the latest features,\nperhaps so you can contribute to Django itself, at the expense of stability?\n\nWe'd recommend sticking with an official release, but it's important to know\nthat the development version exists, because you'll find it mentioned\nin the documentation and by members of the community.\n\nInstalling an Official Release\n------------------------------\n\nOfficial releases have a version number, such as 1.4.2, 1.4.1 or 1.4, and the latest\none is always available at http://www.djangoproject.com/download/.\n\nIf you're on a Linux distribution that includes a package of Django, it's a\ngood idea to use the distributor's version. That way, you'll get security\nupdates along with the rest of your system packages.\n\nIf you don't have access to a prepackaged version, you can download and install\nthe framework manually. To do so, first download the tarball, which will be\nnamed something like ``Django-1.4.2.tar.gz``. (It doesn't matter which\nlocal directory you download this file into; the installation process will put\nDjango's files in the right place.) Then, unzip it and run ``setup.py install``,\nas you do with most Python libraries.\n\nHere's how that process looks on Unix systems:\n\n#. ``tar xzvf Django-1.4.2.tar.gz``\n#. ``cd Django-*``\n#. ``sudo python setup.py install``\n\nOn Windows, we recommend using 7-Zip (http://www.djangoproject.com/r/7zip/)\nto unzip ``.tar.gz`` files. Once you've unzipped the file, start up a DOS\nshell (the \"Command Prompt\") with administrator privileges and run the\nfollowing command from within the directory whose name starts with ``Django-``::\n\n python setup.py install\n\nIn case you're curious: Django's files will be installed into your Python\ninstallation's ``site-packages`` directory -- a directory where Python looks\nfor third-party libraries. Usually it's in a place like\n``/usr/lib/python2.7/site-packages``.\n\nInstalling the \"Development\" Version\n------------------------------------\n\nDjango uses Git (http://git-scm.com) for its source control. The latest and\ngreatest Django development version available from Django's official Git\nrepository (https://github.com/django/django). You should consider installing\nthis version if you want to work on the bleeding edge, or if you want to\ncontribute code to Django itself.\n\nGit is a free, open source distributed revision-control system, and the Django\nteam uses it to manage changes to the Django codebase. You can download and\ninstall Git from http://git-scm.com/download but it is easier to install with\nyour operating system's package manager. You can use Git to grab the very latest\nDjango source code and, at any given time, you can update your local version of\nthe Django code to get the latest changes and improvements made by Django\ndevelopers.\n\nWhen using the development version, keep in mind there's no guarantee things\nwon't be broken at any given moment. With that said, though, some members of the\nDjango team run production sites on the development version, so they have an\nincentive to keep it stable.\n\nTo grab the latest Django, follow these steps:\n\n#. Make sure you have Git installed. You can get the\n software free from http://git-scm.com/, and you can find\n excellent documentation at http://git-scm.com/documentation.\n\n#. Clone the repository using the command ``git clone https://github.com/django/django djmaster``\n\n#. Locate your Python installation's ``site-packages`` directory. Usually\n it's in a place like ``/usr/lib/python2.7/site-packages``. If you have\n no idea, type this command from a command prompt::\n\n python -c 'import sys, pprint; pprint.pprint(sys.path)'\n\n The resulting output should include your ``site-packages`` directory.\n\n#. Within the ``site-packages`` directory, create a file called\n ``djmaster.pth`` and edit it to contain the full path to your ``djmaster``\n directory to it. For example, the file could just contain this line::\n\n /path/to/djmaster\n\n#. Place ``djmaster/django/bin`` on your system PATH. This directory\n includes management utilities such as ``django-admin.py``.\n\n.. admonition:: Tip:\n\n If ``.pth`` files are new to you, you can learn more about them at\n http://www.djangoproject.com/r/python/site-module/.\n\nAfter downloading from Git and following the preceding steps, there's no\nneed to run ``python setup.py install``-- you've just done the work by hand!\n\nBecause the Django code changes often with bug fixes and feature additions,\nyou'll probably want to update it every once in a while. To update the code,\njust run the command ``git pull origin master`` from within the ``djmaster``\ndirectory. When you run that command, Git will contact\nhttps://github.com/django/django, determine whether any of Django's code has\nchanged, and update your local version of the code with any changes that have\nbeen made since you last updated. It's quite slick.\n\nFinally, if you use Django development version, you should know how to figure\nout which version of Django you're running. Knowing your version number is\nimportant if you ever need to reach out to the community for help, or if you\nsubmit improvements to the framework. In these cases, you should tell people the\nrevision, also known as a \"commit,\" that you're using. To find out your current\ncommit, type \"git log -1\" from within the ``django`` directory, and look for the\nidentifier after \"commit\". This number changes each time Django is changed,\nwhether through a bug fix, feature addition, documentation improvement or\nanything else.\n\nTesting the Django installation\n===============================\n\nFor some post-installation positive feedback, take a moment to test whether the\ninstallation worked. In a command shell, change into another directory (e.g.,\n*not* the directory that contains the ``django`` directory) and start the\nPython interactive interpreter by typing ``python``. If the installation was\nsuccessful, you should be able to import the module ``django``:\n\n >>> import django\n >>> django.VERSION\n (1, 4, 2, 'final', 0)\n\n.. admonition:: Interactive Interpreter Examples\n\n The Python interactive interpreter is a command-line program that lets you\n write a Python program interactively. To start it, run the command\n ``python`` at the command line.\n\n Throughout this book, we feature example Python interactive interpreter\n sessions. You can recognize these examples by the triple\n greater-than signs (``>>>``), which designate the interpreter's prompt. If\n you're copying examples from this book, don't copy those greater-than signs.\n\n Multiline statements in the interactive interpreter are padded with three\n dots (``...``). For example::\n\n >>> print \"\"\"This is a\n ... string that spans\n ... three lines.\"\"\"\n This is a\n string that spans\n three lines.\n >>> def my_function(value):\n ... print value\n >>> my_function('hello')\n hello\n\n Those three dots at the start of the additional lines are inserted by the\n Python shell -- they're not part of our input. We include them here to be\n faithful to the actual output of the interpreter. If you copy our examples\n to follow along, don't copy those dots.\n\nSetting Up a Database\n=====================\n\nAt this point, you could very well begin writing a Web application with Django,\nbecause Django's only hard-and-fast prerequisite is a working Python\ninstallation. However, odds are you'll be developing a *database-driven* Web\nsite, in which case you'll need to configure a database server.\n\nIf you just want to start playing with Django, skip ahead to the\n\"Starting a Project\" section -- but keep in mind that all the examples in this\nbook assume you have a working database set up.\n\nDjango supports four database engines:\n\n* PostgreSQL (http://www.postgresql.org/)\n* SQLite 3 (http://www.sqlite.org/)\n* MySQL (http://www.mysql.com/)\n* Oracle (http://www.oracle.com/)\n\nFor the most part, all the engines here work equally well with the core Django\nframework. (A notable exception is Django's optional GIS support, which is much\nmore powerful with PostgreSQL than with other databases.) If you're not tied to\nany legacy system and have the freedom to choose a database backend, we\nrecommend PostgreSQL, which achieves a fine balance between cost, features,\nspeed and stability.\n\nSetting up the database is a two-step process:\n\n* First, you'll need to install and configure the database server itself.\n This process is beyond the scope of this book, but each of the four\n database backends has rich documentation on its Web site. (If you're on\n a shared hosting provider, odds are that they've set this up for you\n already.)\n\n* Second, you'll need to install the Python library for your particular\n database backend. This is a third-party bit of code that allows Python to\n interface with the database. We outline the specific, per-database\n requirements in the following sections.\n\nIf you're just playing around with Django and don't want to install a database\nserver, consider using SQLite. SQLite is unique in the list of supported\ndatabases in that it doesn't require either of the above steps. It merely reads\nand writes its data to a single file on your filesystem, and Python versions 2.5\nand higher include built-in support for it.\n\nOn Windows, obtaining database driver binaries can be frustrating. If you're\neager to jump in, we recommend using Python 2.7 and its built-in support for\nSQLite.\n\nUsing Django with PostgreSQL\n----------------------------\n\nIf you're using PostgreSQL, you'll need to install either the ``psycopg`` or\n``psycopg2`` package from http://www.djangoproject.com/r/python-pgsql/. We\nrecommend ``psycopg2``, as it's newer, more actively developed and can be\neasier to install. Either way, take note of whether you're using version 1 or\n2; you'll need this information later.\n\nIf you're using PostgreSQL on Windows, you can find precompiled binaries of\n``psycopg`` at http://www.djangoproject.com/r/python-pgsql/windows/.\n\nIf you're on Linux, check whether your distribution's package-management\nsystem offers a package called \"python-psycopg2\", \"psycopg2-python\",\n\"python-postgresql\" or something similar.\n\nUsing Django with SQLite 3\n--------------------------\n\nYou're in luck: no database-specific installation is required, because Python\nships with SQLite support. Skip ahead to the next section.\n\nUsing Django with MySQL\n-----------------------\n\nDjango requires MySQL 4.0 or above. The 3.x versions don't support nested\nsubqueries and some other fairly standard SQL statements.\n\nYou'll also need to install the ``MySQLdb`` package from\nhttp://www.djangoproject.com/r/python-mysql/.\n\nIf you're on Linux, check whether your distribution's package-management system\noffers a package called \"python-mysql\", \"python-mysqldb\", \"mysql-python\" or\nsomething similar.\n\nUsing Django with Oracle\n------------------------\n\nDjango works with Oracle Database Server versions 9i and higher.\n\nIf you're using Oracle, you'll need to install the ``cx_Oracle`` library,\navailable at http://cx-oracle.sourceforge.net/. Use version 4.3.1 or higher, but\navoid version 5.0 due to a bug in that version of the driver. Version 5.0.1\nresolved the bug, however, so you can choose a higher version as well.\n\nUsing Django Without a Database\n-------------------------------\n\nAs mentioned earlier, Django doesn't actually require a database. If you just\nwant to use it to serve dynamic pages that don't hit a database, that's\nperfectly fine.\n\nWith that said, bear in mind that some of the extra tools bundled with Django\n*do* require a database, so if you choose not to use a database, you'll miss\nout on those features. (We highlight these features throughout this book.)\n\nStarting a Project\n==================\n\nOnce you've installed Python, Django and (optionally) your database\nserver/library, you can take the first step in developing a Django application\nby creating a *project*.\n\nA project is a collection of settings for an instance of Django, including\ndatabase configuration, Django-specific options and application-specific\nsettings.\n\nIf this is your first time using Django, you'll have to take care of some\ninitial setup. Create a new directory to start working in, perhaps something\nlike ``/home/username/djcode/``.\n\n.. admonition:: Where Should This Directory Live?\n\n If your background is in PHP, you're probably used to putting code under the\n Web server's document root (in a place such as ``/var/www``). With Django,\n you don't do that. It's not a good idea to put any of this Python code\n within your Web server's document root, because in doing so you risk the\n possibility that people will be able to view your raw source code over the\n Web. That's not good.\n\n Put your code in some directory **outside** of the document root.\n\nChange into the directory you created, and run the command\n``django-admin.py startproject mysite``. This will create a ``mysite``\ndirectory in your current directory.\n\n.. note::\n\n ``django-admin.py`` should be on your system path if you installed Django\n via its ``setup.py`` utility.\n\n If you're using the development version, you'll find ``django-admin.py`` in\n ``djmaster/django/bin``. Because you'll be using ``django-admin.py``\n often, consider adding it to your system path. On Unix, you can do so by\n symlinking from ``/usr/local/bin``, using a command such as ``sudo ln -s\n /path/to/django/bin/django-admin.py /usr/local/bin/django-admin.py``. On\n Windows, you'll need to update your ``PATH`` environment variable.\n\n If you installed Django from a packaged version for your Linux\n distribution, ``django-admin.py`` might be called ``django-admin`` instead.\n\nIf you see a \"permission denied\" message when running\n``django-admin.py startproject``, you'll need to change the file's permissions.\nTo do this, navigate to the directory where ``django-admin.py`` is installed\n(e.g., ``cd /usr/local/bin``) and run the command ``chmod +x django-admin.py``.\n\nThe ``startproject`` command creates a directory containing five files::\n\n mysite/\n manage.py\n mysite/\n __init__.py\n settings.py\n urls.py\n wsgi.py\n\n.. note:: Doesn't match what you see?\n\n The default project layout recently changed. If you're seeing a\n \"flat\" layout (with no inner ``mysite/`` directory), you're probably using\n a version of Django that doesn't match this tutorial version. This book covers\n Django 1.4 and above, so if you're using an older version you probably want to\n consult Django's official documentation.\n\n The documentation for Django 1.X version is available at https://docs.djangoproject.com/en/1.X/.\n\nThese files are as follows:\n\n* ``mysite/``: The outer ``mysite/`` directory is just a container for your project.\n Its name doesn't matter to Django; you can rename it to anything you like.\n\n* ``manage.py``: A command-line utility that lets you interact with this\n Django project in various ways. Type ``python manage.py help`` to get a\n feel for what it can do. You should never have to edit this file; it's\n created in this directory purely for convenience.\n\n* ``mysite/mysite/``: The inner ``mysite/`` directory is the actual Python package\n for your project. Its name is the Python package name you'll need to use to\n import anything inside it (e.g. ``import mysite.settings``).\n\n* ``__init__.py``: A file required for Python to treat the ``mysite``\n directory as a package (i.e., a group of Python modules). It's an empty\n file, and generally you won't add anything to it.\n\n* ``settings.py``: Settings/configuration for this Django project. Take a\n look at it to get an idea of the types of settings available, along with\n their default values.\n\n* ``urls.py``: The URLs for this Django project. Think of this as the\n \"table of contents\" of your Django-powered site.\n\n* ``wsgi.py``: An entry-point for WSGI-compatible webservers to serve your project.\n See How to deploy with WSGI (https://docs.djangoproject.com/en/1.4/howto/deployment/wsgi/) for more details.\n\nDespite their small size, these files already constitute a working Django\napplication.\n\nRunning the Development Server\n------------------------------\n\nFor some more post-installation positive feedback, let's run the Django\ndevelopment server to see our barebones application in action.\n\nThe Django development server (also called the \"runserver\" after the command\nthat launches it) is a built-in, lightweight Web server you can use while\ndeveloping your site. It's included with Django so you can develop your site\nrapidly, without having to deal with configuring your production server (e.g.,\nApache) until you're ready for production. The development server watches your\ncode and automatically reloads it, making it easy for you to change your code\nwithout needing to restart anything.\n\nTo start the server, change into your project container directory (``cd mysite``),\nif you haven't already, and run this command::\n\n python manage.py runserver\n\nYou'll see something like this::\n\n Validating models...\n 0 errors found.\n\n Django version 1.4.2, using settings 'mysite.settings'\n Development server is running at http://127.0.0.1:8000/\n Quit the server with CONTROL-C.\n\nThis launches the server locally, on port 8000, accessible only to connections\nfrom your own computer. Now that it's running, visit http://127.0.0.1:8000/\nwith your Web browser. You might see a different Django version depending on\nwhich version of Django you have installed. You'll see a \"Welcome to Django\" page shaded in a\npleasant pastel blue. It worked!\n\nOne final, important note about the development server is worth mentioning\nbefore proceeding. Although this server is convenient for development, resist\nthe temptation to use it in anything resembling a production environment. The\ndevelopment server can handle only a single request at a time reliably, and it\nhas not gone through a security audit of any sort. When the time comes to\nlaunch your site, see Chapter 12 for information on how to deploy Django.\n\n.. admonition:: Changing the Development Server's Host or Port\n\n By default, the ``runserver`` command starts the development server on port\n 8000, listening only for local connections. If you want to change the\n server's port, pass it as a command-line argument::\n\n python manage.py runserver 8080\n\n By specifying an IP address, you can tell the server to allow non-local\n connections. This is especially helpful if you'd like to share a\n development site with other members of your team. The IP address\n ``0.0.0.0`` tells the server to listen on any network interface::\n\n python manage.py runserver 0.0.0.0:8000\n\n When you've done this, other computers on your local network will be able\n to view your Django site by visiting your IP address in their Web browsers,\n e.g., http://192.168.1.103:8000/ . (Note that you'll have to consult your\n network settings to determine your IP address on the local network. Unix\n users, try running \"ifconfig\" in a command prompt to get this information.\n Windows users, try \"ipconfig\".)\n\nWhat's Next?\n============\n\nNow that you have everything installed and the development server running,\nyou're ready to :doc:`learn the basics ` of serving Web pages with Django.\n" }, { "path": "Python/DjangoBook/chapter03.rst", "content": "=============================\nChapter 3: Views and URLconfs\n=============================\n\nIn the previous chapter, we explained how to set up a Django project and run the\nDjango development server. In this chapter, you'll learn the basics of creating\ndynamic Web pages with Django.\n\nYour First Django-Powered Page: Hello World\n===========================================\n\nAs our first goal, let's create a Web page that outputs that famous example\nmessage: \"Hello world.\"\n\nIf you were publishing a simple \"Hello world\" Web page without a Web framework,\nyou'd simply type \"Hello world\" into a text file, call it ``hello.html``,\nand upload it to a directory on a Web server somewhere. Notice, in that\nprocess, you've specified two key pieces of information about that Web page:\nits contents (the string ``\"Hello world\"``) and its URL (\n``http://www.example.com/hello.html``, or maybe ``http://www.example.com/files/hello.html``\nif you put it in a subdirectory).\n\nWith Django, you specify those same two things, but in a different way. The\ncontents of the page are produced by a *view function*, and the URL is\nspecified in a *URLconf*. First, let's write our \"Hello world\" view function.\n\nYour First View\n---------------\n\nWithin the ``mysite`` directory that ``django-admin.py startproject`` made in\nthe last chapter, create an empty file called ``views.py``. This Python module\nwill contain our views for this chapter. Note that there's nothing special\nabout the name ``views.py`` -- Django doesn't care what the file is called, as\nyou'll see in a bit -- but it's a good idea to call it ``views.py`` as a\nconvention, for the benefit of other developers reading your code.\n\nOur \"Hello world\" view is simple. Here's the entire function, plus import\nstatements, which you should type into the ``views.py`` file::\n\n from django.http import HttpResponse\n\n def hello(request):\n return HttpResponse(\"Hello world\")\n\nLet's step through this code one line at a time:\n\n* First, we import the class ``HttpResponse``, which lives in the\n ``django.http`` module. We need to import this class because it's used\n later in our code.\n\n* Next, we define a function called ``hello`` -- the view function.\n\n Each view function takes at least one parameter, called ``request`` by\n convention. This is an object that contains information about the\n current Web request that has triggered this view, and it's an instance of\n the class ``django.http.HttpRequest``. In this example, we don't do\n anything with ``request``, but it must be the first parameter of the view\n nonetheless.\n\n Note that the name of the view function doesn't matter; it doesn't have\n to be named in a certain way in order for Django to recognize it. We're\n calling it ``hello`` here, because that name clearly indicates the gist\n of the view, but it could just as well be named\n ``hello_wonderful_beautiful_world``, or something equally revolting. The\n next section, \"Your First URLconf\", will shed light on how Django finds\n this function.\n\n* The function is a simple one-liner: it merely returns an ``HttpResponse``\n object that has been instantiated with the text ``\"Hello world\"``.\n\nThe main lesson here is this: a view is just a Python function that takes an\n``HttpRequest`` as its first parameter and returns an instance of\n``HttpResponse``. In order for a Python function to be a Django view, it must\ndo these two things. (There are exceptions, but we'll get to those later.)\n\nYour First URLconf\n------------------\n\nIf, at this point, you ran ``python manage.py runserver`` again, you'd still\nsee the \"Welcome to Django\" message, with no trace of our \"Hello world\" view\nanywhere. That's because our ``mysite`` project doesn't yet know about the\n``hello`` view; we need to tell Django explicitly that we're activating this\nview at a particular URL. (Continuing our previous analogy of publishing\nstatic HTML files, at this point we've created the HTML file but haven't\nuploaded it to a directory on the server yet.) To hook a view function to a\nparticular URL with Django, use a URLconf.\n\nA *URLconf* is like a table of contents for your Django-powered Web site.\nBasically, it's a mapping between URLs and the view functions that\nshould be called for those URLs. It's how you tell Django, \"For this\nURL, call this code, and for that URL, call that code.\" For example, \"When\nsomebody visits the URL ``/foo/``, call the view function ``foo_view()``, which\nlives in the Python module ``views.py``.\"\n\nWhen you executed ``django-admin.py startproject`` in the previous chapter, the\nscript created a URLconf for you automatically: the file ``urls.py``. By\ndefault, it looks something like this::\n\n from django.conf.urls import patterns, include, url\n\n # Uncomment the next two lines to enable the admin:\n # from django.contrib import admin\n # admin.autodiscover()\n\n urlpatterns = patterns('',\n # Examples:\n # url(r'^$', 'mysite.views.home', name='home'),\n # url(r'^mysite/', include('mysite.foo.urls')),\n\n # Uncomment the admin/doc line below to enable admin documentation:\n # url(r'^admin/doc/', include('django.contrib.admindocs.urls')),\n\n # Uncomment the next line to enable the admin:\n # url(r'^admin/', include(admin.site.urls)),\n )\n\nThis default URLconf includes some commonly used Django features commented out,\nso that activating those features is as easy as uncommenting the appropriate\nlines. If we ignore the commented-out code, here's the essence of a URLconf::\n\n from django.conf.urls.defaults import patterns, include, url\n\n urlpatterns = patterns('',\n )\n\nLet's step through this code one line at a time:\n\n* The first line imports three functions from the ``django.conf.urls.defaults``\n module, which is Django's URLconf infrastructure: ``patterns``, ``include``,\n and ``urls``.\n\n* The second line calls the function ``patterns`` and saves the result\n into a variable called ``urlpatterns``. The ``patterns`` function gets\n passed only a single argument -- the empty string. (The string can be\n used to supply a common prefix for view functions, which we'll cover in\n :doc:`chapter08`.)\n\nThe main thing to note here is the variable ``urlpatterns``, which Django\nexpects to find in your URLconf module. This variable defines the mapping\nbetween URLs and the code that handles those URLs. By default, as we can see,\nthe URLconf is empty -- your Django application is a blank slate. (As a side\nnote, that's how Django knew to show you the \"Welcome to Django\" page in the\nlast chapter. If your URLconf is empty, Django assumes you just started a new\nproject and, hence, displays that message.)\n\nTo add a URL and view to the URLconf, just add a mapping between a URL\npattern and the view function. Here's how to hook in our ``hello`` view::\n\n from django.conf.urls.defaults import patterns, include, url\n from mysite.views import hello\n\n urlpatterns = patterns('',\n url(r'^hello/$', hello),\n )\n\n(Note that we've removed the commented-out code for brevity. You can choose\nto leave those lines in, if you'd like.)\n\nWe made two changes here:\n\n* First, we imported the ``hello`` view from its module --\n ``mysite/views.py``, which translates into ``mysite.views`` in Python\n import syntax. (This assumes ``mysite/views.py`` is on your Python path;\n see the sidebar for details.)\n\n* Next, we added the line ``url(r'^hello/$', hello),`` to ``urlpatterns``. This\n line is referred to as a *URLpattern*. The ``url()`` function tells Django how\n to handle the url that you are configuring. The first argument is a\n pattern-matching string (a regular expression; more on this in a bit) and the\n second argument is the view function to use for that pattern. ``url()`` can\n take other optional arguments as well, which we'll cover in more depth in\n :doc:`chapter08`.\n\n.. note::\n\n One more important detail we've introduced here is that ``r`` character in\n front of the regular expression string. This tells Python that the string is a\n \"raw string\" -- its contents should not interpret backslashes. In normal\n Python strings, backslashes are used for escaping special characters -- such\n as in the string ``'\\n'``, which is a one-character string containing a\n newline. When you add the ``r`` to make it a raw string, Python does not apply\n its backslash escaping -- so, ``r'\\n'`` is a two-character string containing a\n literal backslash and a lowercase \"n\". There's a natural collision between\n Python's usage of backslashes and the backslashes that are found in regular\n expressions, so it's strongly suggested that you use raw strings any time\n you're defining a regular expression in Python. All of the URLpatterns in this\n book will be raw strings.\n\nIn a nutshell, we just told Django that any request to the URL ``/hello/`` should\nbe handled by the ``hello`` view function.\n\n.. admonition:: Your Python Path\n\n Your *Python path* is the list of directories on your system where Python\n looks when you use the Python ``import`` statement.\n\n For example, let's say your Python path is set to ``['',\n '/usr/lib/python2.7/site-packages', '/home/username/djcode']``. If you\n execute the Python statement ``from foo import bar``, Python will look for\n a module called ``foo.py`` in the current directory. (The first entry in the\n Python path, an empty string, means \"the current directory.\") If that file\n doesn't exist, Python will look for the file\n ``/usr/lib/python2.7/site-packages/foo.py``. If that file doesn't exist, it\n will try ``/home/username/djcode/foo.py``. Finally, if *that* file doesn't\n exist, it will raise ``ImportError``.\n\n If you're interested in seeing the value of your Python path, start the\n Python interactive interpreter and type this::\n\n >>> import sys\n >>> print sys.path\n\n Generally you don't have to worry about setting your Python path -- Python\n and Django take care of things for you automatically behind the scenes.\n (Setting the Python path is one of the things that the ``manage.py`` script\n does.)\n\nIt's worth discussing the syntax of this URLpattern, as it may not be\nimmediately obvious. Although we want to match the URL ``/hello/``, the pattern\nlooks a bit different than that. Here's why:\n\n* Django removes the slash from the front of every incoming URL before it\n checks the URLpatterns. This means that our URLpattern doesn't include\n the leading slash in ``/hello/``. (At first, this may seem unintuitive,\n but this requirement simplifies things -- such as the inclusion of\n URLconfs within other URLconfs, which we'll cover in Chapter 8.)\n\n* The pattern includes a caret (``^``) and a dollar sign (``$``). These are\n regular expression characters that have a special meaning: the caret\n means \"require that the pattern matches the start of the string,\" and the\n dollar sign means \"require that the pattern matches the end of the\n string.\"\n\n This concept is best explained by example. If we had instead used the\n pattern ``'^hello/'`` (without a dollar sign at the end), then *any* URL\n starting with ``/hello/`` would match, such as ``/hello/foo`` and\n ``/hello/bar``, not just ``/hello/``. Similarly, if we had left off the\n initial caret character (i.e., ``'hello/$'``), Django would match *any*\n URL that ends with ``hello/``, such as ``/foo/bar/hello/``. If we had\n simply used ``hello/``, without a caret *or* dollar sign, then any URL\n containing ``hello/`` would match, such as ``/foo/hello/bar``. Thus, we\n use both the caret and dollar sign to ensure that only the URL\n ``/hello/`` matches -- nothing more, nothing less.\n\n Most of your URLpatterns will start with carets and end with dollar\n signs, but it's nice to have the flexibility to perform more\n sophisticated matches.\n\n You may be wondering what happens if someone requests the URL ``/hello``\n (that is, *without* a trailing slash). Because our URLpattern requires a\n trailing slash, that URL would *not* match. However, by default, any\n request to a URL that *doesn't* match a URLpattern and *doesn't* end with\n a slash will be redirected to the same URL with a trailing slash. (This\n is regulated by the ``APPEND_SLASH`` Django setting, which is covered in\n Appendix D.)\n\n If you're the type of person who likes all URLs to end with slashes\n (which is the preference of Django's developers), all you'll need to do\n is add a trailing slash to each URLpattern and leave ``APPEND_SLASH`` set\n to ``True``. If you prefer your URLs *not* to have trailing slashes, or\n if you want to decide it on a per-URL basis, set ``APPEND_SLASH`` to\n ``False`` and put trailing slashes in your URLpatterns as you see fit.\n\nThe other thing to note about this URLconf is that we've passed the\n``hello`` view function as an object without calling the function. This is a\nkey feature of Python (and other dynamic languages): functions are first-class\nobjects, which means you can pass them around just like any other variables.\nCool stuff, eh?\n\nTo test our changes to the URLconf, start the Django development server, as you\ndid in Chapter 2, by running the command ``python manage.py runserver``. (If you\nleft it running, that's fine, too. The development server automatically detects\nchanges to your Python code and reloads as necessary, so you don't have to\nrestart the server between changes.) The server is running at the address\n``http://127.0.0.1:8000/``, so open up a Web browser and go to\n``http://127.0.0.1:8000/hello/``. You should see the text \"Hello world\" -- the\noutput of your Django view.\n\nHooray! You've made your first Django-powered Web page.\n\n.. admonition:: Regular Expressions\n\n *Regular expressions* (or *regexes*) are a compact way of specifying\n patterns in text. While Django URLconfs allow arbitrary regexes for\n powerful URL matching, you'll probably only use a few regex symbols in\n practice. Here's a selection of common symbols:\n\n ============ ==========================================================\n Symbol Matches\n ============ ==========================================================\n ``.`` (dot) Any single character\n\n ``\\d`` Any single digit\n\n ``[A-Z]`` Any character between ``A`` and ``Z`` (uppercase)\n\n ``[a-z]`` Any character between ``a`` and ``z`` (lowercase)\n\n ``[A-Za-z]`` Any character between ``a`` and ``z`` (case-insensitive)\n\n ``+`` One or more of the previous expression (e.g., ``\\d+``\n matches one or more digits)\n\n ``[^/]+`` One or more characters until (and not including) a\n forward slash\n\n ``?`` Zero or one of the previous expression (e.g., ``\\d?``\n matches zero or one digits)\n\n ``*`` Zero or more of the previous expression (e.g., ``\\d*``\n matches zero, one or more than one digit)\n\n ``{1,3}`` Between one and three (inclusive) of the previous\n expression (e.g., ``\\d{1,3}`` matches one, two or three\n digits)\n ============ ==========================================================\n\n For more on regular expressions, see http://www.djangoproject.com/r/python/re-module/.\n\nA Quick Note About 404 Errors\n-----------------------------\n\nAt this point, our URLconf defines only a single URLpattern: the one that\nhandles requests to the URL ``/hello/``. What happens when you request a\ndifferent URL?\n\nTo find out, try running the Django development server and visiting a page such\nas ``http://127.0.0.1:8000/goodbye/`` or\n``http://127.0.0.1:8000/hello/subdirectory/``, or even ``http://127.0.0.1:8000/``\n(the site \"root\"). You should see a \"Page not found\" message (see Figure 3-1).\nDjango displays this message because you requested a URL that's not defined in\nyour URLconf.\n\n.. figure:: graphics/chapter03/404.png\n :alt: Screenshot of Django's 404 page.\n\n Figure 3-1. Django's 404 page\n\nThe utility of this page goes beyond the basic 404 error message. It also tells\nyou precisely which URLconf Django used and every pattern in that URLconf. From\nthat information, you should be able to tell why the requested URL threw a 404.\n\nNaturally, this is sensitive information intended only for you, the Web\ndeveloper. If this were a production site deployed live on the Internet, you\nwouldn't want to expose that information to the public. For that reason, this\n\"Page not found\" page is only displayed if your Django project is in *debug\nmode*. We'll explain how to deactivate debug mode later. For now, just know\nthat every Django project is in debug mode when you first create it, and if the\nproject is not in debug mode, Django outputs a different 404 response.\n\nA Quick Note About The Site Root\n--------------------------------\n\nAs explained in the last section, you'll see a 404 error message if you view\nthe site root -- ``http://127.0.0.1:8000/``. Django doesn't add magically\nanything to the site root; that URL is not special-cased in any way. It's up to\nyou to assign it to a URLpattern, just like every other entry in your URLconf.\n\nThe URLpattern to match the site root is a bit unintuitive, though, so it's\nworth mentioning. When you're ready to implement a view for the site root, use\nthe URLpattern ``'^$'``, which matches an empty string. For example::\n\n from mysite.views import hello, my_homepage_view\n\n urlpatterns = patterns('',\n url(r'^$', my_homepage_view),\n # ...\n )\n\nHow Django Processes a Request\n==============================\n\nBefore continuing to our second view function, let's pause to learn a little\nmore about how Django works. Specifically, when you view your \"Hello world\"\nmessage by visiting ``http://127.0.0.1:8000/hello/`` in your Web browser, what\ndoes Django do behind the scenes?\n\nIt all starts with the *settings file*. When you run ``python manage.py\nrunserver``, the script looks for a file called ``settings.py`` in the inner\n``mysite`` directory. This file contains all sorts of configuration for this\nparticular Django project, all in uppercase: ``TEMPLATE_DIRS``, ``DATABASES``,\netc. The most important setting is called ``ROOT_URLCONF``. ``ROOT_URLCONF``\ntells Django which Python module should be used as the URLconf for this Web\nsite.\n\nRemember when ``django-admin.py startproject`` created the files\n``settings.py`` and ``urls.py``? The autogenerated ``settings.py`` contains a\n``ROOT_URLCONF`` setting that points to the autogenerated ``urls.py``. Open the\n``settings.py`` file and see for yourself; it should look like this::\n\n ROOT_URLCONF = 'mysite.urls'\n\nThis corresponds to the file ``mysite/urls.py``.\n\nWhen a request comes in for a particular URL -- say, a request for ``/hello/``\n-- Django loads the URLconf pointed to by the ``ROOT_URLCONF`` setting. Then it\nchecks each of the URLpatterns in that URLconf, in order, comparing the\nrequested URL with the patterns one at a time, until it finds one that matches.\nWhen it finds one that matches, it calls the view function associated with that\npattern, passing it an ``HttpRequest`` object as the first parameter. (We'll\ncover the specifics of ``HttpRequest`` later.)\n\nAs we saw in our first view example, a view function must return an\n``HttpResponse``. Once it does this, Django does the rest, converting the\nPython object to a proper Web response with the appropriate HTTP headers and\nbody (i.e., the content of the Web page).\n\nIn summary:\n\n1. A request comes in to ``/hello/``.\n2. Django determines the root URLconf by looking at the ``ROOT_URLCONF``\n setting.\n3. Django looks at all of the URLpatterns in the URLconf for the first one\n that matches ``/hello/``.\n4. If it finds a match, it calls the associated view function.\n5. The view function returns an ``HttpResponse``.\n6. Django converts the ``HttpResponse`` to the proper HTTP response, which\n results in a Web page.\n\nYou now know the basics of how to make Django-powered pages. It's quite simple,\nreally -- just write view functions and map them to URLs via URLconfs.\n\nYour Second View: Dynamic Content\n=================================\n\nOur \"Hello world\" view was instructive in demonstrating the basics of how\nDjango works, but it wasn't an example of a *dynamic* Web page, because the\ncontent of the page are always the same. Every time you view ``/hello/``,\nyou'll see the same thing; it might as well be a static HTML file.\n\nFor our second view, let's create something more dynamic -- a Web page that\ndisplays the current date and time. This is a nice, simple next step, because\nit doesn't involve a database or any user input -- just the output of your\nserver's internal clock. It's only marginally more exciting than \"Hello world,\"\nbut it'll demonstrate a few new concepts.\n\nThis view needs to do two things: calculate the current date and time, and\nreturn an ``HttpResponse`` containing that value. If you have experience with\nPython, you know that Python includes a ``datetime`` module for calculating\ndates. Here's how to use it::\n\n >>> import datetime\n >>> now = datetime.datetime.now()\n >>> now\n datetime.datetime(2008, 12, 13, 14, 9, 39, 2731)\n >>> print now\n 2008-12-13 14:09:39.002731\n\nThat's simple enough, and it has nothing to do with Django. It's just Python\ncode. (We want to emphasize that you should be aware of what code is \"just\nPython\" vs. code that is Django-specific. As you learn Django, we want you to\nbe able to apply your knowledge to other Python projects that don't necessarily\nuse Django.)\n\nTo make a Django view that displays the current date and time, then, we just\nneed to hook this ``datetime.datetime.now()`` statement into a view and return\nan ``HttpResponse``. Here's how that looks::\n\n from django.http import HttpResponse\n import datetime\n\n def current_datetime(request):\n now = datetime.datetime.now()\n html = \"It is now %s.\" % now\n return HttpResponse(html)\n\nAs with our ``hello`` view function, this should live in ``views.py``. Note\nthat we've hidden the ``hello`` function from this example for brevity, but for\nthe sake of completeness, here's what the entire ``views.py`` looks like::\n\n from django.http import HttpResponse\n import datetime\n\n def hello(request):\n return HttpResponse(\"Hello world\")\n\n def current_datetime(request):\n now = datetime.datetime.now()\n html = \"It is now %s.\" % now\n return HttpResponse(html)\n\n(From now on, we won't display previous code in code examples, except when\nnecessary. You should be able to tell from context which parts of an example\nare new vs. old.)\n\nLet's step through the changes we've made to ``views.py`` to accommodate\nthe ``current_datetime`` view.\n\n* We've added an ``import datetime`` to the top of the module, so we can\n calculate dates.\n\n* The new ``current_datetime`` function calculates the current date and\n time, as a ``datetime.datetime`` object, and stores that as the local\n variable ``now``.\n\n* The second line of code within the view constructs an HTML response using\n Python's \"format-string\" capability. The ``%s`` within the string is a\n placeholder, and the percent sign after the string means \"Replace the\n ``%s`` in the preceding string with the value of the variable ``now``.\"\n The ``now`` variable is technically a ``datetime.datetime`` object, not\n a string, but the ``%s`` format character converts it to its string\n representation, which is something like ``\"2008-12-13 14:09:39.002731\"``.\n This will result in an HTML string such as\n ``\"It is now 2008-12-13 14:09:39.002731.\"``.\n\n (Yes, our HTML is invalid, but we're trying to keep the example simple\n and short.)\n\n* Finally, the view returns an ``HttpResponse`` object that contains the\n generated response -- just as we did in ``hello``.\n\nAfter adding that to ``views.py``, add the URLpattern to ``urls.py`` to tell\nDjango which URL should handle this view. Something like ``/time/`` would make\nsense::\n\n from django.conf.urls.defaults import patterns, include, url\n from mysite.views import hello, current_datetime\n\n urlpatterns = patterns('',\n url(r'^hello/$', hello),\n url(r'^time/$', current_datetime),\n )\n\nWe've made two changes here. First, we imported the ``current_datetime``\nfunction at the top. Second, and more importantly, we added a URLpattern\nmapping the URL ``/time/`` to that new view. Getting the hang of this?\n\nWith the view written and URLconf updated, fire up the ``runserver`` and visit\n``http://127.0.0.1:8000/time/`` in your browser. You should see the current\ndate and time.\n\n.. admonition:: Django's Time Zone\n\n Depending on your computer, the date and time may be a few hours off.\n That's because Django is time zone-aware and defaults to the\n ``America/Chicago`` time zone. (It has to default to *something*, and that's\n the time zone where the original developers live.) If you live elsewhere,\n you'll want to change it in ``settings.py``. See the comment in that file\n for a link to an up-to-date list of worldwide time zone options.\n\nURLconfs and Loose Coupling\n===========================\n\nNow's a good time to highlight a key philosophy behind URLconfs and behind\nDjango in general: the principle of *loose coupling*. Simply put, loose coupling\nis a software-development approach that values the importance of making pieces\ninterchangeable. If two pieces of code are loosely coupled, then changes made to\none of the pieces will have little or no effect on the other.\n\nDjango's URLconfs are a good example of this principle in practice. In a Django\nweb application, the URL definitions and the view functions they call are\nloosely coupled; that is, the decision of what the URL should be for a given\nfunction, and the implementation of the function itself, reside in two separate\nplaces. This lets you switch out one piece without affecting the other.\n\nFor example, consider our ``current_datetime`` view. If we wanted to change the\nURL for the application -- say, to move it from ``/time/`` to\n``/current-time/`` -- we could make a quick change to the URLconf, without\nhaving to worry about the view itself. Similarly, if we wanted to change the\nview function -- altering its logic somehow -- we could do that without\naffecting the URL to which the function is bound.\n\nFurthermore, if we wanted to expose the current-date functionality at\n*several* URLs, we could easily take care of that by editing the URLconf,\nwithout having to touch the view code. In this example, our\n``current_datetime`` is available at two URLs. It's a contrived example, but\nthis technique can come in handy::\n\n urlpatterns = patterns('',\n url(r'^hello/$', hello),\n url(r'^time/$', current_datetime),\n url(r'^another-time-page/$', current_datetime),\n )\n\nURLconfs and views are loose coupling in action. We'll continue to point out\nexamples of this important philosophy throughout this book.\n\nYour Third View: Dynamic URLs\n=============================\n\nIn our ``current_datetime`` view, the contents of the page -- the current\ndate/time -- were dynamic, but the URL (``/time/``) was static. In most dynamic\nWeb applications, though, a URL contains parameters that influence the output\nof the page. For example, an online bookstore might give each book its own URL,\nlike ``/books/243/`` and ``/books/81196/``.\n\nLet's create a third view that displays the current date and time offset by a\ncertain number of hours. The goal is to craft a site in such a way that the page\n``/time/plus/1/`` displays the date/time one hour into the future, the page\n``/time/plus/2/`` displays the date/time two hours into the future, the page\n``/time/plus/3/`` displays the date/time three hours into the future, and so\non.\n\nA novice might think to code a separate view function for each hour offset,\nwhich might result in a URLconf like this::\n\n urlpatterns = patterns('',\n url(r'^time/$', current_datetime),\n url(r'^time/plus/1/$', one_hour_ahead),\n url(r'^time/plus/2/$', two_hours_ahead),\n url(r'^time/plus/3/$', three_hours_ahead),\n url(r'^time/plus/4/$', four_hours_ahead),\n )\n\nClearly, this line of thought is flawed. Not only would this result in redundant\nview functions, but also the application is fundamentally limited to supporting\nonly the predefined hour ranges -- one, two, three or four hours. If we decided\nto create a page that displayed the time *five* hours into the future, we'd\nhave to create a separate view and URLconf line for that, furthering the\nduplication. We need to do some abstraction here.\n\n.. admonition:: A Word About Pretty URLs\n\n If you're experienced in another Web development platform, such as PHP or\n Java, you may be thinking, \"Hey, let's use a query string parameter!\" --\n something like ``/time/plus?hours=3``, in which the hours would be\n designated by the ``hours`` parameter in the URL's query string (the part\n after the ``?``).\n\n You *can* do that with Django (and we'll tell you how in Chapter 7), but\n one of Django's core philosophies is that URLs should be beautiful. The URL\n ``/time/plus/3/`` is far cleaner, simpler, more readable, easier to recite\n to somebody aloud and . . . just plain prettier than its query string\n counterpart. Pretty URLs are a characteristic of a quality Web application.\n\n Django's URLconf system encourages pretty URLs by making it easier to use\n pretty URLs than *not* to.\n\nHow, then do we design our application to handle arbitrary hour offsets? The\nkey is to use *wildcard URLpatterns*. As we mentioned previously, a URLpattern\nis a regular expression; hence, we can use the regular expression pattern\n``\\d+`` to match one or more digits::\n\n urlpatterns = patterns('',\n # ...\n url(r'^time/plus/\\d+/$', hours_ahead),\n # ...\n )\n\n(We're using the ``# ...`` to imply there might be other URLpatterns that we\ntrimmed from this example.)\n\nThis new URLpattern will match any URL such as ``/time/plus/2/``,\n``/time/plus/25/``, or even ``/time/plus/100000000000/``. Come to think of it,\nlet's limit it so that the maximum allowed offset is 99 hours. That means we\nwant to allow either one- or two-digit numbers -- and in regular expression\nsyntax, that translates into ``\\d{1,2}``::\n\n url(r'^time/plus/\\d{1,2}/$', hours_ahead),\n\n.. note::\n\n When building Web applications, it's always important to consider the most\n outlandish data input possible, and decide whether or not the application\n should support that input. We've curtailed the outlandishness here by\n limiting the offset to 99 hours.\n\nNow that we've designated a wildcard for the URL, we need a way of passing that\nwildcard data to the view function, so that we can use a single view function\nfor any arbitrary hour offset. We do this by placing parentheses around the\ndata in the URLpattern that we want to save. In the case of our example, we\nwant to save whatever number was entered in the URL, so let's put parentheses\naround the ``\\d{1,2}``, like this::\n\n url(r'^time/plus/(\\d{1,2})/$', hours_ahead),\n\nIf you're familiar with regular expressions, you'll be right at home here;\nwe're using parentheses to *capture* data from the matched text.\n\nThe final URLconf, including our previous two views, looks like this::\n\n from django.conf.urls.defaults import *\n from mysite.views import hello, current_datetime, hours_ahead\n\n urlpatterns = patterns('',\n url(r'^hello/$', hello),\n url(r'^time/$', current_datetime),\n url(r'^time/plus/(\\d{1,2})/$', hours_ahead),\n )\n\nWith that taken care of, let's write the ``hours_ahead`` view.\n\n``hours_ahead`` is very similar to the ``current_datetime`` view we wrote\nearlier, with a key difference: it takes an extra argument, the number of hours\nof offset. Here's the view code::\n\n from django.http import Http404, HttpResponse\n import datetime\n\n def hours_ahead(request, offset):\n try:\n offset = int(offset)\n except ValueError:\n raise Http404()\n dt = datetime.datetime.now() + datetime.timedelta(hours=offset)\n html = \"In %s hour(s), it will be %s.\" % (offset, dt)\n return HttpResponse(html)\n\nLet's step through this code one line at a time:\n\n* The view function, ``hours_ahead``, takes *two* parameters: ``request``\n and ``offset``.\n\n * ``request`` is an ``HttpRequest`` object, just as in ``hello`` and\n ``current_datetime``. We'll say it again: each view *always* takes an\n ``HttpRequest`` object as its first parameter.\n\n * ``offset`` is the string captured by the parentheses in the\n URLpattern. For example, if the requested URL were ``/time/plus/3/``,\n then ``offset`` would be the string ``'3'``. If the requested URL were\n ``/time/plus/21/``, then ``offset`` would be the string ``'21'``. Note\n that captured values will always be *strings*, not integers, even if\n the string is composed of only digits, such as ``'21'``.\n\n (Technically, captured values will always be *Unicode objects*, not\n plain Python bytestrings, but don't worry about this distinction at\n the moment.)\n\n We decided to call the variable ``offset``, but you can call it\n whatever you'd like, as long as it's a valid Python identifier. The\n variable name doesn't matter; all that matters is that it's the second\n argument to the function, after ``request``. (It's also possible to\n use keyword, rather than positional, arguments in an URLconf. We cover\n that in Chapter 8.)\n\n* The first thing we do within the function is call ``int()`` on ``offset``.\n This converts the string value to an integer.\n\n Note that Python will raise a ``ValueError`` exception if you call\n ``int()`` on a value that cannot be converted to an integer, such as the\n string ``'foo'``. In this example, if we encounter the ``ValueError``, we\n raise the exception ``django.http.Http404``, which, as you can imagine,\n results in a 404 \"Page not found\" error.\n\n Astute readers will wonder: how could we ever reach the ``ValueError``\n case, anyway, given that the regular expression in our URLpattern --\n ``(\\d{1,2})`` -- captures only digits, and therefore ``offset`` will only\n ever be a string composed of digits? The answer is, we won't, because\n the URLpattern provides a modest but useful level of input validation,\n *but* we still check for the ``ValueError`` in case this view function\n ever gets called in some other way. It's good practice to implement view\n functions such that they don't make any assumptions about their\n parameters. Loose coupling, remember?\n\n* In the next line of the function, we calculate the current date/time and\n add the appropriate number of hours. We've already seen\n ``datetime.datetime.now()`` from the ``current_datetime`` view; the new\n concept here is that you can perform date/time arithmetic by creating a\n ``datetime.timedelta`` object and adding to a ``datetime.datetime``\n object. Our result is stored in the variable ``dt``.\n\n This line also shows why we called ``int()`` on ``offset`` -- the\n ``datetime.timedelta`` function requires the ``hours`` parameter to be an\n integer.\n\n* Next, we construct the HTML output of this view function, just as we did\n in ``current_datetime``. A small difference in this line from the previous\n line is that it uses Python's format-string capability with *two* values,\n not just one. Hence, there are two ``%s`` symbols in the string and a\n tuple of values to insert: ``(offset, dt)``.\n\n* Finally, we return an ``HttpResponse`` of the HTML. By now, this is old\n hat.\n\nWith that view function and URLconf written, start the Django development server\n(if it's not already running), and visit ``http://127.0.0.1:8000/time/plus/3/``\nto verify it works. Then try ``http://127.0.0.1:8000/time/plus/5/``. Then\n``http://127.0.0.1:8000/time/plus/24/``. Finally, visit\n``http://127.0.0.1:8000/time/plus/100/`` to verify that the pattern in your\nURLconf only accepts one- or two-digit numbers; Django should display a \"Page\nnot found\" error in this case, just as we saw in the section \"A Quick Note\nAbout 404 Errors\" earlier. The URL ``http://127.0.0.1:8000/time/plus/`` (with\n*no* hour designation) should also throw a 404.\n\n.. admonition:: Coding Order\n\n In this example, we wrote the URLpattern first and the view second, but in\n the previous examples, we wrote the view first, then the URLpattern. Which\n technique is better?\n\n Well, every developer is different.\n\n If you're a big-picture type of person, it may make the most sense to you\n to write all of the URLpatterns for your application at the same time, at\n the start of your project, and then code up the views. This has the\n advantage of giving you a clear to-do list, and it essentially defines the\n parameter requirements for the view functions you'll need to write.\n\n If you're more of a bottom-up developer, you might prefer to write the\n views first, and then anchor them to URLs afterward. That's OK, too.\n\n In the end, it comes down to which technique fits your brain the best. Both\n approaches are valid.\n\nDjango's Pretty Error Pages\n===========================\n\nTake a moment to admire the fine Web application we've made so far . . . now\nlet's break it! Let's deliberately introduce a Python error into our\n``views.py`` file by commenting out the ``offset = int(offset)`` lines in the\n``hours_ahead`` view::\n\n def hours_ahead(request, offset):\n # try:\n # offset = int(offset)\n # except ValueError:\n # raise Http404()\n dt = datetime.datetime.now() + datetime.timedelta(hours=offset)\n html = \"In %s hour(s), it will be %s.\" % (offset, dt)\n return HttpResponse(html)\n\nLoad up the development server and navigate to ``/time/plus/3/``. You'll see an\nerror page with a significant amount of information, including a ``TypeError``\nmessage displayed at the very top: ``\"unsupported type for timedelta hours\ncomponent: unicode\"``.\n\nWhat happened? Well, the ``datetime.timedelta`` function expects the ``hours``\nparameter to be an integer, and we commented out the bit of code that converted\n``offset`` to an integer. That caused ``datetime.timedelta`` to raise the\n``TypeError``. It's the typical kind of small bug that every programmer runs\ninto at some point.\n\nThe point of this example was to demonstrate Django's error pages. Take some\ntime to explore the error page and get to know the various bits of information\nit gives you.\n\nHere are some things to notice:\n\n* At the top of the page, you get the key information about the exception:\n the type of exception, any parameters to the exception (the ``\"unsupported\n type\"`` message in this case), the file in which the exception was raised,\n and the offending line number.\n\n* Under the key exception information, the page displays the full Python\n traceback for this exception. This is similar to the standard traceback\n you get in Python's command-line interpreter, except it's more\n interactive. For each level (\"frame\") in the stack, Django displays the\n name of the file, the function/method name, the line number, and the\n source code of that line.\n\n Click the line of source code (in dark gray), and you'll see several\n lines from before and after the erroneous line, to give you context.\n\n Click \"Local vars\" under any frame in the stack to view a table of all\n local variables and their values, in that frame, at the exact point in the\n code at which the exception was raised. This debugging information can be\n a great help.\n\n* Note the \"Switch to copy-and-paste view\" text under the \"Traceback\"\n header. Click those words, and the traceback will switch to a alternate\n version that can be easily copied and pasted. Use this when you want to\n share your exception traceback with others to get technical support --\n such as the kind folks in the Django IRC chat room or on the Django users\n mailing list.\n\n Underneath, the \"Share this traceback on a public Web site\" button will\n do this work for you in just one click. Click it to post the traceback to\n http://www.dpaste.com/, where you'll get a distinct URL that you can\n share with other people.\n\n* Next, the \"Request information\" section includes a wealth of information\n about the incoming Web request that spawned the error: GET and POST\n information, cookie values, and meta information, such as CGI headers.\n Appendix G has a complete reference of all the information a request\n object contains.\n\n Below the \"Request information\" section, the \"Settings\" section lists all\n of the settings for this particular Django installation. (We've already\n mentioned ``ROOT_URLCONF``, and we'll show you various Django settings\n throughout the book. All the available settings are covered in detail in\n Appendix D.)\n\nThe Django error page is capable of displaying more information in certain\nspecial cases, such as the case of template syntax errors. We'll get to those\nlater, when we discuss the Django template system. For now, uncomment the\n``offset = int(offset)`` lines to get the view function working properly again.\n\nAre you the type of programmer who likes to debug with the help of carefully\nplaced ``print`` statements? You can use the Django error page to do so -- just\nwithout the ``print`` statements. At any point in your view, temporarily insert\nan ``assert False`` to trigger the error page. Then, you can view the local\nvariables and state of the program. Here's an example, using the\n``hours_ahead`` view::\n\n def hours_ahead(request, offset):\n try:\n offset = int(offset)\n except ValueError:\n raise Http404()\n dt = datetime.datetime.now() + datetime.timedelta(hours=offset)\n assert False\n html = \"In %s hour(s), it will be %s.\" % (offset, dt)\n return HttpResponse(html)\n\nFinally, it's obvious that much of this information is sensitive -- it exposes\nthe innards of your Python code and Django configuration -- and it would be\nfoolish to show this information on the public Internet. A malicious person\ncould use it to attempt to reverse-engineer your Web application and do nasty\nthings. For that reason, the Django error page is only displayed when your\nDjango project is in debug mode. We'll explain how to deactivate debug mode\nin Chapter 12. For now, just know that every Django project is in debug mode\nautomatically when you start it. (Sound familiar? The \"Page not found\" errors,\ndescribed earlier in this chapter, work the same way.)\n\nWhat's next?\n============\n\nSo far, we've been writing our view functions with HTML hard-coded directly\nin the Python code. We've done that to keep things simple while we demonstrated\ncore concepts, but in the real world, this is nearly always a bad idea.\n\nDjango ships with a simple yet powerful template engine that allows you to\nseparate the design of the page from the underlying code. We'll dive into\nDjango's template engine in the :doc:`next chapter `.\n" }, { "path": "Python/DjangoBook/chapter04.rst", "content": "====================\nChapter 4: Templates\n====================\n\nIn the previous chapter, you may have noticed something peculiar in how we\nreturned the text in our example views. Namely, the HTML was hard-coded directly\nin our Python code, like this::\n\n def current_datetime(request):\n now = datetime.datetime.now()\n html = \"It is now %s.\" % now\n return HttpResponse(html)\n\nAlthough this technique was convenient for the purpose of explaining how views\nwork, it's not a good idea to hard-code HTML directly in your views. Here's\nwhy:\n\n* Any change to the design of the page requires a change to\n the Python code. The design of a site tends to change far more frequently\n than the underlying Python code, so it would be convenient if\n the design could change without needing to modify the Python code.\n\n* Writing Python code and designing HTML are two different disciplines, and\n most professional Web development environments split these\n responsibilities between separate people (or even separate departments).\n Designers and HTML/CSS coders shouldn't be required to edit Python code\n to get their job done.\n\n* It's most efficient if programmers can work on Python code and designers\n can work on templates at the same time, rather than one person waiting\n for the other to finish editing a single file that contains both Python\n and HTML.\n\nFor these reasons, it's much cleaner and more maintainable to separate the\ndesign of the page from the Python code itself. We can do this with Django's\n*template system*, which we discuss in this chapter.\n\nTemplate System Basics\n======================\n\nA Django template is a string of text that is intended to separate the\npresentation of a document from its data. A template defines placeholders and\nvarious bits of basic logic (template tags) that regulate how the document\nshould be displayed. Usually, templates are used for producing HTML, but Django\ntemplates are equally capable of generating any text-based format.\n\nLet's start with a simple example template. This Django template describes an\nHTML page that thanks a person for placing an order with a company. Think of it\nas a form letter::\n\n \n Ordering notice\n\n \n\n

Ordering notice

\n\n

Dear {{ person_name }},

\n\n

Thanks for placing an order from {{ company }}. It's scheduled to\n ship on {{ ship_date|date:\"F j, Y\" }}.

\n\n

Here are the items you've ordered:

\n\n
    \n {% for item in item_list %}\n
  • {{ item }}
    • \n {% endfor %}\n
\n\n {% if ordered_warranty %}\n

Your warranty information will be included in the packaging.

\n {% else %}\n

You didn't order a warranty, so you're on your own when\n the products inevitably stop working.

\n {% endif %}\n\n

Sincerely,
{{ company }}

\n\n \n \n\nThis template is basic HTML with some variables and template tags thrown in.\nLet's step through it:\n\n* Any text surrounded by a pair of braces (e.g., ``{{ person_name }}``) is a\n *variable*. This means \"insert the value of the variable with the given\n name.\" (How do we specify the values of the variables? We'll get to that in\n a moment.)\n\n* Any text that's surrounded by curly braces and percent signs (e.g., ``{%\n if ordered_warranty %}``) is a *template tag*. The definition of a tag is\n quite broad: a tag just tells the template system to \"do something.\"\n\n This example template contains a ``for`` tag (``{% for item in item_list\n %}``) and an ``if`` tag (``{% if ordered_warranty %}``).\n\n A ``for`` tag works very much like a ``for`` statement in Python, letting\n you loop over each item in a sequence. An ``if`` tag, as you may expect,\n acts as a logical \"if\" statement. In this particular case, the tag checks\n whether the value of the ``ordered_warranty`` variable evaluates to\n ``True``. If it does, the template system will display everything between\n the ``{% if ordered_warranty %}`` and ``{% else %}``. If not, the\n template system will display everything between ``{% else %}`` and\n ``{% endif %}``. Note that the ``{% else %}`` is optional.\n\n* Finally, the second paragraph of this template contains an example of a\n *filter*, which is the most convenient way to alter the formatting of a\n variable. In this example, ``{{ ship_date|date:\"F j, Y\" }}``, we're passing the\n ``ship_date`` variable to the ``date`` filter, giving the ``date`` filter\n the argument ``\"F j, Y\"``. The ``date`` filter formats dates in a given\n format, as specified by that argument. Filters are attached using a pipe\n character (``|``), as a reference to Unix pipes.\n\nEach Django template has access to several built-in tags and filters, many of\nwhich are discussed in the sections that follow. Appendix E contains the full\nlist of tags and filters, and it's a good idea to familiarize yourself with that\nlist so you know what's possible. It's also possible to create your own filters\nand tags; we'll cover that in Chapter 9.\n\nUsing the Template System\n=========================\n\nLet's dive into Django's template system so you can see how it works -- but\nwe're *not* yet going to integrate it with the views that we created in the\nprevious chapter. Our goal here is to show you how the system works\nindependently of the rest of Django. (Put another way: usually you'll be using\nthe template system within a Django view, but we want to make it clear that the\ntemplate system is just a Python library that you can use *anywhere*, not just\nin Django views.)\n\nHere is the most basic way you can use Django's template system in Python code:\n\n1. Create a ``Template`` object by providing the raw template code as a\n string.\n\n2. Call the ``render()`` method of the ``Template`` object with a given\n set of variables (the *context*). This returns a fully rendered\n template as a string, with all of the variables and template tags\n evaluated according to the context.\n\nIn code, here's what that looks like::\n\n >>> from django import template\n >>> t = template.Template('My name is {{ name }}.')\n >>> c = template.Context({'name': 'Adrian'})\n >>> print t.render(c)\n My name is Adrian.\n >>> c = template.Context({'name': 'Fred'})\n >>> print t.render(c)\n My name is Fred.\n\nThe following sections describe each step in much more detail.\n\nCreating Template Objects\n-------------------------\n\nThe easiest way to create a ``Template`` object is to instantiate it directly.\nThe ``Template`` class lives in the ``django.template`` module, and the\nconstructor takes one argument, the raw template code. Let's dip into the Python\ninteractive interpreter to see how this works in code.\n\nFrom the ``mysite`` project directory created by ``django-admin.py\nstartproject`` (as covered in Chapter 2), type ``python manage.py shell`` to\nstart the interactive interpreter.\n\n.. admonition:: A special Python prompt\n\n If you've used Python before, you may be wondering why we're running\n ``python manage.py shell`` instead of just ``python``. Both commands will\n start the interactive interpreter, but the ``manage.py shell`` command has\n one key difference: before starting the interpreter, it tells Django which\n settings file to use. Many parts of Django, including the template system,\n rely on your settings, and you won't be able to use them unless the\n framework knows which settings to use.\n\n If you're curious, here's how it works behind the scenes. Django looks for\n an environment variable called ``DJANGO_SETTINGS_MODULE``, which should be\n set to the import path of your ``settings.py``. For example,\n ``DJANGO_SETTINGS_MODULE`` might be set to ``'mysite.settings'``, assuming\n ``mysite`` is on your Python path.\n\n When you run ``python manage.py shell``, the command takes care of setting\n ``DJANGO_SETTINGS_MODULE`` for you. We're encouraging you to use\n ``python manage.py shell`` in these examples so as to minimize the amount\n of tweaking and configuring you have to do.\n\nLet's go through some template system basics::\n\n >>> from django.template import Template\n >>> t = Template('My name is {{ name }}.')\n >>> print t\n\nIf you're following along interactively, you'll see something like this::\n\n \n\nThat ``0xb7d5f24c`` will be different every time, and it isn't relevant; it's a\nPython thing (the Python \"identity\" of the ``Template`` object, if you must\nknow).\n\nWhen you create a ``Template`` object, the template system compiles the raw\ntemplate code into an internal, optimized form, ready for rendering. But if your\ntemplate code includes any syntax errors, the call to ``Template()`` will cause\na ``TemplateSyntaxError`` exception::\n\n >>> from django.template import Template\n >>> t = Template('{% notatag %}')\n Traceback (most recent call last):\n File \"\", line 1, in ?\n ...\n django.template.TemplateSyntaxError: Invalid block tag: 'notatag'\n\nThe term \"block tag\" here refers to ``{% notatag %}``. \"Block tag\" and\n\"template tag\" are synonymous.\n\nThe system raises a ``TemplateSyntaxError`` exception for any of the following\ncases:\n\n* Invalid tags\n* Invalid arguments to valid tags\n* Invalid filters\n* Invalid arguments to valid filters\n* Invalid template syntax\n* Unclosed tags (for tags that require closing tags)\n\nRendering a Template\n--------------------\n\nOnce you have a ``Template`` object, you can pass it data by giving it a\n*context*. A context is simply a set of template variable names and their\nassociated values. A template uses this to populate its variables and\nevaluate its tags.\n\nA context is represented in Django by the ``Context`` class, which lives in the\n``django.template`` module. Its constructor takes one optional argument: a\ndictionary mapping variable names to variable values. Call the ``Template``\nobject's ``render()`` method with the context to \"fill\" the template::\n\n >>> from django.template import Context, Template\n >>> t = Template('My name is {{ name }}.')\n >>> c = Context({'name': 'Stephane'})\n >>> t.render(c)\n u'My name is Stephane.'\n\nOne thing we should point out here is that the return value of ``t.render(c)``\nis a Unicode object -- not a normal Python string. You can tell this by the\n``u`` in front of the string. Django uses Unicode objects instead of normal\nstrings throughout the framework. If you understand the repercussions of that,\nbe thankful for the sophisticated things Django does behind the scenes to make\nit work. If you don't understand the repercussions of that, don't worry for\nnow; just know that Django's Unicode support makes it relatively painless for\nyour applications to support a wide variety of character sets beyond the basic\n\"A-Z\" of the English language.\n\n.. admonition:: Dictionaries and Contexts\n\n A Python dictionary is a mapping between known keys and variable\n values. A ``Context`` is similar to a dictionary, but a ``Context``\n provides additional functionality, as covered in Chapter 9.\n\nVariable names must begin with a letter (A-Z or a-z) and may contain more\nletters, digits, underscores, and dots. (Dots are a special case we'll get to in a moment.)\nVariable names are case sensitive.\n\nHere's an example of template compilation and rendering, using a template\nsimilar to the example in the beginning of this chapter::\n\n >>> from django.template import Template, Context\n >>> raw_template = \"\"\"

Dear {{ person_name }},

\n ...\n ...

Thanks for placing an order from {{ company }}. It's scheduled to\n ... ship on {{ ship_date|date:\"F j, Y\" }}.

\n ...\n ... {% if ordered_warranty %}\n ...

Your warranty information will be included in the packaging.

\n ... {% else %}\n ...

You didn't order a warranty, so you're on your own when\n ... the products inevitably stop working.

\n ... {% endif %}\n ...\n ...

Sincerely,
{{ company }}

\"\"\"\n >>> t = Template(raw_template)\n >>> import datetime\n >>> c = Context({'person_name': 'John Smith',\n ... 'company': 'Outdoor Equipment',\n ... 'ship_date': datetime.date(2009, 4, 2),\n ... 'ordered_warranty': False})\n >>> t.render(c)\n u\"

Dear John Smith,

\\n\\n

Thanks for placing an order from Outdoor\n Equipment. It's scheduled to\\nship on April 2, 2009.

\\n\\n\\n

You\n didn't order a warranty, so you're on your own when\\nthe products\n inevitably stop working.

\\n\\n\\n

Sincerely,
Outdoor Equipment\n

\"\n\nLet's step through this code one statement at a time:\n\n* First, we import the classes ``Template`` and ``Context``, which both\n live in the module ``django.template``.\n\n* We save the raw text of our template into the variable\n ``raw_template``. Note that we use triple quote marks to designate the\n string, because it wraps over multiple lines; in contrast, strings\n within single quote marks cannot be wrapped over multiple lines.\n\n* Next, we create a template object, ``t``, by passing ``raw_template`` to\n the ``Template`` class constructor.\n\n* We import the ``datetime`` module from Python's standard library,\n because we'll need it in the following statement.\n\n* Then, we create a ``Context`` object, ``c``. The ``Context``\n constructor takes a Python dictionary, which maps variable names to\n values. Here, for example, we specify that the ``person_name``\n is ``'John Smith'``, ``company`` is ``'Outdoor Equipment'``, and so forth.\n\n* Finally, we call the ``render()`` method on our template object, passing\n it the context. This returns the rendered template -- i.e., it replaces\n template variables with the actual values of the variables, and it\n executes any template tags.\n\n Note that the \"You didn't order a warranty\" paragraph was displayed\n because the ``ordered_warranty`` variable evaluated to ``False``. Also\n note the date, ``April 2, 2009``, which is displayed according to the\n format string ``'F j, Y'``. (We'll explain format strings for the\n ``date`` filter in a little while.)\n\n If you're new to Python, you may wonder why this output includes\n newline characters (``'\\n'``) rather than displaying the line breaks.\n That's happening because of a subtlety in the Python interactive\n interpreter: the call to ``t.render(c)`` returns a string, and by default\n the interactive interpreter displays the *representation* of the string,\n rather than the printed value of the string. If you want to see the\n string with line breaks displayed as true line breaks rather than ``'\\n'``\n characters, use the ``print`` statement: ``print t.render(c)``.\n\nThose are the fundamentals of using the Django template system: just write a\ntemplate string, create a ``Template`` object, create a ``Context``, and call\nthe ``render()`` method.\n\nMultiple Contexts, Same Template\n--------------------------------\n\nOnce you have a ``Template`` object, you can render multiple contexts through\nit. For example::\n\n >>> from django.template import Template, Context\n >>> t = Template('Hello, {{ name }}')\n >>> print t.render(Context({'name': 'John'}))\n Hello, John\n >>> print t.render(Context({'name': 'Julie'}))\n Hello, Julie\n >>> print t.render(Context({'name': 'Pat'}))\n Hello, Pat\n\nWhenever you're using the same template source to render multiple\ncontexts like this, it's more efficient to create the ``Template``\nobject *once*, and then call ``render()`` on it multiple times::\n\n # Bad\n for name in ('John', 'Julie', 'Pat'):\n t = Template('Hello, {{ name }}')\n print t.render(Context({'name': name}))\n\n # Good\n t = Template('Hello, {{ name }}')\n for name in ('John', 'Julie', 'Pat'):\n print t.render(Context({'name': name}))\n\nDjango's template parsing is quite fast. Behind the scenes, most of the parsing\nhappens via a call to a single regular expression. This is in stark\ncontrast to XML-based template engines, which incur the overhead of an XML\nparser and tend to be orders of magnitude slower than Django's template\nrendering engine.\n\nContext Variable Lookup\n-----------------------\n\nIn the examples so far, we've passed simple values in the contexts -- mostly\nstrings, plus a ``datetime.date`` example. However, the template system\nelegantly handles more complex data structures, such as lists, dictionaries, and\ncustom objects.\n\nThe key to traversing complex data structures in Django templates is the dot\ncharacter (``.``). Use a dot to access dictionary keys, attributes, methods,\nor indices of an object.\n\nThis is best illustrated with a few examples. For instance, suppose\nyou're passing a Python dictionary to a template. To access the values\nof that dictionary by dictionary key, use a dot::\n\n >>> from django.template import Template, Context\n >>> person = {'name': 'Sally', 'age': '43'}\n >>> t = Template('{{ person.name }} is {{ person.age }} years old.')\n >>> c = Context({'person': person})\n >>> t.render(c)\n u'Sally is 43 years old.'\n\nSimilarly, dots also allow access of object attributes. For example, a Python\n``datetime.date`` object has ``year``, ``month``, and ``day`` attributes, and\nyou can use a dot to access those attributes in a Django template::\n\n >>> from django.template import Template, Context\n >>> import datetime\n >>> d = datetime.date(1993, 5, 2)\n >>> d.year\n 1993\n >>> d.month\n 5\n >>> d.day\n 2\n >>> t = Template('The month is {{ date.month }} and the year is {{ date.year }}.')\n >>> c = Context({'date': d})\n >>> t.render(c)\n u'The month is 5 and the year is 1993.'\n\nThis example uses a custom class, demonstrating that variable dots also allow\nattribute access on arbitrary objects::\n\n >>> from django.template import Template, Context\n >>> class Person(object):\n ... def __init__(self, first_name, last_name):\n ... self.first_name, self.last_name = first_name, last_name\n >>> t = Template('Hello, {{ person.first_name }} {{ person.last_name }}.')\n >>> c = Context({'person': Person('John', 'Smith')})\n >>> t.render(c)\n u'Hello, John Smith.'\n\nDots can also refer to *methods* on objects. For example, each Python string\nhas the methods ``upper()`` and ``isdigit()``, and you can call those in Django\ntemplates using the same dot syntax::\n\n >>> from django.template import Template, Context\n >>> t = Template('{{ var }} -- {{ var.upper }} -- {{ var.isdigit }}')\n >>> t.render(Context({'var': 'hello'}))\n u'hello -- HELLO -- False'\n >>> t.render(Context({'var': '123'}))\n u'123 -- 123 -- True'\n\nNote that you do *not* include parentheses in the method calls. Also, it's not\npossible to pass arguments to the methods; you can only call methods that have\nno required arguments. (We explain this philosophy later in this chapter.)\n\nFinally, dots are also used to access list indices, for example::\n\n >>> from django.template import Template, Context\n >>> t = Template('Item 2 is {{ items.2 }}.')\n >>> c = Context({'items': ['apples', 'bananas', 'carrots']})\n >>> t.render(c)\n u'Item 2 is carrots.'\n\nNegative list indices are not allowed. For example, the template variable\n``{{ items.-1 }}`` would cause a ``TemplateSyntaxError``.\n\n.. admonition:: Python Lists\n\n A reminder: Python lists have 0-based indices. The first item is at index 0,\n the second is at index 1, and so on.\n\nDot lookups can be summarized like this: when the template system\nencounters a dot in a variable name, it tries the following lookups, in this\norder:\n\n* Dictionary lookup (e.g., ``foo[\"bar\"]``)\n* Attribute lookup (e.g., ``foo.bar``)\n* Method call (e.g., ``foo.bar()``)\n* List-index lookup (e.g., ``foo[2]``)\n\nThe system uses the first lookup type that works. It's short-circuit logic.\n\nDot lookups can be nested multiple levels deep. For instance, the following\nexample uses ``{{ person.name.upper }}``, which translates into a dictionary\nlookup (``person['name']``) and then a method call (``upper()``)::\n\n >>> from django.template import Template, Context\n >>> person = {'name': 'Sally', 'age': '43'}\n >>> t = Template('{{ person.name.upper }} is {{ person.age }} years old.')\n >>> c = Context({'person': person})\n >>> t.render(c)\n u'SALLY is 43 years old.'\n\nMethod Call Behavior\n~~~~~~~~~~~~~~~~~~~~\n\nMethod calls are slightly more complex than the other lookup types. Here are\nsome things to keep in mind:\n\n* If, during the method lookup, a method raises an exception, the exception\n will be propagated, unless the exception has an attribute\n ``silent_variable_failure`` whose value is ``True``. If the exception\n *does* have a ``silent_variable_failure`` attribute, the variable will\n render as an empty string, for example::\n\n >>> t = Template(\"My name is {{ person.first_name }}.\")\n >>> class PersonClass3:\n ... def first_name(self):\n ... raise AssertionError, \"foo\"\n >>> p = PersonClass3()\n >>> t.render(Context({\"person\": p}))\n Traceback (most recent call last):\n ...\n AssertionError: foo\n\n >>> class SilentAssertionError(AssertionError):\n ... silent_variable_failure = True\n >>> class PersonClass4:\n ... def first_name(self):\n ... raise SilentAssertionError\n >>> p = PersonClass4()\n >>> t.render(Context({\"person\": p}))\n u'My name is .'\n\n* A method call will only work if the method has no required arguments.\n Otherwise, the system will move to the next lookup type (list-index\n lookup).\n\n* Obviously, some methods have side effects, and it would be foolish at\n best, and possibly even a security hole, to allow the template system to\n access them.\n\n Say, for instance, you have a ``BankAccount`` object that has a\n ``delete()`` method. If a template includes something like\n ``{{ account.delete }}``, where ``account`` is a ``BankAccount`` object,\n the object would be deleted when the template is rendered!\n\n To prevent this, set the function attribute ``alters_data`` on the\n method::\n\n def delete(self):\n # Delete the account\n delete.alters_data = True\n\n The template system won't execute any method marked in this way.\n Continuing the above example, if a template includes\n ``{{ account.delete }}`` and the ``delete()`` method has the\n ``alters_data=True``, then the ``delete()`` method will not be executed\n when the template is rendered. Instead, it will fail silently.\n\nHow Invalid Variables Are Handled\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nBy default, if a variable doesn't exist, the template system renders it as an\nempty string, failing silently. For example::\n\n >>> from django.template import Template, Context\n >>> t = Template('Your name is {{ name }}.')\n >>> t.render(Context())\n u'Your name is .'\n >>> t.render(Context({'var': 'hello'}))\n u'Your name is .'\n >>> t.render(Context({'NAME': 'hello'}))\n u'Your name is .'\n >>> t.render(Context({'Name': 'hello'}))\n u'Your name is .'\n\nThe system fails silently rather than raising an exception because it's\nintended to be resilient to human error. In this case, all of the\nlookups failed because variable names have the wrong case or name. In the real\nworld, it's unacceptable for a Web site to become inaccessible due to a\nsmall template syntax error.\n\nPlaying with Context Objects\n----------------------------\n\nMost of the time, you'll instantiate ``Context`` objects by passing in a\nfully populated dictionary to ``Context()``. But you can add and delete items\nfrom a ``Context`` object once it's been instantiated, too, using standard\nPython dictionary syntax::\n\n >>> from django.template import Context\n >>> c = Context({\"foo\": \"bar\"})\n >>> c['foo']\n 'bar'\n >>> del c['foo']\n >>> c['foo']\n Traceback (most recent call last):\n ...\n KeyError: 'foo'\n >>> c['newvariable'] = 'hello'\n >>> c['newvariable']\n 'hello'\n\nBasic Template Tags and Filters\n===============================\n\nAs we've mentioned already, the template system ships with built-in tags and\nfilters. The sections that follow provide a rundown of the most common tags and\nfilters.\n\nTags\n----\n\nif/else\n~~~~~~~\n\nThe ``{% if %}`` tag evaluates a variable, and if that variable is \"True\"\n(i.e., it exists, is not empty, and is not a false Boolean value), the system\nwill display everything between ``{% if %}`` and ``{% endif %}``, for example::\n\n {% if today_is_weekend %}\n

Welcome to the weekend!

\n {% endif %}\n\nAn ``{% else %}`` tag is optional::\n\n {% if today_is_weekend %}\n

Welcome to the weekend!

\n {% else %}\n

Get back to work.

\n {% endif %}\n\n.. admonition:: Python \"Truthiness\"\n\n In Python and in the Django template system, these objects evaluate to\n ``False`` in a Boolean context:\n\n * An empty list (``[]``)\n * An empty tuple (``()``)\n * An empty dictionary (``{}``)\n * An empty string (``''``)\n * Zero (``0``)\n * The special object ``None``\n * The object ``False`` (obviously)\n * Custom objects that define their own Boolean context behavior\n (this is advanced Python usage)\n\n Everything else evaluates to ``True``.\n\nThe ``{% if %}`` tag accepts ``and``, ``or``, or ``not`` for testing multiple\nvariables, or to negate a given variable. For example::\n\n {% if athlete_list and coach_list %}\n Both athletes and coaches are available.\n {% endif %}\n\n {% if not athlete_list %}\n There are no athletes.\n {% endif %}\n\n {% if athlete_list or coach_list %}\n There are some athletes or some coaches.\n {% endif %}\n\n {% if not athlete_list or coach_list %}\n There are no athletes or there are some coaches.\n {% endif %}\n\n {% if athlete_list and not coach_list %}\n There are some athletes and absolutely no coaches.\n {% endif %}\n\n``{% if %}`` tags don't allow ``and`` and ``or`` clauses within the same tag,\nbecause the order of logic would be ambiguous. For example, this is invalid::\n\n {% if athlete_list and coach_list or cheerleader_list %}\n\nThe use of parentheses for controlling order of operations is not supported. If\nyou find yourself needing parentheses, consider performing logic outside the\ntemplate and passing the result of that as a dedicated template variable. Or,\njust use nested ``{% if %}`` tags, like this::\n\n {% if athlete_list %}\n {% if coach_list or cheerleader_list %}\n We have athletes, and either coaches or cheerleaders!\n {% endif %}\n {% endif %}\n\nMultiple uses of the same logical operator are fine, but you can't\ncombine different operators. For example, this is valid::\n\n {% if athlete_list or coach_list or parent_list or teacher_list %}\n\nThere is no ``{% elif %}`` tag. Use nested ``{% if %}`` tags to accomplish\nthe same thing::\n\n {% if athlete_list %}\n

Here are the athletes: {{ athlete_list }}.

\n {% else %}\n

No athletes are available.

\n {% if coach_list %}\n

Here are the coaches: {{ coach_list }}.

\n {% endif %}\n {% endif %}\n\nMake sure to close each ``{% if %}`` with an ``{% endif %}``. Otherwise, Django\nwill throw a ``TemplateSyntaxError``.\n\nfor\n~~~\n\nThe ``{% for %}`` tag allows you to loop over each item in a sequence. As in\nPython's ``for`` statement, the syntax is ``for X in Y``, where ``Y`` is the\nsequence to loop over and ``X`` is the name of the variable to use for a\nparticular cycle of the loop. Each time through the loop, the template system\nwill render everything between ``{% for %}`` and ``{% endfor %}``.\n\nFor example, you could use the following to display a list of athletes given a\nvariable ``athlete_list``::\n\n
    \n {% for athlete in athlete_list %}\n
  • {{ athlete.name }}
    • \n {% endfor %}\n
\n\nAdd ``reversed`` to the tag to loop over the list in reverse::\n\n {% for athlete in athlete_list reversed %}\n ...\n {% endfor %}\n\nIt's possible to nest ``{% for %}`` tags::\n\n {% for athlete in athlete_list %}\n

{{ athlete.name }}

\n
    \n {% for sport in athlete.sports_played %}\n
  • {{ sport }}
    • \n {% endfor %}\n
\n {% endfor %}\n\nA common pattern is to check the size of the list before looping over it, and\noutputting some special text if the list is empty::\n\n {% if athlete_list %}\n {% for athlete in athlete_list %}\n

{{ athlete.name }}

\n {% endfor %}\n {% else %}\n

There are no athletes. Only computer programmers.

\n {% endif %}\n\nBecause this pattern is so common, the ``for`` tag supports an optional\n``{% empty %}`` clause that lets you define what to output if the list is\nempty. This example is equivalent to the previous one::\n\n {% for athlete in athlete_list %}\n

{{ athlete.name }}

\n {% empty %}\n

There are no athletes. Only computer programmers.

\n {% endfor %}\n\nThere is no support for \"breaking out\" of a loop before the loop is finished.\nIf you want to accomplish this, change the variable you're looping over so that\nit includes only the values you want to loop over. Similarly, there is no\nsupport for a \"continue\" statement that would instruct the loop processor to\nreturn immediately to the front of the loop. (See the section \"Philosophies and\nLimitations\" later in this chapter for the reasoning behind this design\ndecision.)\n\nWithin each ``{% for %}`` loop, you get access to a template variable called\n``forloop``. This variable has a few attributes that give you information about\nthe progress of the loop:\n\n* ``forloop.counter`` is always set to an integer representing the number\n of times the loop has been entered. This is one-indexed, so the first\n time through the loop, ``forloop.counter`` will be set to ``1``.\n Here's an example::\n\n {% for item in todo_list %}\n

{{ forloop.counter }}: {{ item }}

\n {% endfor %}\n\n* ``forloop.counter0`` is like ``forloop.counter``, except it's\n zero-indexed. Its value will be set to ``0`` the first time through the\n loop.\n\n* ``forloop.revcounter`` is always set to an integer representing the\n number of remaining items in the loop. The first time through the loop,\n ``forloop.revcounter`` will be set to the total number of items in the\n sequence you're traversing. The last time through the loop,\n ``forloop.revcounter`` will be set to ``1``.\n\n* ``forloop.revcounter0`` is like ``forloop.revcounter``, except it's\n zero-indexed. The first time through the loop, ``forloop.revcounter0``\n will be set to the number of elements in the sequence minus 1. The last\n time through the loop, it will be set to ``0``.\n\n* ``forloop.first`` is a Boolean value set to ``True`` if this is the first\n time through the loop. This is convenient for special-casing::\n\n {% for object in objects %}\n {% if forloop.first %}
  • {% else %}
  • {% endif %}\n {{ object }}\n
    • \n {% endfor %}\n\n* ``forloop.last`` is a Boolean value set to ``True`` if this is the last\n time through the loop. A common use for this is to put pipe\n characters between a list of links::\n\n {% for link in links %}{{ link }}{% if not forloop.last %} | {% endif %}{% endfor %}\n\n The above template code might output something like this::\n\n Link1 | Link2 | Link3 | Link4\n\n Another common use for this is to put a comma between words in a list::\n\n Favorite places:\n {% for p in places %}{{ p }}{% if not forloop.last %}, {% endif %}{% endfor %}\n\n* ``forloop.parentloop`` is a reference to the ``forloop`` object for the\n *parent* loop, in case of nested loops. Here's an example::\n\n {% for country in countries %}\n \n {% for city in country.city_list %}\n \n \n \n \n \n {% endfor %}\n
    Country #{{ forloop.parentloop.counter }}City #{{ forloop.counter }}{{ city }}
    \n {% endfor %}\n\nThe magic ``forloop`` variable is only available within loops. After the\ntemplate parser has reached ``{% endfor %}``, ``forloop`` disappears.\n\n.. admonition:: Context and the forloop Variable\n\n Inside the ``{% for %}`` block, the existing variables are moved\n out of the way to avoid overwriting the magic ``forloop``\n variable. Django exposes this moved context in\n ``forloop.parentloop``. You generally don't need to worry about\n this, but if you supply a template variable named ``forloop``\n (though we advise against it), it will be named\n ``forloop.parentloop`` while inside the ``{% for %}`` block.\n\nifequal/ifnotequal\n~~~~~~~~~~~~~~~~~~\n\nThe Django template system deliberately is not a full-fledged programming\nlanguage and thus does not allow you to execute arbitrary Python statements.\n(More on this idea in the section \"Philosophies and Limitations.\") However,\nit's quite a common template requirement to compare two values and display\nsomething if they're equal -- and Django provides an ``{% ifequal %}`` tag for\nthat purpose.\n\nThe ``{% ifequal %}`` tag compares two values and displays everything between\n``{% ifequal %}`` and ``{% endifequal %}`` if the values are equal.\n\nThis example compares the template variables ``user`` and ``currentuser``::\n\n {% ifequal user currentuser %}\n

    Welcome!

    \n {% endifequal %}\n\nThe arguments can be hard-coded strings, with either single or double quotes,\nso the following is valid::\n\n {% ifequal section 'sitenews' %}\n

    Site News

    \n {% endifequal %}\n\n {% ifequal section \"community\" %}\n

    Community

    \n {% endifequal %}\n\nJust like ``{% if %}``, the ``{% ifequal %}`` tag supports an optional\n``{% else %}``::\n\n {% ifequal section 'sitenews' %}\n

    Site News

    \n {% else %}\n

    No News Here

    \n {% endifequal %}\n\nOnly template variables, strings, integers, and decimal numbers are allowed as\narguments to ``{% ifequal %}``. These are valid examples::\n\n {% ifequal variable 1 %}\n {% ifequal variable 1.23 %}\n {% ifequal variable 'foo' %}\n {% ifequal variable \"foo\" %}\n\nAny other types of variables, such as Python dictionaries, lists, or Booleans,\ncan't be hard-coded in ``{% ifequal %}``. These are invalid examples::\n\n {% ifequal variable True %}\n {% ifequal variable [1, 2, 3] %}\n {% ifequal variable {'key': 'value'} %}\n\nIf you need to test whether something is true or false, use the ``{% if %}``\ntags instead of ``{% ifequal %}``.\n\nComments\n~~~~~~~~\n\nJust as in HTML or Python, the Django template language allows for comments. To\ndesignate a comment, use ``{# #}``::\n\n {# This is a comment #}\n\nThe comment will not be output when the template is rendered.\n\nComments using this syntax cannot span multiple lines. This limitation improves\ntemplate parsing performance. In the following template, the rendered output\nwill look exactly the same as the template (i.e., the comment tag will\nnot be parsed as a comment)::\n\n This is a {# this is not\n a comment #}\n test.\n\nIf you want to use multi-line comments, use the ``{% comment %}`` template tag,\nlike this::\n\n {% comment %}\n This is a\n multi-line comment.\n {% endcomment %}\n\nFilters\n-------\n\nAs explained earlier in this chapter, template filters are simple ways of\naltering the value of variables before they're displayed. Filters use a pipe\ncharacter, like this::\n\n {{ name|lower }}\n\nThis displays the value of the ``{{ name }}`` variable after being filtered\nthrough the ``lower`` filter, which converts text to lowercase.\n\nFilters can be *chained* -- that is, they can be used in tandem such that the\noutput of one filter is applied to the next. Here's an example that takes the\nfirst element in a list and converts it to uppercase::\n\n {{ my_list|first|upper }}\n\nSome filters take arguments. A filter argument comes after a colon and is\nalways in double quotes. For example::\n\n {{ bio|truncatewords:\"30\" }}\n\nThis displays the first 30 words of the ``bio`` variable.\n\nThe following are a few of the most important filters. Appendix E covers the rest.\n\n* ``addslashes``: Adds a backslash before any backslash, single quote, or\n double quote. This is useful if the produced text is included in\n a JavaScript string.\n\n* ``date``: Formats a ``date`` or ``datetime`` object according to a\n format string given in the parameter, for example::\n\n {{ pub_date|date:\"F j, Y\" }}\n\n Format strings are defined in Appendix E.\n\n* ``length``: Returns the length of the value. For a list, this returns the\n number of elements. For a string, this returns the number of characters.\n (Python experts, take note that this works on any Python object that\n knows how to determine its length -- i.e., any object that has a\n ``__len__()`` method.)\n\nPhilosophies and Limitations\n============================\n\nNow that you've gotten a feel for the Django template language, we should point\nout some of its intentional limitations, along with some philosophies behind why\nit works the way it works.\n\nMore than any other component of Web applications, template syntax is highly\nsubjective, and programmers' opinions vary wildly. The fact that Python alone\nhas dozens, if not hundreds, of open source template-language implementations\nsupports this point. Each was likely created because its developer deemed all\nexisting template languages inadequate. (In fact, it is said to be a rite of\npassage for a Python developer to write his or her own template language! If\nyou haven't done this yet, consider it. It's a fun exercise.)\n\nWith that in mind, you might be interested to know that Django doesn't require\nthat you use its template language. Because Django is intended to be a\nfull-stack Web framework that provides all the pieces necessary for Web\ndevelopers to be productive, many times it's *more convenient* to use Django's\ntemplate system than other Python template libraries, but it's not a strict\nrequirement in any sense. As you'll see in the upcoming section \"Using Templates\nin Views\", it's very easy to use another template language with Django.\n\nStill, it's clear we have a strong preference for the way Django's template\nlanguage works. The template system has roots in how Web development is done at\nWorld Online and the combined experience of Django's creators. Here are a few of\nthose philosophies:\n\n* *Business logic should be separated from presentation logic*. Django's\n developers see a template system as a tool that controls presentation and\n presentation-related logic -- and that's it. The template system shouldn't\n support functionality that goes beyond this basic goal.\n\n For that reason, it's impossible to call Python code directly within\n Django templates. All \"programming\" is fundamentally limited to the scope\n of what template tags can do. It *is* possible to write custom template\n tags that do arbitrary things, but the out-of-the-box Django template\n tags intentionally do not allow for arbitrary Python code execution.\n\n* *Syntax should be decoupled from HTML/XML*. Although Django's template\n system is used primarily to produce HTML, it's intended to be just as\n usable for non-HTML formats, such as plain text. Some other template\n languages are XML based, placing all template logic within XML tags or\n attributes, but Django deliberately avoids this limitation. Requiring\n valid XML to write templates introduces a world of human mistakes and\n hard-to-understand error messages, and using an XML engine to parse\n templates incurs an unacceptable level of overhead in template processing.\n\n* *Designers are assumed to be comfortable with HTML code*. The template\n system isn't designed so that templates necessarily are displayed nicely\n in WYSIWYG editors such as Dreamweaver. That is too severe a limitation\n and wouldn't allow the syntax to be as friendly as it is. Django expects\n template authors to be comfortable editing HTML directly.\n\n* *Designers are assumed not to be Python programmers*. The template system\n authors recognize that Web page templates are most often written by\n *designers*, not *programmers*, and therefore should not assume Python\n knowledge.\n\n However, the system also intends to accommodate small teams in which the\n templates *are* created by Python programmers. It offers a way to extend\n the system's syntax by writing raw Python code. (More on this in Chapter\n 9.)\n\n* *The goal is not to invent a programming language*. The goal is to offer\n just enough programming-esque functionality, such as branching and\n looping, that is essential for making presentation-related decisions.\n\nUsing Templates in Views\n========================\n\nYou've learned the basics of using the template system; now let's use this\nknowledge to create a view. Recall the ``current_datetime`` view in\n``mysite.views``, which we started in the previous chapter. Here's what it looks\nlike::\n\n from django.http import HttpResponse\n import datetime\n\n def current_datetime(request):\n now = datetime.datetime.now()\n html = \"It is now %s.\" % now\n return HttpResponse(html)\n\nLet's change this view to use Django's template system. At first, you might\nthink to do something like this::\n\n from django.template import Template, Context\n from django.http import HttpResponse\n import datetime\n\n def current_datetime(request):\n now = datetime.datetime.now()\n t = Template(\"It is now {{ current_date }}.\")\n html = t.render(Context({'current_date': now}))\n return HttpResponse(html)\n\nSure, that uses the template system, but it doesn't solve the problems we\npointed out in the introduction of this chapter. Namely, the template is still\nembedded in the Python code, so true separation of data and presentation isn't\nachieved. Let's fix that by putting the template in a *separate file*, which\nthis view will load.\n\nYou might first consider saving your template somewhere on your\nfilesystem and using Python's built-in file-opening functionality to read\nthe contents of the template. Here's what that might look like, assuming the\ntemplate was saved as the file ``/home/djangouser/templates/mytemplate.html``::\n\n from django.template import Template, Context\n from django.http import HttpResponse\n import datetime\n\n def current_datetime(request):\n now = datetime.datetime.now()\n # Simple way of using templates from the filesystem.\n # This is BAD because it doesn't account for missing files!\n fp = open('/home/djangouser/templates/mytemplate.html')\n t = Template(fp.read())\n fp.close()\n html = t.render(Context({'current_date': now}))\n return HttpResponse(html)\n\nThis approach, however, is inelegant for these reasons:\n\n* It doesn't handle the case of a missing file. If the file\n ``mytemplate.html`` doesn't exist or isn't readable, the ``open()`` call\n will raise an ``IOError`` exception.\n\n* It hard-codes your template location. If you were to use this\n technique for every view function, you'd be duplicating the template\n locations. Not to mention it involves a lot of typing!\n\n* It includes a lot of boring boilerplate code. You've got better things to\n do than to write calls to ``open()``, ``fp.read()``, and ``fp.close()``\n each time you load a template.\n\nTo solve these issues, we'll use *template loading* and *template directories*.\n\nTemplate Loading\n================\n\nDjango provides a convenient and powerful API for loading templates from the\nfilesystem, with the goal of removing redundancy both in your template-loading\ncalls and in your templates themselves.\n\nIn order to use this template-loading API, first you'll need to tell the\nframework where you store your templates. The place to do this is in your\nsettings file -- the ``settings.py`` file that we mentioned last chapter, when\nwe introduced the ``ROOT_URLCONF`` setting.\n\nIf you're following along, open your ``settings.py`` and find the\n``TEMPLATE_DIRS`` setting. By default, it's an empty tuple, likely containing\nsome auto-generated comments::\n\n TEMPLATE_DIRS = (\n # Put strings here, like \"/home/html/django_templates\" or \"C:/www/django/templates\".\n # Always use forward slashes, even on Windows.\n # Don't forget to use absolute paths, not relative paths.\n )\n\nThis setting tells Django's template-loading mechanism where to look for\ntemplates. Pick a directory where you'd like to store your templates and add it\nto ``TEMPLATE_DIRS``, like so::\n\n TEMPLATE_DIRS = (\n '/home/django/mysite/templates',\n )\n\nThere are a few things to note:\n\n* You can specify any directory you want, as long as the directory and\n templates within that directory are readable by the user account under\n which your Web server runs. If you can't think of an appropriate\n place to put your templates, we recommend creating a ``templates``\n directory within your project (i.e., within the ``mysite`` directory you\n created in Chapter 2).\n\n* If your ``TEMPLATE_DIRS`` contains only one directory, don't forget the\n comma at the end of the directory string!\n\n Bad::\n\n # Missing comma!\n TEMPLATE_DIRS = (\n '/home/django/mysite/templates'\n )\n\n Good::\n\n # Comma correctly in place.\n TEMPLATE_DIRS = (\n '/home/django/mysite/templates',\n )\n\n The reason for this is that Python requires commas within single-element\n tuples to disambiguate the tuple from a parenthetical expression. This is\n a common newbie gotcha.\n\n* If you're on Windows, include your drive letter and use Unix-style\n forward slashes rather than backslashes, as follows::\n\n TEMPLATE_DIRS = (\n 'C:/www/django/templates',\n )\n\n* It's simplest to use absolute paths (i.e., directory paths that start at\n the root of the filesystem). If you want to be a bit more flexible and\n decoupled, though, you can take advantage of the fact that Django\n settings files are just Python code by constructing the contents of\n ``TEMPLATE_DIRS`` dynamically. For example::\n\n import os.path\n\n TEMPLATE_DIRS = (\n os.path.join(os.path.dirname(__file__), 'templates').replace('\\\\','/'),\n )\n\n This example uses the \"magic\" Python variable ``__file__``, which is\n automatically set to the file name of the Python module in which the code\n lives. It gets the name of the directory that contains ``settings.py``\n (``os.path.dirname``), then joins that with ``templates`` in a\n cross-platform way (``os.path.join``), then ensures that everything uses\n forward slashes instead of backslashes (in case of Windows).\n\n While we're on the topic of dynamic Python code in settings files, we\n should point out that it's very important to avoid Python errors in your\n settings file. If you introduce a syntax error, or a runtime error, your\n Django-powered site will likely crash.\n\nWith ``TEMPLATE_DIRS`` set, the next step is to change the view code to\nuse Django's template-loading functionality rather than hard-coding the\ntemplate paths. Returning to our ``current_datetime`` view, let's change it\nlike so::\n\n from django.template.loader import get_template\n from django.template import Context\n from django.http import HttpResponse\n import datetime\n\n def current_datetime(request):\n now = datetime.datetime.now()\n t = get_template('current_datetime.html')\n html = t.render(Context({'current_date': now}))\n return HttpResponse(html)\n\nIn this example, we're using the function\n``django.template.loader.get_template()`` rather than loading the template from\nthe filesystem manually. The ``get_template()`` function takes a template name\nas its argument, figures out where the template lives on the filesystem, opens\nthat file, and returns a compiled ``Template`` object.\n\nOur template in this example is ``current_datetime.html``, but there's nothing\nspecial about that ``.html`` extension. You can give your templates whatever\nextension makes sense for your application, or you can leave off extensions\nentirely.\n\nTo determine the location of the template on your filesystem,\n``get_template()`` combines your template directories from ``TEMPLATE_DIRS``\nwith the template name that you pass to ``get_template()``. For example, if\nyour ``TEMPLATE_DIRS`` is set to ``'/home/django/mysite/templates'``, the above\n``get_template()`` call would look for the template\n``/home/django/mysite/templates/current_datetime.html``.\n\nIf ``get_template()`` cannot find the template with the given name, it raises\na ``TemplateDoesNotExist`` exception. To see what that looks like, fire up the\nDjango development server again by running ``python manage.py runserver``\nwithin your Django project's directory. Then, point your browser at the page\nthat activates the ``current_datetime`` view (e.g.,\n``http://127.0.0.1:8000/time/``). Assuming your ``DEBUG`` setting is set to\n``True`` and you haven't yet created a ``current_datetime.html`` template, you\nshould see a Django error page highlighting the ``TemplateDoesNotExist`` error.\n\n.. figure:: graphics/chapter04/missing_template.png\n :alt: Screenshot of a \"TemplateDoesNotExist\" error.\n\n Figure 4-1: The error page shown when a template cannot be found.\n\nThis error page is similar to the one we explained in Chapter 3, with one\nadditional piece of debugging information: a \"Template-loader postmortem\"\nsection. This section tells you which templates Django tried to load, along with\nthe reason each attempt failed (e.g., \"File does not exist\"). This information\nis invaluable when you're trying to debug template-loading errors.\n\nMoving along, create the ``current_datetime.html`` file within your template\ndirectory using the following template code::\n\n It is now {{ current_date }}.\n\nRefresh the page in your Web browser, and you should see the fully rendered\npage.\n\nrender()\n--------\n\nWe've shown you how to load a template, fill a ``Context`` and return an\n``HttpResponse`` object with the result of the rendered template. We've\noptimized it to use ``get_template()`` instead of hard-coding templates and\ntemplate paths. But it still requires a fair amount of typing to do those\nthings. Because this is such a common idiom, Django provides a shortcut that\nlets you load a template, render it and return an ``HttpResponse`` -- all in\none line of code.\n\nThis shortcut is a function called ``render()``, which lives in the\nmodule ``django.shortcuts``. Most of the time, you'll be using\n``render()`` rather than loading templates and creating ``Context``\nand ``HttpResponse`` objects manually -- unless your employer judges your work\nby total lines of code written, that is.\n\nHere's the ongoing ``current_datetime`` example rewritten to use\n``render()``::\n\n from django.shortcuts import render\n import datetime\n\n def current_datetime(request):\n now = datetime.datetime.now()\n return render(request, 'current_datetime.html', {'current_date': now})\n\nWhat a difference! Let's step through the code changes:\n\n* We no longer have to import ``get_template``, ``Template``, ``Context``,\n or ``HttpResponse``. Instead, we import\n ``django.shortcuts.render``. The ``import datetime`` remains.\n\n* Within the ``current_datetime`` function, we still calculate ``now``, but\n the template loading, context creation, template rendering, and\n ``HttpResponse`` creation are all taken care of by the\n ``render()`` call. Because ``render()`` returns\n an ``HttpResponse`` object, we can simply ``return`` that value in the\n view.\n\nThe first argument to ``render()`` is the request, the second is the name of\nthe template to use. The third argument, if given, should be a dictionary to\nuse in creating a ``Context`` for that template. If you don't provide a third\nargument, ``render()`` will use an empty dictionary.\n\nSubdirectories in get_template()\n--------------------------------\n\nIt can get unwieldy to store all of your templates in a single directory. You\nmight like to store templates in subdirectories of your template directory, and\nthat's fine. In fact, we recommend doing so; some more advanced Django\nfeatures (such as the generic views system, which we cover in\nChapter 11) expect this template layout as a default convention.\n\nStoring templates in subdirectories of your template directory is easy.\nIn your calls to ``get_template()``, just include\nthe subdirectory name and a slash before the template name, like so::\n\n t = get_template('dateapp/current_datetime.html')\n\nBecause ``render()`` is a small wrapper around ``get_template()``,\nyou can do the same thing with the second argument to ``render()``,\nlike this::\n\n return render(request, 'dateapp/current_datetime.html', {'current_date': now})\n\nThere's no limit to the depth of your subdirectory tree. Feel free to use\nas many subdirectories as you like.\n\n.. note::\n\n Windows users, be sure to use forward slashes rather than backslashes.\n ``get_template()`` assumes a Unix-style file name designation.\n\nThe ``include`` Template Tag\n----------------------------\n\nNow that we've covered the template-loading mechanism, we can introduce a\nbuilt-in template tag that takes advantage of it: ``{% include %}``. This tag\nallows you to include the contents of another template. The argument to the tag\nshould be the name of the template to include, and the template name can be\neither a variable or a hard-coded (quoted) string, in either single or double\nquotes. Anytime you have the same code in multiple templates,\nconsider using an ``{% include %}`` to remove the duplication.\n\nThese two examples include the contents of the template ``nav.html``. The\nexamples are equivalent and illustrate that either single or double quotes\nare allowed::\n\n {% include 'nav.html' %}\n {% include \"nav.html\" %}\n\nThis example includes the contents of the template ``includes/nav.html``::\n\n {% include 'includes/nav.html' %}\n\nThis example includes the contents of the template whose name is contained in\nthe variable ``template_name``::\n\n {% include template_name %}\n\nAs in ``get_template()``, the file name of the template is determined by adding\nthe template directory from ``TEMPLATE_DIRS`` to the requested template name.\n\nIncluded templates are evaluated with the context of the template\nthat's including them. For example, consider these two templates::\n\n # mypage.html\n\n \n \n {% include \"includes/nav.html\" %}\n

    {{ title }}

    \n \n \n\n # includes/nav.html\n\n
    \n You are in: {{ current_section }}\n
    \n\nIf you render ``mypage.html`` with a context containing ``current_section``,\nthen the variable will be available in the \"included\" template, as you would\nexpect.\n\nIf, in an ``{% include %}`` tag, a template with the given name isn't found,\nDjango will do one of two things:\n\n* If ``DEBUG`` is set to ``True``, you'll see the\n ``TemplateDoesNotExist`` exception on a Django error page.\n\n* If ``DEBUG`` is set to ``False``, the tag will fail\n silently, displaying nothing in the place of the tag.\n\nTemplate Inheritance\n====================\n\nOur template examples so far have been tiny HTML snippets, but in the real\nworld, you'll be using Django's template system to create entire HTML pages.\nThis leads to a common Web development problem: across a Web site, how does\none reduce the duplication and redundancy of common page areas, such as\nsitewide navigation?\n\nA classic way of solving this problem is to use *server-side includes*,\ndirectives you can embed within your HTML pages to \"include\" one Web page\ninside another. Indeed, Django supports that approach, with the\n``{% include %}`` template tag just described. But the preferred way of\nsolving this problem with Django is to use a more elegant strategy called\n*template inheritance*.\n\nIn essence, template inheritance lets you build a base \"skeleton\" template that\ncontains all the common parts of your site and defines \"blocks\" that child\ntemplates can override.\n\nLet's see an example of this by creating a more complete template for our\n``current_datetime`` view, by editing the ``current_datetime.html`` file::\n\n \n \n \n The current time\n \n \n

    My helpful timestamp site

    \n

    It is now {{ current_date }}.

    \n\n
    \n

    Thanks for visiting my site.

    \n \n \n\nThat looks just fine, but what happens when we want to create a template for\nanother view -- say, the ``hours_ahead`` view from Chapter 3? If we want again\nto make a nice, valid, full HTML template, we'd create something like::\n\n \n \n \n Future time\n \n \n

    My helpful timestamp site

    \n

    In {{ hour_offset }} hour(s), it will be {{ next_time }}.

    \n\n
    \n

    Thanks for visiting my site.

    \n \n \n\nClearly, we've just duplicated a lot of HTML. Imagine if we had a more\ntypical site, including a navigation bar, a few style sheets, perhaps some\nJavaScript -- we'd end up putting all sorts of redundant HTML into each\ntemplate.\n\nThe server-side include solution to this problem is to factor out the\ncommon bits in both templates and save them in separate template snippets,\nwhich are then included in each template. Perhaps you'd store the top\nbit of the template in a file called ``header.html``::\n\n \n \n \n\nAnd perhaps you'd store the bottom bit in a file called ``footer.html``::\n\n
    \n

    Thanks for visiting my site.

    \n \n \n\nWith an include-based strategy, headers and footers are easy. It's the\nmiddle ground that's messy. In this example, both pages feature a title --\n``

    My helpful timestamp site

    `` -- but that title can't fit into\n``header.html`` because the ```` on both pages is different. If we\nincluded the ``<h1>`` in the header, we'd have to include the ``<title>``,\nwhich wouldn't allow us to customize it per page. See where this is going?\n\nDjango's template inheritance system solves these problems. You can think of it\nas an \"inside-out\" version of server-side includes. Instead of defining the\nsnippets that are *common*, you define the snippets that are *different*.\n\nThe first step is to define a *base template* -- a skeleton of your page that\n*child templates* will later fill in. Here's a base template for our ongoing\nexample::\n\n <!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01//EN\">\n <html lang=\"en\">\n <head>\n <title>{% block title %}{% endblock %}\n \n \n

    My helpful timestamp site

    \n {% block content %}{% endblock %}\n {% block footer %}\n
    \n

    Thanks for visiting my site.

    \n {% endblock %}\n \n \n\nThis template, which we'll call ``base.html``, defines a simple HTML skeleton\ndocument that we'll use for all the pages on the site. It's the job of child\ntemplates to override, or add to, or leave alone the contents of the blocks.\n(If you're following along, save this file to your template directory as\n``base.html``.)\n\nWe're using a template tag here that you haven't seen before: the\n``{% block %}`` tag. All the ``{% block %}`` tags do is tell the template\nengine that a child template may override those portions of the template.\n\nNow that we have this base template, we can modify our existing\n``current_datetime.html`` template to use it::\n\n {% extends \"base.html\" %}\n\n {% block title %}The current time{% endblock %}\n\n {% block content %}\n

    It is now {{ current_date }}.

    \n {% endblock %}\n\nWhile we're at it, let's create a template for the ``hours_ahead`` view from\nChapter 3. (If you're following along with code, we'll leave it up to you to\nchange ``hours_ahead`` to use the template system instead of hard-coded HTML.)\nHere's what that could look like::\n\n {% extends \"base.html\" %}\n\n {% block title %}Future time{% endblock %}\n\n {% block content %}\n

    In {{ hour_offset }} hour(s), it will be {{ next_time }}.

    \n {% endblock %}\n\nIsn't this beautiful? Each template contains only the code that's *unique* to\nthat template. No redundancy needed. If you need to make a site-wide design\nchange, just make the change to ``base.html``, and all of the other templates\nwill immediately reflect the change.\n\nHere's how it works. When you load the template ``current_datetime.html``,\nthe template engine sees the ``{% extends %}`` tag, noting that\nthis template is a child template. The engine immediately loads the\nparent template -- in this case, ``base.html``.\n\nAt that point, the template engine notices the three ``{% block %}`` tags\nin ``base.html`` and replaces those blocks with the contents of the child\ntemplate. So, the title we've defined in ``{% block title %}`` will be\nused, as will the ``{% block content %}``.\n\nNote that since the child template doesn't define the ``footer`` block,\nthe template system uses the value from the parent template instead.\nContent within a ``{% block %}`` tag in a parent template is always\nused as a fallback.\n\nInheritance doesn't affect the template context. In other words, any template\nin the inheritance tree will have access to every one of your template\nvariables from the context.\n\nYou can use as many levels of inheritance as needed. One common way of using\ninheritance is the following three-level approach:\n\n1. Create a ``base.html`` template that holds the main look and feel of\n your site. This is the stuff that rarely, if ever, changes.\n\n2. Create a ``base_SECTION.html`` template for each \"section\" of your site\n (e.g., ``base_photos.html`` and ``base_forum.html``). These templates\n extend ``base.html`` and include section-specific styles/design.\n\n3. Create individual templates for each type of page, such as a forum page\n or a photo gallery. These templates extend the appropriate section\n template.\n\nThis approach maximizes code reuse and makes it easy to add items to shared\nareas, such as section-wide navigation.\n\nHere are some guidelines for working with template inheritance:\n\n* If you use ``{% extends %}`` in a template, it must be the first\n template tag in that template. Otherwise, template inheritance won't\n work.\n\n* Generally, the more ``{% block %}`` tags in your base templates, the\n better. Remember, child templates don't have to define all parent blocks,\n so you can fill in reasonable defaults in a number of blocks, and then\n define only the ones you need in the child templates. It's better to have\n more hooks than fewer hooks.\n\n* If you find yourself duplicating code in a number of templates, it\n probably means you should move that code to a ``{% block %}`` in a\n parent template.\n\n* If you need to get the content of the block from the parent template,\n use ``{{ block.super }}``, which is a \"magic\" variable providing the\n rendered text of the parent template. This is useful if you want to add\n to the contents of a parent block instead of completely overriding it.\n\n* You may not define multiple ``{% block %}`` tags with the same name in\n the same template. This limitation exists because a block tag works in\n \"both\" directions. That is, a block tag doesn't just provide a hole to\n fill, it also defines the content that fills the hole in the *parent*.\n If there were two similarly named ``{% block %}`` tags in a template,\n that template's parent wouldn't know which one of the blocks' content to\n use.\n\n* The template name you pass to ``{% extends %}`` is loaded using the same\n method that ``get_template()`` uses. That is, the template name is\n appended to your ``TEMPLATE_DIRS`` setting.\n\n* In most cases, the argument to ``{% extends %}`` will be a string, but it\n can also be a variable, if you don't know the name of the parent template\n until runtime. This lets you do some cool, dynamic stuff.\n\nWhat's next?\n============\n\nYou now have the basics of Django's template system under your belt. What's next?\n\nMany modern Web sites are *database-driven*: the content of the Web site is\nstored in a relational database. This allows a clean separation of data and logic\n(in the same way views and templates allow the separation of logic and display.)\n\nThe :doc:`next chapter ` covers the tools Django gives you to\ninteract with a database.\n" }, { "path": "Python/DjangoBook/chapter05.rst", "content": "=================\nChapter 5: Models\n=================\n\nIn Chapter 3, we covered the fundamentals of building dynamic Web sites\nwith Django: setting up views and URLconfs. As we explained, a view is\nresponsible for doing *some arbitrary logic*, and then returning a response. In\none of the examples, our arbitrary logic was to calculate the current date and\ntime.\n\nIn modern Web applications, the arbitrary logic often involves interacting\nwith a database. Behind the scenes, a *database-driven Web site* connects to\na database server, retrieves some data out of it, and displays that data on a\nWeb page. The site might also provide ways for site visitors to populate the\ndatabase on their own.\n\nMany complex Web sites provide some combination of the two. Amazon.com, for\ninstance, is a great example of a database-driven site. Each product page is\nessentially a query into Amazon's product database formatted as HTML, and when\nyou post a customer review, it gets inserted into the database of reviews.\n\nDjango is well suited for making database-driven Web sites, because it comes\nwith easy yet powerful tools for performing database queries using Python. This\nchapter explains that functionality: Django's database layer.\n\n(Note: While it's not strictly necessary to know basic relational database\ntheory and SQL in order to use Django's database layer, it's highly\nrecommended. An introduction to those concepts is beyond the scope of this\nbook, but keep reading even if you're a database newbie. You'll probably be\nable to follow along and grasp concepts based on the context.)\n\nThe \"Dumb\" Way to Do Database Queries in Views\n==============================================\n\nJust as Chapter 3 detailed a \"dumb\" way to produce output within a\nview (by hard-coding the text directly within the view), there's a \"dumb\" way to\nretrieve data from a database in a view. It's simple: just use any existing\nPython library to execute an SQL query and do something with the results.\n\nIn this example view, we use the ``MySQLdb`` library (available via\nhttp://www.djangoproject.com/r/python-mysql/) to connect to a MySQL database,\nretrieve some records, and feed them to a template for display as a Web page::\n\n from django.shortcuts import render\n import MySQLdb\n\n def book_list(request):\n db = MySQLdb.connect(user='me', db='mydb', passwd='secret', host='localhost')\n cursor = db.cursor()\n cursor.execute('SELECT name FROM books ORDER BY name')\n names = [row[0] for row in cursor.fetchall()]\n db.close()\n return render(request, 'book_list.html', {'names': names})\n\n.. SL Tested ok\n\nThis approach works, but some problems should jump out at you immediately:\n\n* We're hard-coding the database connection parameters. Ideally, these\n parameters would be stored in the Django configuration.\n\n* We're having to write a fair bit of boilerplate code: creating a\n connection, creating a cursor, executing a statement, and closing the\n connection. Ideally, all we'd have to do is specify which results we\n wanted.\n\n* It ties us to MySQL. If, down the road, we switch from MySQL to\n PostgreSQL, we'll have to use a different database adapter (e.g.,\n ``psycopg`` rather than ``MySQLdb``), alter the connection parameters,\n and -- depending on the nature of the SQL statement -- possibly rewrite\n the SQL. Ideally, the database server we're using would be abstracted, so\n that a database server change could be made in a single place. (This\n feature is particularly relevant if you're building an open-source Django\n application that you want to be used by as many people as possible.)\n\nAs you might expect, Django's database layer aims to solve these problems.\nHere's a sneak preview of how the previous view can be rewritten using Django's\ndatabase API::\n\n from django.shortcuts import render\n from mysite.books.models import Book\n\n def book_list(request):\n books = Book.objects.order_by('name')\n return render(request, 'book_list.html', {'books': books})\n\nWe'll explain this code a little later in the chapter. For now, just get a\nfeel for how it looks.\n\nThe MTV (or MVC) Development Pattern\n====================================\n\nBefore we delve into any more code, let's take a moment to consider the overall\ndesign of a database-driven Django Web application.\n\nAs we mentioned in previous chapters, Django is designed to encourage loose\ncoupling and strict separation between pieces of an application. If you follow\nthis philosophy, it's easy to make changes to one particular piece of the\napplication without affecting the other pieces. In view functions, for\ninstance, we discussed the importance of separating the business logic from the\npresentation logic by using a template system. With the database layer, we're\napplying that same philosophy to data access logic.\n\nThose three pieces together -- data access logic, business logic, and\npresentation logic -- comprise a concept that's sometimes called the\n*Model-View-Controller* (MVC) pattern of software architecture. In this\npattern, \"Model\" refers to the data access layer, \"View\" refers to the part of\nthe system that selects what to display and how to display it, and\n\"Controller\" refers to the part of the system that decides which view to use,\ndepending on user input, accessing the model as needed.\n\n.. admonition:: Why the Acronym?\n\n The goal of explicitly defining patterns such as MVC is mostly to\n streamline communication among developers. Instead of having to tell your\n coworkers, \"Let's make an abstraction of the data access, then let's have a\n separate layer that handles data display, and let's put a layer in the\n middle that regulates this,\" you can take advantage of a shared vocabulary\n and say, \"Let's use the MVC pattern here.\"\n\nDjango follows this MVC pattern closely enough that it can be called an MVC\nframework. Here's roughly how the M, V, and C break down in Django:\n\n* *M*, the data-access portion, is handled by Django's database layer,\n which is described in this chapter.\n\n* *V*, the portion that selects which data to display and how to display\n it, is handled by views and templates.\n\n* *C*, the portion that delegates to a view depending on user input, is\n handled by the framework itself by following your URLconf and calling the\n appropriate Python function for the given URL.\n\nBecause the \"C\" is handled by the framework itself and most of the excitement\nin Django happens in models, templates and views, Django has been referred to\nas an *MTV framework*. In the MTV development pattern,\n\n* *M* stands for \"Model,\" the data access layer. This layer contains\n anything and everything about the data: how to access it, how to validate\n it, which behaviors it has, and the relationships between the data.\n\n* *T* stands for \"Template,\" the presentation layer. This layer contains\n presentation-related decisions: how something should be displayed on a\n Web page or other type of document.\n\n* *V* stands for \"View,\" the business logic layer. This layer contains the\n logic that access the model and defers to the appropriate template(s).\n You can think of it as the bridge between models and templates.\n\nIf you're familiar with other MVC Web-development frameworks, such as Ruby on\nRails, you may consider Django views to be the \"controllers\" and Django\ntemplates to be the \"views.\" This is an unfortunate confusion brought about by\ndiffering interpretations of MVC. In Django's interpretation of MVC, the \"view\"\ndescribes the data that gets presented to the user; it's not necessarily just\n*how* the data looks, but *which* data is presented. In contrast, Ruby on Rails\nand similar frameworks suggest that the controller's job includes deciding\nwhich data gets presented to the user, whereas the view is strictly *how* the\ndata looks, not *which* data is presented.\n\nNeither interpretation is more \"correct\" than the other. The important thing is\nto understand the underlying concepts.\n\nConfiguring the Database\n========================\n\nWith all of that philosophy in mind, let's start exploring Django's database\nlayer. First, we need to take care of some initial configuration; we need to\ntell Django which database server to use and how to connect to it.\n\nWe'll assume you've set up a database server, activated it, and created a\ndatabase within it (e.g., using a ``CREATE DATABASE`` statement). If you're\nusing SQLite, no such setup is required, because SQLite uses standalone files\non the filesystem to store its data.\n\nAs with ``TEMPLATE_DIRS`` in the previous chapter, database configuration lives in\nthe Django settings file, called ``settings.py`` by default. Edit that file and\nlook for the database settings::\n\n DATABASES = {\n 'default': {\n 'ENGINE': 'django.db.backends.', # Add 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'.\n 'NAME': '', # Or path to database file if using sqlite3.\n 'USER': '', # Not used with sqlite3.\n 'PASSWORD': '', # Not used with sqlite3.\n 'HOST': '', # Set to empty string for localhost. Not used with sqlite3.\n 'PORT': '', # Set to empty string for default. Not used with sqlite3.\n }\n }\n\nHere's a rundown of each setting.\n\n* ``ENGINE`` tells Django which database engine to use. If you're\n using a database with Django, ``ENGINE`` must be set to one of\n the strings shown in Table 5-1.\n\n .. table:: Table 5-1. Database Engine Settings\n\n ============================================ ============ ================================================\n Setting Database Required Adapter\n ============================================ ============ ================================================\n ``django.db.backends.postgresql_psycopg2`` PostgreSQL ``psycopg`` version 2.x,\n http://www.djangoproject.com/r/python-pgsql/.\n\n ``django.db.backends.mysql`` MySQL ``MySQLdb``,\n http://www.djangoproject.com/r/python-mysql/.\n\n ``django.db.backends.sqlite3`` SQLite No adapter needed.\n\n ``django.db.backends.oracle`` Oracle ``cx_Oracle``,\n http://www.djangoproject.com/r/python-oracle/.\n ============================================ ============ ================================================\n\n Note that for whichever database back-end you use, you'll need to download\n and install the appropriate database adapter. Each one is available for\n free on the Web; just follow the links in the \"Required Adapter\" column\n in Table 5-1. If you're on Linux, your distribution's package-management\n system might offer convenient packages. (Look for packages called\n ``python-postgresql`` or ``python-psycopg``, for example.)\n\n Example::\n\n 'ENGINE': 'django.db.backends.postgresql_psycopg2',\n\n* ``NAME`` tells Django the name of your database. For example::\n\n 'NAME': 'mydb',\n\n If you're using SQLite, specify the full filesystem path to the database\n file on your filesystem. For example::\n\n 'NAME': '/home/django/mydata.db',\n\n As for where you put that SQLite database, we're using the ``/home/django``\n directory in this example, but you should pick a directory that works\n best for you.\n\n* ``USER`` tells Django which username to use when connecting to\n your database. For example: If you're using SQLite, leave this blank.\n\n* ``PASSWORD`` tells Django which password to use when connecting\n to your database. If you're using SQLite or have an empty password, leave\n this blank.\n\n* ``HOST`` tells Django which host to use when connecting to your\n database. If your database is on the same computer as your Django\n installation (i.e., localhost), leave this blank. If you're using SQLite,\n leave this blank.\n\n MySQL is a special case here. If this value starts with a forward slash\n (``'/'``) and you're using MySQL, MySQL will connect via a Unix socket to\n the specified socket, for example::\n\n 'HOST': '/var/run/mysql',\n\n.. SL The usual convention is for the socket to be named 'mysql.sock' or similar,\n.. SL so would '/var/run/mysql.sock' be a better example?\n\n If you're using MySQL and this value *doesn't* start with a forward\n slash, then this value is assumed to be the host.\n\n* ``PORT`` tells Django which port to use when connecting to your\n database. If you're using SQLite, leave this blank. Otherwise, if you\n leave this blank, the underlying database adapter will use whichever\n port is default for your given database server. In most cases, the\n default port is fine, so you can leave this blank.\n\nOnce you've entered those settings and saved ``settings.py``, it's a good idea\nto test your configuration. To do this, run ``python manage.py shell`` as in\nthe last chapter, from within the ``mysite`` project directory. (As we pointed\nout last chapter ``manage.py shell`` is a way to run the Python interpreter\nwith the correct Django settings activated. This is necessary in our case,\nbecause Django needs to know which settings file to use in order to get your\ndatabase connection information.)\n\nIn the shell, type these commands to test your database configuration::\n\n >>> from django.db import connection\n >>> cursor = connection.cursor()\n\nIf nothing happens, then your database is configured properly. Otherwise, check\nthe error message for clues about what's wrong. Table 5-2 shows some common errors.\n\n.. table:: Table 5-2. Database Configuration Error Messages\n\n ========================================================= ===============================================\n Error Message Solution\n ========================================================= ===============================================\n You haven't set the ENGINE setting yet. Set the ``ENGINE`` setting to\n something other than an empty string. Valid\n values are in Table 5-1.\n Environment variable DJANGO_SETTINGS_MODULE is undefined. Run the command ``python manage.py shell``\n rather than ``python``.\n Error loading _____ module: No module named _____. You haven't installed the appropriate\n database-specific adapter (e.g., ``psycopg``\n or ``MySQLdb``). Adapters are *not* bundled\n with Django, so it's your responsibility to\n download and install them on your own.\n _____ isn't an available database backend. Set your ``ENGINE`` setting to\n one of the valid engine settings described\n previously. Perhaps you made a typo?\n database _____ does not exist Change the ``NAME`` setting to\n point to a database that exists, or\n execute the appropriate\n ``CREATE DATABASE`` statement in order to\n create it.\n role _____ does not exist Change the ``USER`` setting to point\n to a user that exists, or create the user\n in your database.\n could not connect to server Make sure ``HOST`` and\n ``PORT`` are set correctly, and\n make sure the database server is running.\n ========================================================= ===============================================\n\nYour First App\n==============\n\nNow that you've verified the connection is working, it's time to create a\n*Django app* -- a bundle of Django code, including models and views, that\nlives together in a single Python package and represents a full Django\napplication.\n\nIt's worth explaining the terminology here, because this tends to trip up\nbeginners. We'd already created a *project*, in Chapter 2, so what's the\ndifference between a *project* and an *app*? The difference is that of\nconfiguration vs. code:\n\n* A project is an instance of a certain set of Django apps, plus the\n configuration for those apps.\n\n Technically, the only requirement of a project is that it supplies a\n settings file, which defines the database connection information, the\n list of installed apps, the ``TEMPLATE_DIRS``, and so forth.\n\n* An app is a portable set of Django functionality, usually including\n models and views, that lives together in a single Python package.\n\n For example, Django comes with a number of apps, such as a commenting\n system and an automatic admin interface. A key thing to note about these\n apps is that they're portable and reusable across multiple projects.\n\nThere are very few hard-and-fast rules about how you fit your Django code into\nthis scheme. If you're building a simple Web site, you may use only a single\napp. If you're building a complex Web site with several unrelated pieces such\nas an e-commerce system and a message board, you'll probably want to split\nthose into separate apps so that you'll be able to reuse them individually in\nthe future.\n\nIndeed, you don't necessarily need to create apps at all, as evidenced by the\nexample view functions we've created so far in this book. In those cases, we\nsimply created a file called ``views.py``, filled it with view functions, and\npointed our URLconf at those functions. No \"apps\" were needed.\n\nHowever, there's one requirement regarding the app convention: if you're using\nDjango's database layer (models), you must create a Django app. Models must\nlive within apps. Thus, in order to start writing our models, we'll need to\ncreate a new app.\n\nWithin the ``mysite`` project directory, type this command to create a\n``books`` app::\n\n python manage.py startapp books\n\nThis command does not produce any output, but it does create a ``books``\ndirectory within the ``mysite`` directory. Let's look at the contents\nof that directory::\n\n books/\n __init__.py\n models.py\n tests.py\n views.py\n\nThese files will contain the models and views for this app.\n\nHave a look at ``models.py`` and ``views.py`` in your favorite text editor.\nBoth files are empty, except for comments and an import in ``models.py``. This\nis the blank slate for your Django app.\n\nDefining Models in Python\n=========================\n\nAs we discussed earlier in this chapter, the \"M\" in \"MTV\" stands for \"Model.\" A\nDjango model is a description of the data in your database, represented as\nPython code. It's your data layout -- the equivalent of your SQL ``CREATE\nTABLE`` statements -- except it's in Python instead of SQL, and it includes\nmore than just database column definitions. Django uses a model to execute SQL\ncode behind the scenes and return convenient Python data structures representing\nthe rows in your database tables. Django also uses models to represent\nhigher-level concepts that SQL can't necessarily handle.\n\nIf you're familiar with databases, your immediate thought might be, \"Isn't it\nredundant to define data models in Python instead of in SQL?\" Django works the\nway it does for several reasons:\n\n* Introspection requires overhead and is imperfect. In order to provide\n convenient data-access APIs, Django needs to know the\n database layout *somehow*, and there are two ways of accomplishing this.\n The first way would be to explicitly describe the data in Python, and the\n second way would be to introspect the database at runtime to determine\n the data models.\n\n This second way seems cleaner, because the metadata about your tables\n lives in only one place, but it introduces a few problems. First,\n introspecting a database at runtime obviously requires overhead. If the\n framework had to introspect the database each time it processed a\n request, or even only when the Web server was initialized, this would\n incur an unacceptable level of overhead. (While some believe that level\n of overhead is acceptable, Django's developers aim to trim as much\n framework overhead as possible.) Second, some databases, notably older\n versions of MySQL, do not store sufficient metadata for accurate and\n complete introspection.\n\n* Writing Python is fun, and keeping everything in Python limits the number\n of times your brain has to do a \"context switch.\" It helps productivity\n if you keep yourself in a single programming environment/mentality for as\n long as possible. Having to write SQL, then Python, and then SQL again is\n disruptive.\n\n* Having data models stored as code rather than in your database makes it\n easier to keep your models under version control. This way, you can\n easily keep track of changes to your data layouts.\n\n* SQL allows for only a certain level of metadata about a data layout. Most\n database systems, for example, do not provide a specialized data type for\n representing email addresses or URLs. Django models do. The advantage of\n higher-level data types is higher productivity and more reusable code.\n\n* SQL is inconsistent across database platforms. If you're distributing a\n Web application, for example, it's much more pragmatic to distribute a\n Python module that describes your data layout than separate sets of\n ``CREATE TABLE`` statements for MySQL, PostgreSQL, and SQLite.\n\nA drawback of this approach, however, is that it's possible for the Python code\nto get out of sync with what's actually in the database. If you make changes to\na Django model, you'll need to make the same changes inside your database to\nkeep your database consistent with the model. We'll discuss some strategies for\nhandling this problem later in this chapter.\n\nFinally, we should note that Django includes a utility that can generate models\nby introspecting an existing database. This is useful for quickly getting up\nand running with legacy data. We'll cover this in Chapter 18.\n\nYour First Model\n================\n\nAs an ongoing example in this chapter and the next chapter, we'll focus on a\nbasic book/author/publisher data layout. We use this as our example because the\nconceptual relationships between books, authors, and publishers are well known,\nand this is a common data layout used in introductory SQL textbooks. You're\nalso reading a book that was written by authors and produced by a publisher!\n\nWe'll suppose the following concepts, fields, and relationships:\n\n* An author has a first name, a last name and an email address.\n\n* A publisher has a name, a street address, a city, a state/province, a\n country, and a Web site.\n\n* A book has a title and a publication date. It also has one or more\n authors (a many-to-many relationship with authors) and a single publisher\n (a one-to-many relationship -- aka foreign key -- to publishers).\n\nThe first step in using this database layout with Django is to express it as\nPython code. In the ``models.py`` file that was created by the ``startapp``\ncommand, enter the following::\n\n from django.db import models\n\n class Publisher(models.Model):\n name = models.CharField(max_length=30)\n address = models.CharField(max_length=50)\n city = models.CharField(max_length=60)\n state_province = models.CharField(max_length=30)\n country = models.CharField(max_length=50)\n website = models.URLField()\n\n class Author(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=40)\n email = models.EmailField()\n\n class Book(models.Model):\n title = models.CharField(max_length=100)\n authors = models.ManyToManyField(Author)\n publisher = models.ForeignKey(Publisher)\n publication_date = models.DateField()\n\nLet's quickly examine this code to cover the basics. The first thing to notice\nis that each model is represented by a Python class that is a subclass of\n``django.db.models.Model``. The parent class, ``Model``, contains all the\nmachinery necessary to make these objects capable of interacting with a\ndatabase -- and that leaves our models responsible solely for defining their\nfields, in a nice and compact syntax. Believe it or not, this is all the code\nwe need to write to have basic data access with Django.\n\nEach model generally corresponds to a single database table, and each attribute\non a model generally corresponds to a column in that database table. The\nattribute name corresponds to the column's name, and the type of field (e.g.,\n``CharField``) corresponds to the database column type (e.g., ``varchar``). For\nexample, the ``Publisher`` model is equivalent to the following table (assuming\nPostgreSQL ``CREATE TABLE`` syntax)::\n\n CREATE TABLE \"books_publisher\" (\n \"id\" serial NOT NULL PRIMARY KEY,\n \"name\" varchar(30) NOT NULL,\n \"address\" varchar(50) NOT NULL,\n \"city\" varchar(60) NOT NULL,\n \"state_province\" varchar(30) NOT NULL,\n \"country\" varchar(50) NOT NULL,\n \"website\" varchar(200) NOT NULL\n );\n\nIndeed, Django can generate that ``CREATE TABLE`` statement automatically, as\nwe'll show you in a moment.\n\nThe exception to the one-class-per-database-table rule is the case of\nmany-to-many relationships. In our example models, ``Book`` has a\n``ManyToManyField`` called ``authors``. This designates that a book has one or\nmany authors, but the ``Book`` database table doesn't get an ``authors``\ncolumn. Rather, Django creates an additional table -- a many-to-many \"join\ntable\" -- that handles the mapping of books to authors.\n\nFor a full list of field types and model syntax options, see Appendix B.\n\nFinally, note we haven't explicitly defined a primary key in any of these\nmodels. Unless you instruct it otherwise, Django automatically gives every\nmodel an auto-incrementing integer primary key field called ``id``. Each Django\nmodel is required to have a single-column primary key.\n\nInstalling the Model\n====================\n\nWe've written the code; now let's create the tables in our database. In order\nto do that, the first step is to *activate* these models in our Django project.\nWe do that by adding the ``books`` app to the list of \"installed apps\" in the\nsettings file.\n\nEdit the ``settings.py`` file again, and look for the ``INSTALLED_APPS``\nsetting. ``INSTALLED_APPS`` tells Django which apps are activated for a given\nproject. By default, it looks something like this::\n\n INSTALLED_APPS = (\n 'django.contrib.auth',\n 'django.contrib.contenttypes',\n 'django.contrib.sessions',\n 'django.contrib.sites',\n )\n\nTemporarily comment out all four of those strings by putting a hash character\n(``#``) in front of them. (They're included by default as a common-case\nconvenience, but we'll activate and discuss them in subsequent chapters.)\nWhile you're at it, comment out the default ``MIDDLEWARE_CLASSES`` setting, too;\nthe default values in ``MIDDLEWARE_CLASSES`` depend on some of the apps we\njust commented out. Then, add ``'mysite.books'`` to the ``INSTALLED_APPS``\nlist, so the setting ends up looking like this::\n\n MIDDLEWARE_CLASSES = (\n # 'django.middleware.common.CommonMiddleware',\n # 'django.contrib.sessions.middleware.SessionMiddleware',\n # 'django.contrib.auth.middleware.AuthenticationMiddleware',\n )\n\n INSTALLED_APPS = (\n # 'django.contrib.auth',\n # 'django.contrib.contenttypes',\n # 'django.contrib.sessions',\n # 'django.contrib.sites',\n 'mysite.books',\n )\n\n(As we mentioned last chapter when setting ``TEMPLATE_DIRS``, you'll need to be\nsure to include the trailing comma in ``INSTALLED_APPS``, because it's a\nsingle-element tuple. By the way, this book's authors prefer to put a comma\nafter *every* element of a tuple, regardless of whether the tuple has only a\nsingle element. This avoids the issue of forgetting commas, and there's no\npenalty for using that extra comma.)\n\n``'mysite.books'`` refers to the ``books`` app we're working on. Each app in\n``INSTALLED_APPS`` is represented by its full Python path -- that is, the path\nof packages, separated by dots, leading to the app package.\n\nNow that the Django app has been activated in the settings file, we can create\nthe database tables in our database. First, let's validate the models by\nrunning this command::\n\n python manage.py validate\n\n.. SL Tested ok\n\nThe ``validate`` command checks whether your models' syntax and logic are\ncorrect. If all is well, you'll see the message ``0 errors found``. If you\ndon't, make sure you typed in the model code correctly. The error output should\ngive you helpful information about what was wrong with the code.\n\nAny time you think you have problems with your models, run\n``python manage.py validate``. It tends to catch all the common model problems.\n\nIf your models are valid, run the following command for Django to generate\n``CREATE TABLE`` statements for your models in the ``books`` app (with colorful\nsyntax highlighting available, if you're using Unix)::\n\n python manage.py sqlall books\n\nIn this command, ``books`` is the name of the app. It's what you specified when\nyou ran the command ``manage.py startapp``. When you run the command, you\nshould see something like this::\n\n BEGIN;\n CREATE TABLE \"books_publisher\" (\n \"id\" serial NOT NULL PRIMARY KEY,\n \"name\" varchar(30) NOT NULL,\n \"address\" varchar(50) NOT NULL,\n \"city\" varchar(60) NOT NULL,\n \"state_province\" varchar(30) NOT NULL,\n \"country\" varchar(50) NOT NULL,\n \"website\" varchar(200) NOT NULL\n )\n ;\n CREATE TABLE \"books_author\" (\n \"id\" serial NOT NULL PRIMARY KEY,\n \"first_name\" varchar(30) NOT NULL,\n \"last_name\" varchar(40) NOT NULL,\n \"email\" varchar(75) NOT NULL\n )\n ;\n CREATE TABLE \"books_book\" (\n \"id\" serial NOT NULL PRIMARY KEY,\n \"title\" varchar(100) NOT NULL,\n \"publisher_id\" integer NOT NULL REFERENCES \"books_publisher\" (\"id\") DEFERRABLE INITIALLY DEFERRED,\n \"publication_date\" date NOT NULL\n )\n ;\n CREATE TABLE \"books_book_authors\" (\n \"id\" serial NOT NULL PRIMARY KEY,\n \"book_id\" integer NOT NULL REFERENCES \"books_book\" (\"id\") DEFERRABLE INITIALLY DEFERRED,\n \"author_id\" integer NOT NULL REFERENCES \"books_author\" (\"id\") DEFERRABLE INITIALLY DEFERRED,\n UNIQUE (\"book_id\", \"author_id\")\n )\n ;\n CREATE INDEX \"books_book_publisher_id\" ON \"books_book\" (\"publisher_id\");\n COMMIT;\n\n.. SL Tested ok (sqlall output for postgres matches that shown here)\n\nNote the following:\n\n* Table names are automatically generated by combining the name of the app\n (``books``) and the lowercase name of the model (``publisher``,\n ``book``, and ``author``). You can override this behavior, as detailed\n in Appendix B.\n\n* As we mentioned earlier, Django adds a primary key for each table\n automatically -- the ``id`` fields. You can override this, too.\n\n* By convention, Django appends ``\"_id\"`` to the foreign key field name. As\n you might have guessed, you can override this behavior, too.\n\n* The foreign key relationship is made explicit by a ``REFERENCES``\n statement.\n\n* These ``CREATE TABLE`` statements are tailored to the database you're\n using, so database-specific field types such as ``auto_increment``\n (MySQL), ``serial`` (PostgreSQL), or ``integer primary key`` (SQLite) are\n handled for you automatically. The same goes for quoting of column names\n (e.g., using double quotes or single quotes). This example output is in\n PostgreSQL syntax.\n\nThe ``sqlall`` command doesn't actually create the tables or otherwise touch\nyour database -- it just prints output to the screen so you can see what SQL\nDjango would execute if you asked it. If you wanted to, you could copy and\npaste this SQL into your database client, or use Unix pipes to pass it\ndirectly (e.g., ``python manage.py sqlall books | psql mydb``). However, Django\nprovides an easier way of committing the SQL to the database: the ``syncdb``\ncommand::\n\n python manage.py syncdb\n\nRun that command, and you'll see something like this::\n\n Creating table books_publisher\n Creating table books_author\n Creating table books_book\n Installing index for books.Book model\n\n.. SL Tested ok\n\nThe ``syncdb`` command is a simple \"sync\" of your models to your database. It\nlooks at all of the models in each app in your ``INSTALLED_APPS`` setting,\nchecks the database to see whether the appropriate tables exist yet, and\ncreates the tables if they don't yet exist. Note that ``syncdb`` does *not*\nsync changes in models or deletions of models; if you make a change to a model\nor delete a model, and you want to update the database, ``syncdb`` will not\nhandle that. (More on this in the \"Making Changes to a Database Schema\" section\ntoward the end of this chapter.)\n\nIf you run ``python manage.py syncdb`` again, nothing happens, because you\nhaven't added any models to the ``books`` app or added any apps to\n``INSTALLED_APPS``. Ergo, it's always safe to run ``python manage.py syncdb``\n-- it won't clobber things.\n\nIf you're interested, take a moment to dive into your database server's\ncommand-line client and see the database tables Django created. You can\nmanually run the command-line client (e.g., ``psql`` for PostgreSQL) or\nyou can run the command ``python manage.py dbshell``, which will figure out\nwhich command-line client to run, depending on your ``DATABASE_SERVER``\nsetting. The latter is almost always more convenient.\n\nBasic Data Access\n=================\n\nOnce you've created a model, Django automatically provides a high-level Python\nAPI for working with those models. Try it out by running\n``python manage.py shell`` and typing the following::\n\n >>> from books.models import Publisher\n >>> p1 = Publisher(name='Apress', address='2855 Telegraph Avenue',\n ... city='Berkeley', state_province='CA', country='U.S.A.',\n ... website='http://www.apress.com/')\n >>> p1.save()\n >>> p2 = Publisher(name=\"O'Reilly\", address='10 Fawcett St.',\n ... city='Cambridge', state_province='MA', country='U.S.A.',\n ... website='http://www.oreilly.com/')\n >>> p2.save()\n >>> publisher_list = Publisher.objects.all()\n >>> publisher_list\n [, ]\n\n.. SL Tested ok\n\nThese few lines of code accomplish quite a bit. Here are the highlights:\n\n* First, we import our ``Publisher`` model class. This lets us interact\n with the database table that contains publishers.\n\n* We create a ``Publisher`` object by instantiating it with values for\n each field -- ``name``, ``address``, etc.\n\n* To save the object to the database, call its ``save()`` method. Behind\n the scenes, Django executes an SQL ``INSERT`` statement here.\n\n* To retrieve publishers from the database, use the attribute\n ``Publisher.objects``, which you can think of as a set of all publishers.\n Fetch a list of *all* ``Publisher`` objects in the database with the\n statement ``Publisher.objects.all()``. Behind the scenes, Django executes\n an SQL ``SELECT`` statement here.\n\nOne thing is worth mentioning, in case it wasn't clear from this example. When\nyou're creating objects using the Django model API, Django doesn't save the\nobjects to the database until you call the ``save()`` method::\n\n p1 = Publisher(...)\n # At this point, p1 is not saved to the database yet!\n p1.save()\n # Now it is.\n\nIf you want to create an object and save it to the database in a single step,\nuse the ``objects.create()`` method. This example is equivalent to the example\nabove::\n\n >>> p1 = Publisher.objects.create(name='Apress',\n ... address='2855 Telegraph Avenue',\n ... city='Berkeley', state_province='CA', country='U.S.A.',\n ... website='http://www.apress.com/')\n >>> p2 = Publisher.objects.create(name=\"O'Reilly\",\n ... address='10 Fawcett St.', city='Cambridge',\n ... state_province='MA', country='U.S.A.',\n ... website='http://www.oreilly.com/')\n >>> publisher_list = Publisher.objects.all()\n >>> publisher_list\n\n.. SL Tested ok\n\nNaturally, you can do quite a lot with the Django database API -- but first,\nlet's take care of a small annoyance.\n\nAdding Model String Representations\n===================================\n\nWhen we printed out the list of publishers, all we got was this\nunhelpful display that makes it difficult to tell the ``Publisher`` objects\napart::\n\n [, ]\n\nWe can fix this easily by adding a method called ``__unicode__()`` to our\n``Publisher`` class. A ``__unicode__()`` method tells Python how to display the\n\"unicode\" representation of an object. You can see this in action by adding a\n``__unicode__()`` method to the three models:\n\n.. parsed-literal::\n\n from django.db import models\n\n class Publisher(models.Model):\n name = models.CharField(max_length=30)\n address = models.CharField(max_length=50)\n city = models.CharField(max_length=60)\n state_province = models.CharField(max_length=30)\n country = models.CharField(max_length=50)\n website = models.URLField()\n\n **def __unicode__(self):**\n **return self.name**\n\n class Author(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=40)\n email = models.EmailField()\n\n **def __unicode__(self):**\n **return u'%s %s' % (self.first_name, self.last_name)**\n\n class Book(models.Model):\n title = models.CharField(max_length=100)\n authors = models.ManyToManyField(Author)\n publisher = models.ForeignKey(Publisher)\n publication_date = models.DateField()\n\n **def __unicode__(self):**\n **return self.title**\n\nAs you can see, a ``__unicode__()`` method can do whatever it needs to do in order\nto return a representation of an object. Here, the ``__unicode__()`` methods for\n``Publisher`` and ``Book`` simply return the object's name and title,\nrespectively, but the ``__unicode__()`` for ``Author`` is slightly more complex --\nit pieces together the ``first_name`` and ``last_name`` fields, separated by a\nspace.\n\nThe only requirement for ``__unicode__()`` is that it return a Unicode object.\nIf ``__unicode__()`` doesn't return a Unicode object -- if it returns, say, an\ninteger -- then Python will raise a ``TypeError`` with a message like\n``\"coercing to Unicode: need string or buffer, int found\"``.\n\n.. admonition:: Unicode objects\n\n What are Unicode objects?\n\n You can think of a Unicode object as a Python string that can handle more\n than a million different types of characters, from accented versions of\n Latin characters to non-Latin characters to curly quotes and obscure\n symbols.\n\n Normal Python strings are *encoded*, which means they use an encoding such\n as ASCII, ISO-8859-1 or UTF-8. If you're storing fancy characters (anything\n beyond the standard 128 ASCII characters such as 0-9 and A-Z) in a normal\n Python string, you have to keep track of which encoding your string is\n using, or the fancy characters might appear messed up when they're\n displayed or printed. Problems occur when you have data that's stored in\n one encoding and you try to combine it with data in a different encoding,\n or you try to display it in an application that assumes a certain encoding.\n We've all seen Web pages and e-mails that are littered with \"??? ??????\"\n or other characters in odd places; that generally suggests there's an\n encoding problem.\n\n Unicode objects, however, have no encoding; they use a consistent,\n universal set of characters called, well, \"Unicode.\" When you deal with\n Unicode objects in Python, you can mix and match them safely without having\n to worry about encoding issues.\n\n Django uses Unicode objects throughout the framework. Model objects are\n retrieved as Unicode objects, views interact with Unicode data, and\n templates are rendered as Unicode. Generally, you won't have to worry about\n making sure your encodings are right; things should just work.\n\n Note that this has been a *very* high-level, dumbed down overview of\n Unicode objects, and you owe it to yourself to learn more about the topic.\n A good place to start is http://www.joelonsoftware.com/articles/Unicode.html .\n\nFor the ``__unicode__()`` changes to take effect, exit out of the Python shell\nand enter it again with ``python manage.py shell``. (This is the simplest way\nto make code changes take effect.) Now the list of ``Publisher`` objects is\nmuch easier to understand::\n\n >>> from books.models import Publisher\n >>> publisher_list = Publisher.objects.all()\n >>> publisher_list\n [, ]\n\n.. SL Tested ok\n\nMake sure any model you define has a ``__unicode__()`` method -- not only for\nyour own convenience when using the interactive interpreter, but also because\nDjango uses the output of ``__unicode__()`` in several places when it needs to\ndisplay objects.\n\nFinally, note that ``__unicode__()`` is a good example of adding *behavior* to\nmodels. A Django model describes more than the database table layout for an\nobject; it also describes any functionality that object knows how to do.\n``__unicode__()`` is one example of such functionality -- a model knows how to\ndisplay itself.\n\nInserting and Updating Data\n===========================\n\nYou've already seen this done: to insert a row into your database, first create\nan instance of your model using keyword arguments, like so::\n\n >>> p = Publisher(name='Apress',\n ... address='2855 Telegraph Ave.',\n ... city='Berkeley',\n ... state_province='CA',\n ... country='U.S.A.',\n ... website='http://www.apress.com/')\n\nAs we noted above, this act of instantiating a model class does *not* touch\nthe database. The record isn't saved into the database until you call\n``save()``, like this::\n\n >>> p.save()\n\n.. SL Tested ok\n\nIn SQL, this can roughly be translated into the following::\n\n INSERT INTO books_publisher\n (name, address, city, state_province, country, website)\n VALUES\n ('Apress', '2855 Telegraph Ave.', 'Berkeley', 'CA',\n 'U.S.A.', 'http://www.apress.com/');\n\nBecause the ``Publisher`` model uses an autoincrementing primary key ``id``,\nthe initial call to ``save()`` does one more thing: it calculates the primary\nkey value for the record and sets it to the ``id`` attribute on the instance::\n\n >>> p.id\n 52 # this will differ based on your own data\n\n.. SL Should be '52L' to match actual output.\n\nSubsequent calls to ``save()`` will save the record in place, without creating\na new record (i.e., performing an SQL ``UPDATE`` statement instead of an\n``INSERT``)::\n\n >>> p.name = 'Apress Publishing'\n >>> p.save()\n\n.. SL Tested ok\n\nThe preceding ``save()`` statement will result in roughly the following SQL::\n\n UPDATE books_publisher SET\n name = 'Apress Publishing',\n address = '2855 Telegraph Ave.',\n city = 'Berkeley',\n state_province = 'CA',\n country = 'U.S.A.',\n website = 'http://www.apress.com'\n WHERE id = 52;\n\nYes, note that *all* of the fields will be updated, not just the ones that have\nbeen changed. Depending on your application, this may cause a race condition.\nSee \"Updating Multiple Objects in One Statement\" below to find out how to\nexecute this (slightly different) query::\n\n UPDATE books_publisher SET\n name = 'Apress Publishing'\n WHERE id=52;\n\nSelecting Objects\n=================\n\nKnowing how to create and update database records is essential, but chances are\nthat the Web applications you'll build will be doing more querying of existing\nobjects than creating new ones. We've already seen a way to retrieve *every*\nrecord for a given model::\n\n >>> Publisher.objects.all()\n [, ]\n\n.. SL Tested ok\n\nThis roughly translates to this SQL::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher;\n\n.. note::\n\n Notice that Django doesn't use ``SELECT *`` when looking up data and instead\n lists all fields explicitly. This is by design: in certain circumstances\n ``SELECT *`` can be slower, and (more important) listing fields more closely\n follows one tenet of the Zen of Python: \"Explicit is better than implicit.\"\n\n For more on the Zen of Python, try typing ``import this`` at a Python\n prompt.\n\nLet's take a close look at each part of this ``Publisher.objects.all()`` line:\n\n* First, we have the model we defined, ``Publisher``. No surprise here: when\n you want to look up data, you use the model for that data.\n\n* Next, we have the ``objects`` attribute. This is called a *manager*.\n Managers are discussed in detail in Chapter 10. For now, all you need to\n know is that managers take care of all \"table-level\" operations on data\n including, most important, data lookup.\n\n All models automatically get a ``objects`` manager; you'll use it\n any time you want to look up model instances.\n\n* Finally, we have ``all()``. This is a method on the ``objects`` manager\n that returns all the rows in the database. Though this object *looks*\n like a list, it's actually a *QuerySet* -- an object that represents a\n specific set of rows from the database. Appendix C deals with QuerySets\n in detail. For the rest of this chapter, we'll just treat them like the\n lists they emulate.\n\nAny database lookup is going to follow this general pattern -- we'll call methods on\nthe manager attached to the model we want to query against.\n\nFiltering Data\n--------------\n\nNaturally, it's rare to want to select *everything* from a database at once; in\nmost cases, you'll want to deal with a subset of your data. In the Django API,\nyou can filter your data using the ``filter()`` method::\n\n >>> Publisher.objects.filter(name='Apress')\n []\n\n.. SL Tested ok\n\n``filter()`` takes keyword arguments that get translated into the appropriate\nSQL ``WHERE`` clauses. The preceding example would get translated into\nsomething like this::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n WHERE name = 'Apress';\n\nYou can pass multiple arguments into ``filter()`` to narrow down things further::\n\n >>> Publisher.objects.filter(country=\"U.S.A.\", state_province=\"CA\")\n []\n\n.. SL Tested ok\n\nThose multiple arguments get translated into SQL ``AND`` clauses. Thus, the\nexample in the code snippet translates into the following::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n WHERE country = 'U.S.A.'\n AND state_province = 'CA';\n\nNotice that by default the lookups use the SQL ``=`` operator to do exact match\nlookups. Other lookup types are available::\n\n >>> Publisher.objects.filter(name__contains=\"press\")\n []\n\n.. SL Tested ok\n\nThat's a *double* underscore there between ``name`` and ``contains``. Like\nPython itself, Django uses the double underscore to signal that something\n\"magic\" is happening -- here, the ``__contains`` part gets translated by Django\ninto a SQL ``LIKE`` statement::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n WHERE name LIKE '%press%';\n\nMany other types of lookups are available, including ``icontains``\n(case-insensitive ``LIKE``), ``startswith`` and ``endswith``, and ``range`` (SQL\n``BETWEEN`` queries). Appendix C describes all of these lookup types in detail.\n\nRetrieving Single Objects\n-------------------------\n\nThe ``filter()`` examples above all returned a ``QuerySet``, which you can\ntreat like a list. Sometimes it's more convenient to fetch only a single object,\nas opposed to a list. That's what the ``get()`` method is for::\n\n >>> Publisher.objects.get(name=\"Apress\")\n \n\n.. SL Tested ok\n\nInstead of a list (rather, ``QuerySet``), only a single object is returned.\nBecause of that, a query resulting in multiple objects will cause an\nexception::\n\n >>> Publisher.objects.get(country=\"U.S.A.\")\n Traceback (most recent call last):\n ...\n MultipleObjectsReturned: get() returned more than one Publisher --\n it returned 2! Lookup parameters were {'country': 'U.S.A.'}\n\n.. SL Tested ok\n\nA query that returns no objects also causes an exception::\n\n >>> Publisher.objects.get(name=\"Penguin\")\n Traceback (most recent call last):\n ...\n DoesNotExist: Publisher matching query does not exist.\n\n.. SL Tested ok\n\nThe ``DoesNotExist`` exception is an attribute of the model's class --\n``Publisher.DoesNotExist``. In your applications, you'll want to trap these\nexceptions, like this::\n\n try:\n p = Publisher.objects.get(name='Apress')\n except Publisher.DoesNotExist:\n print \"Apress isn't in the database yet.\"\n else:\n print \"Apress is in the database.\"\n\n.. SL Tested ok\n\nOrdering Data\n-------------\n\nAs you play around with the previous examples, you might discover that the objects\nare being returned in a seemingly random order. You aren't imagining things; so\nfar we haven't told the database how to order its results, so we're simply\ngetting back data in some arbitrary order chosen by the database.\n\nIn your Django applications, you'll probably want to order your results\naccording to a certain value -- say, alphabetically. To do this, use the\n``order_by()`` method::\n\n >>> Publisher.objects.order_by(\"name\")\n [, ]\n\n.. SL Tested ok\n\nThis doesn't look much different from the earlier ``all()`` example, but the\nSQL now includes a specific ordering::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n ORDER BY name;\n\nYou can order by any field you like::\n\n >>> Publisher.objects.order_by(\"address\")\n [, ]\n\n >>> Publisher.objects.order_by(\"state_province\")\n [, ]\n\n.. SL Tested ok\n\nTo order by multiple fields (where the second field is used to disambiguate\nordering in cases where the first is the same), use multiple arguments::\n\n >>> Publisher.objects.order_by(\"state_province\", \"address\")\n [, ]\n\n.. SL Tested ok\n\nYou can also specify reverse ordering by prefixing the field name with a ``-``\n(that's a minus character)::\n\n >>> Publisher.objects.order_by(\"-name\")\n [, ]\n\n.. SL Tested ok\n\nWhile this flexibility is useful, using ``order_by()`` all the time can be quite\nrepetitive. Most of the time you'll have a particular field you usually want\nto order by. In these cases, Django lets you specify a default ordering in the\nmodel:\n\n.. parsed-literal::\n\n class Publisher(models.Model):\n name = models.CharField(max_length=30)\n address = models.CharField(max_length=50)\n city = models.CharField(max_length=60)\n state_province = models.CharField(max_length=30)\n country = models.CharField(max_length=50)\n website = models.URLField()\n\n def __unicode__(self):\n return self.name\n\n **class Meta:**\n **ordering = ['name']**\n\nHere, we've introduced a new concept: the ``class Meta``, which is a class\nthat's embedded within the ``Publisher`` class definition (i.e., it's indented\nto be within ``class Publisher``). You can use this ``Meta`` class on any model\nto specify various model-specific options. A full reference of ``Meta`` options\nis available in Appendix B, but for now, we're concerned with the ``ordering``\noption. If you specify this, it tells Django that unless an ordering is given\nexplicitly with ``order_by()``, all ``Publisher`` objects should be ordered by\nthe ``name`` field whenever they're retrieved with the Django database API.\n\nChaining Lookups\n----------------\n\nYou've seen how you can filter data, and you've seen how you can order it. Often, of course,\nyou'll need to do both. In these cases, you simply \"chain\" the lookups together::\n\n >>> Publisher.objects.filter(country=\"U.S.A.\").order_by(\"-name\")\n [, ]\n\n.. SL Tested ok\n\nAs you might expect, this translates to a SQL query with both a ``WHERE`` and an\n``ORDER BY``::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n WHERE country = 'U.S.A'\n ORDER BY name DESC;\n\nSlicing Data\n------------\n\nAnother common need is to look up only a fixed number of rows. Imagine you have thousands\nof publishers in your database, but you want to display only the first one. You can do this\nusing Python's standard list slicing syntax::\n\n >>> Publisher.objects.order_by('name')[0]\n \n\n.. SL Tested ok\n\nThis translates roughly to::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n ORDER BY name\n LIMIT 1;\n\nSimilarly, you can retrieve a specific subset of data using Python's\nrange-slicing syntax::\n\n >>> Publisher.objects.order_by('name')[0:2]\n\n.. SL Tested ok (but should show expected output?)\n\nThis returns two objects, translating roughly to::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n ORDER BY name\n OFFSET 0 LIMIT 2;\n\nNote that negative slicing is *not* supported::\n\n >>> Publisher.objects.order_by('name')[-1]\n Traceback (most recent call last):\n ...\n AssertionError: Negative indexing is not supported.\n\nThis is easy to get around, though. Just change the ``order_by()`` statement,\nlike this::\n\n >>> Publisher.objects.order_by('-name')[0]\n\nUpdating Multiple Objects in One Statement\n------------------------------------------\n\nWe pointed out in the \"Inserting and Updating Data\" section that the model\n``save()`` method updates *all* columns in a row. Depending on your\napplication, you may want to update only a subset of columns.\n\nFor example, let's say we want to update the Apress ``Publisher`` to change\nthe name from ``'Apress'`` to ``'Apress Publishing'``. Using ``save()``, it\nwould look something like this::\n\n >>> p = Publisher.objects.get(name='Apress')\n >>> p.name = 'Apress Publishing'\n >>> p.save()\n\n.. SL Tested ok\n\nThis roughly translates to the following SQL::\n\n SELECT id, name, address, city, state_province, country, website\n FROM books_publisher\n WHERE name = 'Apress';\n\n UPDATE books_publisher SET\n name = 'Apress Publishing',\n address = '2855 Telegraph Ave.',\n city = 'Berkeley',\n state_province = 'CA',\n country = 'U.S.A.',\n website = 'http://www.apress.com'\n WHERE id = 52;\n\n(Note that this example assumes Apress has a publisher ID of ``52``.)\n\nYou can see in this example that Django's ``save()`` method sets *all* of the\ncolumn values, not just the ``name`` column. If you're in an environment where\nother columns of the database might change due to some other process, it's\nsmarter to change *only* the column you need to change. To do this, use the\n``update()`` method on ``QuerySet`` objects. Here's an example::\n\n >>> Publisher.objects.filter(id=52).update(name='Apress Publishing')\n\n.. SL Tested ok\n\nThe SQL translation here is much more efficient and has no chance of race\nconditions::\n\n UPDATE books_publisher\n SET name = 'Apress Publishing'\n WHERE id = 52;\n\nThe ``update()`` method works on any ``QuerySet``, which means you can edit\nmultiple records in bulk. Here's how you might change the ``country`` from\n``'U.S.A.'`` to ``USA`` in each ``Publisher`` record::\n\n >>> Publisher.objects.all().update(country='USA')\n 2\n\n.. SL Tested ok\n\nThe ``update()`` method has a return value -- an integer representing how many\nrecords changed. In the above example, we got ``2``.\n\nDeleting Objects\n================\n\nTo delete an object from your database, simply call the object's ``delete()``\nmethod::\n\n >>> p = Publisher.objects.get(name=\"O'Reilly\")\n >>> p.delete()\n >>> Publisher.objects.all()\n []\n\n.. SL Tested ok\n\nYou can also delete objects in bulk by calling ``delete()`` on the result of\nany ``QuerySet``. This is similar to the ``update()`` method we showed in the\nlast section::\n\n >>> Publisher.objects.filter(country='USA').delete()\n >>> Publisher.objects.all().delete()\n >>> Publisher.objects.all()\n []\n\n.. SL Tested ok\n\nBe careful deleting your data! As a precaution against deleting all of the data\nin a particular table, Django requires you to explicitly use ``all()`` if you\nwant to delete *everything* in your table. For example, this won't work::\n\n >>> Publisher.objects.delete()\n Traceback (most recent call last):\n File \"\", line 1, in \n AttributeError: 'Manager' object has no attribute 'delete'\n\n.. SL Tested ok\n\nBut it'll work if you add the ``all()`` method::\n\n >>> Publisher.objects.all().delete()\n\n.. SL Tested ok\n\nIf you're just deleting a subset of your data, you don't need to include\n``all()``. To repeat a previous example::\n\n >>> Publisher.objects.filter(country='USA').delete()\n\n.. SL Tested ok\n\nWhat's Next?\n============\n\nHaving read this chapter, you have enough knowledge of Django models to be able\nto write basic database applications. Chapter 10 will provide some information\non more advanced usage of Django's database layer.\n\nOnce you've defined your models, the next step is to populate your database\nwith data. You might have legacy data, in which case Chapter 18 will give you\nadvice about integrating with legacy databases. You might rely on site users\nto supply your data, in which case Chapter 7 will teach you how to process\nuser-submitted form data.\n\nBut in some cases, you or your team might need to enter data manually, in which\ncase it would be helpful to have a Web-based interface for entering and\nmanaging data. The :doc:`next chapter ` covers Django's admin interface, which exists\nprecisely for that reason.\n" }, { "path": "Python/DjangoBook/chapter06.rst", "content": "================================\nChapter 6: The Django Admin Site\n================================\n\nFor a certain class of Web sites, an *admin interface* is an essential part of\nthe infrastructure. This is a Web-based interface, limited to trusted site\nadministrators, that enables the adding, editing and deletion of site content.\nSome common examples: the interface you use to post to your blog, the backend\nsite managers use to moderate user-generated comments, the tool your clients\nuse to update the press releases on the Web site you built for them.\n\nThere's a problem with admin interfaces, though: it's boring to build them.\nWeb development is fun when you're developing public-facing functionality, but\nbuilding admin interfaces is always the same. You have to authenticate users,\ndisplay and handle forms, validate input, and so on. It's boring, and it's\nrepetitive.\n\nSo what's Django's approach to these boring, repetitive tasks? It does it all\nfor you -- in just a couple of lines of code, no less. With Django, building an\nadmin interface is a solved problem.\n\nThis chapter is about Django's automatic admin interface. The feature works by\nreading metadata in your model to provide a powerful and production-ready\ninterface that site administrators can start using immediately. Here, we discuss\nhow to activate, use, and customize this feature.\n\nNote that we recommend reading this chapter even if you don't intend to use the\nDjango admin site, because we introduce a few concepts that apply to all of\nDjango, regardless of admin-site usage.\n\nThe django.contrib packages\n===========================\n\nDjango's automatic admin is part of a larger suite of Django functionality\ncalled ``django.contrib`` -- the part of the Django codebase that contains\nvarious useful add-ons to the core framework. You can think of\n``django.contrib`` as Django's equivalent of the Python standard library --\noptional, de facto implementations of common patterns. They're bundled with\nDjango so that you don't have to reinvent the wheel in your own applications.\n\nThe admin site is the first part of ``django.contrib`` that we're covering in\nthis book; technically, it's called ``django.contrib.admin``. Other available\nfeatures in ``django.contrib`` include a user authentication system\n(``django.contrib.auth``), support for anonymous sessions\n(``django.contrib.sessions``) and even a system for user comments\n(``django.contrib.comments``). You'll get to know the various ``django.contrib``\nfeatures as you become a Django expert, and we'll spend some more time\ndiscussing them in Chapter 16. For now, just know that Django ships with many\nnice add-ons, and ``django.contrib`` is generally where they live.\n\nActivating the Admin Interface\n==============================\n\nThe Django admin site is entirely optional, because only certain types of sites\nneed this functionality. That means you'll need to take a few steps to activate\nit in your project.\n\nFirst, make a few changes to your settings file:\n\n1. Add ``'django.contrib.admin'`` to the ``INSTALLED_APPS`` setting. (The\n order of ``INSTALLED_APPS`` doesn't matter, but we like to keep things\n alphabetical so it's easy for a human to read.)\n\n2. Make sure ``INSTALLED_APPS`` contains ``'django.contrib.auth'``,\n ``'django.contrib.contenttypes'`` and ``'django.contrib.sessions'``. The\n Django admin site requires these three packages. (If you're following\n along with our ongoing ``mysite`` project, note that we commented out\n these three ``INSTALLED_APPS`` entries in Chapter 5. Uncomment them now.)\n\n3. Make sure ``MIDDLEWARE_CLASSES`` contains\n ``'django.middleware.common.CommonMiddleware'``,\n ``'django.contrib.sessions.middleware.SessionMiddleware'`` and\n ``'django.contrib.auth.middleware.AuthenticationMiddleware'``. (Again,\n if you're following along, note that we commented them out in Chapter 5,\n so uncomment them.)\n\nSecond, run ``python manage.py syncdb``. This step will install the extra\ndatabase tables that the admin interface uses. The first time you run\n``syncdb`` with ``'django.contrib.auth'`` in ``INSTALLED_APPS``, you'll be\nasked about creating a superuser. If you don't do this, you'll need to run\n``python manage.py createsuperuser`` separately to create an admin user\naccount; otherwise, you won't be able to log in to the admin site. (Potential\ngotcha: the ``python manage.py createsuperuser`` command is only available if\n``'django.contrib.auth'`` is in your ``INSTALLED_APPS``.)\n\nThird, add the admin site to your URLconf (in ``urls.py``, remember). By\ndefault, the ``urls.py`` generated by ``django-admin.py startproject`` contains\ncommented-out code for the Django admin, and all you have to do is uncomment\nit. For the record, here are the bits you need to make sure are in there::\n\n # Include these import statements...\n from django.contrib import admin\n admin.autodiscover()\n\n # And include this URLpattern...\n urlpatterns = patterns('',\n # ...\n (r'^admin/', include(admin.site.urls)),\n # ...\n )\n\nWith that bit of configuration out of the way, now you can see the Django\nadmin site in action. Just run the development server\n(``python manage.py runserver``, as in previous chapters) and visit\n``http://127.0.0.1:8000/admin/`` in your Web browser.\n\nUsing the Admin Site\n====================\n\nThe admin site is designed to be used by nontechnical users, and as such it\nshould be pretty self-explanatory. Nevertheless, we'll give you a quick\nwalkthrough of the basic features.\n\nThe first thing you'll see is a login screen, as shown in Figure 6-1.\n\n.. figure:: graphics/chapter06/login.png\n :alt: Screenshot of Django's login page.\n\n Figure 6-1. Django's login screen\n\nLog in with the username and password you set up when you added your superuser.\nIf you're unable to log in, make sure you've actually created a superuser --\ntry running ``python manage.py createsuperuser``.\n\nOnce you're logged in, the first thing you'll see will be the admin home page.\nThis page lists all the available types of data that can be edited on the admin\nsite. At this point, because we haven't activated any of our own models yet,\nthe list is sparse: it includes only Groups and Users, which are the two\ndefault admin-editable models.\n\n.. DWP The screenshot contains books etc too.\n\n.. figure:: graphics/chapter06/admin_index.png\n :alt: Screenshot of the Django admin home page.\n\n Figure 6-2. The Django admin home page\n\nEach type of data in the Django admin site has a *change list* and an\n*edit form*. Change lists show you all the available objects in the database,\nand edit forms let you add, change or delete particular records in your\ndatabase.\n\n.. admonition:: Other languages\n\n If your primary language is not English and your Web browser is configured\n to prefer a language other than English, you can make a quick change to\n see whether the Django admin site has been translated into your language.\n Just add ``'django.middleware.locale.LocaleMiddleware'`` to your\n ``MIDDLEWARE_CLASSES`` setting, making sure it appears *after*\n ``'django.contrib.sessions.middleware.SessionMiddleware'``.\n\n When you've done that, reload the admin index page. If a translation for\n your language is available, then the various parts of the interface -- from\n the \"Change password\" and \"Log out\" links at the top of the page, to the\n \"Groups\" and \"Users\" links in the middle -- will appear in your language\n instead of English. Django ships with translations for dozens of languages.\n\n For much more on Django's internationalization features, see Chapter 19.\n\nClick the \"Change\" link in the \"Users\" row to load the change list page for\nusers.\n\n.. figure:: graphics/chapter06/user_changelist.png\n :alt: Screenshot of the user change list page.\n\n Figure 6-3. The user change list page\n\n.. DWP This screenshot is actually the list for books.\n\nThis page displays all users in the database; you can think of it as a\nprettied-up Web version of a ``SELECT * FROM auth_user;`` SQL query. If you're\nfollowing along with our ongoing example, you'll only see one user here,\nassuming you've added only one, but once you have more users, you'll probably\nfind the filtering, sorting and searching options useful. Filtering options are\nat right, sorting is available by clicking a column header, and the search box\nat the top lets you search by username.\n\nClick the username of the user you created, and you'll see the edit form for\nthat user.\n\n.. figure:: graphics/chapter06/user_editform.png\n :alt: Screenshot of the user edit form\n\n Figure 6-4. The user edit form\n\n.. DWP The edit form screenshot is for a book.\n\nThis page lets you change the attributes of the user, like the\nfirst/last names and various permissions. (Note that to change a user's\npassword, you should click \"change password form\" under the password field\nrather than editing the hashed code.) Another thing to note here is that fields\nof different types get different widgets -- for example, date/time fields have\ncalendar controls, boolean fields have checkboxes, character fields have simple\ntext input fields.\n\nYou can delete a record by clicking the delete button at the bottom left of its\nedit form. That'll take you to a confirmation page, which, in some cases, will\ndisplay any dependent objects that will be deleted, too. (For example, if you\ndelete a publisher, any book with that publisher will be deleted, too!)\n\nYou can add a record by clicking \"Add\" in the appropriate column of the admin\nhome page. This will give you an empty version of the edit page, ready for you\nto fill out.\n\nYou'll also notice that the admin interface also handles input validation for\nyou. Try leaving a required field blank or putting an invalid date into a date\nfield, and you'll see those errors when you try to save, as shown in Figure 6-5.\n\n.. figure:: graphics/chapter06/user_editform_errors.png\n :alt: Screenshot of an edit form displaying errors.\n\n Figure 6-5. An edit form displaying errors\n\n.. DWP The screenshots are still following a book example.\n\nWhen you edit an existing object, you'll notice a History link in the\nupper-right corner of the window. Every change made through the admin interface\nis logged, and you can examine this log by clicking the History link (see\nFigure 6-6).\n\n.. figure:: graphics/chapter06/user_history.png\n :alt: Screenshot of an object history page.\n\n Figure 6-6. An object history page\n\n.. DWP Still using a book in the pictures.\n\nAdding Your Models to the Admin Site\n====================================\n\nThere's one crucial part we haven't done yet. Let's add our own models to the\nadmin site, so we can add, change and delete objects in our custom database\ntables using this nice interface. We'll continue the ``books`` example from\nChapter 5, where we defined three models: ``Publisher``, ``Author`` and\n``Book``.\n\nWithin the ``books`` directory (``mysite/books``), create a file called\n``admin.py``, and type in the following lines of code::\n\n from django.contrib import admin\n from mysite.books.models import Publisher, Author, Book\n\n admin.site.register(Publisher)\n admin.site.register(Author)\n admin.site.register(Book)\n\nThis code tells the Django admin site to offer an interface for each of these\nmodels.\n\nOnce you've done this, go to your admin home page in your Web browser\n(``http://127.0.0.1:8000/admin/``), and you should see a \"Books\" section with\nlinks for Authors, Books and Publishers. (You might have to stop and start the\n``runserver`` for the changes to take effect.)\n\n.. SL Tested ok\n\nYou now have a fully functional admin interface for each of those three models.\nThat was easy!\n\nTake some time to add and change records, to populate your database with some\ndata. If you followed Chapter 5's examples of creating ``Publisher`` objects\n(and you didn't delete them), you'll already see those records on the publisher\nchange list page.\n\nOne feature worth mentioning here is the admin site's handling of foreign keys\nand many-to-many relationships, both of which appear in the ``Book`` model. As\na reminder, here's what the ``Book`` model looks like::\n\n class Book(models.Model):\n title = models.CharField(max_length=100)\n authors = models.ManyToManyField(Author)\n publisher = models.ForeignKey(Publisher)\n publication_date = models.DateField()\n\n def __unicode__(self):\n return self.title\n\nOn the Django admin site's \"Add book\" page\n(``http://127.0.0.1:8000/admin/books/book/add/``), the publisher (a\n``ForeignKey``) is represented by a select box, and the authors field\n(a ``ManyToManyField``) is represented by a multiple-select box. Both fields\nsit next to a green plus sign icon that lets you add related records of that\ntype. For example, if you click the green plus sign next to the \"Publisher\"\nfield, you'll get a pop-up window that lets you add a publisher. After you\nsuccessfully create the publisher in the pop-up, the \"Add book\" form will be\nupdated with the newly created publisher. Slick.\n\nHow the Admin Site Works\n========================\n\nBehind the scenes, how does the admin site work? It's pretty straightforward.\n\nWhen Django loads your URLconf from ``urls.py`` at server startup, it executes\nthe ``admin.autodiscover()`` statement that we added as part of activating the\nadmin. This function iterates over your ``INSTALLED_APPS`` setting and looks\nfor a file called ``admin.py`` in each installed app. If an ``admin.py``\nexists in a given app, it executes the code in that file.\n\nIn the ``admin.py`` in our ``books`` app, each call to\n``admin.site.register()`` simply registers the given model with the admin. The\nadmin site will only display an edit/change interface for models that have been\nexplicitly registered.\n\nThe app ``django.contrib.auth`` includes its own ``admin.py``, which is why\nUsers and Groups showed up automatically in the admin. Other ``django.contrib``\napps, such as ``django.contrib.redirects``, also add themselves to the admin,\nas do many third-party Django applications you might download from the Web.\n\nBeyond that, the Django admin site is just a Django application, with its own\nmodels, templates, views and URLpatterns. You add it to your application by\nhooking it into your URLconf, just as you hook in your own views. You can\ninspect its templates, views and URLpatterns by poking around in\n``django/contrib/admin`` in your copy of the Django codebase -- but don't be\ntempted to change anything directly in there, as there are plenty of hooks for\nyou to customize the way the admin site works. (If you do decide to poke around\nthe Django admin application, keep in mind it does some rather complicated\nthings in reading metadata about models, so it would probably take a good\namount of time to read and understand the code.)\n\nMaking Fields Optional\n======================\n\nAfter you play around with the admin site for a while, you'll probably notice a\nlimitation -- the edit forms require every field to be filled out, whereas in\nmany cases you'd want certain fields to be optional. Let's say, for example,\nthat we want our ``Author`` model's ``email`` field to be optional -- that is,\na blank string should be allowed. In the real world, you might not have an\ne-mail address on file for every author.\n\nTo specify that the ``email`` field is optional, edit the ``Author`` model\n(which, as you'll recall from Chapter 5, lives in ``mysite/books/models.py``).\nSimply add ``blank=True`` to the ``email`` field, like so:\n\n.. parsed-literal::\n\n class Author(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=40)\n email = models.EmailField(**blank=True**)\n\n.. SL Tested ok\n\nThis tells Django that a blank value is indeed allowed for authors' e-mail\naddresses. By default, all fields have ``blank=False``, which means blank\nvalues are not allowed.\n\nThere's something interesting happening here. Until now, with the exception of\nthe ``__unicode__()`` method, our models have served as definitions of our\ndatabase tables -- Pythonic expressions of SQL ``CREATE TABLE`` statements,\nessentially. In adding ``blank=True``, we have begun expanding our model beyond\na simple definition of what the database table looks like. Now, our model class\nis starting to become a richer collection of knowledge about what ``Author``\nobjects are and what they can do. Not only is the ``email`` field represented\nby a ``VARCHAR`` column in the database; it's also an optional field in\ncontexts such as the Django admin site.\n\nOnce you've added that ``blank=True``, reload the \"Add author\" edit form\n(``http://127.0.0.1:8000/admin/books/author/add/``), and you'll notice the\nfield's label -- \"Email\" -- is no longer bolded. This signifies it's not a\nrequired field. You can now add authors without needing to provide\ne-mail addresses; you won't get the loud red \"This field is required\" message\nanymore, if the field is submitted empty.\n\nMaking Date and Numeric Fields Optional\n---------------------------------------\n\nA common gotcha related to ``blank=True`` has to do with date and numeric\nfields, but it requires a fair amount of background explanation.\n\nSQL has its own way of specifying blank values -- a special value called\n``NULL``. ``NULL`` could mean \"unknown,\" or \"invalid,\" or some other\napplication-specific meaning.\n\nIn SQL, a value of ``NULL`` is different than an empty string, just as the\nspecial Python object ``None`` is different than an empty Python string\n(``\"\"``). This means it's possible for a particular character field (e.g., a\n``VARCHAR`` column) to contain both ``NULL`` values and empty string values.\n\nThis can cause unwanted ambiguity and confusion: \"Why does this record have a\n``NULL`` but this other one has an empty string? Is there a difference, or was\nthe data just entered inconsistently?\" And: \"How do I get all the records that\nhave a blank value -- should I look for both ``NULL`` records and empty\nstrings, or do I only select the ones with empty strings?\"\n\nTo help avoid such ambiguity, Django's automatically generated ``CREATE TABLE``\nstatements (which were covered in Chapter 5) add an explicit ``NOT NULL`` to\neach column definition. For example, here's the generated statement for our\n``Author`` model, from Chapter 5::\n\n CREATE TABLE \"books_author\" (\n \"id\" serial NOT NULL PRIMARY KEY,\n \"first_name\" varchar(30) NOT NULL,\n \"last_name\" varchar(40) NOT NULL,\n \"email\" varchar(75) NOT NULL\n )\n ;\n\nIn most cases, this default behavior is optimal for your application and will\nsave you from data-inconsistency headaches. And it works nicely with the rest\nof Django, such as the Django admin site, which inserts an empty string (*not*\na ``NULL`` value) when you leave a character field blank.\n\nBut there's an exception with database column types that do not accept empty\nstrings as valid values -- such as dates, times and numbers. If you try to\ninsert an empty string into a date or integer column, you'll likely get a\ndatabase error, depending on which database you're using. (PostgreSQL, which is\nstrict, will raise an exception here; MySQL might accept it or might not,\ndepending on the version you're using, the time of day and the phase of the\nmoon.) In this case, ``NULL`` is the only way to specify an empty\nvalue. In Django models, you can specify that ``NULL`` is allowed by adding\n``null=True`` to a field.\n\nSo that's a long way of saying this: if you want to allow blank values in a\ndate field (e.g., ``DateField``, ``TimeField``, ``DateTimeField``) or numeric\nfield (e.g., ``IntegerField``, ``DecimalField``, ``FloatField``), you'll need\nto use both ``null=True`` *and* ``blank=True``.\n\nFor sake of example, let's change our ``Book`` model to allow a blank\n``publication_date``. Here's the revised code:\n\n.. parsed-literal::\n\n class Book(models.Model):\n title = models.CharField(max_length=100)\n authors = models.ManyToManyField(Author)\n publisher = models.ForeignKey(Publisher)\n publication_date = models.DateField(**blank=True, null=True**)\n\n.. SL Tested ok\n\nAdding ``null=True`` is more complicated than adding ``blank=True``, because\n``null=True`` changes the semantics of the database -- that is, it changes the\n``CREATE TABLE`` statement to remove the ``NOT NULL`` from the\n``publication_date`` field. To complete this change, we'll need to update the\ndatabase.\n\nFor a number of reasons, Django does not attempt to automate changes to\ndatabase schemas, so it's your own responsibility to execute the appropriate\n``ALTER TABLE`` statement whenever you make such a change to a model. Recall\nthat you can use ``manage.py dbshell`` to enter your database server's shell.\nHere's how to remove the ``NOT NULL`` in this particular case::\n\n ALTER TABLE books_book ALTER COLUMN publication_date DROP NOT NULL;\n\n(Note that this SQL syntax is specific to PostgreSQL.)\n\nWe'll cover schema changes in more depth in Chapter 10.\n\nBringing this back to the admin site, now the \"Add book\" edit form should allow\nfor empty publication date values.\n\nCustomizing Field Labels\n========================\n\nOn the admin site's edit forms, each field's label is generated from its model\nfield name. The algorithm is simple: Django just replaces underscores with\nspaces and capitalizes the first character, so, for example, the ``Book``\nmodel's ``publication_date`` field has the label \"Publication date.\"\n\nHowever, field names don't always lend themselves to nice admin field labels,\nso in some cases you might want to customize a label. You can do this by\nspecifying ``verbose_name`` in the appropriate model field.\n\nFor example, here's how we can change the label of the ``Author.email`` field\nto \"e-mail,\" with a hyphen:\n\n.. parsed-literal::\n\n class Author(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=40)\n email = models.EmailField(blank=True, **verbose_name='e-mail'**)\n\nMake that change and reload the server, and you should see the field's new\nlabel on the author edit form.\n\nNote that you shouldn't capitalize the first letter of a ``verbose_name``\nunless it should *always* be capitalized (e.g., ``\"USA state\"``). Django will\nautomatically capitalize it when it needs to, and it will use the exact\n``verbose_name`` value in other places that don't require capitalization.\n\nFinally, note that you can pass the ``verbose_name`` as a positional argument,\nfor a slightly more compact syntax. This example is equivalent to the previous\none:\n\n.. parsed-literal::\n\n class Author(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=40)\n email = models.EmailField(**'e-mail',** blank=True)\n\n.. SL Tested ok\n\nThis won't work with ``ManyToManyField`` or ``ForeignKey`` fields, though,\nbecause they require the first argument to be a model class. In those cases,\nspecifying ``verbose_name`` explicitly is the way to go.\n\nCustom ModelAdmin classes\n=========================\n\nThe changes we've made so far -- ``blank=True``, ``null=True`` and\n``verbose_name`` -- are really model-level changes, not admin-level changes.\nThat is, these changes are fundamentally a part of the model and just so happen\nto be used by the admin site; there's nothing admin-specific about them.\n\nBeyond these, the Django admin site offers a wealth of options that let you\ncustomize how the admin site works for a particular model. Such options live in\n*ModelAdmin classes*, which are classes that contain configuration for a\nspecific model in a specific admin site instance.\n\nCustomizing change lists\n------------------------\n\nLet's dive into admin customization by specifying the fields that are\ndisplayed on the change list for our ``Author`` model. By default, the change\nlist displays the result of ``__unicode__()`` for each object. In Chapter 5, we\ndefined the ``__unicode__()`` method for ``Author`` objects to display the\nfirst name and last name together:\n\n.. parsed-literal::\n\n class Author(models.Model):\n first_name = models.CharField(max_length=30)\n last_name = models.CharField(max_length=40)\n email = models.EmailField(blank=True, verbose_name='e-mail')\n\n **def __unicode__(self):**\n **return u'%s %s' % (self.first_name, self.last_name)**\n\nAs a result, the change list for ``Author`` objects displays each other's\nfirst name and last name together, as you can see in Figure 6-7.\n\n.. DWP The image is of the change list for a book, not an author.\n\n.. figure:: graphics/chapter06/author_changelist1.png\n :alt: Screenshot of the author change list page.\n\n Figure 6-7. The author change list page\n\nWe can improve on this default behavior by adding a few other fields to the\nchange list display. It'd be handy, for example, to see each author's e-mail\naddress in this list, and it'd be nice to be able to sort by first and last\nname.\n\nTo make this happen, we'll define a ``ModelAdmin`` class for the ``Author``\nmodel. This class is the key to customizing the admin, and one of the most\nbasic things it lets you do is specify the list of fields to display on change\nlist pages. Edit ``admin.py`` to make these changes:\n\n.. parsed-literal::\n\n from django.contrib import admin\n from mysite.books.models import Publisher, Author, Book\n\n **class AuthorAdmin(admin.ModelAdmin):**\n **list_display = ('first_name', 'last_name', 'email')**\n\n admin.site.register(Publisher)\n **admin.site.register(Author, AuthorAdmin)**\n admin.site.register(Book)\n\n.. SL Tested ok\n\nHere's what we've done:\n\n* We created the class ``AuthorAdmin``. This class, which subclasses\n ``django.contrib.admin.ModelAdmin``, holds custom configuration\n for a specific admin model. We've only specified one customization --\n ``list_display``, which is set to a tuple of field names to display on\n the change list page. These field names must exist in the model, of\n course.\n\n* We altered the ``admin.site.register()`` call to add ``AuthorAdmin`` after\n ``Author``. You can read this as: \"Register the ``Author`` model with the\n ``AuthorAdmin`` options.\"\n\n The ``admin.site.register()`` function takes a ``ModelAdmin`` subclass as\n an optional second argument. If you don't specify a second argument (as\n is the case for ``Publisher`` and ``Book``), Django will use the default\n admin options for that model.\n\nWith that tweak made, reload the author change list page, and you'll see it's\nnow displaying three columns -- the first name, last name and e-mail address.\nIn addition, each of those columns is sortable by clicking on the column\nheader. (See Figure 6-8.)\n\n.. figure:: graphics/chapter06/author_changelist2.png\n :alt: Screenshot of the author change list page after list_display.\n\n Figure 6-8. The author change list page after list_display\n\n.. DWP This figure has the same filename as the last one.\n\nNext, let's add a simple search bar. Add ``search_fields`` to the\n``AuthorAdmin``, like so:\n\n.. parsed-literal::\n\n class AuthorAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name', 'email')\n **search_fields = ('first_name', 'last_name')**\n\n.. SL Tested ok\n\nReload the page in your browser, and you should see a search bar at the top.\n(See Figure 6-9.) We've just told the admin change list page to include a\nsearch bar that searches against the ``first_name`` and ``last_name`` fields.\nAs a user might expect, this is case-insensitive and searches both fields, so\nsearching for the string ``\"bar\"`` would find both an author with the first\nname Barney and an author with the last name Hobarson.\n\n.. DWP Again, same screenshot.\n\n.. figure:: graphics/chapter06/author_changelist3.png\n :alt: Screenshot of the author change list page after search_fields.\n\n Figure 6-9. The author change list page after search_fields\n\nNext, let's add some date filters to our ``Book`` model's change list page:\n\n.. parsed-literal::\n\n from django.contrib import admin\n from mysite.books.models import Publisher, Author, Book\n\n class AuthorAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name', 'email')\n search_fields = ('first_name', 'last_name')\n\n **class BookAdmin(admin.ModelAdmin):**\n **list_display = ('title', 'publisher', 'publication_date')**\n **list_filter = ('publication_date',)**\n\n admin.site.register(Publisher)\n admin.site.register(Author, AuthorAdmin)\n **admin.site.register(Book, BookAdmin)**\n\n.. SL Tested ok\n\nHere, because we're dealing with a different set of options, we created a\nseparate ``ModelAdmin`` class -- ``BookAdmin``. First, we defined a\n``list_display`` just to make the change list look a bit nicer. Then, we\nused ``list_filter``, which is set to a tuple of fields to use to create\nfilters along the right side of the change list page. For date fields, Django\nprovides shortcuts to filter the list to \"Today,\" \"Past 7 days,\" \"This month\"\nand \"This year\" -- shortcuts that Django's developers have found hit the\ncommon cases for filtering by date. Figure 6-10 shows what that looks like.\n\n.. DWP Screenshot needs changing.\n\n.. figure:: graphics/chapter06/book_changelist1.png\n :alt: Screenshot of the book change list page after list_filter.\n\n Figure 6-10. The book change list page after list_filter\n\n``list_filter`` also works on fields of other types, not just ``DateField``.\n(Try it with ``BooleanField`` and ``ForeignKey`` fields, for example.) The\nfilters show up as long as there are at least 2 values to choose from.\n\nAnother way to offer date filters is to use the ``date_hierarchy`` admin\noption, like this:\n\n.. parsed-literal::\n\n class BookAdmin(admin.ModelAdmin):\n list_display = ('title', 'publisher', 'publication_date')\n list_filter = ('publication_date',)\n **date_hierarchy = 'publication_date'**\n\n.. SL Tested ok\n\nWith this in place, the change list page gets a date drill-down navigation bar\nat the top of the list, as shown in Figure 6-11. It starts with a list of\navailable years, then drills down into months and individual days.\n\n.. DWP Screenshot again.\n\n.. figure:: graphics/chapter06/book_changelist2.png\n :alt: Screenshot of the book change list page after date_hierarchy.\n\n Figure 6-11. The book change list page after date_hierarchy\n\nNote that ``date_hierarchy`` takes a *string*, not a tuple, because only one\ndate field can be used to make the hierarchy.\n\nFinally, let's change the default ordering so that books on the change list\npage are always ordered descending by their publication date. By default,\nthe change list orders objects according to their model's ``ordering`` within\n``class Meta`` (which we covered in Chapter 5) -- but you haven't specified\nthis ``ordering`` value, then the ordering is undefined.\n\n.. parsed-literal::\n\n class BookAdmin(admin.ModelAdmin):\n list_display = ('title', 'publisher', 'publication_date')\n list_filter = ('publication_date',)\n date_hierarchy = 'publication_date'\n **ordering = ('-publication_date',)**\n\n.. SL Tested ok\n\nThis admin ``ordering`` option works exactly as the ``ordering`` in models'\n``class Meta``, except that it only uses the first field name in the list. Just\npass a list or tuple of field names, and add a minus sign to a field to use\ndescending sort order.\n\nReload the book change list to see this in action. Note that the\n\"Publication date\" header now includes a small arrow that indicates which way\nthe records are sorted. (See Figure 6-12.)\n\n.. DWP Different screenshot needed.\n\n.. figure:: graphics/chapter06/book_changelist3.png\n :alt: Screenshot of the book change list page after ordering.\n\n Figure 6-12. The book change list page after ordering\n\nWe've covered the main change list options here. Using these options, you can\nmake a very powerful, production-ready data-editing interface with only a few\nlines of code.\n\nCustomizing edit forms\n----------------------\n\nJust as the change list can be customized, edit forms can be customized in many\nways.\n\nFirst, let's customize the way fields are ordered. By default, the order of\nfields in an edit form corresponds to the order they're defined in the model.\nWe can change that using the ``fields`` option in our ``ModelAdmin`` subclass:\n\n.. parsed-literal::\n\n class BookAdmin(admin.ModelAdmin):\n list_display = ('title', 'publisher', 'publication_date')\n list_filter = ('publication_date',)\n date_hierarchy = 'publication_date'\n ordering = ('-publication_date',)\n **fields = ('title', 'authors', 'publisher', 'publication_date')**\n\n.. SL Tested ok\n\nAfter this change, the edit form for books will use the given ordering for\nfields. It's slightly more natural to have the authors after the book title.\nOf course, the field order should depend on your data-entry workflow. Every\nform is different.\n\nAnother useful thing the ``fields`` option lets you do is to *exclude* certain\nfields from being edited entirely. Just leave out the field(s) you want to\nexclude. You might use this if your admin users are only trusted to edit a\ncertain segment of your data, or if part of your fields are changed by some\noutside, automated process. For example, in our book database, we could\nhide the ``publication_date`` field from being editable:\n\n.. parsed-literal::\n\n class BookAdmin(admin.ModelAdmin):\n list_display = ('title', 'publisher', 'publication_date')\n list_filter = ('publication_date',)\n date_hierarchy = 'publication_date'\n ordering = ('-publication_date',)\n **fields = ('title', 'authors', 'publisher')**\n\n.. SL Tested ok\n\nAs a result, the edit form for books doesn't offer a way to specify the\npublication date. This could be useful, say, if you're an editor who prefers\nthat his authors not push back publication dates. (This is purely a\nhypothetical example, of course.)\n\nWhen a user uses this incomplete form to add a new book, Django will simply set\nthe ``publication_date`` to ``None`` -- so make sure that field has\n``null=True``.\n\nAnother commonly used edit-form customization has to do with many-to-many\nfields. As we've seen on the edit form for books, the admin site represents each\n``ManyToManyField`` as a multiple-select boxes, which is the most logical\nHTML input widget to use -- but multiple-select boxes can be difficult to use.\nIf you want to select multiple items, you have to hold down the control key,\nor command on a Mac, to do so. The admin site helpfully inserts a bit of text\nthat explains this, but, still, it gets unwieldy when your field contains\nhundreds of options.\n\nThe admin site's solution is ``filter_horizontal``. Let's add that to\n``BookAdmin`` and see what it does.\n\n.. parsed-literal::\n\n class BookAdmin(admin.ModelAdmin):\n list_display = ('title', 'publisher', 'publication_date')\n list_filter = ('publication_date',)\n date_hierarchy = 'publication_date'\n ordering = ('-publication_date',)\n **filter_horizontal = ('authors',)**\n\n.. SL Tested ok\n\n(If you're following along, note that we've also removed the ``fields`` option\nto restore all the fields in the edit form.)\n\nReload the edit form for books, and you'll see that the \"Authors\" section now\nuses a fancy JavaScript filter interface that lets you search through the\noptions dynamically and move specific authors from \"Available authors\" to\nthe \"Chosen authors\" box, and vice versa.\n\n.. DWP screenshot!\n\n.. figure:: graphics/chapter06/book_editform1.png\n :alt: Screenshot of the book edit form after adding filter_horizontal.\n\n Figure 6-13. The book edit form after adding filter_horizontal\n\nWe'd highly recommend using ``filter_horizontal`` for any ``ManyToManyField``\nthat has more than 10 items. It's far easier to use than a simple\nmultiple-select widget. Also, note you can use ``filter_horizontal``\nfor multiple fields -- just specify each name in the tuple.\n\n``ModelAdmin`` classes also support a ``filter_vertical`` option. This works\nexactly as ``filter_horizontal``, but the resulting JavaScript interface stacks\nthe two boxes vertically instead of horizontally. It's a matter of personal\ntaste.\n\n``filter_horizontal`` and ``filter_vertical`` only work on ``ManyToManyField``\nfields, not ``ForeignKey`` fields. By default, the admin site uses simple\n```` box.\n\nThe way to fix this is to use an option called ``raw_id_fields``. Set this to\na tuple of ``ForeignKey`` field names, and those fields will be displayed in\nthe admin with a simple text input box (````) instead of a\n``\n \n \n \n \n\nThe URLpattern in ``urls.py`` could look like this::\n\n from mysite.books import views\n\n urlpatterns = patterns('',\n # ...\n (r'^search-form/$', views.search_form),\n # ...\n )\n\n(Note that we're importing the ``views`` module directly, instead of something\nlike ``from mysite.views import search_form``, because the former is less\nverbose. We'll cover this importing approach in more detail in Chapter 8.)\n\nNow, if you run the ``runserver`` and visit\n``http://127.0.0.1:8000/search-form/``, you'll see the search interface. Simple\nenough.\n\n.. SL Tested ok\n\nTry submitting the form, though, and you'll get a Django 404 error. The form\npoints to the URL ``/search/``, which hasn't yet been implemented. Let's fix\nthat with a second view function::\n\n # urls.py\n\n urlpatterns = patterns('',\n # ...\n (r'^search-form/$', views.search_form),\n (r'^search/$', views.search),\n # ...\n )\n\n # views.py\n\n def search(request):\n if 'q' in request.GET:\n message = 'You searched for: %r' % request.GET['q']\n else:\n message = 'You submitted an empty form.'\n return HttpResponse(message)\n\n.. SL Tested ok\n\nFor the moment, this merely displays the user's search term, so we can make\nsure the data is being submitted to Django properly, and so you can get a feel\nfor how the search term flows through the system. In short:\n\n1. The HTML ``
    `` defines a variable ``q``. When it's submitted, the\n value of ``q`` is sent via ``GET`` (``method=\"get\"``) to the URL\n ``/search/``.\n\n2. The Django view that handles the URL ``/search/`` (``search()``) has\n access to the ``q`` value in ``request.GET``.\n\nAn important thing to point out here is that we explicitly check that ``'q'``\nexists in ``request.GET``. As we pointed out in the ``request.META`` section\nabove, you shouldn't trust anything submitted by users or even assume that\nthey've submitted anything in the first place. If we didn't add this check, any\nsubmission of an empty form would raise ``KeyError`` in the view::\n\n # BAD!\n def bad_search(request):\n # The following line will raise KeyError if 'q' hasn't\n # been submitted!\n message = 'You searched for: %r' % request.GET['q']\n return HttpResponse(message)\n\n.. SL Tested ok\n\n.. admonition:: Query string parameters\n\n Because ``GET`` data is passed in the query string (e.g.,\n ``/search/?q=django``), you can use ``request.GET`` to access query string\n variables. In Chapter 3's introduction of Django's URLconf system, we\n compared Django's pretty URLs to more traditional PHP/Java URLs such as\n ``/time/plus?hours=3`` and said we'd show you how to do the latter in\n Chapter 7. Now you know how to access query string parameters in your\n views (like ``hours=3`` in this example) -- use ``request.GET``.\n\n``POST`` data works the same way as ``GET`` data -- just use ``request.POST``\ninstead of ``request.GET``. What's the difference between ``GET`` and ``POST``?\nUse ``GET`` when the act of submitting the form is just a request to \"get\"\ndata. Use ``POST`` whenever the act of submitting the form will have some side\neffect -- *changing* data, or sending an e-mail, or something else that's\nbeyond simple *display* of data. In our book-search example, we're using\n``GET`` because the query doesn't change any data on our server. (See\nhttp://www.w3.org/2001/tag/doc/whenToUseGet.html if you want to learn more\nabout ``GET`` and ``POST``.)\n\nNow that we've verified ``request.GET`` is being passed in properly, let's hook\nthe user's search query into our book database (again, in ``views.py``)::\n\n from django.http import HttpResponse\n from django.shortcuts import render\n from mysite.books.models import Book\n\n def search(request):\n if 'q' in request.GET and request.GET['q']:\n q = request.GET['q']\n books = Book.objects.filter(title__icontains=q)\n return render(request, 'search_results.html',\n {'books': books, 'query': q})\n else:\n return HttpResponse('Please submit a search term.')\n\nA couple of notes on what we did here:\n\n* Aside from checking that ``'q'`` exists in ``request.GET``, we also make\n sure that ``request.GET['q']`` is a non-empty value before passing it to\n the database query.\n\n* We're using ``Book.objects.filter(title__icontains=q)`` to query our\n book table for all books whose title includes the given submission. The\n ``icontains`` is a lookup type (as explained in Chapter 5 and Appendix\n B), and the statement can be roughly translated as \"Get the books whose\n title contains ``q``, without being case-sensitive.\"\n\n This is a very simple way to do a book search. We wouldn't recommend\n using a simple ``icontains`` query on a large production database, as\n it can be slow. (In the real world, you'd want to use a custom search\n system of some sort. Search the Web for *open-source full-text search*\n to get an idea of the possibilities.)\n\n* We pass ``books``, a list of ``Book`` objects, to the template. The\n template code for ``search_results.html`` might include something like\n this::\n\n

    You searched for: {{ query }}

    \n\n {% if books %}\n

    Found {{ books|length }} book{{ books|pluralize }}.

    \n
      \n {% for book in books %}\n
    • {{ book.title }}
      • \n {% endfor %}\n
    \n {% else %}\n

    No books matched your search criteria.

    \n {% endif %}\n\n Note usage of the ``pluralize`` template filter, which outputs an \"s\"\n if appropriate, based on the number of books found.\n\n.. SL Tested ok\n\nImproving Our Simple Form-Handling Example\n==========================================\n\nAs in previous chapters, we've shown you the simplest thing that could possibly\nwork. Now we'll point out some problems and show you how to improve it.\n\nFirst, our ``search()`` view's handling of an empty query is poor -- we're just\ndisplaying a ``\"Please submit a search term.\"`` message, requiring the user to\nhit the browser's back button. This is horrid and unprofessional, and if you\never actually implement something like this in the wild, your Django privileges\nwill be revoked.\n\nIt would be much better to redisplay the form, with an error above it, so that\nthe user can try again immediately. The easiest way to do that would be to\nrender the template again, like this:\n\n.. parsed-literal::\n\n from django.http import HttpResponse\n from django.shortcuts import render\n from mysite.books.models import Book\n\n def search_form(request):\n return render(request, 'search_form.html')\n\n def search(request):\n if 'q' in request.GET and request.GET['q']:\n q = request.GET['q']\n books = Book.objects.filter(title__icontains=q)\n return render(request, 'search_results.html',\n {'books': books, 'query': q})\n else:\n **return render(request, 'search_form.html', {'error': True})**\n\n(Note that we've included ``search_form()`` here so you can see both views in\none place.)\n\nHere, we've improved ``search()`` to render the ``search_form.html`` template\nagain, if the query is empty. And because we need to display an error message\nin that template, we pass a template variable. Now we can edit\n``search_form.html`` to check for the ``error`` variable:\n\n.. parsed-literal::\n\n \n \n Search\n \n \n **{% if error %}**\n **

    Please submit a search term.

    **\n **{% endif %}**\n \n \n \n
    \n \n \n\n.. SL Tested ok\n\nWe can still use this template from our original view, ``search_form()``,\nbecause ``search_form()`` doesn't pass ``error`` to the template -- so the\nerror message won't show up in that case.\n\nWith this change in place, it's a better application, but it now begs the\nquestion: is a dedicated ``search_form()`` view really necessary? As it stands,\na request to the URL ``/search/`` (without any ``GET`` parameters) will display\nthe empty form (but with an error). We can remove the ``search_form()`` view,\nalong with its associated URLpattern, as long as we change ``search()`` to\nhide the error message when somebody visits ``/search/`` with no ``GET``\nparameters::\n\n def search(request):\n error = False\n if 'q' in request.GET:\n q = request.GET['q']\n if not q:\n error = True\n else:\n books = Book.objects.filter(title__icontains=q)\n return render(request, 'search_results.html',\n {'books': books, 'query': q})\n return render(request, 'search_form.html',\n {'error': error})\n\n.. SL Tested ok\n\nIn this updated view, if a user visits ``/search/`` with no ``GET`` parameters,\nhe'll see the search form with no error message. If a user submits the form\nwith an empty value for ``'q'``, he'll see the search form *with* an error\nmessage. And, finally, if a user submits the form with a non-empty value for\n``'q'``, he'll see the search results.\n\nWe can make one final improvement to this application, to remove a bit of\nredundancy. Now that we've rolled the two views and URLs into one and\n``/search/`` handles both search-form display and result display, the HTML\n``
    `` in ``search_form.html`` doesn't have to hard-code a URL. Instead\nof this::\n\n \n\nIt can be changed to this::\n\n \n\nThe ``action=\"\"`` means \"Submit the form to the same URL as the current page.\"\nWith this change in place, you won't have to remember to change the ``action``\nif you ever hook the ``search()`` view to another URL.\n\nSimple validation\n=================\n\nOur search example is still reasonably simple, particularly in terms of its\ndata validation; we're merely checking to make sure the search query isn't\nempty. Many HTML forms include a level of validation that's more complex than\nmaking sure the value is non-empty. We've all seen the error messages on Web\nsites:\n\n* \"Please enter a valid e-mail address. 'foo' is not an e-mail address.\"\n* \"Please enter a valid five-digit U.S. ZIP code. '123' is not a ZIP code.\"\n* \"Please enter a valid date in the format YYYY-MM-DD.\"\n* \"Please enter a password that is at least 8 characters long and contains\n at least one number.\"\n\n.. admonition:: A note on JavaScript validation\n\n This is beyond the scope of this book, but you can use JavaScript to\n validate data on the client side, directly in the browser. But be warned:\n even if you do this, you *must* validate data on the server side, too. Some\n people have JavaScript turned off, and some malicious users might submit\n raw, unvalidated data directly to your form handler to see whether they can\n cause mischief.\n\n There's nothing you can do about this, other than *always* validate\n user-submitted data server-side (i.e., in your Django views). You should\n think of JavaScript validation as a bonus usability feature, not as your\n only means of validating.\n\nLet's tweak our ``search()`` view so that it validates that the search term is\nless than or equal to 20 characters long. (For sake of example, let's say\nanything longer than that might make the query too slow.) How might we do that?\nThe simplest possible thing would be to embed the logic directly in the view,\nlike this:\n\n.. parsed-literal::\n\n def search(request):\n error = False\n if 'q' in request.GET:\n q = request.GET['q']\n if not q:\n error = True\n **elif len(q) > 20:**\n **error = True**\n else:\n books = Book.objects.filter(title__icontains=q)\n return render(request, 'search_results.html',\n {'books': books, 'query': q})\n return render(request, 'search_form.html',\n {'error': error})\n\nNow, if you try submitting a search query greater than 20 characters long,\nit won't let you search; you'll get an error message. But that error message\nin ``search_form.html`` currently says ``\"Please submit a search term.\"`` --\nso we'll have to change it to be accurate for both cases:\n\n.. parsed-literal::\n\n \n \n Search\n \n \n {% if error %}\n

    Please submit a search term 20 characters or shorter.

    \n {% endif %}\n \n \n \n
    \n \n \n\n.. SL Tested ok\n\nThere's something ugly about this. Our one-size-fits-all error message is\npotentially confusing. Why should the error message for an empty form\nsubmission mention anything about a 20-character limit? Error messages should\nbe specific, unambiguous and not confusing.\n\nThe problem is in the fact that we're using a simple boolean value for\n``error``, whereas we should be using a *list* of error message strings. Here's\nhow we might fix that:\n\n.. parsed-literal::\n\n def search(request):\n **errors = []**\n if 'q' in request.GET:\n q = request.GET['q']\n if not q:\n **errors.append('Enter a search term.')**\n elif len(q) > 20:\n **errors.append('Please enter at most 20 characters.')**\n else:\n books = Book.objects.filter(title__icontains=q)\n return render(request, 'search_results.html',\n {'books': books, 'query': q})\n return render(request, 'search_form.html',\n {**'errors': errors**})\n\nThen, we need make a small tweak to the ``search_form.html`` template to\nreflect that it's now passed an ``errors`` list instead of an ``error`` boolean\nvalue:\n\n.. parsed-literal::\n\n \n \n Search\n \n \n **{% if errors %}**\n **
      **\n **{% for error in errors %}**\n **
    • {{ error }}
      • **\n **{% endfor %}**\n **
    **\n **{% endif %}**\n
    \n \n \n
    \n \n \n\n.. SL Tested ok\n\nMaking a Contact Form\n=====================\n\nAlthough we iterated over the book search form example several times and\nimproved it nicely, it's still fundamentally simple: just a single field,\n``'q'``. Because it's so simple, we didn't even use Django's form library to\ndeal with it. But more complex forms call for more complex treatment -- and now\nwe'll develop something more complex: a site contact form.\n\nThis will be a form that lets site users submit a bit of feedback, along with\nan optional e-mail return address. After the form is submitted and the\ndata is validated, we'll automatically send the message via e-mail to the site\nstaff.\n\nWe'll start with our template, ``contact_form.html``.\n\n.. parsed-literal::\n\n \n \n Contact us\n \n \n

    Contact us

    \n\n {% if errors %}\n
      \n {% for error in errors %}\n
    • {{ error }}
      • \n {% endfor %}\n
    \n {% endif %}\n\n
    \n

    Subject:

    \n

    Your e-mail (optional):

    \n

    Message:

    \n \n
    \n \n \n\nWe've defined three fields: the subject, e-mail address and message. The second\nis optional, but the other two fields are required. Note we're using\n``method=\"post\"`` here instead of ``method=\"get\"`` because this form submission\nhas a side effect -- it sends an e-mail. Also, we copied the error-displaying\ncode from our previous template ``search_form.html``.\n\nIf we continue down the road established by our ``search()`` view from the\nprevious section, a naive version of our ``contact()`` view might look like\nthis::\n\n from django.core.mail import send_mail\n from django.http import HttpResponseRedirect\n from django.shortcuts import render\n\n def contact(request):\n errors = []\n if request.method == 'POST':\n if not request.POST.get('subject', ''):\n errors.append('Enter a subject.')\n if not request.POST.get('message', ''):\n errors.append('Enter a message.')\n if request.POST.get('email') and '@' not in request.POST['email']:\n errors.append('Enter a valid e-mail address.')\n if not errors:\n send_mail(\n request.POST['subject'],\n request.POST['message'],\n request.POST.get('email', 'noreply@example.com'),\n ['siteowner@example.com'],\n )\n return HttpResponseRedirect('/contact/thanks/')\n return render(request, 'contact_form.html',\n {'errors': errors})\n\n.. SL Tested ok (modulo email config and lack of thanks view)\n\n(If you're following along, you may be wondering whether to put this view in\nthe ``books/views.py`` file. It doesn't have anything to do with the books\napplication, so should it live elsewhere? It's totally up to you; Django\ndoesn't care, as long as you're able to point to the view from your URLconf.\nOur personal preference would be to create a separate directory, ``contact``,\nat the same level in the directory tree as ``books``. This would contain an\nempty ``__init__.py`` and ``views.py``.)\n\nA couple of new things are happening here:\n\n* We're checking that ``request.method`` is ``'POST'``. This will only be\n true in the case of a form submission; it won't be true if somebody is\n merely viewing the contact form. (In the latter case,\n ``request.method will be set to 'GET'``, because in normal Web browsing,\n browsers use ``GET``, not ``POST``.) This makes it a nice way to isolate\n the \"form display\" case from the \"form processing\" case.\n\n* Instead of ``request.GET``, we're using ``request.POST`` to access the\n submitted form data. This is necessary because the HTML ``
    `` in\n ``contact_form.html`` uses ``method=\"post\"``. If this view is accessed\n via ``POST``, then ``request.GET`` will be empty.\n\n* This time, we have *two* required fields, ``subject`` and ``message``, so\n we have to validate both. Note that we're using ``request.POST.get()``\n and providing a blank string as the default value; this is a nice, short\n way of handling both the cases of missing keys and missing data.\n\n* Although the ``email`` field is not required, we still validate it if it\n is indeed submitted. Our validation algorithm here is fragile -- we're\n just checking that the string contains an ``@`` character. In the real\n world, you'd want more robust validation (and Django provides it, which\n we'll show you very shortly).\n\n* We're using the function ``django.core.mail.send_mail`` to send an\n e-mail. This function has four required arguments: the e-mail subject,\n the e-mail body, the \"from\" address, and a list of recipient addresses.\n ``send_mail`` is a convenient wrapper around Django's ``EmailMessage``\n class, which provides advanced features such as attachments, multipart\n e-mails, and full control over e-mail headers.\n\n Note that in order to send e-mail using ``send_mail()``, your server must\n be configured to send mail, and Django must be told about your outbound\n e-mail server. See http://docs.djangoproject.com/en/dev/topics/email/ for\n the specifics.\n\n* After the e-mail is sent, we redirect to a \"success\" page by returning an\n ``HttpResponseRedirect`` object. We'll leave the implementation of that\n \"success\" page up to you (it's a simple view/URLconf/template), but we\n should explain why we initiate a redirect instead of, for example, simply\n calling ``render()`` with a template right there.\n\n The reason: if a user hits \"Refresh\" on a page that was loaded via\n ``POST``, that request will be repeated. This can often lead to undesired\n behavior, such as a duplicate record being added to the database -- or,\n in our example, the e-mail being sent twice. If the user is redirected to\n another page after the ``POST``, then there's no chance of repeating the\n request.\n\n You should *always* issue a redirect for successful ``POST`` requests.\n It's a Web development best practice.\n\nThis view works, but those validation functions are kind of crufty. Imagine\nprocessing a form with a dozen fields; would you really want to have to write\nall of those ``if`` statements?\n\nAnother problem is *form redisplay*. In the case of validation errors, it's\nbest practice to redisplay the form *with* the previously submitted data\nalready filled in, so the user can see what he did wrong (and also so the user\ndoesn't have to reenter data in fields that were submitted correctly). We\n*could* manually pass the ``POST`` data back to the template, but we'd have to\nedit each HTML field to insert the proper value in the proper place:\n\n.. parsed-literal::\n\n # views.py\n\n def contact(request):\n errors = []\n if request.method == 'POST':\n if not request.POST.get('subject', ''):\n errors.append('Enter a subject.')\n if not request.POST.get('message', ''):\n errors.append('Enter a message.')\n if request.POST.get('email') and '@' not in request.POST['email']:\n errors.append('Enter a valid e-mail address.')\n if not errors:\n send_mail(\n request.POST['subject'],\n request.POST['message'],\n request.POST.get('email', 'noreply@example.com'),\n ['siteowner@example.com'],\n )\n return HttpResponseRedirect('/contact/thanks/')\n return render(request, 'contact_form.html', {\n 'errors': errors,\n **'subject': request.POST.get('subject', ''),**\n **'message': request.POST.get('message', ''),**\n **'email': request.POST.get('email', ''),**\n })\n\n # contact_form.html\n\n \n \n Contact us\n \n \n

    Contact us

    \n\n {% if errors %}\n
      \n {% for error in errors %}\n
    • {{ error }}
      • \n {% endfor %}\n
    \n {% endif %}\n\n \n

    Subject:

    \n

    Your e-mail (optional):

    \n

    Message:

    \n \n
    \n \n \n\n.. SL Tested ok\n\nThis is a lot of cruft, and it introduces a lot of opportunities for human\nerror. We hope you're starting to see the opportunity for some higher-level\nlibrary that handles form- and validation-related tasks.\n\nYour First Form Class\n=====================\n\nDjango comes with a form library, called ``django.forms``, that handles many of\nthe issues we've been exploring this chapter -- from HTML form display to\nvalidation. Let's dive in and rework our contact form application using the\nDjango forms framework.\n\n.. admonition:: Django's \"newforms\" library\n\n Throughout the Django community, you might see chatter about something\n called ``django.newforms``. When people speak of ``django.newforms``,\n they're talking about what is now ``django.forms`` -- the library covered by\n this chapter.\n\n The reason for this name change is historic. When Django was first released\n to the public, it had a complicated, confusing forms system,\n ``django.forms``. It was completely rewritten, and the new version was\n called ``django.newforms`` so that people could still use the old system.\n When Django 1.0 was released, the old ``django.forms`` went away, and\n ``django.newforms`` became ``django.forms``.\n\nThe primary way to use the forms framework is to define a ``Form`` class for\neach HTML ``
    `` you're dealing with. In our case, we only have one\n````, so we'll have one ``Form`` class. This class can live anywhere you\nwant -- including directly in your ``views.py`` file -- but community\nconvention is to keep ``Form`` classes in a separate file called ``forms.py``.\nCreate this file in the same directory as your ``views.py``, and enter the\nfollowing::\n\n from django import forms\n\n class ContactForm(forms.Form):\n subject = forms.CharField()\n email = forms.EmailField(required=False)\n message = forms.CharField()\n\nThis is pretty intuitive, and it's similar to Django's model syntax. Each field\nin the form is represented by a type of ``Field`` class -- ``CharField`` and\n``EmailField`` are the only types of fields used here -- as attributes of a\n``Form`` class. Each field is required by default, so to make ``email``\noptional, we specify ``required=False``.\n\nLet's hop into the Python interactive interpreter and see what this class can\ndo. The first thing it can do is display itself as HTML::\n\n >>> from contact.forms import ContactForm\n >>> f = ContactForm()\n >>> print f\n \n \n \n\n.. SL Tested ok\n\nDjango adds a label to each field, along with ``