mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-31 09:41:08 +00:00
Code Issues 32 Releases Wiki Activity

Merged recent changes from trunk.

Browse Source
This commit is contained in:
Russell Keith-Magee
2012-08-20 13:09:09 +08:00
parent 507bb50a92 26e0ba07ae
commit 8e3fd703d0
940 changed files with 21954 additions and 15445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/conf.py
View File

@@ -11,6 +11,8 @@
# All configuration values have a default; values that are commented out
# serve to show the default.
from __future__ import unicode_literals
import sys
import os
@@ -92,6 +94,7 @@ pygments_style = 'trac'
intersphinx_mapping = {
'python': ('http://docs.python.org/2.7', None),
'sphinx': ('http://sphinx.pocoo.org/', None),
'six': ('http://packages.python.org/six/', None),
}
# Python's docs don't change every week.
@@ -187,18 +190,16 @@ modindex_common_prefix = ["django."]
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
latex_elements = {
'preamble': '\\DeclareUnicodeCharacter{2265}{\\ensuremath{\\ge}}'
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
#latex_documents = []
latex_documents = [
('contents', 'django.tex', u'Django Documentation',
u'Django Software Foundation', 'manual'),
('contents', 'django.tex', 'Django Documentation',
'Django Software Foundation', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -215,9 +216,6 @@ latex_documents = [
# If true, show URL addresses after external links.
#latex_show_urls = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
@@ -237,10 +235,10 @@ man_pages = [
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'Django'
epub_author = u'Django Software Foundation'
epub_publisher = u'Django Software Foundation'
epub_copyright = u'2010, Django Software Foundation'
epub_title = 'Django'
epub_author = 'Django Software Foundation'
epub_publisher = 'Django Software Foundation'
epub_copyright = '2010, Django Software Foundation'
# The language of the text. It defaults to the language option
# or en if the language is not set.

3
docs/faq/index.txt
View File

@@ -11,4 +11,5 @@ Django FAQ
help
models
admin
contributing
contributing
troubleshooting

6
docs/faq/install.txt
View File

@@ -16,8 +16,8 @@ How do I get started?
What are Django's prerequisites?
--------------------------------
Django requires Python_, specifically Python 2.6 or 2.7.
No other Python libraries are required for basic Django usage.
Django requires Python_, specifically Python 2.6.5 - 2.7.x. No other Python
libraries are required for basic Django usage.
For a development environment -- if you just want to experiment with Django --
you don't need to have a separate Web server installed; Django comes with its
@@ -42,7 +42,7 @@ Do I lose anything by using Python 2.6 versus newer Python versions, such as Pyt
----------------------------------------------------------------------------------------
Not in the core framework. Currently, Django itself officially supports
Python 2.6 and 2.7. However, newer versions of
Python 2.6 (2.6.5 or higher) and 2.7. However, newer versions of
Python are often faster, have more features, and are better supported. If you
use a newer version of Python you will also have access to some APIs that
aren't available under older versions of Python.

13
docs/faq/models.txt
View File

@@ -26,8 +26,6 @@ SELECTs, etc. Each time your app hits the database, the query will be recorded.
Note that the SQL recorded here may be :ref:`incorrectly quoted under SQLite
<sqlite-connection-queries>`.
.. versionadded:: 1.2
If you are using :doc:`multiple databases</topics/db/multi-db>`, you can use the
same interface on each member of the ``connections`` dictionary::
@@ -42,18 +40,15 @@ Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`.
If I make changes to a model, how do I update the database?
-----------------------------------------------------------
If you don't mind clearing data, your project's ``manage.py`` utility has an
option to reset the SQL for a particular application::
manage.py reset appname
This drops any tables associated with ``appname`` and recreates them.
If you don't mind clearing data, your project's ``manage.py`` utility has a
:djadmin:`flush` option to reset the database to the state it was in
immediately after :djadmin:`syncdb` was executed.
If you do care about deleting data, you'll have to execute the ``ALTER TABLE``
statements manually in your database.
There are `external projects which handle schema updates
<http://djangopackages.com/grids/g/database-migration/>`_, of which the current
<http://www.djangopackages.com/grids/g/database-migration/>`_, of which the current
defacto standard is `south <http://south.aeracode.org/>`_.
Do Django models support multiple-column primary keys?

16
docs/faq/troubleshooting.txt Normal file
View File

@@ -0,0 +1,16 @@
===============
Troubleshooting
===============
This page contains some advice about errors and problems commonly encountered
during the development of Django applications.
"command not found: django-admin.py"
------------------------------------
:doc:`django-admin.py </ref/django-admin>` should be on your system path if you
installed Django via ``python setup.py``. If it's not on your path, you can
find it in ``site-packages/django/bin``, where ``site-packages`` is a directory
within your Python installation. Consider symlinking to :doc:`django-admin.py
</ref/django-admin>` from some place on your path, such as
:file:`/usr/local/bin`.

2
docs/glossary.txt
View File

@@ -16,7 +16,7 @@ Glossary
A higher-order :term:`view` function that provides an abstract/generic
implementation of a common idiom or pattern found in view development.
See :doc:`/ref/class-based-views`.
See :doc:`/topics/class-based-views/index`.
model
Models store your application's data.

2
docs/howto/custom-management-commands.txt
View File

@@ -129,7 +129,7 @@ default options such as :djadminopt:`--verbosity` and :djadminopt:`--traceback`.
class Command(BaseCommand):
...
self.can_import_settings = True
can_import_settings = True
def handle(self, *args, **options):

29
docs/howto/custom-model-fields.txt
View File

@@ -313,9 +313,6 @@ Custom database types
.. method:: Field.db_type(self, connection)
.. versionadded:: 1.2
The ``connection`` argument was added to support multiple databases.
Returns the database column data type for the :class:`~django.db.models.Field`,
taking into account the connection object, and the settings associated with it.
@@ -334,7 +331,6 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
class Person(models.Model):
name = models.CharField(max_length=80)
gender = models.CharField(max_length=1)
something_else = MytypeField()
If you aim to build a database-agnostic application, you should account for
@@ -438,10 +434,14 @@ database, so we need to be able to process strings and ``Hand`` instances in
p1 = re.compile('.{26}')
p2 = re.compile('..')
args = [p2.findall(x) for x in p1.findall(value)]
if len(args) != 4:
raise ValidationError("Invalid input for a Hand instance")
return Hand(*args)
Notice that we always return a ``Hand`` instance from this method. That's the
Python object type we want to store in the model's attribute.
Python object type we want to store in the model's attribute. If anything is
going wrong during value conversion, you should raise a
:exc:`~django.core.exceptions.ValidationError` exception.
**Remember:** If your custom field needs the :meth:`to_python` method to be
called when it is created, you should be using `The SubfieldBase metaclass`_
@@ -453,9 +453,6 @@ Converting Python objects to query values
.. method:: Field.get_prep_value(self, value)
.. versionadded:: 1.2
This method was factored out of ``get_db_prep_value()``
This is the reverse of :meth:`.to_python` when working with the
database backends (as opposed to serialization). The ``value``
parameter is the current value of the model's attribute (a field has
@@ -481,9 +478,6 @@ Converting query values to database values
.. method:: Field.get_db_prep_value(self, value, connection, prepared=False)
.. versionadded:: 1.2
The ``connection`` and ``prepared`` arguments were added to support multiple databases.
Some data types (for example, dates) need to be in a specific format
before they can be used by a database backend.
:meth:`.get_db_prep_value` is the method where those conversions should
@@ -500,9 +494,6 @@ processing.
.. method:: Field.get_db_prep_save(self, value, connection)
.. versionadded:: 1.2
The ``connection`` argument was added to support multiple databases.
Same as the above, but called when the Field value must be *saved* to
the database. As the default implementation just calls
:meth:`.get_db_prep_value`, you shouldn't need to implement this method
@@ -541,9 +532,6 @@ two phase process.
.. method:: Field.get_prep_lookup(self, lookup_type, value)
.. versionadded:: 1.2
This method was factored out of ``get_db_prep_lookup()``
:meth:`.get_prep_lookup` performs the first phase of lookup preparation,
performing generic data validity checks
@@ -592,9 +580,6 @@ accepted lookup types to ``exact`` and ``in``::
.. method:: Field.get_db_prep_lookup(self, lookup_type, value, connection, prepared=False)
.. versionadded:: 1.2
The ``connection`` and ``prepared`` arguments were added to support multiple databases.
Performs any database-specific data conversions required by a lookup.
As with :meth:`.get_db_prep_value`, the specific connection that will
be used for the query is passed as the ``connection`` parameter.
@@ -685,7 +670,7 @@ data storage anyway, we can reuse some existing conversion code::
def value_to_string(self, obj):
value = self._get_val_from_obj(obj)
return self.get_db_prep_value(value)
return self.get_prep_value(value)
Some general advice
--------------------
@@ -703,7 +688,7 @@ smoothly:
2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're
wrapping up as a field. There are a lot of places where the default
behavior of the field code is to call
:func:`~django.utils.encoding.force_unicode` on the value. (In our
:func:`~django.utils.encoding.force_text` on the value. (In our
examples in this document, ``value`` would be a ``Hand`` instance, not a
``HandField``). So if your :meth:`__unicode__` method automatically
converts to the string form of your Python object, you can save yourself

8
docs/howto/custom-template-tags.txt
View File

@@ -189,7 +189,7 @@ passed around inside the template code:
They're commonly used for output that contains raw HTML that is intended
to be interpreted as-is on the client side.
Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
Internally, these strings are of type ``SafeBytes`` or ``SafeText``.
They share a common base class of ``SafeData``, so you can test
for them using code like:
@@ -204,8 +204,8 @@ passed around inside the template code:
not. These strings are only escaped once, however, even if auto-escaping
applies.
Internally, these strings are of type ``EscapeString`` or
``EscapeUnicode``. Generally you don't have to worry about these; they
Internally, these strings are of type ``EscapeBytes`` or
``EscapeText``. Generally you don't have to worry about these; they
exist for the implementation of the :tfilter:`escape` filter.
Template filter code falls into one of two situations:
@@ -540,8 +540,6 @@ tag is used inside a :ttag:`{% autoescape off %}<autoescape>` block.
Thread-safety considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.2
Once a node is parsed, its ``render`` method may be called any number of times.
Since Django is sometimes run in multi-threaded environments, a single node may
be simultaneously rendering with different contexts in response to two separate

2
docs/howto/deployment/wsgi/gunicorn.txt
View File

@@ -13,7 +13,7 @@ There are two ways to use Gunicorn with Django. One is to have Gunicorn treat
Django as just another WSGI application. The second is to use Gunicorn's
special `integration with Django`_.
.. _integration with Django: http://gunicorn.org/run.html#django-manage-py_
.. _integration with Django: http://gunicorn.org/run.html#django-manage-py
Installing Gunicorn
===================

2
docs/howto/deployment/wsgi/uwsgi.txt
View File

@@ -46,7 +46,7 @@ uWSGI supports multiple ways to configure the process. See uWSGI's
Here's an example command to start a uWSGI server::
uwsgi --chdir=/path/to/your/project
uwsgi --chdir=/path/to/your/project \
--module=mysite.wsgi:application \
--env DJANGO_SETTINGS_MODULE=mysite.settings \
--master --pidfile=/tmp/project-master.pid \

12
docs/howto/initial-data.txt
View File

@@ -67,12 +67,12 @@ And here's that same fixture as YAML:
You'll store this data in a ``fixtures`` directory inside your app.
Loading data is easy: just call :djadmin:`manage.py loaddata <fixturename>
<loaddata>`, where ``<fixturename>`` is the name of the fixture file you've
created. Each time you run :djadmin:`loaddata`, the data will be read from the
fixture and re-loaded into the database. Note this means that if you change one
of the rows created by a fixture and then run :djadmin:`loaddata` again, you'll
wipe out any changes you've made.
Loading data is easy: just call :djadmin:`manage.py loaddata <loaddata>`
``<fixturename>``, where ``<fixturename>`` is the name of the fixture file
you've created. Each time you run :djadmin:`loaddata`, the data will be read
from the fixture and re-loaded into the database. Note this means that if you
change one of the rows created by a fixture and then run :djadmin:`loaddata`
again, you'll wipe out any changes you've made.
Automatically loading initial data fixtures
-------------------------------------------

2
docs/howto/jython.txt
View File

@@ -36,7 +36,7 @@ such as `Apache Tomcat`_. Full JavaEE applications servers such as `GlassFish`_
or `JBoss`_ are also OK, if you need the extra features they include.
.. _`Apache Tomcat`: http://tomcat.apache.org/
.. _GlassFish: https://glassfish.dev.java.net/
.. _GlassFish: http://glassfish.java.net/
.. _JBoss: http://www.jboss.org/
Installing Django

6
docs/howto/outputting-pdf.txt
View File

@@ -100,6 +100,12 @@ mention:
* Finally, it's important to call ``showPage()`` and ``save()`` on the PDF
file.
.. note::
ReportLab is not thread-safe. Some of our users have reported odd issues
with building PDF-generating Django views that are accessed by many people
at the same time.
Complex PDFs
============

10
docs/howto/static-files.txt
View File

@@ -68,7 +68,7 @@ Basic usage
.. code-block:: html+django
<img src="{{ STATIC_URL }}images/hi.jpg" />
<img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" />
See :ref:`staticfiles-in-templates` for more details, **including** an
alternate method using a template tag.
@@ -131,7 +131,7 @@ You could, of course, simply hardcode the path to you assets in the templates:
.. code-block:: html
<img src="http://static.example.com/static/myimage.jpg" />
<img src="http://static.example.com/static/myimage.jpg" alt="Sample image" />
Of course, there are some serious problems with this: it doesn't work well in
development, and it makes it *very* hard to change where you've deployed your
@@ -167,7 +167,7 @@ Once that's done, you can refer to :setting:`STATIC_URL` in your templates:
.. code-block:: html+django
<img src="{{ STATIC_URL }}images/hi.jpg" />
<img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" />
If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not
using :class:`~django.template.RequestContext` when rendering the template.
@@ -175,7 +175,7 @@ using :class:`~django.template.RequestContext` when rendering the template.
As a brief refresher, context processors add variables into the contexts of
every template. However, context processors require that you use
:class:`~django.template.RequestContext` when rendering templates. This happens
automatically if you're using a :doc:`generic view </ref/class-based-views>`,
automatically if you're using a :doc:`generic view </ref/class-based-views/index>`,
but in views written by hand you'll need to explicitly use ``RequestContext``
To see how that works, and to read more details, check out
:ref:`subclassing-context-requestcontext`.
@@ -193,7 +193,7 @@ tag. It builds the URL for the given relative path by using the configured
.. code-block:: html+django
{% load staticfiles %}
<img src="{% static "images/hi.jpg" %}" />
<img src="{% static "images/hi.jpg" %}" alt="Hi!"/>
It is also able to consume standard context variables, e.g. assuming a
``user_stylesheet`` variable is passed to the template:

147
docs/index.txt
View File

@@ -34,6 +34,8 @@ Having trouble? We'd like to help!
First steps
===========
Are you new to Django or to programming? This is the place to start!
* **From scratch:**
:doc:`Overview <intro/overview>` |
:doc:`Installation <intro/install>`
@@ -47,6 +49,9 @@ First steps
The model layer
===============
Django provides an abstraction layer (the "models") for structuring and
manipulating the data of your Web application. Learn more about it below:
* **Models:**
:doc:`Model syntax <topics/db/models>` |
:doc:`Field types <ref/models/fields>` |
@@ -74,20 +79,13 @@ The model layer
:doc:`Providing initial data <howto/initial-data>` |
:doc:`Optimize database access <topics/db/optimization>`
The template layer
==================
* **For designers:**
:doc:`Syntax overview <topics/templates>` |
:doc:`Built-in tags and filters <ref/templates/builtins>`
* **For programmers:**
:doc:`Template API <ref/templates/api>` |
:doc:`Custom tags and filters <howto/custom-template-tags>`
The view layer
==============
Django has the concept of "views" to encapsulate the logic responsible for
processing a user's request and for returning the response. Find all you need
to know about views via the links below:
* **The basics:**
:doc:`URLconfs <topics/http/urls>` |
:doc:`View functions <topics/http/views>` |
@@ -105,9 +103,10 @@ The view layer
:doc:`Managing files <topics/files>` |
:doc:`Custom storage <howto/custom-file-storage>`
* **Generic views:**
:doc:`Overview<topics/class-based-views>` |
:doc:`Built-in generic views<ref/class-based-views>`
* **Class-based views:**
:doc:`Overview<topics/class-based-views/index>` |
:doc:`Built-in class-based views<ref/class-based-views/index>` |
:doc:`Built-in view mixins<ref/class-based-views/mixins>`
* **Advanced:**
:doc:`Generating CSV <howto/outputting-csv>` |
@@ -117,9 +116,29 @@ The view layer
:doc:`Overview <topics/http/middleware>` |
:doc:`Built-in middleware classes <ref/middleware>`
The template layer
==================
The template layer provides a designer-friendly syntax for rendering the
information to be presented to the user. Learn how this syntax can be used by
designers and how it can be extended by programmers:
* **For designers:**
:doc:`Syntax overview <topics/templates>` |
:doc:`Built-in tags and filters <ref/templates/builtins>` |
:doc:`Web design helpers <ref/contrib/webdesign>` |
:doc:`Humanization <ref/contrib/humanize>`
* **For programmers:**
:doc:`Template API <ref/templates/api>` |
:doc:`Custom tags and filters <howto/custom-template-tags>`
Forms
=====
Django provides a rich framework to facilitate the creation of forms and the
manipulation of form data.
* **The basics:**
:doc:`Overview <topics/forms/index>` |
:doc:`Form API <ref/forms/api>` |
@@ -139,6 +158,9 @@ Forms
The development process
=======================
Learn about the various components and tools to help you in the development and
testing of Django applications:
* **Settings:**
:doc:`Overview <topics/settings>` |
:doc:`Full list of settings <ref/settings>`
@@ -160,50 +182,99 @@ The development process
:doc:`Handling static files <howto/static-files>` |
:doc:`Tracking code errors by email <howto/error-reporting>`
Other batteries included
========================
The admin
=========
* :doc:`Admin site <ref/contrib/admin/index>` | :doc:`Admin actions <ref/contrib/admin/actions>` | :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
* :doc:`Authentication <topics/auth>`
* :doc:`Cache system <topics/cache>`
Find all you need to know about the automated admin interface, one of Django's
most popular features:
* :doc:`Admin site <ref/contrib/admin/index>`
* :doc:`Admin actions <ref/contrib/admin/actions>`
* :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`
Security
========
Security is a topic of paramount importance in the development of Web
applications and Django provides multiple protection tools and mechanisms:
* :doc:`Security overview <topics/security>`
* :doc:`Clickjacking protection <ref/clickjacking>`
* :doc:`Comments <ref/contrib/comments/index>` | :doc:`Moderation <ref/contrib/comments/moderation>` | :doc:`Custom comments <ref/contrib/comments/custom>`
* :doc:`Conditional content processing <topics/conditional-view-processing>`
* :doc:`Content types and generic relations <ref/contrib/contenttypes>`
* :doc:`Cross Site Request Forgery protection <ref/contrib/csrf>`
* :doc:`Cryptographic signing <topics/signing>`
* :doc:`Databrowse <ref/contrib/databrowse>`
* :doc:`E-mail (sending) <topics/email>`
* :doc:`Flatpages <ref/contrib/flatpages>`
* :doc:`GeoDjango <ref/contrib/gis/index>`
* :doc:`Humanize <ref/contrib/humanize>`
Internationalization and localization
=====================================
Django offers a robust internationalization and localization framework to
assist you in the development of applications for multiple languages and world
regions:
* :doc:`Internationalization <topics/i18n/index>`
* :doc:`Jython support <howto/jython>`
* :doc:`"Local flavor" <ref/contrib/localflavor>`
Python compatibility
====================
Django aims to be compatible with multiple different flavors and versions of
Python:
* :doc:`Jython support <howto/jython>`
* :doc:`Python 3 compatibility <topics/python3>`
Geographic framework
====================
:doc:`GeoDjango <ref/contrib/gis/index>` intends to be a world-class geographic
Web framework. Its goal is to make it as easy as possible to build GIS Web
applications and harness the power of spatially enabled data.
Common Web application tools
============================
Django offers multiple tools commonly needed in the development of Web
applications:
* :doc:`Authentication <topics/auth>`
* :doc:`Caching <topics/cache>`
* :doc:`Logging <topics/logging>`
* :doc:`Messages <ref/contrib/messages>`
* :doc:`Sending e-mails <topics/email>`
* :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
* :doc:`Comments <ref/contrib/comments/index>`, :doc:`comment moderation <ref/contrib/comments/moderation>` and :doc:`custom comments <ref/contrib/comments/custom>`
* :doc:`Pagination <topics/pagination>`
* :doc:`Redirects <ref/contrib/redirects>`
* :doc:`Security <topics/security>`
* :doc:`Messages framework <ref/contrib/messages>`
* :doc:`Serialization <topics/serialization>`
* :doc:`Sessions <topics/http/sessions>`
* :doc:`Signals <topics/signals>`
* :doc:`Sitemaps <ref/contrib/sitemaps>`
* :doc:`Sites <ref/contrib/sites>`
* :doc:`Static Files <ref/contrib/staticfiles>`
* :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
* :doc:`Static files management <ref/contrib/staticfiles>`
* :doc:`Data validation <ref/validators>`
Other core functionalities
==========================
Learn about some other core functionalities of the Django framework:
* :doc:`Conditional content processing <topics/conditional-view-processing>`
* :doc:`Content types and generic relations <ref/contrib/contenttypes>`
* :doc:`Databrowse <ref/contrib/databrowse>`
* :doc:`Flatpages <ref/contrib/flatpages>`
* :doc:`Redirects <ref/contrib/redirects>`
* :doc:`Signals <topics/signals>`
* :doc:`The sites framework <ref/contrib/sites>`
* :doc:`Unicode in Django <ref/unicode>`
* :doc:`Web design helpers <ref/contrib/webdesign>`
* :doc:`Validators <ref/validators>`
The Django open-source project
==============================
Learn about the development process for the Django project itself and about how
you can contribute:
* **Community:**
:doc:`How to get involved <internals/contributing/index>` |
:doc:`The release process <internals/release-process>` |
:doc:`Team of committers <internals/committers>` |
:doc:`The Django source code repository <internals/svn>`
:doc:`The Django source code repository <internals/git>` |
:doc:`Security policies <internals/security>`
* **Design philosophies:**
:doc:`Overview <misc/design-philosophies>`

50
docs/internals/committers.txt
View File

@@ -146,9 +146,10 @@ Joseph Kocherhans
Brian lives in Denver, Colorado, USA.
.. _brian rosner: http://oebfare.com/
.. _brian rosner: http://brosner.com/
.. _eldarion: http://eldarion.com/
.. _django dose: http://djangodose.com/
.. _pinax: http://pinaxproject.com/
`Gary Wilson`_
Gary starting contributing patches to Django in 2006 while developing Web
@@ -162,7 +163,7 @@ Joseph Kocherhans
Gary lives in Austin, Texas, USA.
.. _Gary Wilson: http://gdub.wordpress.com/
.. _Gary Wilson: http://thegarywilson.com/
.. _The University of Texas: http://www.utexas.edu/
Justin Bronn
@@ -174,7 +175,7 @@ Justin Bronn
implementing GeoDjango, Justin obtained a deep knowledge of Django's
internals including the ORM, the admin, and Oracle support.
Justin lives in Houston, Texas.
Justin lives in San Francisco, CA.
.. _GeoDjango: http://geodjango.org/
@@ -191,14 +192,19 @@ Karen Tracey
`Jannis Leidel`_
Jannis graduated in media design from `Bauhaus-University Weimar`_,
is the author of a number of pluggable Django apps and likes to
contribute to Open Source projects like Pinax_. He currently works as
a freelance Web developer and designer.
contribute to Open Source projects like virtualenv_ and pip_.
He has worked on Django's auth, admin and staticfiles apps as well as
the form, core, internationalization and test systems. He currently works
as the lead engineer at Gidsy_.
Jannis lives in Berlin, Germany.
.. _Jannis Leidel: http://jezdez.com/
.. _Bauhaus-University Weimar: http://www.uni-weimar.de/
.. _pinax: http://pinaxproject.com/
.. _virtualenv: http://www.virtualenv.org/
.. _pip: http://www.pip-installer.org/
.. _Gidsy: http://gidsy.com/
`James Tauber`_
James is the lead developer of Pinax_ and the CEO and founder of
@@ -214,15 +220,15 @@ Karen Tracey
.. _James Tauber: http://jtauber.com/
`Alex Gaynor`_
Alex is a student at Rensselaer Polytechnic Institute, and is also an
independent contractor. He found Django in 2007 and has been addicted ever
since he found out you don't need to write out your forms by hand. He has
a small obsession with compilers. He's contributed to the ORM, forms,
admin, and other components of Django.
Alex is a software engineer working at Rdio_. He found Django in 2007 and
has been addicted ever since he found out you don't need to write out your
forms by hand. He has a small obsession with compilers. He's contributed
to the ORM, forms, admin, and other components of Django.
Alex lives in Chicago, IL, but spends most of his time in Troy, NY.
Alex lives in San Francisco, CA, USA.
.. _Alex Gaynor: http://alexgaynor.net
.. _Rdio: http://rdio.com
`Andrew Godwin`_
Andrew is a freelance Python developer and tinkerer, and has been
@@ -355,6 +361,26 @@ Honza Král
.. _Claude Paroz: http://www.2xlibre.net
.. _l10n.gnome.org: http://l10n.gnome.org
Anssi Kääriäinen
Anssi works as a developer at Finnish National Institute for Health and
Welfare. He is also a computer science student at Aalto University. In his
work he uses Django for developing internal business applications and sees
Django as a great match for that use case.
Anssi is interested in developing the object relational mapper (ORM) and
all related features. He's also a fan of benckmarking and he tries keep
Django as fast as possible.
Florian Apolloner
Florian is currently studying Physics at the `Graz University of Technology`_.
Soon after he started using Django he joined the `Ubuntuusers webteam`_ to
work on *Inyoka*, the software powering the whole Ubuntusers site.
For the time beeing he lives in Graz, Austria (not Australia ;)).
.. _Graz University of Technology: http://tugraz.at/
.. _Ubuntuusers webteam: http://wiki.ubuntuusers.de/ubuntuusers/Webteam
Specialists
-----------

52
docs/internals/contributing/bugs-and-features.txt
View File

@@ -2,7 +2,16 @@
Reporting bugs and requesting features
======================================
Before reporting a bug or requesting a new feature, please consider these
.. Important::
Please report security issues **only** to
security@djangoproject.com. This is a private list only open to
long-time, highly trusted Django developers, and its archives are
not public. For further details, please see :doc:`our security
policies </internals/security>`.
Otherwise, before reporting a bug or requesting a new feature, please consider these
general points:
* Check that someone hasn't already filed the bug or feature request by
@@ -53,42 +62,6 @@ To understand the lifecycle of your ticket once you have created it, refer to
.. _django-updates: http://groups.google.com/group/django-updates
.. _reporting-security-issues:
Reporting security issues
-------------------------
.. Important::
Please report security issues **only** to security@djangoproject.com.
This is a private list only open to long-time, highly trusted Django
developers, and its archives are not publicly readable.
In the event of a confirmed vulnerability in Django itself, we will take the
following actions:
* Acknowledge to the reporter that we've received the report and that a
fix is forthcoming. We'll give a rough timeline and ask the reporter
to keep the issue confidential until we announce it.
* Focus on developing a fix as quickly as possible and produce patches
against the current and two previous releases.
* Determine a go-public date for announcing the vulnerability and the fix.
To try to mitigate a possible "arms race" between those applying the
patch and those trying to exploit the hole, we will not announce
security problems immediately.
* Pre-notify third-party distributors of Django ("vendors"). We will send
these vendor notifications through private email which will include
documentation of the vulnerability, links to the relevant patch(es), and
a request to keep the vulnerability confidential until the official
go-public date.
* Publicly announce the vulnerability and the fix on the pre-determined
go-public date. This will probably mean a new release of Django, but
in some cases it may simply be patches against current releases.
Reporting user interface bugs and features
------------------------------------------
@@ -149,9 +122,8 @@ description.
As with most open-source projects, code talks. If you are willing to write the
code for the feature yourself or, even better, if you've already written it,
it's much more likely to be accepted. If it's a large feature that might need
multiple developers, we're always happy to give you an experimental branch in
our repository; see the :doc:`writing-code/branch-policy`.
it's much more likely to be accepted. Just fork Django on GitHub, create a
feature branch, and show us your work!
See also: :ref:`documenting-new-features`.

171
docs/internals/contributing/committing-code.txt
View File

@@ -3,7 +3,9 @@ Committing code
===============
This section is addressed to the :doc:`/internals/committers` and to anyone
interested in knowing how code gets committed into Django core.
interested in knowing how code gets committed into Django core. If you're a
community member who wants to contribute code to Django, have a look at
:doc:`writing-code/working-with-git` instead.
Commit access
-------------
@@ -21,7 +23,7 @@ Partial committers
access to the subsystems that fall under their jurisdiction, and they're
given a formal vote in questions that involve their subsystems. This type
of access is likely to be given to someone who contributes a large
subframework to Django and wants to continue to maintain it.
sub-framework to Django and wants to continue to maintain it.
Partial commit access is granted by the same process as full
committers. However, the bar is set lower; proven expertise in the area
@@ -30,13 +32,101 @@ Partial committers
Decisions on new committers will follow the process explained in
:ref:`how-we-make-decisions`. To request commit access, please contact an
existing committer privately. Public requests for commit access are potential
flame-war starters, and will be ignored.
flame-war starters, and will simply be ignored.
Handling pull requests
----------------------
Since Django is now hosted at GitHub, many patches are provided in the form of
pull requests.
When committing a pull request, make sure each individual commit matches the
commit guidelines described below. Contributors are expected to provide the
best pull requests possible. In practice however, committers - who will likely
be more familiar with the commit guidelines - may decide to bring a commit up
to standard themselves.
Here is one way to commit a pull request::
# Create a new branch tracking upstream/master -- upstream is assumed
# to be django/django.
git checkout -b pull_xxxxx upstream/master
# Download the patches from github and apply them.
curl https://github.com/django/django/pull/xxxxx.patch | git am
At this point, you can work on the code. Use ``git rebase -i`` and ``git
commit --amend`` to make sure the commits have the expected level of quality.
Once you're ready::
# Make sure master is ready to receive changes.
git checkout master
git pull upstream master
# Merge the work as "fast-forward" to master, to avoid a merge commit.
git merge --ff-only pull_xxxxx
# Check that only the changes you expect will be pushed to upstream.
git push --dry-run upstream master
# Push!
git push upstream master
# Get rid of the pull_xxxxx branch.
git branch -d pull_xxxxx
An alternative is to add the contributor's repository as a new remote,
checkout the branch and work from there::
git remote add <contributor> https://github.com/<contributor>/django.git
git checkout pull_xxxxx <contributor> <contributor's pull request branch>
Yet another alternative is to fetch the branch without adding the
contributor's repository as a remote::
git fetch https://github.com/<contributor>/django.git <contributor's pull request branch>
git checkout -b pull_xxxxx FETCH_HEAD
At this point, you can work on the code and continue as above.
GitHub provides a one-click merge functionality for pull requests. This should
only be used if the pull request is 100% ready, and you have checked it for
errors (or trust the request maker enough to skip checks). Currently, it isn't
possible to check that the tests pass and that the docs build without
downloading the changes to your development environment.
When rewriting the commit history of a pull request, the goal is to make
Django's commit history as usable as possible:
* If a patch contains back-and-forth commits, then rewrite those into one.
Typically, a commit can add some code, and a second commit can fix
stylistic issues introduced in the first commit.
* Separate changes to different commits by logical grouping: if you do a
stylistic cleanup at the same time as you do other changes to a file,
separating the changes into two different commits will make reviewing
history easier.
* Beware of merges of upstream branches in the pull requests.
* Tests should pass and docs should build after each commit. Neither the
tests nor the docs should emit warnings.
* Trivial and small patches usually are best done in one commit. Medium to
large work should be split into multiple commits if possible.
Practicality beats purity, so it is up to each committer to decide how much
history mangling to do for a pull request. The main points are engaging the
community, getting work done, and having a usable commit history.
.. _committing-guidlines:
Committing guidelines
---------------------
Please follow these guidelines when committing code to Django's Subversion
repository:
In addition, please follow the following guidelines when committing code to
Django's Git repository:
* Never change the published history of django/django branches! **Never force-
push your changes to django/django.** If you absolutely must (for security
reasons for example) first discuss the situation with the core team.
* For any medium-to-big changes, where "medium-to-big" is according to
your judgment, please bring things up on the `django-developers`_
@@ -55,8 +145,23 @@ repository:
* Bad: "Fixes Unicode bug in RSS API."
* Bad: "Fixing Unicode bug in RSS API."
The commit message should be in lines of 72 chars maximum. There should be
a subject line, separated by a blank line and then paragraphs of 72 char
lines. The limits are soft. For the subject line, shorter is better. In the
body of the commit message more detail is better than less::
Fixed #18307 -- Added git workflow guidelines
Refactored the Django's documentation to remove mentions of SVN
specific tasks. Added guidelines of how to use Git, GitHub, and
how to use pull request together with Trac instead.
If the patch wasn't a pull request, you should credit the contributors in
the commit message: "Thanks A for report, B for the patch and C for the
review."
* For commits to a branch, prefix the commit message with the branch name.
For example: "magic-removal: Added support for mind reading."
For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."
* Limit commits to the most granular change that makes sense. This means,
use frequent small commits rather than infrequent large commits. For
@@ -65,31 +170,29 @@ repository:
separate commit. This goes a *long way* in helping all core Django
developers follow your changes.
* Separate bug fixes from feature changes.
Bug fixes need to be added to the current bugfix branch as well as the
current trunk.
* Separate bug fixes from feature changes. Bugfixes may need to be backported
to the stable branch, according to the :ref:`backwards-compatibility policy
<backwards-compatibility-policy>`.
* If your commit closes a ticket in the Django `ticket tracker`_, begin
your commit message with the text "Fixed #abc", where "abc" is the
your commit message with the text "Fixed #xxxxx", where "xxxxx" is the
number of the ticket your commit fixes. Example: "Fixed #123 -- Added
support for foo". We've rigged Subversion and Trac so that any commit
message in that format will automatically close the referenced ticket
and post a comment to it with the full commit message.
whizbang feature.". We've rigged Trac so that any commit message in that
format will automatically close the referenced ticket and post a comment
to it with the full commit message.
If your commit closes a ticket and is in a branch, use the branch name
first, then the "Fixed #abc." For example:
"magic-removal: Fixed #123 -- Added whizbang feature."
first, then the "Fixed #xxxxx." For example:
"[1.4.x] Fixed #123 -- Added whizbang feature."
For the curious: we're using a `Trac post-commit hook`_ for this.
For the curious, we're using a `Trac plugin`_ for this.
.. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-svn-post-commit-hook.cmd
.. _Trac plugin: https://github.com/aaugustin/trac-github
* If your commit references a ticket in the Django `ticket tracker`_ but
does *not* close the ticket, include the phrase "Refs #abc", where "abc"
is the number of the ticket your commit references. We've rigged
Subversion and Trac so that any commit message in that format will
automatically post a comment to the appropriate ticket.
does *not* close the ticket, include the phrase "Refs #xxxxx", where "xxxxx"
is the number of the ticket your commit references. This will automatically
post a comment to the appropriate ticket.
* Write commit messages for backports using this pattern::
@@ -99,26 +202,30 @@ repository:
For example::
[1.3.X] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.
[1.3.x] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.
Backport of r17115 from trunk.
Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from master.
Reverting commits
-----------------
Nobody's perfect; mistakes will be committed. When a mistaken commit is
discovered, please follow these guidelines:
Nobody's perfect; mistakes will be committed.
* Try very hard to ensure that mistakes don't happen. Just because we
have a reversion policy doesn't relax your responsibility to aim for
the highest quality possible. Really: double-check your work before
you commit it in the first place!
But try very hard to ensure that mistakes don't happen. Just because we have a
reversion policy doesn't relax your responsibility to aim for the highest
quality possible. Really: double-check your work, or have it checked by
another committer, **before** you commit it in the first place!
When a mistaken commit is discovered, please follow these guidelines:
* If possible, have the original author revert his/her own commit.
* Don't revert another author's changes without permission from the
original author.
* Use git revert -- this will make a reverse commit, but the original
commit will still be part of the commit history.
* If the original author can't be reached (within a reasonable amount
of time -- a day or so) and the problem is severe -- crashing bug,
major test failures, etc -- then ask for objections on the
@@ -139,5 +246,9 @@ discovered, please follow these guidelines:
* The release branch maintainer may back out commits to the release
branch without permission if the commit breaks the release branch.
* If you mistakenly push a topic branch to django/django, just delete it.
For instance, if you did: ``git push upstream feature_antigravity``,
just do a reverse push: ``git push upstream :feature_antigravity``.
.. _django-developers: http://groups.google.com/group/django-developers
.. _ticket tracker: https://code.djangoproject.com/newticket

6
docs/internals/contributing/localizing.txt
View File

@@ -60,7 +60,7 @@ Django source tree, as for any code change:
* Open a ticket in Django's ticket system, set its ``Component`` field to
``Translations``, and attach the patch to it.
.. _Transifex: https://www.transifex.net/
.. _Transifex: https://www.transifex.com/
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
.. _Django project page: https://www.transifex.net/projects/p/django/
.. _Transifex User Guide: http://help.transifex.net/
.. _Django project page: https://www.transifex.com/projects/p/django/
.. _Transifex User Guide: http://help.transifex.com/

171
docs/internals/contributing/writing-code/branch-policy.txt
View File

@@ -1,171 +0,0 @@
=============
Branch policy
=============
In general, the trunk must be kept stable. People should be able to run
production sites against the trunk at any time. Additionally, commits to trunk
ought to be as atomic as possible -- smaller changes are better. Thus, large
feature changes -- that is, changes too large to be encapsulated in a single
patch, or changes that need multiple eyes on them -- must happen on dedicated
branches.
This means that if you want to work on a large feature -- anything that would
take more than a single patch, or requires large-scale refactoring -- you need
to do it on a feature branch. Our development process recognizes two options
for feature branches:
1. Feature branches using a distributed revision control system like
Git_, Mercurial_, Bazaar_, etc.
If you're familiar with one of these tools, this is probably your best
option since it doesn't require any support or buy-in from the Django
core developers.
However, do keep in mind that Django will continue to use Subversion
for the foreseeable future, and this will naturally limit the
recognition of your branch. Further, if your branch becomes eligible
for merging to trunk you'll need to find a core developer familiar
with your DVCS of choice who'll actually perform the merge.
If you do decided to start a distributed branch of Django and choose to
make it public, please add the branch to the `Django branches`_ wiki
page.
2. Feature branches using SVN have a higher bar. If you want a branch
in SVN itself, you'll need a "mentor" among the :doc:`core committers
</internals/committers>`. This person is responsible for actually
creating the branch, monitoring your process (see below), and
ultimately merging the branch into trunk.
If you want a feature branch in SVN, you'll need to ask in
`django-developers`_ for a mentor.
.. _git: http://git-scm.com/
.. _mercurial: http://mercurial.selenic.com/
.. _bazaar: http://bazaar.canonical.com/
.. _django branches: https://code.djangoproject.com/wiki/DjangoBranches
Branch rules
------------
We've got a few rules for branches born out of experience with what makes a
successful Django branch.
DVCS branches are obviously not under central control, so we have no way of
enforcing these rules. However, if you're using a DVCS, following these rules
will give you the best chance of having a successful branch (read: merged back
to trunk).
Developers with branches in SVN, however, **must** follow these rules. The
branch mentor will keep on eye on the branch and **will delete it** if these
rules are broken.
* Only branch entire copies of the Django tree, even if work is only
happening on part of that tree. This makes it painless to switch to a
branch.
* Merge changes from trunk no less than once a week, and preferably every
couple-three days.
In our experience, doing regular trunk merges is often the difference
between a successful branch and one that fizzles and dies.
If you're working on an SVN branch, you should be using `svnmerge.py`_
to track merges from trunk.
* Keep tests passing and documentation up-to-date. As with patches,
we'll only merge a branch that comes with tests and documentation.
.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
Once the branch is stable and ready to be merged into the trunk, alert
`django-developers`_.
After a branch has been merged, it should be considered "dead"; write access
to it will be disabled, and old branches will be periodically "trimmed."
To keep our SVN wrangling to a minimum, we won't be merging from a given
branch into the trunk more than once.
Using branches
--------------
To use a branch, you'll need to do two things:
* Get the branch's code through Subversion.
* Point your Python ``site-packages`` directory at the branch's version of
the ``django`` package rather than the version you already have
installed.
Getting the code from Subversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To get the latest version of a branch's code, check it out using Subversion:
.. code-block:: bash
svn co https://code.djangoproject.com/svn/django/branches/<branch>/
...where ``<branch>`` is the branch's name. See the `list of branch names`_.
Alternatively, you can automatically convert an existing directory of the
Django source code as long as you've checked it out via Subversion. To do the
conversion, execute this command from within your ``django`` directory:
.. code-block:: bash
svn switch https://code.djangoproject.com/svn/django/branches/<branch>/
The advantage of using ``svn switch`` instead of ``svn co`` is that the
``switch`` command retains any changes you might have made to your local copy
of the code. It attempts to merge those changes into the "switched" code. The
disadvantage is that it may cause conflicts with your local changes if the
"switched" code has altered the same lines of code.
(Note that if you use ``svn switch``, you don't need to point Python at the
new version, as explained in the next section.)
.. _list of branch names: https://code.djangoproject.com/browser/django/branches
.. _pointing-python-at-the-new-django-version:
Pointing Python at the new Django version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you've retrieved the branch's code, you'll need to change your Python
``site-packages`` directory so that it points to the branch version of the
``django`` directory. (The ``site-packages`` directory is somewhere such as
``/usr/lib/python2.7/site-packages`` or
``/usr/local/lib/python2.7/site-packages`` or ``C:\Python\site-packages``.)
The simplest way to do this is by renaming the old ``django`` directory to
``django.OLD`` and moving the trunk version of the code into the directory
and calling it ``django``.
Alternatively, you can use a symlink called ``django`` that points to the
location of the branch's ``django`` package. If you want to switch back, just
change the symlink to point to the old code.
A third option is to use a path file (``<something>.pth``). This is a feature of
the :mod:`site` module. First, make sure there are no files, directories or
symlinks named ``django`` in your ``site-packages`` directory. Then create a
text file named ``django.pth`` and save it to your ``site-packages`` directory.
That file should contain a path to your copy of Django on a single line and
optional comments. Here is an example that points to multiple branches. Just
uncomment the line for the branch you want to use ('trunk' in this example) and
make sure all other lines are commented::
# Trunk is a svn checkout of:
# https://code.djangoproject.com/svn/django/trunk/
#
/path/to/trunk
# <branch> is a svn checkout of:
# https://code.djangoproject.com/svn/django/branches/<branch>/
#
#/path/to/<branch>
# On windows a path may look like this:
# C:/path/to/<branch>
.. _django-developers: http://groups.google.com/group/django-developers

2
docs/internals/contributing/writing-code/index.txt
View File

@@ -12,4 +12,4 @@ chances to be included in Django core:
coding-style
unit-tests
submitting-patches
branch-policy
working-with-git

94
docs/internals/contributing/writing-code/submitting-patches.txt
View File

@@ -6,14 +6,24 @@ We're always grateful for patches to Django's code. Indeed, bug reports
with associated patches will get fixed *far* more quickly than those
without patches.
Typo fixes and trivial documentation changes
--------------------------------------------
If you are fixing a really trivial issue, for example changing a word in the
documentation, the preferred way to provide the patch is using GitHub pull
requests without a Trac ticket. Trac tickets are still acceptable.
See the :doc:`working-with-git` for more details on how to use pull requests.
"Claiming" tickets
------------------
In an open-source project with hundreds of contributors around the world, it's
important to manage communication efficiently so that work doesn't get
duplicated and contributors can be as effective as possible. Hence, our policy
is for contributors to "claim" tickets in order to let other developers know
that a particular bug or feature is being worked on.
duplicated and contributors can be as effective as possible.
Hence, our policy is for contributors to "claim" tickets in order to let other
developers know that a particular bug or feature is being worked on.
If you have identified a contribution you want to make and you're capable of
fixing it (as measured by your coding ability, knowledge of Django internals
@@ -59,38 +69,60 @@ no longer monopolized and somebody else can claim it.
If you've claimed a ticket and it's taking a long time (days or weeks) to code,
keep everybody updated by posting comments on the ticket. If you don't provide
regular updates, and you don't respond to a request for a progress report,
your claim on the ticket may be revoked. As always, more communication is
better than less communication!
your claim on the ticket may be revoked.
As always, more communication is better than less communication!
Which tickets should be claimed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Of course, going through the steps of claiming tickets is overkill in some
cases. In the case of small changes, such as typos in the documentation or
cases.
In the case of small changes, such as typos in the documentation or
small bugs that will only take a few minutes to fix, you don't need to jump
through the hoops of claiming tickets. Just submit your patch and be done with
it.
Of course, it is *always* acceptable, regardless whether someone has claimed it
or not, to submit patches to a ticket if you happen to have a patch ready.
.. _patch-style:
Patch style
-----------
* Make sure your code matches our :doc:`coding-style`.
Make sure that any contribution you do fulfills at least the following
requirements:
* Submit patches in the format returned by the ``svn diff`` command.
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also include a
:doc:`regression test <unit-tests>` to validate the behavior that has been
fixed and to prevent the problem from arising again. Also, if some tickets
are relevant to the code that you've written, mention the ticket numbers in
some comments in the test so that one can easily trace back the relevant
discussions after your patch gets committed, and the tickets get closed.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
documentation.
You can use either GitHub branches and pull requests or direct patches
to publish your work. If you use the Git workflow, then you should
announce your branch in the ticket by including a link to your branch.
When you think your work is ready to be merged in create a pull request.
See the :doc:`working-with-git` documentation for mode details.
You can also use patches in Trac. When using this style, follow these
guidelines.
* Submit patches in the format returned by the ``git diff`` command.
An exception is for code changes that are described more clearly in
plain English than in code. Indentation is the most common example; it's
hard to read patches when the only difference in code is that it's
indented.
Patches in ``git diff`` format are also acceptable.
* When creating patches, always run ``svn diff`` from the top-level
``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
``tests``, ``AUTHORS``, etc. This makes it easy for other people to
apply your patches.
* Attach patches to a ticket in the `ticket tracker`_, using the "attach
file" button. Please *don't* put the patch in the ticket description
or comment unless it's a single line patch.
@@ -98,21 +130,14 @@ Patch style
* Name the patch file with a ``.diff`` extension; this will let the ticket
tracker apply correct syntax highlighting, which is quite helpful.
Regardless of the way you submit your work, follow these steps.
* Make sure your code matches our :doc:`coding-style`.
* Check the "Has patch" box on the ticket details. This will make it
obvious that the ticket includes a patch, and it will add the ticket to
the `list of tickets with patches`_.
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also
include a regression test to validate the behavior that has been fixed
and to prevent the problem from arising again. Also, if some tickets are
relevant to the code that you've written, mention the ticket numbers in
some comments in the test so that one can easily trace back the relevant
discussions after your patch gets committed and the tickets get closed.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
documentation.
Non-trivial patches
-------------------
@@ -121,14 +146,14 @@ A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
that introduces Django functionality and makes some sort of design decision.
If you provide a non-trivial patch, include evidence that alternatives have
been discussed on `django-developers`_. If you're not sure whether your patch
should be considered non-trivial, just ask.
been discussed on `django-developers`_.
If you're not sure whether your patch should be considered non-trivial, just
ask.
Javascript patches
------------------
.. versionadded:: 1.2
Django's admin system leverages the jQuery framework to increase the
capabilities of the admin interface. In conjunction, there is an emphasis on
admin javascript performance and minimizing overall admin media file size.
@@ -140,9 +165,12 @@ code for future development (e.g. ``foo.js``), and a compressed version for
production use (e.g. ``foo.min.js``). Any links to the file in the codebase
should point to the compressed version.
Compressing JavaScript
~~~~~~~~~~~~~~~~~~~~~~
To simplify the process of providing optimized javascript code, Django
includes a handy script which should be used to create a "minified" version.
This script is located at ``django/contrib/admin/static/js/compress.py``.
This script is located at ``django/contrib/admin/static/admin/js/compress.py``.
Behind the scenes, ``compress.py`` is a front-end for Google's
`Closure Compiler`_ which is written in Java. However, the Closure Compiler
@@ -151,11 +179,11 @@ complete javascript patches will need to download and install the library
independently.
The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with
higher on Mac OS X. Note that Mac OS X 10.5 and earlier did not ship with
Java 1.6 by default, so it may be necessary to upgrade your Java installation
before the tool will be functional. Also note that even after upgrading Java,
the default ``/usr/bin/java`` command may remain linked to the previous Java
binary, so relinking that command may be necessary as well.
binary, so relinking that command may be necessary as well.)
Please don't forget to run ``compress.py`` and include the ``diff`` of the
minified scripts when submitting patches for Django's javascript.

6
docs/internals/contributing/writing-code/unit-tests.txt
View File

@@ -36,9 +36,7 @@ with this sample ``settings`` module, ``cd`` into the Django
./runtests.py --settings=test_sqlite
If you get an ``ImportError: No module named django.contrib`` error,
you need to add your install of Django to your ``PYTHONPATH``. For
more details on how to do this, read
:ref:`pointing-python-at-the-new-django-version`.
you need to add your install of Django to your ``PYTHONPATH``.
Using another ``settings`` module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -161,7 +159,7 @@ associated tests will be skipped.
.. _Textile: http://pypi.python.org/pypi/textile
.. _docutils: http://pypi.python.org/pypi/docutils/0.4
.. _setuptools: http://pypi.python.org/pypi/setuptools/
.. _memcached: http://www.danga.com/memcached/
.. _memcached: http://memcached.org/
.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
.. _selenium: http://pypi.python.org/pypi/selenium

253
docs/internals/contributing/writing-code/working-with-git.txt Normal file
View File

@@ -0,0 +1,253 @@
Working with Git and GitHub
===========================
This section explains how the community can contribute code to Django via pull
requests. If you're interested in how core developers handle them, see
:doc:`../committing-code`.
Below, we are going to show how to create a GitHub pull request containing the
changes for Trac ticket #xxxxx. By creating a fully-ready pull request you
will make the committers' job easier, meaning that your work is more likely to
be merged into Django.
You could also upload a traditional patch to Trac, but it's less practical for
reviews.
Installing Git
--------------
Django uses `Git`_ for its source control. You can `download
<http://git-scm.com/download>`_ Git, but it's often easier to install with
your operating system's package manager.
Django's `Git repository`_ is hosted on `GitHub`_, and it is recommended
that you also work using GitHub.
After installing Git the first thing you should do is setup your name and
email::
$ git config --global user.name "Your Real Name"
$ git config --global user.email "you@email.com"
Note that ``user.name`` should be your real name, not your GitHub nick. GitHub
should know the email you use in the ``user.email`` field, as this will be
used to associate your commits with your GitHub account.
.. _Git: http://git-scm.com/
.. _Git repository: https://github.com/django/django/
.. _GitHub: https://github.com/
Setting up local repository
---------------------------
When you have created your GitHub account, with the nick "github_nick", and
forked Django's repository, create a local copy of your fork::
git clone git@github.com:github_nick/django.git
This will create a new directory "django", containing a clone of your GitHub
repository.
Your GitHub repository will be called "origin" in Git.
You should also setup django/django as an "upstream" remote (that is, tell git
that the reference Django repository was the source of your fork of it)::
git remote add upstream git@github.com:django/django.git
git fetch upstream
You can add other remotes similarly, for example::
git remote add akaariai git@github.com:akaariai/django.git
Working on a ticket
-------------------
When working on a ticket create a new branch for the work, and base that work
on upstream/master::
git checkout -b ticket_xxxxx upstream/master
The -b flag creates a new branch for you locally. Don't hesitate to create new
branches even for the smallest things - that's what they are there for.
If instead you were working for a fix on the 1.4 branch, you would do::
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
Assume the work is carried on ticket_xxxxx branch. Make some changes and
commit them::
git commit
When writing the commit message, follow the :ref:`commit message
guidelines <committing-guidlines>` to ease the work of the committer. If
you're uncomfortable with English, try at least to describe precisely what the
commit does.
If you need to do additional work on your branch, commit as often as
necessary::
git commit -m 'Added two more tests for edge cases'
Publishing work
~~~~~~~~~~~~~~~
You can publish your work on GitHub just by doing::
git push origin ticket_xxxxx
When you go to your GitHub page you will notice a new branch has been created.
If you are working on a Trac ticket, you should mention in the ticket that
your work is available from branch ticket_xxxxx of your github repo. Include a
link to your branch.
Note that the above branch is called a "topic branch" in Git parlance. You are
free to rewrite the history of this branch, by using ``git rebase`` for
example. Other people shouldn't base their work on such a branch, because
their clone would become corrupt when you edit commits.
There are also "public branches". These are branches other people are supposed
to fork, so the history of these branches should never change. Good examples
of public branches are the ``master`` and ``stable/A.B.x`` branches in the
django/django repository.
When you think your work is ready to be pulled into Django, you should create
a pull request at GitHub. A good pull request means:
* commits with one logical change in each, following the
:doc:`coding style <coding-style>`,
* well-formed messages for each commit: a summary line and then paragraphs
wrapped at 72 characters thereafter -- see the :ref:`committing guidelines
<committing-guidlines>` for more details,
* documentation and tests, if needed -- actually tests are always needed,
except for documentation changes.
The test suite must pass and the documentation must build without warnings.
Once you have created your pull request, you should add a comment in the
related Trac ticket explaining what you've done. In particular you should note
the environment in which you ran the tests, for instance: "all tests pass
under SQLite and MySQL".
Pull requests at GitHub have only two states: open and closed. The committer
who will deal with your pull request has only two options: merge it or close
it. For this reason, it isn't useful to make a pull request until the code is
ready for merging -- or sufficiently close that a committer will finish it
himself.
Rebasing branches
~~~~~~~~~~~~~~~~~
In the example above you created two commits, the "Fixed ticket_xxxxx" commit
and "Added two more tests" commit.
We do not want to have the entire history of your working process in your
repository. Your commit "Added two more tests" would be unhelpful noise.
Instead, we would rather only have one commit containing all your work.
To rework the history of your branch you can squash the commits into one by
using interactive rebase::
git rebase -i HEAD~2
The HEAD~2 above is shorthand for two latest commits. The above command
will open an editor showing the two commits, prefixed with the word "pick".
Change the second line to "squash" instead. This will keep the
first commit, and squash the second commit into the first one. Save and quit
the editor. A second editor window should open, so you can reword the
commit message for the commit now that it includes both your steps.
You can also use the "edit" option in rebase. This way you can change a single
commit, for example to fix a typo in a docstring::
git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.
If your topic branch is already published at GitHub, for example if you're
making minor changes to take into account a review, you will need to force-
push the changes::
git push -f origin ticket_xxxxx
Note that this will rewrite history of ticket_xxxxx - if you check the commit
hashes before and after the operation at GitHub you will notice that the
commit hashes do not match any more. This is acceptable, as the branch is merely
a topic branch, and nobody should be basing their work on it.
After upstream has changed
~~~~~~~~~~~~~~~~~~~~~~~~~~
When upstream (django/django) has changed, you should rebase your work. To
do this, use::
git fetch upstream
git rebase
The work is automatically rebased using the branch you forked on, in the
example case using upstream/master.
The rebase command removes all your local commits temporarily, applies the
upstream commits, and then applies your local commits again on the work.
If there are merge conflicts you will need to resolve them and then use ``git
rebase --continue``. At any point you can use ``git rebase --abort`` to return
to the original state.
Note that you want to *rebase* on upstream, not *merge* the upstream.
The reason for this is that by rebasing, your commits will always be *on
top of* the upstream's work, not *mixed in with* the changes in the upstream.
This way your branch will contain only commits related to its topic, which
makes squashing easier.
After review
------------
It is unusual to get any non-trivial amount of code into core without changes
requested by reviewers. In this case, it is often a good idea to add the
changes as one incremental commit to your work. This allows the reviewer to
easily check what changes you have done.
In this case, do the changes required by the reviewer. Commit as often as
necessary. Before publishing the changes, rebase your work. If you added two
commits, you would run::
git rebase -i HEAD~2
Squash the second commit into the first. Write a commit message along the lines of::
Made changes asked in review by <reviewer>
- Fixed whitespace errors in foobar
- Reworded the docstring of bar()
Finally push your work back to your GitHub repository. Since you didn't touch
the public commits during the rebase, you should not need to force-push::
git push origin ticket_xxxxx
Your pull request should now contain the new commit too.
Note that the committer is likely to squash the review commit into the previous commit
when committing the code.
Summary
-------
* Work on GitHub if you can.
* Announce your work on the Trac ticket by linking to your GitHub branch.
* When you have something ready, make a pull request.
* Make your pull requests as good as you can.
* When doing fixes to your work, use ``git rebase -i`` to squash the commits.
* When upstream has changed, do ``git fetch upstream; git rebase``.

16
docs/internals/contributing/writing-documentation.txt
View File

@@ -18,6 +18,22 @@ Documentation changes generally come in two forms:
This section explains how writers can craft their documentation changes
in the most useful and least error-prone ways.
Getting the raw documentation
-----------------------------
Though Django's documentation is intended to be read as HTML at
https://docs.djangoproject.com/, we edit it as a collection of text files for
maximum flexibility. These files live in the top-level ``docs/`` directory of a
Django release.
If you'd like to start contributing to our docs, get the development version of
Django from the source code repository
(see :ref:`installing-development-version`). The development version has the
latest-and-greatest documentation, just as it has latest-and-greatest code.
Generally, we only revise documentation in the development version, as our
policy is to freeze documentation for existing releases (see
:ref:`differences-between-doc-versions`).
Getting started with Sphinx
---------------------------

11
docs/internals/deprecation.txt
View File

@@ -134,7 +134,7 @@ these changes.
* The function-based generic view modules will be removed in favor of their
class-based equivalents, outlined :doc:`here
</topics/class-based-views>`:
</topics/class-based-views/index>`:
* The :class:`~django.core.servers.basehttp.AdminMediaHandler` will be
removed. In its place use
@@ -221,7 +221,7 @@ these changes.
the 1.4 release. They will be removed.
* The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
refactored to use class based views with pluggable backends in 1.4.
refactored to use class-based views with pluggable backends in 1.4.
The previous implementation will be removed.
* Legacy ways of calling
@@ -276,6 +276,13 @@ these changes.
* The function ``django.utils.itercompat.product`` will be removed. The Python
builtin version should be used instead.
* Auto-correction of INSTALLED_APPS and TEMPLATE_DIRS settings when they are
specified as a plain string instead of a tuple will be removed and raise an
exception.
* The ``mimetype`` argument to :class:`~django.http.HttpResponse` ``__init__``
will be removed (``content_type`` should be used instead).
2.0
---

237
docs/internals/git.txt Normal file
View File

@@ -0,0 +1,237 @@
=================================
The Django source code repository
=================================
When deploying a Django application into a real production environment, you
will almost always want to use `an official packaged release of Django`_.
However, if you'd like to try out in-development code from an upcoming release
or contribute to the development of Django, you'll need to obtain a clone of
Django's source code repository.
This document covers the way the code repository is laid out and how to work
with and find things in it.
.. _an official packaged release of Django: https://www.djangoproject.com/download/
High-level overview
===================
The Django source code repository uses `Git`_ to track changes to the code
over time, so you'll need a copy of the Git client (a program called ``git``)
on your computer, and you'll want to familiarize yourself with the basics of
how Git works.
Git's web site offers downloads for various operating systems. The site also
contains vast amounts of `documentation`_.
The Django Git repository is located online at `github.com/django/django
<https://github.com/django/django>`_. It contains the full source code for all
Django releases, which you can browse online.
The Git repository includes several `branches`_:
* ``master`` contains the main in-development code which will become
the next packaged release of Django. This is where most development
activity is focused.
* ``stable/A.B.x`` are the maintenance branches. They are used to support
older versions of Django.
* ``soc20XX/<project>`` branches were used by students who worked on Django
during the 2009 and 2010 Google Summer of Code programs.
* ``attic/<project>`` branches were used to develop major or experimental new
features without affecting the rest of Django's code.
The Git repository also contains `tags`_. These are the exact revisions from
which packaged Django releases were produced, since version 1.0.
The source code for the `Djangoproject.com <https://www.djangoproject.com/>`_ web
site can be found at `github.com/django/djangoproject.com
<https://github.com/django/djangoproject.com>`_.
.. _Git: http://git-scm.com/
.. _documentation: http://git-scm.com/documentation
.. _branches: https://github.com/django/django/branches
.. _tags: https://github.com/django/django/tags
The master branch
=================
If you'd like to try out the in-development code for the next release of
Django, or if you'd like to contribute to Django by fixing bugs or developing
new features, you'll want to get the code from the master branch.
Note that this will get *all* of Django: in addition to the top-level
``django`` module containing Python code, you'll also get a copy of Django's
documentation, test suite, packaging scripts and other miscellaneous bits.
Django's code will be present in your clone as a directory named
``django``.
To try out the in-development code with your own applications, simply place
the directory containing your clone on your Python import path. Then
``import`` statements which look for Django will find the ``django`` module
within your clone.
If you're going to be working on Django's code (say, to fix a bug or
develop a new feature), you can probably stop reading here and move
over to :doc:`the documentation for contributing to Django
</internals/contributing/index>`, which covers things like the preferred
coding style and how to generate and submit a patch.
Other branches
==============
Django uses branches for two main purposes:
1. Development of major or experimental features, to keep them from
affecting progress on other work in master.
2. Security and bugfix support for older releases of Django, during
their support lifetimes.
Feature-development branches
----------------------------
.. admonition:: Historical information
Since Django moved to Git in 2012, anyone can clone the repository and
create his own branches, alleviating the need for official branches in the
source code repository.
The following section is mostly useful if you're exploring the repository's
history, for example if you're trying to understand how some features were
designed.
Feature-development branches tend by their nature to be temporary. Some
produce successful features which are merged back into Django's master to
become part of an official release, but others do not; in either case there
comes a time when the branch is no longer being actively worked on by any
developer. At this point the branch is considered closed.
Unfortunately, Django used to be maintained with the Subversion revision
control system, that has no standard way of indicating this. As a workaround,
branches of Django which are closed and no longer maintained were moved into
``attic``.
For reference, the following are branches whose code eventually became
part of Django itself, and so are no longer separately maintained:
* ``boulder-oracle-sprint``: Added support for Oracle databases to
Django's object-relational mapper. This has been part of Django
since the 1.0 release.
* ``gis``: Added support for geographic/spatial queries to Django's
object-relational mapper. This has been part of Django since the 1.0
release, as the bundled application ``django.contrib.gis``.
* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
Django. This has been part of Django since the 0.90 release.
* ``magic-removal``: A major refactoring of both the internals and
public APIs of Django's object-relational mapper. This has been part
of Django since the 0.95 release.
* ``multi-auth``: A refactoring of :doc:`Django's bundled
authentication framework </topics/auth>` which added support for
:ref:`authentication backends <authentication-backends>`. This has
been part of Django since the 0.95 release.
* ``new-admin``: A refactoring of :doc:`Django's bundled
administrative application </ref/contrib/admin/index>`. This became part of
Django as of the 0.91 release, but was superseded by another
refactoring (see next listing) prior to the Django 1.0 release.
* ``newforms-admin``: The second refactoring of Django's bundled
administrative application. This became part of Django as of the 1.0
release, and is the basis of the current incarnation of
``django.contrib.admin``.
* ``queryset-refactor``: A refactoring of the internals of Django's
object-relational mapper. This became part of Django as of the 1.0
release.
* ``unicode``: A refactoring of Django's internals to consistently use
Unicode-based strings in most places within Django and Django
applications. This became part of Django as of the 1.0 release.
When Django moved from SVN to Git, the information about branch merges wasn't
preserved in the source code repository. This means that the ``master`` branch
of Django doesn't contain merge commits for the above branches.
However, this information is `available as a grafts file`_. You can restore it
by putting the following lines in ``.git/info/grafts`` in your local clone::
ac64e91a0cadc57f4bc5cd5d66955832320ca7a1 553a20075e6991e7a60baee51ea68c8adc520d9a 0cb8e31823b2e9f05c4ae868c19f5f38e78a5f2e
79e68c225b926302ebb29c808dda8afa49856f5c d0f57e7c7385a112cb9e19d314352fc5ed5b0747 aa239e3e5405933af6a29dac3cf587b59a099927
5cf8f684237ab5addaf3549b2347c3adf107c0a7 cb45fd0ae20597306cd1f877efc99d9bd7cbee98 e27211a0deae2f1d402537f0ebb64ad4ccf6a4da
f69cf70ed813a8cd7e1f963a14ae39103e8d5265 d5dbeaa9be359a4c794885c2e9f1b5a7e5e51fb8 d2fcbcf9d76d5bb8a661ee73dae976c74183098b
aab3a418ac9293bb4abd7670f65d930cb0426d58 4ea7a11659b8a0ab07b0d2e847975f7324664f10 adf4b9311d5d64a2bdd58da50271c121ea22e397
ff60c5f9de3e8690d1e86f3e9e3f7248a15397c8 7ef212af149540aa2da577a960d0d87029fd1514 45b4288bb66a3cda401b45901e85b645674c3988
9dda4abee1225db7a7b195b84c915fdd141a7260 4fe5c9b7ee09dc25921918a6dbb7605edb374bc9 3a7c14b583621272d4ef53061287b619ce3c290d
a19ed8aea395e8e07164ff7d85bd7dff2f24edca dc375fb0f3b7fbae740e8cfcd791b8bccb8a4e66 42ea7a5ce8aece67d16c6610a49560c1493d4653
9c52d56f6f8a9cdafb231adf9f4110473099c9b5 c91a30f00fd182faf8ca5c03cd7dbcf8b735b458 4a5c5c78f2ecd4ed8859cd5ac773ff3a01bccf96
953badbea5a04159adbfa970f5805c0232b6a401 4c958b15b250866b70ded7d82aa532f1e57f96ae 5664a678b29ab04cad425c15b2792f4519f43928
471596fc1afcb9c6258d317c619eaf5fd394e797 4e89105d64bb9e04c409139a41e9c7aac263df4c 3e9035a9625c8a8a5e88361133e87ce455c4fc13
9233d0426537615e06b78d28010d17d5a66adf44 6632739e94c6c38b4c5a86cf5c80c48ae50ac49f 18e151bc3f8a85f2766d64262902a9fcad44d937
.. _available as a grafts file: https://github.com/ramiro/django-git-grafts
Additionally, the following branches are closed, but their code was
never merged into Django and the features they aimed to implement
were never finished:
* ``full-history``
* ``generic-auth``
* ``multiple-db-support``
* ``per-object-permissions``
* ``schema-evolution``
* ``schema-evolution-ng``
* ``search-api``
* ``sqlalchemy``
All of the above-mentioned branches now reside in ``attic``.
Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature
branches, used for Google Summer of Code projects.
Support and bugfix branches
---------------------------
In addition to fixing bugs in current master, the Django project provides
official bugfix support for the most recent released version of Django, and
security support for the two most recently-released versions of Django.
This support is provided via branches in which the necessary bug or security
fixes are applied; the branches are then used as the basis for issuing bugfix
or security releases.
These branches can be found in the repository as ``stable/A.B.x``
branches, and new branches will be created there after each new Django
release.
For example, shortly after the release of Django 1.0, the branch
``stable/1.0.x`` was created to receive bug fixes, and shortly after the
release of Django 1.1 the branch ``stable/1.1.x`` was created.
Official support for the above mentioned releases has expired, and so they no
longer receive direct maintenance from the Django project. However, the
branches continue to exist and interested community members have occasionally
used them to provide unofficial support for old Django releases.
Tags
====
Each Django release is tagged and signed by Django's release manager.
The tags can be found on GitHub's `tags`_ page.
.. _tags: https://github.com/django/django/tags

3
docs/internals/index.txt
View File

@@ -18,6 +18,7 @@ the hood".
contributing/index
committers
security
release-process
deprecation
svn
git

24
docs/internals/release-process.txt
View File

@@ -31,10 +31,14 @@ Since version 1.0, Django's release numbering works as follows:
These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth``
alpha/beta/release candidate of version ``A.B``.
In Subversion, each Django release will be tagged under ``tags/releases``. If
it's necessary to release a bug fix release or a security release that doesn't
come from the trunk, we'll copy that tag to ``branches/releases`` to make the
bug fix release.
In git, each Django release will have a tag indicating its version
number, signed with the Django release key. Additionally, each release
series (X.Y) has its own branch, and bugfix/security releases will be
issued from those branches.
For more information about how the Django project issues new releases
for security purposes, please see :doc:`our security policies
<security>`.
Major releases
--------------
@@ -84,6 +88,8 @@ person will be responsible for making sure that bug fixes are applied to both
trunk and the maintained micro-release branch. This person will also work with
the release manager to decide when to release the micro releases.
.. _backwards-compatibility-policy:
Supported versions
==================
@@ -196,15 +202,15 @@ and an rc complete with string freeze two weeks before the end of the schedule.
Bug-fix releases
----------------
After a minor release (e.g. 1.1), the previous release will go into bug-fix
After a minor release (e.g. 1.1), the previous release will go into bugfix
mode.
A branch will be created of the form ``branches/releases/1.0.X`` to track
bug-fixes to the previous release. Critical bugs fixed on trunk must
*also* be fixed on the bug-fix branch; this means that commits need to cleanly
bugfixes to the previous release. Critical bugs fixed on trunk must
*also* be fixed on the bugfix branch; this means that commits need to cleanly
separate bug fixes from feature additions. The developer who commits a fix to
trunk will be responsible for also applying the fix to the current bug-fix
branch. Each bug-fix branch will have a maintainer who will work with the
trunk will be responsible for also applying the fix to the current bugfix
branch. Each bugfix branch will have a maintainer who will work with the
committers to keep them honest on backporting bug fixes.
How this all fits together

215
docs/internals/security.txt Normal file
View File

@@ -0,0 +1,215 @@
==========================
Django's security policies
==========================
Django's development team is strongly committed to responsible
reporting and disclosure of security-related issues. As such, we've
adopted and follow a set of policies which conform to that ideal and
are geared toward allowing us to deliver timely security updates to
the official distribution of Django, as well as to third-party
distributions.
.. _reporting-security-issues:
Reporting security issues
=========================
**Short version: please report security issues by emailing
security@djangoproject.com**.
Most normal bugs in Django are reported to `our public Trac
instance`_, but due to the sensitive nature of security issues, we ask
that they *not* be publicly reported in this fashion.
Instead, if you believe you've found something in Django which has
security implications, please send a description of the issue via
email to ``security@djangoproject.com``. Mail sent to that address
reaches a subset of the core development team, who can forward
security issues into the private committers' mailing list for broader
discussion if needed.
You can send encrypted email to this address; the public key ID for
``security@djangoproject.com`` is ``0xfcb84b8d1d17f80b``, and this
public key is available from most commonly-used keyservers.
Once you've submitted an issue via email, you should receive an
acknowledgment from a member of the Django development team within 48
hours, and depending on the action to be taken, you may receive
further followup emails.
.. _our public Trac instance: https://code.djangoproject.com/query
.. _security-support:
Supported versions
==================
At any given time, the Django team provides official security support
for several versions of Django:
* The `master development branch`_, hosted on GitHub, which will
become the next release of Django, receives security support.
* The two most recent Django release series receive security
support. For example, during the development cycle leading to the
release of Django 1.5, support will be provided for Django 1.4 and
Django 1.3. Upon the release of Django 1.5, Django 1.3's security
support will end.
When new releases are issued for security reasons, the accompanying
notice will include a list of affected versions. This list is
comprised solely of *supported* versions of Django: older versions may
also be affected, but we do not investigate to determine that, and
will not issue patches or new releases for those versions.
.. _master development branch: https://github.com/django/django/
.. _security-disclosure:
How Django discloses security issues
====================================
Our process for taking a security issue from private discussion to
public disclosure involves multiple steps.
Approximately one week before full public disclosure, we will send
advance notification of the issue to a list of people and
organizations, primarily composed of operating-system vendors and
other distributors of Django. This notification will consist of an
email message, signed with the Django release key, containing:
* A full description of the issue and the affected versions of Django.
* The steps we will be taking to remedy the issue.
* The patch(es), if any, that will be applied to Django.
* The date on which the Django team will apply these patches, issue
new releases and publicy disclose the issue.
Simultaneously, the reporter of the issue will receive notification of
the date on which we plan to take the issue public.
On the day of disclosure, we will take the following steps:
1. Apply the relevant patch(es) to Django's codebase. The commit
messages for these patches will indicate that they are for security
issues, but will not describe the issue in any detail; instead,
they will warn of upcoming disclosure.
2. Issue the relevant release(s), by placing new packages on `the
Python Package Index`_ and on the Django website, and tagging the
new release(s) in Django's git repository.
3. Post a public entry on `the official Django development blog`_,
describing the issue and its resolution in detail, pointing to the
relevant patches and new releases, and crediting the reporter of
the issue (if the reporter wishes to be publicly identified).
.. _the Python Package Index: http://pypi.python.org/pypi
.. _the official Django development blog: https://www.djangoproject.com/weblog/
If a reported issue is believed to be particularly time-sensitive --
due to a known exploit in the wild, for example -- the time between
advance notification and public disclosure may be shortened
considerably.
Additionally, if we have reason to believe that an issue reported to
us affects other frameworks or tools in the Python/web ecosystem, we
may privately contact and discuss those issues with the appropriate
maintainers, and coordinate our own disclosure and resolution with
theirs.
.. _security-notifications:
Who receives advance notification
=================================
The full list of people and organizations who receive advance
notification of security issues is not and will not be made public.
We also aim to keep this list as small as effectively possible, in
order to better manage the flow of confidential information prior to
disclosure. As such, our notification list is *not* simply a list of
users of Django, and merely being a user of Django is not sufficient
reason to be placed on the notification list.
In broad terms, recipients of security notifications fall into three
groups:
1. Operating-system vendors and other distributors of Django who
provide a suitably-generic (i.e., *not* an individual's personal
email address) contact address for reporting issues with their
Django package, or for general security reporting. In either case,
such addresses **must not** forward to public mailing lists or bug
trackers. Addresses which forward to the private email of an
individual maintainer or security-response contact are acceptable,
although private security trackers or security-response groups are
strongly preferred.
2. On a case-by-case basis, individual package maintainers who have
demonstrated a commitment to responding to and responsibly acting
on these notifications.
3. On a case-by-case basis, other entities who, in the judgment of the
Django development team, need to be made aware of a pending
security issue. Typically, membership in this group will consist of
some of the largest and/or most likely to be severely impacted
known users or distributors of Django, and will require a
demonstrated ability to responsibly receive, keep confidential and
act on these notifications.
Additionally, a maximum of six days prior to disclosure, notification
will be sent to the ``distros@vs.openwall.org`` mailing list, whose
membership includes representatives of most major open-source
operating system vendors.
Requesting notifications
========================
If you believe that you, or an organization you are authorized to
represent, fall into one of the groups listed above, you can ask to be
added to Django's notification list by emailing
``security@djangoproject.com``. Please use the subject line "Security
notification request".
Your request **must** include the following information:
* Your full, real name and the name of the organization you represent,
if applicable, as well as your role within that organization.
* A detailed explanation of how you or your organization fit at least
one set of criteria listed above.
* A detailed explanation of why you are requesting security
notifications. Again, please keep in mind that this is *not* simply
a list for users of Django, and the overwhelming majority of users
of Django should not request notifications and will not be added to
our notification list if they do.
* The email address you would like to have added to our notification
list.
* An explanation of who will be receiving/reviewing mail sent to that
address, as well as information regarding any automated actions that
will be taken (i.e., filing of a confidential issue in a bug
tracker).
* For individuals, the ID of a public key associated with your address
which can be used to verify email received from you and encrypt
email sent to you, as needed.
Once submitted, your request will be considered by the Django
development team; you will receive a reply notifying you of the result
of your request within 30 days.
Please also bear in mind that for any individual or organization,
receiving security notifications is a privilege granted at the sole
discretion of the Django development team, and that this privilege can
be revoked at any time, with or without explanation.
If you are added to the notification list, security-related emails
will be sent to you by Django's release manager, and all notification
emails will be signed with the same key used to sign Django releases;
that key has the ID ``0x3684C0C08C8B2AE1``, and is available from most
commonly-used keyservers.

254
docs/internals/svn.txt
View File

@@ -1,254 +0,0 @@
=================================
The Django source code repository
=================================
When deploying a Django application into a real production
environment, you will almost always want to use `an official packaged
release of Django`_. However, if you'd like to try out in-development
code from an upcoming release or contribute to the development of
Django, you'll need to obtain a checkout from Django's source code
repository. This document covers the way the code repository is laid
out and how to work with and find things in it.
.. _an official packaged release of Django: https://www.djangoproject.com/download/
High-level overview
===================
The Django source code repository uses `Subversion`_ to track changes
to the code over time, so you'll need a copy of the Subversion client
(a program called ``svn``) on your computer, and you'll want to
familiarize yourself with the basics of how Subversion
works. Subversion's Web site offers downloads for various operating
systems, and `a free online book`_ is available to help you get up to
speed with using Subversion.
The Django Subversion repository is located online at
`code.djangoproject.com/svn <https://code.djangoproject.com/svn/>`_. `A
friendly Web-based interface for browsing the code`_ is also
available, though when using Subversion you'll always want to use the
repository address instead. At the top level of the repository are two
directories: ``django`` contains the full source code for all Django
releases, while ``djangoproject.com`` contains the source code and
templates for the `djangoproject.com <https://www.djangoproject.com/>`_
Web site. For trying out in-development Django code, or contributing
to Django, you'll always want to check out code from some location in
the ``django`` directory.
Inside the ``django`` directory, Django's source code is organized
into three areas:
* ``branches`` contains branched copies of Django's code, which are
(or were) maintained for various purposes. Some branches exist to
provide a place to develop major or experimental new features
without affecting the rest of Django's code, while others serve to
provide bug fixes or support for older Django releases.
* ``tags`` contains snapshots of Django's code at various important
points in its history; mostly these are the exact revisions from
which packaged Django releases were produced.
* ``trunk`` contains the main in-development code which will become
the next packaged release of Django, and is where most development
activity is focused.
.. _Subversion: http://subversion.tigris.org/
.. _a free online book: http://svnbook.red-bean.com/
.. _A friendly Web-based interface for browsing the code: https://code.djangoproject.com/browser/
Working with Django's trunk
===========================
If you'd like to try out the in-development code for the next release
of Django, or if you'd like to contribute to Django by fixing bugs or
developing new features, you'll want to get the code from trunk. You
can get a complete copy of this code (a "Subversion checkout") by
typing::
svn co https://code.djangoproject.com/svn/django/trunk/
Note that this will get *all* of Django: in addition to the top-level
``django`` module containing Python code, you'll also get a copy of
Django's documentation, unit-test suite, packaging scripts and other
miscellaneous bits. Django's code will be present in your checkout as
a directory named ``django``.
To try out the in-development trunk code with your own applications,
simply place the directory containing your checkout on your Python
import path. Then ``import`` statements which look for Django will find
the ``django`` module within your checkout.
If you're going to be working on Django's code (say, to fix a bug or
develop a new feature), you can probably stop reading here and move
over to :doc:`the documentation for contributing to Django
</internals/contributing/index>`, which covers things like the preferred
coding style and how to generate and submit a patch.
Branches
========
Django uses branches for two main purposes:
1. Development of major or experimental features, to keep them from
affecting progress on other work in trunk.
2. Security and bug-fix support for older releases of Django, during
their support lifetimes.
Feature-development branches
----------------------------
Feature-development branches tend by their nature to be
temporary. Some produce successful features which are merged back into
Django's trunk to become part of an official release, but others do
not; in either case there comes a time when the branch is no longer
being actively worked on by any developer. At this point the branch is
considered closed.
Unfortunately, Subversion has no standard way of indicating this. As a
workaround, branches of Django which are closed and no longer
maintained are moved into the directory ``django/branches/attic``.
For reference, the following are branches whose code eventually became
part of Django itself, and so are no longer separately maintained:
* ``boulder-oracle-sprint``: Added support for Oracle databases to
Django's object-relational mapper. This has been part of Django
since the 1.0 release.
* ``gis``: Added support for geographic/spatial queries to Django's
object-relational mapper. This has been part of Django since the 1.0
release, as the bundled application ``django.contrib.gis``.
* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
Django. This has been part of Django since the 0.90 release.
* ``magic-removal``: A major refactoring of both the internals and
public APIs of Django's object-relational mapper. This has been part
of Django since the 0.95 release.
* ``multi-auth``: A refactoring of :doc:`Django's bundled
authentication framework </topics/auth>` which added support for
:ref:`authentication backends <authentication-backends>`. This has
been part of Django since the 0.95 release.
* ``new-admin``: A refactoring of :doc:`Django's bundled
administrative application </ref/contrib/admin/index>`. This became part of
Django as of the 0.91 release, but was superseded by another
refactoring (see next listing) prior to the Django 1.0 release.
* ``newforms-admin``: The second refactoring of Django's bundled
administrative application. This became part of Django as of the 1.0
release, and is the basis of the current incarnation of
``django.contrib.admin``.
* ``queryset-refactor``: A refactoring of the internals of Django's
object-relational mapper. This became part of Django as of the 1.0
release.
* ``unicode``: A refactoring of Django's internals to consistently use
Unicode-based strings in most places within Django and Django
applications. This became part of Django as of the 1.0 release.
Additionally, the following branches are closed, but their code was
never merged into Django and the features they aimed to implement
were never finished:
* ``full-history``
* ``generic-auth``
* ``multiple-db-support``
* ``per-object-permissions``
* ``schema-evolution``
* ``schema-evolution-ng``
* ``search-api``
* ``sqlalchemy``
All of the above-mentioned branches now reside in
``django/branches/attic``.
Support and bugfix branches
---------------------------
In addition to fixing bugs in current trunk, the Django project
provides official bug-fix support for the most recent released version
of Django, and security support for the two most recently-released
versions of Django. This support is provided via branches in which the
necessary bug or security fixes are applied; the branches are then
used as the basis for issuing bugfix or security releases.
As of the Django 1.0 release, these branches can be found in the
repository in the directory ``django/branches/releases``, and new branches
will be created there approximately one month after each new Django
release. For example, shortly after the release of Django 1.0, the
branch ``django/branches/releases/1.0.X`` was created to receive bug
fixes, and shortly after the release of Django 1.1 the branch
``django/branches/releases/1.1.X`` was created.
Prior to the Django 1.0 release, these branches were maintained within
the top-level ``django/branches`` directory, and so the following
branches exist there and provided support for older Django releases:
* ``0.90-bugfixes``
* ``0.91-bugfixes``
* ``0.95-bugfixes``
* ``0.96-bugfixes``
Official support for those releases has expired, and so they no longer
receive direct maintenance from the Django project. However, the
branches continue to exist and interested community members have
occasionally used them to provide unofficial support for old Django
releases.
Tags
====
The directory ``django/tags`` within the repository contains complete
copies of the Django source code as it existed at various points in
its history. These "tagged" copies of Django are *never* changed or
updated; new tags may be added as needed, but once added they are
considered read-only and serve as useful guides to Django's
development history.
Within ``django/tags/releases`` are copies of the code which formed each
packaged release of Django, and each tag is named with the version
number of the release to which it corresponds. So, for example,
``django/tags/releases/1.1`` is a complete copy of the code which was
packaged as the Django 1.1 release.
Within ``django/tags/notable_moments`` are copies of the Django code from
points which do not directly correspond to releases, but which are
nonetheless important historical milestones for Django
development. The current "notable moments" marked there are:
* ``ipo``: Django's code as it existed at the moment Django was first
publicly announced in 2005.
* ``pre-magic-removal``: The state of Django's code just before the
merging of the ``magic-removal`` branch (described above), which
significantly updated Django's object-relational mapper.
* ``pre-newforms-admin``: The state of Django's code just before the
merging of the ``newforms-admin`` branch (see above), which
significantly updated Django's bundled administrative application.
* Tags corresponding to each of the alpha, beta and release-candidate
packages in the run up to the Django 1.0 release.

BIN
docs/intro/_images/admin12t.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/intro/_images/admin15t.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

5
docs/intro/install.txt
View File

@@ -10,7 +10,7 @@ Install Python
--------------
Being a Python Web framework, Django requires Python. It works with any Python
version from 2.6 to 2.7 (due to backwards incompatibilities in Python 3.0,
version from 2.6.5 to 2.7 (due to backwards incompatibilities in Python 3.0,
Django does not currently work with Python 3.0; see :doc:`the Django FAQ
</faq/install>` for more information on supported Python versions and the 3.0
transition), these versions of Python include a lightweight database called
@@ -84,8 +84,9 @@ Then at the Python prompt, try to import Django::
>>> import django
>>> print(django.get_version())
1.4
1.5
You may have another version of Django installed.
That's it!
----------

2
docs/intro/overview.txt
View File

@@ -279,7 +279,7 @@ Here's what the "base.html" template might look like:
<title>{% block title %}{% endblock %}</title>
</head>
<body>
<img src="sitelogo.gif" alt="Logo" />
<img src="sitelogo.png" alt="Logo" />
{% block content %}{% endblock %}
</body>
</html>

10
docs/intro/tutorial01.txt
View File

@@ -52,7 +52,8 @@ code, then run the following command:
django-admin.py startproject mysite
This will create a ``mysite`` directory in your current directory.
This will create a ``mysite`` directory in your current directory. If it didn't
work, see :doc:`Troubleshooting </faq/troubleshooting>`.
.. admonition:: Script name may differ in distribution packages
@@ -78,13 +79,6 @@ This will create a ``mysite`` directory in your current directory.
``django`` (which will conflict with Django itself) or ``test`` (which
conflicts with a built-in Python package).
:doc:`django-admin.py </ref/django-admin>` should be on your system path if you
installed Django via ``python setup.py``. If it's not on your path, you can find
it in ``site-packages/django/bin``, where ``site-packages`` is a directory
within your Python installation. Consider symlinking to :doc:`django-admin.py
</ref/django-admin>` from some place on your path, such as
:file:`/usr/local/bin`.
.. admonition:: Where should this code live?
If your background is in PHP, you're probably used to putting code under the

31
docs/intro/tutorial02.txt
View File

@@ -113,8 +113,8 @@ Just one thing to do: We need to tell the admin that ``Poll``
objects have an admin interface. To do this, create a file called
``admin.py`` in your ``polls`` directory, and edit it to look like this::
from polls.models import Poll
from django.contrib import admin
from polls.models import Poll
admin.site.register(Poll)
@@ -283,6 +283,9 @@ It'd be better if you could add a bunch of Choices directly when you create the
Remove the ``register()`` call for the ``Choice`` model. Then, edit the ``Poll``
registration code to read::
from django.contrib import admin
from polls.models import Choice, Poll
class ChoiceInline(admin.StackedInline):
model = Choice
extra = 3
@@ -308,6 +311,14 @@ It works like this: There are three slots for related Choices -- as specified
by ``extra`` -- and each time you come back to the "Change" page for an
already-created object, you get another three extra slots.
At the end of the three current slots you will find an "Add another Choice"
link. If you click on it, a new slot will be added. If you want to remove the
added slot, you can click on the X to the top right of the added slot. Note
that you can't remove the original three slots. This image shows an added slot:
.. image:: _images/admin15t.png
:alt: Additional slot added dynamically
One small problem, though. It takes a lot of screen space to display all the
fields for entering related ``Choice`` objects. For that reason, Django offers a
tabular way of displaying inline related objects; you just need to change
@@ -319,9 +330,12 @@ the ``ChoiceInline`` declaration to read::
With that ``TabularInline`` (instead of ``StackedInline``), the
related objects are displayed in a more compact, table-based format:
.. image:: _images/admin12.png
.. image:: _images/admin12t.png
:alt: Add poll page now has more compact choices
Note that there is an extra "Delete?" column that allows removing rows added
using the "Add Another Choice" button and rows that have already been saved.
Customize the admin change list
===============================
@@ -442,6 +456,19 @@ above, then copy ``django/contrib/admin/templates/admin/base_site.html`` to
``/home/my_username/mytemplates/admin/base_site.html``. Don't forget that
``admin`` subdirectory.
.. admonition:: Where are the Django source files?
If you have difficulty finding where the Django source files are located
on your system, run the following command:
.. code-block:: bash
python -c "
import sys
sys.path = sys.path[1:]
import django
print(django.__path__)"
Then, just edit the file and replace the generic Django text with your own
site's name as you see fit.

28
docs/intro/tutorial03.txt
View File

@@ -533,5 +533,33 @@ under "/content/polls/", or any other path root, and the app will still work.
All the poll app cares about is its relative path, not its absolute path.
Removing hardcoded URLs in templates
------------------------------------
Remember, when we wrote the link to a poll in our template, the link was
partially hardcoded like this:
.. code-block:: html+django
<li><a href="/polls/{{ poll.id }}/">{{ poll.question }}</a></li>
To use the decoupled URLs we've just introduced, replace the hardcoded link
with the :ttag:`url` template tag:
.. code-block:: html+django
<li><a href="{% url 'polls.views.detail' poll.id %}">{{ poll.question }}</a></li>
.. note::
If ``{% url 'polls.views.detail' poll.id %}`` (with quotes) doesn't work,
but ``{% url polls.views.detail poll.id %}`` (without quotes) does, that
means you're using a version of Django ≤ 1.4. In this case, add the
following declaration at the top of your template:
.. code-block:: html+django
{% load url from future %}
When you're comfortable with writing views, read :doc:`part 4 of this tutorial
</intro/tutorial04>` to learn about simple form processing and generic views.

25
docs/intro/tutorial04.txt
View File

@@ -18,7 +18,7 @@ tutorial, so that the template contains an HTML ``<form>`` element:
{% if error_message %}<p><strong>{{ error_message }}</strong></p>{% endif %}
<form action="/polls/{{ poll.id }}/vote/" method="post">
<form action="{% url 'polls.views.vote' poll.id %}" method="post">
{% csrf_token %}
{% for choice in poll.choice_set.all %}
<input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />
@@ -35,7 +35,7 @@ A quick rundown:
selects one of the radio buttons and submits the form, it'll send the
POST data ``choice=3``. This is HTML Forms 101.
* We set the form's ``action`` to ``/polls/{{ poll.id }}/vote/``, and we
* We set the form's ``action`` to ``{% url 'polls.views.vote' poll.id %}``, and we
set ``method="post"``. Using ``method="post"`` (as opposed to
``method="get"``) is very important, because the act of submitting this
form will alter data server-side. Whenever you create a form that alters
@@ -172,7 +172,7 @@ Now, create a ``results.html`` template:
{% endfor %}
</ul>
<a href="/polls/{{ poll.id }}/">Vote again?</a>
<a href="{% url 'polls.views.detail' poll.id %}">Vote again?</a>
Now, go to ``/polls/1/`` in your browser and vote in the poll. You should see a
results page that gets updated each time you vote. If you submit the form
@@ -238,11 +238,13 @@ Change it like so::
ListView.as_view(
queryset=Poll.objects.order_by('-pub_date')[:5],
context_object_name='latest_poll_list',
template_name='polls/index.html')),
template_name='polls/index.html'),
name='poll_index'),
url(r'^(?P<pk>\d+)/$',
DetailView.as_view(
model=Poll,
template_name='polls/detail.html')),
template_name='polls/detail.html'),
name='poll_detail'),
url(r'^(?P<pk>\d+)/results/$',
DetailView.as_view(
model=Poll,
@@ -265,8 +267,8 @@ two views abstract the concepts of "display a list of objects" and
``"pk"``, so we've changed ``poll_id`` to ``pk`` for the generic
views.
* We've added a name, ``poll_results``, to the results view so
that we have a way to refer to its URL later on (see the
* We've added the ``name`` argument to the views (e.g. ``name='poll_results'``)
so that we have a way to refer to their URL later on (see the
documentation about :ref:`naming URL patterns
<naming-url-patterns>` for information). We're also using the
:func:`~django.conf.urls.url` function from
@@ -317,10 +319,17 @@ function anymore -- generic views can be (and are) used multiple times
return HttpResponseRedirect(reverse('poll_results', args=(p.id,)))
The same rule apply for the :ttag:`url` template tag. For example in the
``results.html`` template:
.. code-block:: html+django
<a href="{% url 'poll_detail' poll.id %}">Vote again?</a>
Run the server, and use your new polling app based on generic views.
For full details on generic views, see the :doc:`generic views documentation
</topics/class-based-views>`.
</topics/class-based-views/index>`.
Coming soon
===========

8
docs/intro/whatsnext.txt
View File

@@ -108,7 +108,7 @@ On the Web
----------
The most recent version of the Django documentation lives at
http://docs.djangoproject.com/en/dev/. These HTML pages are generated
https://docs.djangoproject.com/en/dev/. These HTML pages are generated
automatically from the text files in source control. That means they reflect the
"latest and greatest" in Django -- they include the very latest corrections and
additions, and they discuss the latest Django features, which may only be
@@ -124,7 +124,7 @@ rather than asking broad tech-support questions. If you need help with your
particular Django setup, try the `django-users mailing list`_ or the `#django
IRC channel`_ instead.
.. _ticket system: https://code.djangoproject.com/simpleticket?component=Documentation
.. _ticket system: https://code.djangoproject.com/newticket?component=Documentation
.. _django-users mailing list: http://groups.google.com/group/django-users
.. _#django IRC channel: irc://irc.freenode.net/django
@@ -191,6 +191,8 @@ You can get a local copy of the HTML documentation following a few easy steps:
__ http://sphinx.pocoo.org/
__ http://www.gnu.org/software/make/
.. _differences-between-doc-versions:
Differences between versions
============================
@@ -226,4 +228,4 @@ We follow this policy:
* The `main documentation Web page`_ includes links to documentation for
all previous versions.
.. _main documentation Web page: http://docs.djangoproject.com/en/dev/
.. _main documentation Web page: https://docs.djangoproject.com/en/dev/

2
docs/misc/api-stability.txt
View File

@@ -54,7 +54,7 @@ of 1.0. This includes these APIs:
- :doc:`HTTP request/response handling </topics/http/index>`, including file
uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
- :doc:`Generic views </topics/class-based-views>`.
- :doc:`Generic views </topics/class-based-views/index>`.
- :doc:`Internationalization </topics/i18n/index>`.

1367
docs/ref/class-based-views.txt
View File

File diff suppressed because it is too large Load Diff

233
docs/ref/class-based-views/base.txt Normal file
View File

@@ -0,0 +1,233 @@
==========
Base views
==========
The following three classes provide much of the functionality needed to create
Django views. You may think of them as *parent* views, which can be used by
themselves or inherited from. They may not provide all the capabilities
required for projects, in which case there are Mixins and Generic class-based
views.
View
----
.. class:: django.views.generic.base.View
The master class-based base view. All other class-based views inherit from
this base class.
**Method Flowchart**
1. :meth:`dispatch()`
2. :meth:`http_method_not_allowed()`
**Example views.py**::
from django.http import HttpResponse
from django.views.generic import View
class MyView(View):
def get(self, request, *args, **kwargs):
return HttpResponse('Hello, World!')
**Example urls.py**::
from django.conf.urls import patterns, url
from myapp.views import MyView
urlpatterns = patterns('',
url(r'^mine/$', MyView.as_view(), name='my-view'),
)
**Methods**
.. method:: dispatch(request, *args, **kwargs)
The ``view`` part of the view -- the method that accepts a ``request``
argument plus arguments, and returns a HTTP response.
The default implementation will inspect the HTTP method and attempt to
delegate to a method that matches the HTTP method; a ``GET`` will be
delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
and so on.
The default implementation also sets ``request``, ``args`` and
``kwargs`` as instance variables, so any method on the view can know
the full details of the request that was made to invoke the view.
.. method:: http_method_not_allowed(request, *args, **kwargs)
If the view was called with a HTTP method it doesn't support, this
method is called instead.
The default implementation returns ``HttpResponseNotAllowed`` with list
of allowed methods in plain text.
.. note::
Documentation on class-based views is a work in progress. As yet, only the
methods defined directly on the class are documented here, not methods
defined on superclasses.
TemplateView
------------
.. class:: django.views.generic.base.TemplateView
Renders a given template, passing it a ``{{ params }}`` template variable,
which is a dictionary of the parameters captured in the URL.
**Ancestors (MRO)**
* :class:`django.views.generic.base.TemplateView`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.base.View`
**Method Flowchart**
1. :meth:`dispatch()`
2. :meth:`http_method_not_allowed()`
3. :meth:`get_context_data()`
**Example views.py**::
from django.views.generic.base import TemplateView
from articles.models import Article
class HomePageView(TemplateView):
template_name = "home.html"
def get_context_data(self, **kwargs):
context = super(HomePageView, self).get_context_data(**kwargs)
context['latest_articles'] = Article.objects.all()[:5]
return context
**Example urls.py**::
from django.conf.urls import patterns, url
from myapp.views import HomePageView
urlpatterns = patterns('',
url(r'^$', HomePageView.as_view(), name='home'),
)
**Methods and Attributes**
.. attribute:: template_name
The full name of a template to use.
.. method:: get_context_data(**kwargs)
Return a context data dictionary consisting of the contents of
``kwargs`` stored in the context variable ``params``.
**Context**
* ``params``: The dictionary of keyword arguments captured from the URL
pattern that served the view.
.. note::
Documentation on class-based views is a work in progress. As yet, only the
methods defined directly on the class are documented here, not methods
defined on superclasses.
RedirectView
------------
.. class:: django.views.generic.base.RedirectView
Redirects to a given URL.
The given URL may contain dictionary-style string formatting, which will be
interpolated against the parameters captured in the URL. Because keyword
interpolation is *always* done (even if no arguments are passed in), any
``"%"`` characters in the URL must be written as ``"%%"`` so that Python
will convert them to a single percent sign on output.
If the given URL is ``None``, Django will return an ``HttpResponseGone``
(410).
**Ancestors (MRO)**
* :class:`django.views.generic.base.View`
**Method Flowchart**
1. :meth:`dispatch()`
2. :meth:`http_method_not_allowed()`
3. :meth:`get_redirect_url()`
**Example views.py**::
from django.shortcuts import get_object_or_404
from django.views.generic.base import RedirectView
from articles.models import Article
class ArticleCounterRedirectView(RedirectView):
permanent = False
query_string = True
def get_redirect_url(self, pk):
article = get_object_or_404(Article, pk=pk)
article.update_counter()
return reverse('product_detail', args=(pk,))
**Example urls.py**::
from django.conf.urls import patterns, url
from django.views.generic.base import RedirectView
from article.views import ArticleCounterRedirectView
urlpatterns = patterns('',
url(r'r^(?P<pk>\d+)/$', ArticleCounterRedirectView.as_view(), name='article-counter'),
url(r'^go-to-django/$', RedirectView.as_view(url='http://djangoproject.com'), name='go-to-django'),
)
**Methods and Attributes**
.. attribute:: url
The URL to redirect to, as a string. Or ``None`` to raise a 410 (Gone)
HTTP error.
.. attribute:: permanent
Whether the redirect should be permanent. The only difference here is
the HTTP status code returned. If ``True``, then the redirect will use
status code 301. If ``False``, then the redirect will use status code
302. By default, ``permanent`` is ``True``.
.. attribute:: query_string
Whether to pass along the GET query string to the new location. If
``True``, then the query string is appended to the URL. If ``False``,
then the query string is discarded. By default, ``query_string`` is
``False``.
.. method:: get_redirect_url(**kwargs)
Constructs the target URL for redirection.
The default implementation uses :attr:`~RedirectView.url` as a starting
string, performs expansion of ``%`` parameters in that string, as well
as the appending of query string if requested by
:attr:`~RedirectView.query_string`. Subclasses may implement any
behavior they wish, as long as the method returns a redirect-ready URL
string.
.. note::
Documentation on class-based views is a work in progress. As yet, only the
methods defined directly on the class are documented here, not methods
defined on superclasses.

298
docs/ref/class-based-views/generic-date-based.txt Normal file
View File

@@ -0,0 +1,298 @@
==================
Generic date views
==================
Date-based generic views (in the module :mod:`django.views.generic.dates`)
are views for displaying drilldown pages for date-based data.
ArchiveIndexView
----------------
.. class:: django.views.generic.dates.ArchiveIndexView
A top-level index page showing the "latest" objects, by date. Objects with
a date in the *future* are not included unless you set ``allow_future`` to
``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.ArchiveIndexView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseArchiveIndexView`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Notes**
* Uses a default ``context_object_name`` of ``latest``.
* Uses a default ``template_name_suffix`` of ``_archive``.
* Defaults to providing ``date_list`` by year, but this can be altered to
month or day using the attribute ``date_list_period``. This also applies
to all subclass views.
YearArchiveView
---------------
.. class:: django.views.generic.dates.YearArchiveView
A yearly archive page showing all available months in a given year. Objects
with a date in the *future* are not displayed unless you set
``allow_future`` to ``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.YearArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseYearArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
.. attribute:: make_object_list
A boolean specifying whether to retrieve the full list of objects for
this year and pass those to the template. If ``True``, the list of
objects will be made available to the context. By default, this is
``False``.
.. method:: get_make_object_list()
Determine if an object list will be returned as part of the context. If
``False``, the ``None`` queryset will be used as the object list.
**Context**
In addition to the context provided by
:class:`django.views.generic.list.MultipleObjectMixin` (via
:class:`django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``date_list``: A
:meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object object
containing all months that have objects available according to
``queryset``, represented as
:class:`datetime.datetime<python:datetime.datetime>` objects, in
ascending order.
* ``year``: A :class:`datetime.date<python:datetime.date>` object
representing the given year.
* ``next_year``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the next year. If the next year is in the
future, this will be ``None``.
* ``previous_year``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the previous year. Unlike ``next_year``,
this will never be ``None``.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_year``.
MonthArchiveView
----------------
.. class:: django.views.generic.dates.MonthArchiveView
A monthly archive page showing all objects in a given month. Objects with a
date in the *future* are not displayed unless you set ``allow_future`` to
``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.MonthArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseMonthArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Context**
In addition to the context provided by
:class:`~django.views.generic.list.MultipleObjectMixin` (via
:class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``date_list``: A
:meth:`DateQuerySet<django.db.models.query.QuerySet.dates>` object
containing all days that have objects available in the given month,
according to ``queryset``, represented as
:class:`datetime.datetime<python:datetime.datetime>` objects, in
ascending order.
* ``month``: A :class:`datetime.date<python:datetime.date>` object
representing the given month.
* ``next_month``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the next month. If the next month is in the
future, this will be ``None``.
* ``previous_month``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the previous month. Unlike ``next_month``,
this will never be ``None``.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_month``.
WeekArchiveView
---------------
.. class:: django.views.generic.dates.WeekArchiveView
A weekly archive page showing all objects in a given week. Objects with a
date in the *future* are not displayed unless you set ``allow_future`` to
``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.WeekArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseWeekArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.WeekMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Context**
In addition to the context provided by
:class:`~django.views.generic.list.MultipleObjectMixin` (via
:class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``week``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the given week.
* ``next_week``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the next week. If the next week is in the
future, this will be ``None``.
* ``previous_week``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the previous week. Unlike ``next_week``,
this will never be ``None``.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_week``.
DayArchiveView
--------------
.. class:: django.views.generic.dates.DayArchiveView
A day archive page showing all objects in a given day. Days in the future
throw a 404 error, regardless of whether any objects exist for future days,
unless you set ``allow_future`` to ``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.DayArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseDayArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.DayMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
**Context**
In addition to the context provided by
:class:`~django.views.generic.list.MultipleObjectMixin` (via
:class:`~django.views.generic.dates.BaseDateListView`), the template's
context will be:
* ``day``: A :class:`datetime.date<python:datetime.date>` object
representing the given day.
* ``next_day``: A :class:`datetime.date<python:datetime.date>` object
representing the next day. If the next day is in the future, this will be
``None``.
* ``previous_day``: A :class:`datetime.date<python:datetime.date>` object
representing the previous day. Unlike ``next_day``, this will never be
``None``.
* ``next_month``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the next month. If the next month is in the
future, this will be ``None``.
* ``previous_month``: A :class:`datetime.date<python:datetime.date>` object
representing the first day of the previous month. Unlike ``next_month``,
this will never be ``None``.
**Notes**
* Uses a default ``template_name_suffix`` of ``_archive_day``.
TodayArchiveView
----------------
.. class:: django.views.generic.dates.TodayArchiveView
A day archive page showing all objects for *today*. This is exactly the
same as :class:`django.views.generic.dates.DayArchiveView`, except today's
date is used instead of the ``year``/``month``/``day`` arguments.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.TodayArchiveView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseTodayArchiveView`
* :class:`django.views.generic.dates.BaseDayArchiveView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.DayMixin`
* :class:`django.views.generic.dates.BaseDateListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.base.View`
DateDetailView
--------------
.. class:: django.views.generic.dates.DateDetailView
A page representing an individual object. If the object has a date value in
the future, the view will throw a 404 error by default, unless you set
``allow_future`` to ``True``.
**Ancestors (MRO)**
* :class:`django.views.generic.dates.DateDetailView`
* :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.dates.BaseDateDetailView`
* :class:`django.views.generic.dates.YearMixin`
* :class:`django.views.generic.dates.MonthMixin`
* :class:`django.views.generic.dates.DayMixin`
* :class:`django.views.generic.dates.DateMixin`
* :class:`django.views.generic.detail.BaseDetailView`
* :class:`django.views.generic.detail.SingleObjectMixin`
* :class:`django.views.generic.base.View`
.. note::
All of the generic views listed above have matching Base* views that only
differ in that the they do not include the
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.

92
docs/ref/class-based-views/generic-display.txt Normal file
View File

@@ -0,0 +1,92 @@
=====================
Generic display views
=====================
The two following generic class-based views are designed to display data. On
many projects they are typically the most commonly used views.
DetailView
----------
.. class:: django.views.generic.detail.DetailView
While this view is executing, ``self.object`` will contain the object that
the view is operating upon.
**Ancestors (MRO)**
* :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.detail.BaseDetailView`
* :class:`django.views.generic.detail.SingleObjectMixin`
* :class:`django.views.generic.base.View`
**Method Flowchart**
1. :meth:`dispatch()`
2. :meth:`http_method_not_allowed()`
3. :meth:`get_template_names()`
4. :meth:`get_slug_field()`
5. :meth:`get_queryset()`
6. :meth:`get_object()`
7. :meth:`get_context_object_name()`
8. :meth:`get_context_data()`
9. :meth:`get()`
10. :meth:`render_to_response()`
**Example views.py**::
from django.views.generic.detail import DetailView
from django.utils import timezone
from articles.models import Article
class ArticleDetailView(DetailView):
model = Article
def get_context_data(self, **kwargs):
context = super(ArticleDetailView, self).get_context_data(**kwargs)
context['now'] = timezone.now()
return context
**Example urls.py**::
from django.conf.urls import patterns, url
from article.views import ArticleDetailView
urlpatterns = patterns('',
url(r'^(?P<slug>[-_\w]+)/$', ArticleDetailView.as_view(), name='article-detail'),
)
ListView
--------
.. class:: django.views.generic.list.ListView
A page representing a list of objects.
While this view is executing, ``self.object_list`` will contain the list of
objects (usually, but not necessarily a queryset) that the view is
operating upon.
**Mixins**
* :class:`django.views.generic.list.ListView`
* :class:`django.views.generic.list.MultipleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.list.BaseListView`
* :class:`django.views.generic.list.MultipleObjectMixin`
* :class:`django.views.generic.base.View`
**Method Flowchart**
1. :meth:`dispatch()`
2. :meth:`http_method_not_allowed()`
3. :meth:`get_template_names()`
4. :meth:`get_queryset()`
5. :meth:`get_objects()`
6. :meth:`get_context_data()`
7. :meth:`get()`
8. :meth:`render_to_response()`

199
docs/ref/class-based-views/generic-editing.txt Normal file
View File

@@ -0,0 +1,199 @@
=====================
Generic editing views
=====================
The following views are described on this page and provide a foundation for
editing content:
* :class:`django.views.generic.edit.FormView`
* :class:`django.views.generic.edit.CreateView`
* :class:`django.views.generic.edit.UpdateView`
* :class:`django.views.generic.edit.DeleteView`
.. note::
Some of the examples on this page assume that a model titled 'Author'
has been defined. For these cases we assume the following has been defined
in `myapp/models.py`::
from django import models
from django.core.urlresolvers import reverse
class Author(models.Model):
name = models.CharField(max_length=200)
def get_absolute_url(self):
return reverse('author-detail', kwargs={'pk': self.pk})
FormView
--------
.. class:: django.views.generic.edit.FormView
A view that displays a form. On error, redisplays the form with validation
errors; on success, redirects to a new URL.
**Ancestors (MRO)**
This view inherits methods and attributes from the following views:
* :class:`django.views.generic.edit.FormView`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.edit.BaseFormView`
* :class:`django.views.generic.edit.FormMixin`
* :class:`django.views.generic.edit.ProcessFormView`
* :class:`django.views.generic.base.View`
**Example forms.py**::
from django import forms
class ContactForm(forms.Form):
name = forms.CharField()
message = forms.CharField(widget=forms.Textarea)
def send_email(self):
# send email using the self.cleaned_data dictionary
pass
**Example views.py**::
from myapp.forms import ContactForm
from django.views.generic.edit import FormView
class ContactView(FormView):
template_name = 'contact.html'
form_class = ContactForm
success_url = '/thanks/'
def form_valid(self, form):
# This method is called when valid form data has been POSTed.
# It should return an HttpResponse.
form.send_email()
return super(ContactView, self).form_valid(form)
CreateView
----------
.. class:: django.views.generic.edit.CreateView
A view that displays a form for creating an object, redisplaying the form
with validation errors (if there are any) and saving the object.
**Ancestors (MRO)**
This view inherits methods and attributes from the following views:
* :class:`django.views.generic.edit.CreateView`
* :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.edit.BaseCreateView`
* :class:`django.views.generic.edit.ModelFormMixin`
* :class:`django.views.generic.edit.FormMixin`
* :class:`django.views.generic.detail.SingleObjectMixin`
* :class:`django.views.generic.edit.ProcessFormView`
* :class:`django.views.generic.base.View`
**Attributes**
.. attribute:: template_name_suffix
The CreateView page displayed to a GET request uses a
``template_name_suffix`` of ``'_form.html'``. For
example, changing this attribute to ``'_create_form.html'`` for a view
creating objects for the the example `Author` model would cause the the
default `template_name` to be ``'myapp/author_create_form.html'``.
**Example views.py**::
from django.views.generic.edit import CreateView
from myapp.models import Author
class AuthorCreate(CreateView):
model = Author
UpdateView
----------
.. class:: django.views.generic.edit.UpdateView
A view that displays a form for editing an existing object, redisplaying
the form with validation errors (if there are any) and saving changes to
the object. This uses a form automatically generated from the object's
model class (unless a form class is manually specified).
**Ancestors (MRO)**
This view inherits methods and attributes from the following views:
* :class:`django.views.generic.edit.UpdateView`
* :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.edit.BaseUpdateView`
* :class:`django.views.generic.edit.ModelFormMixin`
* :class:`django.views.generic.edit.FormMixin`
* :class:`django.views.generic.detail.SingleObjectMixin`
* :class:`django.views.generic.edit.ProcessFormView`
* :class:`django.views.generic.base.View`
**Attributes**
.. attribute:: template_name_suffix
The UpdateView page displayed to a GET request uses a
``template_name_suffix`` of ``'_form.html'``. For
example, changing this attribute to ``'_update_form.html'`` for a view
updating objects for the the example `Author` model would cause the the
default `template_name` to be ``'myapp/author_update_form.html'``.
**Example views.py**::
from django.views.generic.edit import UpdateView
from myapp.models import Author
class AuthorUpdate(UpdateView):
model = Author
DeleteView
----------
.. class:: django.views.generic.edit.DeleteView
A view that displays a confirmation page and deletes an existing object.
The given object will only be deleted if the request method is ``POST``. If
this view is fetched via ``GET``, it will display a confirmation page that
should contain a form that POSTs to the same URL.
**Ancestors (MRO)**
This view inherits methods and attributes from the following views:
* :class:`django.views.generic.edit.DeleteView`
* :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
* :class:`django.views.generic.base.TemplateResponseMixin`
* :class:`django.views.generic.edit.BaseDeleteView`
* :class:`django.views.generic.edit.DeletionMixin`
* :class:`django.views.generic.detail.BaseDetailView`
* :class:`django.views.generic.detail.SingleObjectMixin`
* :class:`django.views.generic.base.View`
**Attributes**
.. attribute:: template_name_suffix
The DeleteView page displayed to a GET request uses a
``template_name_suffix`` of ``'_confirm_delete.html'``. For
example, changing this attribute to ``'_check_delete.html'`` for a view
deleting objects for the the example `Author` model would cause the the
default `template_name` to be ``'myapp/author_check_delete.html'``.
**Example views.py**::
from django.views.generic.edit import DeleteView
from django.core.urlresolvers import reverse_lazy
from myapp.models import Author
class AuthorDelete(DeleteView):
model = Author
success_url = reverse_lazy('author-list')

59
docs/ref/class-based-views/index.txt Normal file
View File

@@ -0,0 +1,59 @@
=================
Class-based views
=================
Class-based views API reference. For introductory material, see
:doc:`/topics/class-based-views/index`.
.. toctree::
:maxdepth: 3
base
generic-display
generic-editing
generic-date-based
mixins
Specification
-------------
Each request served by a class-based view has an independent state; therefore,
it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
a thread-safe operation).
A class-based view is deployed into a URL pattern using the
:meth:`~View.as_view()` classmethod::
urlpatterns = patterns('',
(r'^view/$', MyView.as_view(size=42)),
)
.. admonition:: Thread safety with view arguments
Arguments passed to a view are shared between every instance of a view.
This means that you shoudn't use a list, dictionary, or any other
mutable object as an argument to a view. If you do and the shared object
is modified, the actions of one user visiting your view could have an
effect on subsequent users visiting the same view.
Any argument passed into :meth:`~View.as_view()` will be assigned onto the
instance that is used to service a request. Using the previous example,
this means that every request on ``MyView`` is able to use ``self.size``.
Base vs Generic views
---------------------
Base class-based views can be thought of as *parent* views, which can be
used by themselves or inherited from. They may not provide all the
capabilities required for projects, in which case there are Mixins which
extend what base views can do.
Django’s generic views are built off of those base views, and were developed
as a shortcut for common usage patterns such as displaying the details of an
object. They take certain common idioms and patterns found in view
development and abstract them so that you can quickly write common views of
data without having to repeat yourself.
Most generic views require the ``queryset`` key, which is a ``QuerySet``
instance; see :doc:`/topics/db/queries` for more information about ``QuerySet``
objects.

274
docs/ref/class-based-views/mixins-date-based.txt Normal file
View File

@@ -0,0 +1,274 @@
=================
Date-based mixins
=================
YearMixin
---------
.. class:: django.views.generic.dates.YearMixin
A mixin that can be used to retrieve and provide parsing information for a
year component of a date.
**Methods and Attributes**
.. attribute:: year_format
The :func:`~time.strftime` format to use when parsing the year.
By default, this is ``'%Y'``.
.. attribute:: year
**Optional** The value for the year (as a string). By default, set to
``None``, which means the year will be determined using other means.
.. method:: get_year_format()
Returns the :func:`~time.strftime` format to use when parsing the year. Returns
:attr:`YearMixin.year_format` by default.
.. method:: get_year()
Returns the year for which this view will display data. Tries the
following sources, in order:
* The value of the :attr:`YearMixin.year` attribute.
* The value of the `year` argument captured in the URL pattern
* The value of the `year` GET query argument.
Raises a 404 if no valid year specification can be found.
MonthMixin
----------
.. class:: django.views.generic.dates.MonthMixin
A mixin that can be used to retrieve and provide parsing information for a
month component of a date.
**Methods and Attributes**
.. attribute:: month_format
The :func:`~time.strftime` format to use when parsing the month. By default, this is
``'%b'``.
.. attribute:: month
**Optional** The value for the month (as a string). By default, set to
``None``, which means the month will be determined using other means.
.. method:: get_month_format()
Returns the :func:`~time.strftime` format to use when parsing the month. Returns
:attr:`MonthMixin.month_format` by default.
.. method:: get_month()
Returns the month for which this view will display data. Tries the
following sources, in order:
* The value of the :attr:`MonthMixin.month` attribute.
* The value of the `month` argument captured in the URL pattern
* The value of the `month` GET query argument.
Raises a 404 if no valid month specification can be found.
.. method:: get_next_month(date)
Returns a date object containing the first day of the month after the
date provided. Returns ``None`` if mixed with a view that sets
``allow_future = False``, and the next month is in the future. If
``allow_empty = False``, returns the next month that contains data.
.. method:: get_prev_month(date)
Returns a date object containing the first day of the month before the
date provided. If ``allow_empty = False``, returns the previous month
that contained data.
DayMixin
--------
.. class:: django.views.generic.dates.DayMixin
A mixin that can be used to retrieve and provide parsing information for a
day component of a date.
**Methods and Attributes**
.. attribute:: day_format
The :func:`~time.strftime` format to use when parsing the day. By default, this is
``'%d'``.
.. attribute:: day
**Optional** The value for the day (as a string). By default, set to
``None``, which means the day will be determined using other means.
.. method:: get_day_format()
Returns the :func:`~time.strftime` format to use when parsing the day. Returns
:attr:`DayMixin.day_format` by default.
.. method:: get_day()
Returns the day for which this view will display data. Tries the
following sources, in order:
* The value of the :attr:`DayMixin.day` attribute.
* The value of the `day` argument captured in the URL pattern
* The value of the `day` GET query argument.
Raises a 404 if no valid day specification can be found.
.. method:: get_next_day(date)
Returns a date object containing the next day after the date provided.
Returns ``None`` if mixed with a view that sets ``allow_future = False``,
and the next day is in the future. If ``allow_empty = False``, returns
the next day that contains data.
.. method:: get_prev_day(date)
Returns a date object containing the previous day. If
``allow_empty = False``, returns the previous day that contained data.
WeekMixin
---------
.. class:: django.views.generic.dates.WeekMixin
A mixin that can be used to retrieve and provide parsing information for a
week component of a date.
**Methods and Attributes**
.. attribute:: week_format
The :func:`~time.strftime` format to use when parsing the week. By default, this is
``'%U'``.
.. attribute:: week
**Optional** The value for the week (as a string). By default, set to
``None``, which means the week will be determined using other means.
.. method:: get_week_format()
Returns the :func:`~time.strftime` format to use when parsing the week. Returns
:attr:`WeekMixin.week_format` by default.
.. method:: get_week()
Returns the week for which this view will display data. Tries the
following sources, in order:
* The value of the :attr:`WeekMixin.week` attribute.
* The value of the `week` argument captured in the URL pattern
* The value of the `week` GET query argument.
Raises a 404 if no valid week specification can be found.
DateMixin
---------
.. class:: django.views.generic.dates.DateMixin
A mixin class providing common behavior for all date-based views.
**Methods and Attributes**
.. attribute:: date_field
The name of the ``DateField`` or ``DateTimeField`` in the
``QuerySet``'s model that the date-based archive should use to
determine the objects on the page.
When :doc:`time zone support </topics/i18n/timezones>` is enabled and
``date_field`` is a ``DateTimeField``, dates are assumed to be in the
current time zone. Otherwise, the queryset could include objects from
the previous or the next day in the end user's time zone.
.. warning::
In this situation, if you have implemented per-user time zone
selection, the same URL may show a different set of objects,
depending on the end user's time zone. To avoid this, you should
use a ``DateField`` as the ``date_field`` attribute.
.. attribute:: allow_future
A boolean specifying whether to include "future" objects on this page,
where "future" means objects in which the field specified in
``date_field`` is greater than the current date/time. By default, this
is ``False``.
.. method:: get_date_field()
Returns the name of the field that contains the date data that this
view will operate on. Returns :attr:`DateMixin.date_field` by default.
.. method:: get_allow_future()
Determine whether to include "future" objects on this page, where
"future" means objects in which the field specified in ``date_field``
is greater than the current date/time. Returns
:attr:`DateMixin.allow_future` by default.
BaseDateListView
----------------
.. class:: django.views.generic.dates.BaseDateListView
A base class that provides common behavior for all date-based views. There
won't normally be a reason to instantiate
:class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
the subclasses instead.
While this view (and it's subclasses) are executing, ``self.object_list``
will contain the list of objects that the view is operating upon, and
``self.date_list`` will contain the list of dates for which data is
available.
**Mixins**
* :class:`~django.views.generic.dates.DateMixin`
* :class:`~django.views.generic.list.MultipleObjectMixin`
**Methods and Attributes**
.. attribute:: allow_empty
A boolean specifying whether to display the page if no objects are
available. If this is ``True`` and no objects are available, the view
will display an empty page instead of raising a 404. By default, this
is ``False``.
.. method:: get_dated_items():
Returns a 3-tuple containing (``date_list``, ``object_list``,
``extra_context``).
``date_list`` is the list of dates for which data is available.
``object_list`` is the list of objects. ``extra_context`` is a
dictionary of context data that will be added to any context data
provided by the
:class:`~django.views.generic.list.MultipleObjectMixin`.
.. method:: get_dated_queryset(**lookup)
Returns a queryset, filtered using the query arguments defined by
``lookup``. Enforces any restrictions on the queryset, such as
``allow_empty`` and ``allow_future``.
.. method:: get_date_list(queryset, date_type)
Returns the list of dates of type ``date_type`` for which
``queryset`` contains entries. For example, ``get_date_list(qs,
'year')`` will return the list of years for which ``qs`` has entries.
See :meth:`~django.db.models.query.QuerySet.dates()` for the
ways that the ``date_type`` argument can be used.

205
docs/ref/class-based-views/mixins-editing.txt Normal file
View File

@@ -0,0 +1,205 @@
==============
Editing mixins
==============
The following mixins are used to construct Django's editing views:
* :class:`django.views.generic.edit.FormMixin`
* :class:`django.views.generic.edit.ModelFormMixin`
* :class:`django.views.generic.edit.ProcessFormView`
* :class:`django.views.generic.edit.DeletionMixin`
.. note::
Examples of how these are combined into editing views can be found at
the documentation on ``Generic editing views``.
FormMixin
---------
.. class:: django.views.generic.edit.FormMixin
A mixin class that provides facilities for creating and displaying forms.
**Methods and Attributes**
.. attribute:: initial
A dictionary containing initial data for the form.
.. attribute:: form_class
The form class to instantiate.
.. attribute:: success_url
The URL to redirect to when the form is successfully processed.
.. method:: get_initial()
Retrieve initial data for the form. By default, returns a copy of
:attr:`~django.views.generic.edit.FormMixin.initial`.
.. versionchanged:: 1.4
In Django 1.3, this method was returning the
:attr:`~django.views.generic.edit.FormMixin.initial` class variable
itself.
.. method:: get_form_class()
Retrieve the form class to instantiate. By default
:attr:`.form_class`.
.. method:: get_form(form_class)
Instantiate an instance of ``form_class`` using
:meth:`~django.views.generic.edit.FormMixin.get_form_kwargs`.
.. method:: get_form_kwargs()
Build the keyword arguments required to instantiate the form.
The ``initial`` argument is set to :meth:`.get_initial`. If the
request is a ``POST`` or ``PUT``, the request data (``request.POST``
and ``request.FILES``) will also be provided.
.. method:: get_success_url()
Determine the URL to redirect to when the form is successfully
validated. Returns
:attr:`~django.views.generic.edit.FormMixin.success_url` by default.
.. method:: form_valid(form)
Redirects to
:meth:`~django.views.generic.edit.FormMixin.get_success_url`.
.. method:: form_invalid(form)
Renders a response, providing the invalid form as context.
.. method:: get_context_data(**kwargs)
Populates a context containing the contents of ``kwargs``.
**Context**
* ``form``: The form instance that was generated for the view.
.. note::
Views mixing :class:`FormMixin` must provide an implementation of
:meth:`~django.views.generic.FormMixin.form_valid` and
:meth:`~django.views.generic.FormMixin.form_invalid`.
ModelFormMixin
--------------
.. class:: django.views.generic.edit.ModelFormMixin
A form mixin that works on ModelForms, rather than a standalone form.
Since this is a subclass of
:class:`~django.views.generic.detail.SingleObjectMixin`, instances of this
mixin have access to the :attr:`~SingleObjectMixin.model` and
:attr:`~SingleObjectMixin.queryset` attributes, describing the type of
object that the ModelForm is manipulating. The view also provides
``self.object``, the instance being manipulated. If the instance is being
created, ``self.object`` will be ``None``.
**Mixins**
* :class:`django.views.generic.edit.FormMixin`
* :class:`django.views.generic.detail.SingleObjectMixin`
**Methods and Attributes**
.. attribute:: success_url
The URL to redirect to when the form is successfully processed.
``success_url`` may contain dictionary string formatting, which
will be interpolated against the object's field attributes. For
example, you could use ``success_url="/polls/%(slug)s/"`` to
redirect to a URL composed out of the ``slug`` field on a model.
.. method:: get_form_class()
Retrieve the form class to instantiate. If
:attr:`FormMixin.form_class` is provided, that class will be used.
Otherwise, a ModelForm will be instantiated using the model associated
with the :attr:`~SingleObjectMixin.queryset`, or with the
:attr:`~SingleObjectMixin.model`, depending on which attribute is
provided.
.. method:: get_form_kwargs()
Add the current instance (``self.object``) to the standard
:meth:`FormMixin.get_form_kwargs`.
.. method:: get_success_url()
Determine the URL to redirect to when the form is successfully
validated. Returns :attr:`ModelFormMixin.success_url` if it is provided;
otherwise, attempts to use the ``get_absolute_url()`` of the object.
.. method:: form_valid(form)
Saves the form instance, sets the current object for the view, and
redirects to
:meth:`~django.views.generic.edit.FormMixin.get_success_url`.
.. method:: form_invalid()
Renders a response, providing the invalid form as context.
ProcessFormView
---------------
.. class:: django.views.generic.edit.ProcessFormView
A mixin that provides basic HTTP GET and POST workflow.
.. note::
This is named 'ProcessFormView' and inherits directly from
:class:`django.views.generic.base.View`, but breaks if used
independently, so it is more of a mixin.
**Extends**
* :class:`django.views.generic.base.View`
**Methods and Attributes**
.. method:: get(request, *args, **kwargs)
Constructs a form, then renders a response using a context that
contains that form.
.. method:: post(request, *args, **kwargs)
Constructs a form, checks the form for validity, and handles it
accordingly.
The PUT action is also handled, as an analog of POST.
.. class:: django.views.generic.edit.DeletionMixin
Enables handling of the ``DELETE`` http action.
**Methods and Attributes**
.. attribute:: success_url
The url to redirect to when the nominated object has been
successfully deleted.
.. method:: get_success_url(obj)
Returns the url to redirect to when the nominated object has been
successfully deleted. Returns
:attr:`~django.views.generic.edit.DeletionMixin.success_url` by
default.

181
docs/ref/class-based-views/mixins-multiple-object.txt Normal file
View File

@@ -0,0 +1,181 @@
======================
Multiple object mixins
======================
MultipleObjectMixin
-------------------
.. class:: django.views.generic.list.MultipleObjectMixin
A mixin that can be used to display a list of objects.
If ``paginate_by`` is specified, Django will paginate the results returned
by this. You can specify the page number in the URL in one of two ways:
* Use the ``page`` parameter in the URLconf. For example, this is what
your URLconf might look like::
(r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view())
* Pass the page number via the ``page`` query-string parameter. For
example, a URL would look like this::
/objects/?page=3
These values and lists are 1-based, not 0-based, so the first page would be
represented as page ``1``.
For more on pagination, read the :doc:`pagination documentation
</topics/pagination>`.
As a special case, you are also permitted to use ``last`` as a value for
``page``::
/objects/?page=last
This allows you to access the final page of results without first having to
determine how many pages there are.
Note that ``page`` *must* be either a valid page number or the value
``last``; any other value for ``page`` will result in a 404 error.
**Extends**
* :class:`django.views.generic.base.ContextMixin`
**Methods and Attributes**
.. attribute:: allow_empty
A boolean specifying whether to display the page if no objects are
available. If this is ``False`` and no objects are available, the view
will raise a 404 instead of displaying an empty page. By default, this
is ``True``.
.. attribute:: model
The model that this view will display data for. Specifying ``model
= Foo`` is effectively the same as specifying ``queryset =
Foo.objects.all()``.
.. attribute:: queryset
A ``QuerySet`` that represents the objects. If provided, the value of
:attr:`MultipleObjectMixin.queryset` supersedes the value provided for
:attr:`MultipleObjectMixin.model`.
.. attribute:: paginate_by
An integer specifying how many objects should be displayed per page. If
this is given, the view will paginate objects with
:attr:`MultipleObjectMixin.paginate_by` objects per page. The view will
expect either a ``page`` query string parameter (via ``GET``) or a
``page`` variable specified in the URLconf.
.. attribute:: paginator_class
The paginator class to be used for pagination. By default,
:class:`django.core.paginator.Paginator` is used. If the custom paginator
class doesn't have the same constructor interface as
:class:`django.core.paginator.Paginator`, you will also need to
provide an implementation for :meth:`MultipleObjectMixin.get_paginator`.
.. attribute:: context_object_name
Designates the name of the variable to use in the context.
.. method:: get_queryset()
Returns the queryset that represents the data this view will display.
.. method:: paginate_queryset(queryset, page_size)
Returns a 4-tuple containing (``paginator``, ``page``, ``object_list``,
``is_paginated``).
Constructed by paginating ``queryset`` into pages of size ``page_size``.
If the request contains a ``page`` argument, either as a captured URL
argument or as a GET argument, ``object_list`` will correspond to the
objects from that page.
.. method:: get_paginate_by(queryset)
Returns the number of items to paginate by, or ``None`` for no
pagination. By default this simply returns the value of
:attr:`MultipleObjectMixin.paginate_by`.
.. method:: get_paginator(queryset, per_page, orphans=0, allow_empty_first_page=True)
Returns an instance of the paginator to use for this view. By default,
instantiates an instance of :attr:`paginator_class`.
.. method:: get_allow_empty()
Return a boolean specifying whether to display the page if no objects
are available. If this method returns ``False`` and no objects are
available, the view will raise a 404 instead of displaying an empty
page. By default, this is ``True``.
.. method:: get_context_object_name(object_list)
Return the context variable name that will be used to contain
the list of data that this view is manipulating. If
``object_list`` is a queryset of Django objects and
:attr:`~MultipleObjectMixin.context_object_name` is not set,
the context name will be the ``object_name`` of the model that
the queryset is composed from, with postfix ``'_list'``
appended. For example, the model ``Article`` would have a
context object named ``article_list``.
.. method:: get_context_data(**kwargs)
Returns context data for displaying the list of objects.
**Context**
* ``object_list``: The list of objects that this view is displaying. If
``context_object_name`` is specified, that variable will also be set
in the context, with the same value as ``object_list``.
* ``is_paginated``: A boolean representing whether the results are
paginated. Specifically, this is set to ``False`` if no page size has
been specified, or if the available objects do not span multiple
pages.
* ``paginator``: An instance of
:class:`django.core.paginator.Paginator`. If the page is not
paginated, this context variable will be ``None``.
* ``page_obj``: An instance of
:class:`django.core.paginator.Page`. If the page is not paginated,
this context variable will be ``None``.
MultipleObjectTemplateResponseMixin
-----------------------------------
.. class:: django.views.generic.list.MultipleObjectTemplateResponseMixin
A mixin class that performs template-based response rendering for views
that operate upon a list of object instances. Requires that the view it is
mixed with provides ``self.object_list``, the list of object instances that
the view is operating on. ``self.object_list`` may be, but is not required
to be, a :class:`~django.db.models.query.QuerySet`.
**Extends**
* :class:`~django.views.generic.base.TemplateResponseMixin`
**Methods and Attributes**
.. attribute:: template_name_suffix
The suffix to append to the auto-generated candidate template name.
Default suffix is ``_list``.
.. method:: get_template_names()
Returns a list of candidate template names. Returns the following list:
* the value of ``template_name`` on the view (if provided)
* ``<app_label>/<object_name><template_name_suffix>.html``

78
docs/ref/class-based-views/mixins-simple.txt Normal file
View File

@@ -0,0 +1,78 @@
=============
Simple mixins
=============
ContextMixin
------------
.. class:: django.views.generic.base.ContextMixin
.. versionadded:: 1.5
**classpath**
``django.views.generic.base.ContextMixin``
**Methods**
.. method:: get_context_data(**kwargs)
Returns a dictionary representing the template context. The keyword
arguments provided will make up the returned context.
The template context of all class-based generic views include a
``view`` variable that points to the ``View`` instance.
.. admonition:: Use ``alters_data`` where appropriate
Note that having the view instance in the template context may
expose potentially hazardous methods to template authors. To
prevent methods like this from being called in the template, set
``alters_data=True`` on those methods. For more information, read
the documentation on :ref:`rendering a template context
<alters-data-description>`.
TemplateResponseMixin
---------------------
.. class:: django.views.generic.base.TemplateResponseMixin
Provides a mechanism to construct a
:class:`~django.template.response.TemplateResponse`, given
suitable context. The template to use is configurable and can be
further customized by subclasses.
**Methods and Attributes**
.. attribute:: response_class
The response class to be returned by ``render_to_response`` method.
Default is
:class:`TemplateResponse <django.template.response.TemplateResponse>`.
The template and context of ``TemplateResponse`` instances can be
altered later (e.g. in
:ref:`template response middleware <template-response-middleware>`).
If you need custom template loading or custom context object
instantiation, create a ``TemplateResponse`` subclass and assign it to
``response_class``.
.. method:: render_to_response(context, **response_kwargs)
Returns a ``self.response_class`` instance.
If any keyword arguments are provided, they will be
passed to the constructor of the response class.
Calls :meth:`~TemplateResponseMixin.get_template_names()` to obtain the
list of template names that will be searched looking for an existent
template.
.. method:: get_template_names()
Returns a list of template names to search for when rendering the
template.
If :attr:`TemplateResponseMixin.template_name` is specified, the
default implementation will return a list containing
:attr:`TemplateResponseMixin.template_name` (if it is specified).

130
docs/ref/class-based-views/mixins-single-object.txt Normal file
View File

@@ -0,0 +1,130 @@
====================
Single object mixins
====================
SingleObjectMixin
-----------------
.. class:: django.views.generic.detail.SingleObjectMixin
Provides a mechanism for looking up an object associated with the
current HTTP request.
**Methods and Attributes**
.. attribute:: model
The model that this view will display data for. Specifying ``model
= Foo`` is effectively the same as specifying ``queryset =
Foo.objects.all()``.
.. attribute:: queryset
A ``QuerySet`` that represents the objects. If provided, the value of
:attr:`SingleObjectMixin.queryset` supersedes the value provided for
:attr:`SingleObjectMixin.model`.
.. attribute:: slug_field
The name of the field on the model that contains the slug. By default,
``slug_field`` is ``'slug'``.
.. attribute:: slug_url_kwarg
.. versionadded:: 1.4
The name of the URLConf keyword argument that contains the slug. By
default, ``slug_url_kwarg`` is ``'slug'``.
.. attribute:: pk_url_kwarg
.. versionadded:: 1.4
The name of the URLConf keyword argument that contains the primary key.
By default, ``pk_url_kwarg`` is ``'pk'``.
.. attribute:: context_object_name
Designates the name of the variable to use in the context.
.. method:: get_object(queryset=None)
Returns the single object that this view will display. If
``queryset`` is provided, that queryset will be used as the
source of objects; otherwise,
:meth:`~SingleObjectMixin.get_queryset` will be used.
``get_object()`` looks for a
:attr:`SingleObjectMixin.pk_url_kwarg` argument in the arguments
to the view; if this argument is found, this method performs a
primary-key based lookup using that value. If this argument is not
found, it looks for a :attr:`SingleObjectMixin.slug_url_kwarg`
argument, and performs a slug lookup using the
:attr:`SingleObjectMixin.slug_field`.
.. method:: get_queryset()
Returns the queryset that will be used to retrieve the object that
this view will display. By default,
:meth:`~SingleObjectMixin.get_queryset` returns the value of the
:attr:`~SingleObjectMixin.queryset` attribute if it is set, otherwise
it constructs a :class:`QuerySet` by calling the `all()` method on the
:attr:`~SingleObjectMixin.model` attribute's default manager.
.. method:: get_context_object_name(obj)
Return the context variable name that will be used to contain the
data that this view is manipulating. If
:attr:`~SingleObjectMixin.context_object_name` is not set, the context
name will be constructed from the ``object_name`` of the model that
the queryset is composed from. For example, the model ``Article``
would have context object named ``'article'``.
.. method:: get_context_data(**kwargs)
Returns context data for displaying the list of objects.
**Context**
* ``object``: The object that this view is displaying. If
``context_object_name`` is specified, that variable will also be
set in the context, with the same value as ``object``.
SingleObjectTemplateResponseMixin
---------------------------------
.. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin
A mixin class that performs template-based response rendering for views
that operate upon a single object instance. Requires that the view it is
mixed with provides ``self.object``, the object instance that the view is
operating on. ``self.object`` will usually be, but is not required to be,
an instance of a Django model. It may be ``None`` if the view is in the
process of constructing a new instance.
**Extends**
* :class:`~django.views.generic.base.TemplateResponseMixin`
**Methods and Attributes**
.. attribute:: template_name_field
The field on the current object instance that can be used to determine
the name of a candidate template. If either ``template_name_field``
itself or the value of the ``template_name_field`` on the current
object instance is ``None``, the object will not be used for a
candidate template name.
.. attribute:: template_name_suffix
The suffix to append to the auto-generated candidate template name.
Default suffix is ``_detail``.
.. method:: get_template_names()
Returns a list of candidate template names. Returns the following list:
* the value of ``template_name`` on the view (if provided)
* the contents of the ``template_name_field`` field on the
object instance that the view is operating upon (if available)
* ``<app_label>/<object_name><template_name_suffix>.html``

14
docs/ref/class-based-views/mixins.txt Normal file
View File

@@ -0,0 +1,14 @@
========================
Class-based views mixins
========================
Class-based views API reference. For introductory material, see :doc:`/topics/class-based-views/mixins`.
.. toctree::
:maxdepth: 1
mixins-simple
mixins-single-object
mixins-multiple-object
mixins-editing
mixins-date-based

BIN
docs/ref/contrib/admin/_images/article_actions.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 51 KiB

BIN
docs/ref/contrib/admin/_images/article_actions_message.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/ref/contrib/admin/_images/user_actions.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 35 KiB

81
docs/ref/contrib/admin/index.txt
View File

@@ -115,9 +115,7 @@ subclass::
.. attribute:: ModelAdmin.actions_selection_counter
.. versionadded:: 1.2
Controls whether a selection counter is display next to the action dropdown.
Controls whether a selection counter is displayed next to the action dropdown.
By default, the admin changelist will display it
(``actions_selection_counter = True``).
@@ -177,12 +175,9 @@ subclass::
fields = ('url', 'title', 'content')
In the above example, only the fields ``url``, ``title`` and ``content``
will be displayed, sequentially, in the form.
.. versionadded:: 1.2
``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields`
to be displayed as read-only.
will be displayed, sequentially, in the form. ``fields`` can contain
values defined in :attr:`ModelAdmin.readonly_fields` to be displayed as
read-only.
.. versionadded:: 1.4
@@ -262,8 +257,6 @@ subclass::
'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
}
.. versionadded:: 1.2
``fields`` can contain values defined in
:attr:`~ModelAdmin.readonly_fields` to be displayed as read-only.
@@ -378,14 +371,6 @@ subclass::
because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
their own.
.. attribute:: ModelAdmin.get_changelist
.. versionchanged:: 1.2
Returns the Changelist class to be used for listing. By default,
``django.contrib.admin.views.main.ChangeList`` is used. By inheriting this
class you can change the behavior of the listing.
.. attribute:: ModelAdmin.inlines
See :class:`InlineModelAdmin` objects below.
@@ -638,7 +623,7 @@ subclass::
provided in the query string and retrievable via
`self.value()`.
"""
# Compare the requested value (either '80s' or 'other')
# Compare the requested value (either '80s' or '90s')
# to decide how to filter the queryset.
if self.value() == '80s':
return queryset.filter(birthday__gte=date(1980, 1, 1),
@@ -819,8 +804,6 @@ subclass::
.. attribute:: ModelAdmin.readonly_fields
.. versionadded:: 1.2
By default the admin shows all fields as editable. Any fields in this
option (which should be a ``list`` or ``tuple``) will display its data
as-is and non-editable. This option behaves nearly identical to
@@ -928,8 +911,6 @@ templates used by the :class:`ModelAdmin` views:
.. attribute:: ModelAdmin.add_form_template
.. versionadded:: 1.2
Path to a custom template, used by :meth:`add_view`.
.. attribute:: ModelAdmin.change_form_template
@@ -947,8 +928,6 @@ templates used by the :class:`ModelAdmin` views:
.. attribute:: ModelAdmin.delete_selected_confirmation_template
.. versionadded:: 1.2
Path to a custom template, used by the :meth:`delete_selected`
action method for displaying a confirmation page when deleting one
or more objects. See the :doc:`actions
@@ -1035,8 +1014,6 @@ templates used by the :class:`ModelAdmin` views:
.. method:: ModelAdmin.get_readonly_fields(self, request, obj=None)
.. versionadded:: 1.2
The ``get_readonly_fields`` method is given the ``HttpRequest`` and the
``obj`` being edited (or ``None`` on an add form) and is expected to return
a ``list`` or ``tuple`` of field names that will be displayed as read-only,
@@ -1185,6 +1162,12 @@ templates used by the :class:`ModelAdmin` views:
kwargs['choices'] += (('ready', 'Ready for deployment'),)
return super(MyModelAdmin, self).formfield_for_choice_field(db_field, request, **kwargs)
.. method:: ModelAdmin.get_changelist(self, request, **kwargs)
Returns the Changelist class to be used for listing. By default,
``django.contrib.admin.views.main.ChangeList`` is used. By inheriting this
class you can change the behavior of the listing.
.. method:: ModelAdmin.has_add_permission(self, request)
Should return ``True`` if adding an object is permitted, ``False``
@@ -1283,11 +1266,11 @@ provided some extra mapping data that would not otherwise be available::
# ...
pass
def change_view(self, request, object_id, extra_context=None):
def change_view(self, request, object_id, form_url='', extra_context=None):
extra_context = extra_context or {}
extra_context['osm_data'] = self.get_osm_info()
return super(MyModelAdmin, self).change_view(request, object_id,
extra_context=extra_context)
form_url, extra_context=extra_context)
.. versionadded:: 1.4
@@ -1405,20 +1388,17 @@ adds some of its own (the shared features are actually defined in the
- :attr:`~InlineModelAdmin.form`
- :attr:`~ModelAdmin.fieldsets`
- :attr:`~ModelAdmin.fields`
- :attr:`~ModelAdmin.formfield_overrides`
- :attr:`~ModelAdmin.exclude`
- :attr:`~ModelAdmin.filter_horizontal`
- :attr:`~ModelAdmin.filter_vertical`
- :attr:`~ModelAdmin.prepopulated_fields`
- :attr:`~ModelAdmin.radio_fields`
- :attr:`~ModelAdmin.readonly_fields`
- :attr:`~InlineModelAdmin.raw_id_fields`
- :meth:`~ModelAdmin.formfield_for_foreignkey`
- :meth:`~ModelAdmin.formfield_for_manytomany`
.. versionadded:: 1.2
- :attr:`~ModelAdmin.readonly_fields`
- :attr:`~ModelAdmin.formfield_overrides`
.. versionadded:: 1.3
- :attr:`~ModelAdmin.ordering`
@@ -1463,8 +1443,6 @@ The ``InlineModelAdmin`` class adds:
:doc:`formsets documentation </topics/forms/formsets>` for more
information.
.. versionadded:: 1.2
For users with JavaScript-enabled browsers, an "Add another" link is
provided to enable any number of additional inlines to be added in addition
to those provided as a result of the ``extra`` argument.
@@ -1541,8 +1519,6 @@ automatically::
Working with many-to-many models
--------------------------------
.. versionadded:: 1.2
By default, admin widgets for many-to-many relations will be displayed
on whichever model contains the actual reference to the
:class:`~django.db.models.ManyToManyField`. Depending on your ``ModelAdmin``
@@ -1842,21 +1818,15 @@ Templates can override or extend base admin templates as described in
.. attribute:: AdminSite.logout_template
.. versionadded:: 1.2
Path to a custom template that will be used by the admin site logout view.
.. attribute:: AdminSite.password_change_template
.. versionadded:: 1.2
Path to a custom template that will be used by the admin site password
change view.
.. attribute:: AdminSite.password_change_done_template
.. versionadded:: 1.2
Path to a custom template that will be used by the admin site password
change done view.
@@ -1978,16 +1948,17 @@ accessible using Django's :ref:`URL reversing system <naming-url-patterns>`.
The :class:`AdminSite` provides the following named URL patterns:
====================== ======================== =============
Page URL name Parameters
====================== ======================== =============
Index ``index``
Logout ``logout``
Password change ``password_change``
Password change done ``password_change_done``
i18n javascript ``jsi18n``
Application index page ``app_list`` ``app_label``
====================== ======================== =============
========================= ======================== ==================================
Page URL name Parameters
========================= ======================== ==================================
Index ``index``
Logout ``logout``
Password change ``password_change``
Password change done ``password_change_done``
i18n javascript ``jsi18n``
Application index page ``app_list`` ``app_label``
Redirect to object's page ``view_on_site`` ``content_type_id``, ``object_id``
========================= ======================== ==================================
Each :class:`ModelAdmin` instance provides an additional set of named URLs:

10
docs/ref/contrib/comments/custom.txt
View File

@@ -51,9 +51,9 @@ To make this kind of customization, we'll need to do three things:
custom :setting:`COMMENTS_APP`.
So, carrying on the example above, we're dealing with a typical app structure in
the ``my_custom_app`` directory::
the ``my_comment_app`` directory::
my_custom_app/
my_comment_app/
__init__.py
models.py
forms.py
@@ -98,11 +98,11 @@ Django provides a couple of "helper" classes to make writing certain types of
custom comment forms easier; see :mod:`django.contrib.comments.forms` for
more.
Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to
Finally, we'll define a couple of methods in ``my_comment_app/__init__.py`` to
point Django at these classes we've created::
from my_comments_app.models import CommentWithTitle
from my_comments_app.forms import CommentFormWithTitle
from my_comment_app.models import CommentWithTitle
from my_comment_app.forms import CommentFormWithTitle
def get_model():
return CommentWithTitle

2
docs/ref/contrib/comments/example.txt
View File

@@ -37,8 +37,6 @@ available in the context, then you can refer to it directly::
{% get_comment_count for entry as comment_count %}
<p>{{ comment_count }} comments have been posted.</p>
.. versionadded:: 1.2
Next, we can use the :ttag:`render_comment_list` tag, to render all comments
to the given instance (``entry``) by using the ``comments/list.html`` template::

4
docs/ref/contrib/comments/index.txt
View File

@@ -130,8 +130,6 @@ details.
Linking to comments
-------------------
.. versionadded:: 1.2
To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`::
{% get_comment_permalink comment_obj [format_string] %}
@@ -252,7 +250,7 @@ Redirecting after the comment post
To specify the URL you want to redirect to after the comment has been posted,
you can include a hidden form input called ``next`` in your comment form. For example::
<input type="hidden" name="next" value="{% url my_comment_was_posted %}" />
<input type="hidden" name="next" value="{% url 'my_comment_was_posted' %}" />
.. _notes-on-the-comment-form:

17
docs/ref/contrib/contenttypes.txt
View File

@@ -187,13 +187,13 @@ The ``ContentTypeManager``
probably won't ever need to call this method yourself; Django will call
it automatically when it's needed.
.. method:: get_for_model(model)
.. method:: get_for_model(model[, for_concrete_model=True])
Takes either a model class or an instance of a model, and returns the
:class:`~django.contrib.contenttypes.models.ContentType` instance
representing that model.
.. method:: get_for_models(*models)
.. method:: get_for_models(*models[, for_concrete_models=True])
Takes a variadic number of model classes, and returns a dictionary
mapping the model classes to the
@@ -224,6 +224,19 @@ lookup::
.. _generic-relations:
.. versionadded:: 1.5
Prior to Django 1.5 :meth:`~ContentTypeManager.get_for_model()` and
:meth:`~ContentTypeManager.get_for_models()` always returned the
:class:`~django.contrib.contenttypes.models.ContentType` associated with the
concrete model of the specified one(s). That means there was no way to retreive
the :class:`~django.contrib.contenttypes.models.ContentType` of a proxy model
using those methods. As of Django 1.5 you can now pass a boolean flag –
respectively ``for_concrete_model`` and ``for_concrete_models`` – to specify
wether or not you want to retreive the
:class:`~django.contrib.contenttypes.models.ContentType` for the concrete or
direct model.
Generic relations
=================

8
docs/ref/contrib/csrf.txt
View File

@@ -434,14 +434,12 @@ A number of settings can be used to control Django's CSRF behavior.
CSRF_COOKIE_DOMAIN
------------------
.. versionadded:: 1.2
Default: ``None``
The domain to be used when setting the CSRF cookie. This can be useful for
easily allowing cross-subdomain requests to be excluded from the normal cross
site request forgery protection. It should be set to a string such as
``".lawrence.com"`` to allow a POST request from a form on one subdomain to be
``".example.com"`` to allow a POST request from a form on one subdomain to be
accepted by a view served from another subdomain.
Please note that, with or without use of this setting, this CSRF protection
@@ -450,8 +448,6 @@ mechanism is not safe against cross-subdomain attacks -- see `Limitations`_.
CSRF_COOKIE_NAME
----------------
.. versionadded:: 1.2
Default: ``'csrftoken'``
The name of the cookie to use for the CSRF authentication token. This can be
@@ -485,8 +481,6 @@ cookie is only sent under an HTTPS connection.
CSRF_FAILURE_VIEW
-----------------
.. versionadded:: 1.2
Default: ``'django.views.csrf.csrf_failure'``
A dotted path to the view function to be used when an incoming request

2
docs/ref/contrib/formtools/form-preview.txt
View File

@@ -110,8 +110,6 @@ default templates.
Advanced ``FormPreview`` methods
================================
.. versionadded:: 1.2
.. method:: FormPreview.process_preview
Given a validated form, performs any extra processing before displaying the

11
docs/ref/contrib/formtools/form-wizard.txt
View File

@@ -86,8 +86,8 @@ the message itself. Here's what the :file:`forms.py` might look like::
section :ref:`Handling files <wizard-files>` below to learn more about
what to do.
Creating a ``WizardView`` class
-------------------------------
Creating a ``WizardView`` subclass
----------------------------------
The next step is to create a
:class:`django.contrib.formtools.wizard.views.WizardView` subclass. You can
@@ -528,7 +528,7 @@ We define our wizard in a ``views.py``::
We need to add the ``ContactWizard`` to our ``urls.py`` file::
from django.conf.urls import pattern
from django.conf.urls import patterns
from myapp.forms import ContactForm1, ContactForm2
from myapp.views import ContactWizard, show_message_form_condition
@@ -554,9 +554,8 @@ How to work with ModelForm and ModelFormSet
WizardView supports :doc:`ModelForms </topics/forms/modelforms>` and
:ref:`ModelFormSets <model-formsets>`. Additionally to
:attr:`~WizardView.initial_dict`, the :meth:`~WizardView.as_view` method takes
an ``instance_dict`` argument that should contain instances of ``ModelForm`` and
``ModelFormSet``. Similarly to :attr:`~WizardView.initial_dict`, these
dictionary key values should be equal to the step number in the form list.
an ``instance_dict`` argument that should contain model instances for steps
based on ``ModelForm`` and querysets for steps based on ``ModelFormSet``.
Usage of ``NamedUrlWizardView``
===============================

6
docs/ref/contrib/gis/db-api.txt
View File

@@ -12,11 +12,7 @@ GeoDjango Database API
Spatial Backends
================
.. versionadded:: 1.2
In Django 1.2, support for :doc:`multiple databases </topics/db/multi-db>` was
introduced. In order to support multiple databases, GeoDjango has segregated
its functionality into full-fledged spatial database backends:
GeoDjango currently provides the following spatial database backends:
* :mod:`django.contrib.gis.db.backends.postgis`
* :mod:`django.contrib.gis.db.backends.mysql`

59
docs/ref/contrib/gis/deployment.txt
View File

@@ -2,6 +2,10 @@
Deploying GeoDjango
===================
Basically, the deployment of a GeoDjango application is not different from
the deployment of a normal Django application. Please consult Django's
:doc:`deployment documentation </howto/deployment/index>`.
.. warning::
GeoDjango uses the GDAL geospatial library which is
@@ -10,58 +14,7 @@ Deploying GeoDjango
appropriate configuration of Apache or the prefork method
when using FastCGI through another Web server.
Apache
======
In this section there are some example ``VirtualHost`` directives for
when deploying using ``mod_wsgi``, which is now officially the recommended
way to deploy Django applications with Apache.
As long as ``mod_wsgi`` is configured correctly, it does not
matter whether the version of Apache is prefork or worker.
.. note::
The ``Alias`` and ``Directory`` configurations in the examples
below use an example path to a system-wide installation folder of Django.
Substitute in an appropriate location, if necessary, as it may be
different than the path on your system.
``mod_wsgi``
------------
Example::
<VirtualHost *:80>
WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1
WSGIProcessGroup geodjango
WSGIScriptAlias / /home/geo/geodjango/world.wsgi
Alias /media/ "/usr/lib/python2.6/site-packages/django/contrib/admin/media/"
<Directory "/usr/lib/python2.6/site-packages/django/contrib/admin/media/">
Order allow,deny
Options Indexes
Allow from all
IndexOptions FancyIndexing
</Directory>
</VirtualHost>
.. warning::
If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then
For example, when configuring your application with ``mod_wsgi``,
set the ``WSGIDaemonProcess`` attribute ``threads`` to ``1``, unless
Apache may crash when running your GeoDjango application. Increase the
number of ``processes`` instead.
For more information, please consult Django's
:doc:`mod_wsgi documentation </howto/deployment/wsgi/modwsgi>`.
Lighttpd
========
FastCGI
-------
Nginx
=====
FastCGI
-------

12
docs/ref/contrib/gis/gdal.txt
View File

@@ -212,8 +212,6 @@ __ http://www.gdal.org/ogr/ogr_formats.html
.. attribute:: spatial_filter
.. versionadded:: 1.2
Property that may be used to retrieve or set a spatial filter for this
layer. A spatial filter can only be set with an :class:`OGRGeometry`
instance, a 4-tuple extent, or ``None``. When set with something
@@ -449,7 +447,7 @@ systems and coordinate transformation::
This object is a wrapper for the `OGR Geometry`__ class.
These objects are instantiated directly from the given ``geom_input``
parameter, which may be a string containing WKT or HEX, a ``buffer``
parameter, which may be a string containing WKT, HEX, GeoJSON, a ``buffer``
containing WKB data, or an :class:`OGRGeomType` object. These objects
are also returned from the :class:`Feature.geom` attribute, when
reading vector data from :class:`Layer` (which is in turn a part of
@@ -490,15 +488,9 @@ systems and coordinate transformation::
.. attribute:: coord_dim
.. versionchanged:: 1.2
Returns or sets the coordinate dimension of this geometry. For
example, the value would be 2 for two-dimensional geometries.
.. note::
Setting this property is only available in versions 1.2 and above.
.. attribute:: geom_count
Returns the number of elements in this geometry::
@@ -619,8 +611,6 @@ systems and coordinate transformation::
.. attribute:: ewkt
.. versionadded:: 1.2
Returns the EWKT representation of this geometry.
.. method:: clone()

18
docs/ref/contrib/gis/geoquerysets.txt
View File

@@ -117,8 +117,6 @@ SpatiaLite ``Contains(poly, geom)``
contains_properly
-----------------
.. versionadded:: 1.2
*Availability*: PostGIS
Returns true if the lookup geometry intersects the interior of the
@@ -803,8 +801,6 @@ Geometry Editors
.. method:: GeoQuerySet.force_rhr(**kwargs)
.. versionadded:: 1.2
*Availability*: PostGIS
Returns a modified version of the polygon/multipolygon in which all
@@ -816,8 +812,6 @@ of the vertices follow the Right-Hand-Rule, and attaches as a
.. method:: GeoQuerySet.reverse_geom(**kwargs)
.. versionadded:: 1.2
*Availability*: PostGIS, Oracle
Reverse the coordinate order of the geometry field, and attaches as a
@@ -943,8 +937,6 @@ of the geometry field in each model converted to the requested output format.
.. method:: GeoQuerySet.geohash(precision=20, **kwargs)
.. versionadded:: 1.2
Attaches a ``geohash`` attribute to every model the queryset
containing the `GeoHash`__ representation of the geometry.
@@ -1034,7 +1026,7 @@ Keyword Argument Description
representation -- the default value is 8.
===================== =====================================================
__ http://code.google.com/apis/kml/documentation/
__ https://developers.google.com/kml/documentation/
``svg``
~~~~~~~
@@ -1136,8 +1128,6 @@ Example::
.. method:: GeoQuerySet.extent3d(**kwargs)
.. versionadded:: 1.2
*Availability*: PostGIS
Returns the 3D extent of the ``GeoQuerySet`` as a six-tuple, comprising
@@ -1195,7 +1185,7 @@ Keyword Argument Description
details.
===================== =====================================================
__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150
__ http://docs.oracle.com/html/B14255_01/sdo_intro.htm#sthref150
Aggregate Functions
-------------------
@@ -1224,8 +1214,6 @@ Returns the same as the :meth:`GeoQuerySet.extent` aggregate method.
.. class:: Extent3D(geo_field)
.. versionadded:: 1.2
Returns the same as the :meth:`GeoQuerySet.extent3d` aggregate method.
``MakeLine``
@@ -1244,6 +1232,6 @@ Returns the same as the :meth:`GeoQuerySet.union` aggregate method.
.. rubric:: Footnotes
.. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
.. [#fnsdorelate] *See* `SDO_RELATE documentation <http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_, from Ch. 11 of the Oracle Spatial User's Guide and Manual.
.. [#fnsdorelate] *See* `SDO_RELATE documentation <http://docs.oracle.com/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_, from Ch. 11 of the Oracle Spatial User's Guide and Manual.
.. [#fncovers] For an explanation of this routine, read `Quirks of the "Contains" Spatial Predicate <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ by Martin Davis (a PostGIS developer).
.. [#fncontainsproperly] Refer to the PostGIS ``ST_ContainsProperly`` `documentation <http://postgis.refractions.net/documentation/manual-1.4/ST_ContainsProperly.html>`_ for more details.

19
docs/ref/contrib/gis/geos.txt
View File

@@ -75,6 +75,17 @@ return a :class:`GEOSGeometry` object from an input string or a file::
>>> pnt = fromfile('/path/to/pnt.wkt')
>>> pnt = fromfile(open('/path/to/pnt.wkt'))
.. _geos-exceptions-in-logfile:
.. admonition:: My logs are filled with GEOS-related errors
You find many ``TypeError`` or ``AttributeError`` exceptions filling your
Web server's log files. This generally means that you are creating GEOS
objects at the top level of some of your Python modules. Then, due to a race
condition in the garbage collector, your module is garbage collected before
the GEOS object. To prevent this, create :class:`GEOSGeometry` objects
inside the local scope of your functions/methods.
Geometries are Pythonic
-----------------------
:class:`GEOSGeometry` objects are 'Pythonic', in other words components may
@@ -265,8 +276,6 @@ because it is not a part of the OGC specification (use the
.. attribute:: GEOSGeometry.hexewkb
.. versionadded:: 1.2
Returns the EWKB of this Geometry in hexadecimal form. This is an
extension of the WKB specification that includes SRID and Z values
that are a part of this geometry.
@@ -314,8 +323,6 @@ as a Python buffer. SRID and Z values are not included, use the
.. attribute:: GEOSGeometry.ewkb
.. versionadded:: 1.2
Return the EWKB representation of this Geometry as a Python buffer.
This is an extension of the WKB specification that includes any SRID
and Z values that are a part of this geometry.
@@ -328,7 +335,7 @@ and Z values that are a part of this geometry.
Returns the Well-Known Text of the geometry (an OGC standard).
__ http://code.google.com/apis/kml/documentation/
__ https://developers.google.com/kml/documentation/
Spatial Predicate Methods
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -895,7 +902,7 @@ Returns the WKT of the given geometry. Example::
.. rubric:: Footnotes
.. [#fnogc] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/docs/ch04.html#id2591381>`_, PostGIS documentation at Ch. 4.1.2.
.. [#fnogc] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/docs/using_postgis_dbmanagement.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2.
.. [#fncascadedunion] For more information, read Paul Ramsey's blog post about `(Much) Faster Unions in PostGIS 1.4 <http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html>`_ and Martin Davis' blog post on `Fast polygon merging in JTS using Cascaded Union <http://lin-ear-th-inking.blogspot.com/2007/11/fast-polygon-merging-in-jts-using.html>`_.
Settings

121
docs/ref/contrib/gis/install.txt
View File

@@ -60,14 +60,14 @@ The geospatial libraries required for a GeoDjango installation depends
on the spatial database used. The following lists the library requirements,
supported versions, and any notes for each of the supported database backends:
================== ============================== ================== ==========================================================
================== ============================== ================== =========================================
Database Library Requirements Supported Versions Notes
================== ============================== ================== ==========================================================
================== ============================== ================== =========================================
PostgreSQL GEOS, PROJ.4, PostGIS 8.1+ Requires PostGIS.
MySQL GEOS 5.x Not OGC-compliant; limited functionality.
Oracle GEOS 10.2, 11 XE not supported; not tested with 9.
SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1.
================== ============================== ================== ==========================================================
SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+
================== ============================== ================== =========================================
.. _geospatial_libs:
@@ -81,7 +81,7 @@ Program Description Required
======================== ==================================== ================================ ==========================
:ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.3, 3.2, 3.1, 3.0
`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.7, 4.6, 4.5, 4.4
:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.8, 1.7, 1.6, 1.5, 1.4
:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.9, 1.8, 1.7, 1.6, 1.5
:ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 1.5, 1.4, 1.3
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 3.0, 2.4, 2.3
@@ -102,7 +102,7 @@ Program Description Required
.. _PROJ.4: http://trac.osgeo.org/proj/
__ http://postgis.refractions.net/
__ http://www.gaia-gis.it/spatialite/index.html
__ http://www.gaia-gis.it/gaia-sins/
.. _build_from_source:
@@ -140,7 +140,7 @@ internal geometry representation used by GeoDjango (it's behind the "lazy"
geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``)
directly from Python using ctypes.
First, download GEOS 3.2 from the refractions Web site and untar the source
First, download GEOS 3.3.0 from the refractions Web site and untar the source
archive::
$ wget http://download.osgeo.org/geos/geos-3.3.0.tar.bz2
@@ -191,6 +191,8 @@ GEOS C library. For example:
The setting must be the *full* path to the **C** shared library; in
other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
.. _proj4:
PROJ.4
@@ -233,7 +235,7 @@ installed prior to building PostGIS.
The `psycopg2`_ module is required for use as the database adaptor
when using GeoDjango with PostGIS.
.. _psycopg2: http://initd.org/projects/psycopg2
.. _psycopg2: http://initd.org/psycopg/
First download the source archive, and extract::
@@ -270,9 +272,9 @@ supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_.
First download the latest GDAL release version and untar the archive::
$ wget http://download.osgeo.org/gdal/gdal-1.8.1.tar.gz
$ tar xzf gdal-1.8.1.tar.gz
$ cd gdal-1.8.1
$ wget http://download.osgeo.org/gdal/gdal-1.9.1.tar.gz
$ tar xzf gdal-1.9.1.tar.gz
$ cd gdal-1.9.1
Configure, make and install::
@@ -376,7 +378,7 @@ SpatiaLite.
After installation is complete, don't forget to read the post-installation
docs on :ref:`create_spatialite_db`.
__ http://www.gaia-gis.it/spatialite/index.html
__ http://www.gaia-gis.it/gaia-sins/
.. _sqlite:
@@ -418,8 +420,8 @@ SpatiaLite library (``libspatialite``) and tools (``spatialite``)
After SQLite has been built with the R*Tree module enabled, get the latest
SpatiaLite library source and tools bundle from the `download page`__::
$ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz
$ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz
$ wget http://www.gaia-gis.it/gaia-sins/libspatialite-sources/libspatialite-amalgamation-2.3.1.tar.gz
$ wget http://www.gaia-gis.it/gaia-sins/spatialite-tools-sources/spatialite-tools-2.3.1.tar.gz
$ tar xzf libspatialite-amalgamation-2.3.1.tar.gz
$ tar xzf spatialite-tools-2.3.1.tar.gz
@@ -457,7 +459,7 @@ Finally, do the same for the SpatiaLite tools::
$ ./configure --target=macosx
__ http://www.gaia-gis.it/spatialite/sources.html
__ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
.. _pysqlite2:
@@ -465,8 +467,8 @@ pysqlite2
^^^^^^^^^
Because SpatiaLite must be loaded as an external extension, it requires the
``enable_load_extension`` method, which is only available in versions 2.5+.
Thus, download pysqlite2 2.6, and untar::
``enable_load_extension`` method, which is only available in versions 2.5+ of
pysqlite2. Thus, download pysqlite2 2.6, and untar::
$ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz
$ tar xzf pysqlite-2.6.0.tar.gz
@@ -581,7 +583,7 @@ After you've installed SpatiaLite, you'll need to create a number of spatial
metadata tables in your database in order to perform spatial queries.
If you're using SpatiaLite 3.0 or newer, use the ``spatialite`` utility to
call the ``InitSpatiaMetaData()`` function, like this::
call the ``InitSpatialMetaData()`` function, like this::
$ spatialite geodjango.db "SELECT InitSpatialMetaData();"
the SPATIAL_REF_SYS table already contains some row(s)
@@ -603,7 +605,7 @@ http://www.gaia-gis.it/spatialite-2.4.0/ for 2.4)::
Then, use the ``spatialite`` command to initialize a spatial database::
$ spatialite geodjango.db < init_spatialite-2.X.sql
$ spatialite geodjango.db < init_spatialite-2.3.sql
.. note::
@@ -624,8 +626,6 @@ features such as the geographic admin or KML sitemaps will not function properly
Add Google projection to ``spatial_ref_sys`` table
--------------------------------------------------
.. versionchanged:: 1.2
.. note::
If you're running PostGIS 1.4 or above, you can skip this step. The entry
@@ -643,10 +643,6 @@ Invoke the Django shell from your project and execute the
>>> from django.contrib.gis.utils import add_srs_entry
>>> add_srs_entry(900913)
.. note::
In Django 1.1 the name of this function is ``add_postgis_srs``.
This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent)
table, making it possible for the spatial database to transform coordinates in
this projection. You only need to execute this command *once* per spatial database.
@@ -666,7 +662,7 @@ community! You can:
and specify the component as "GIS".
__ http://groups.google.com/group/geodjango
__ https://code.djangoproject.com/simpleticket
__ https://code.djangoproject.com/newticket
.. _libsettings:
@@ -764,13 +760,13 @@ Python
^^^^^^
Although OS X comes with Python installed, users can use framework
installers (`2.5`__ and `2.6`__ are available) provided by
installers (`2.6`__ and `2.7`__ are available) provided by
the Python Software Foundation. An advantage to using the installer is
that OS X's Python will remain "pristine" for internal operating system
use.
__ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg
__ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg
__ http://python.org/ftp/python/2.6.6/python-2.6.6-macosx10.3.dmg
__ http://python.org/ftp/python/2.7.3/
.. note::
@@ -840,17 +836,6 @@ your ``.profile`` to be able to run the package programs from the command-line::
__ http://www.kyngchaos.com/software/frameworks
__ http://www.kyngchaos.com/software/postgres
.. note::
Use of these binaries requires Django 1.0.3 and above. If you are
using a previous version of Django (like 1.0.2), then you will have
to add the following in your settings:
.. code-block:: python
GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS'
GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL'
.. _psycopg2_kyngchaos:
psycopg2
@@ -905,7 +890,7 @@ add the following to your ``settings.py``:
SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3'
__ http://www.gaia-gis.it/spatialite/binaries.html
__ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
.. _fink:
@@ -1047,61 +1032,11 @@ Optional packages to consider:
do not plan on doing any database transformation of geometries to the
Google projection (900913).
.. _heron:
8.04 and lower
~~~~~~~~~~~~~~
The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages,
which is incompatible with GeoDjango. Thus, do *not* use the binary packages
for GEOS or PostGIS and build some prerequisites from source, per the instructions
in this document; however, it is okay to use the PostgreSQL binary packages.
For more details, please see the Debian instructions for :ref:`etch` below.
.. _debian:
Debian
------
.. _etch:
4.0 (Etch)
^^^^^^^^^^
The situation here is the same as that of Ubuntu :ref:`heron` -- in other words,
some packages must be built from source to work properly with GeoDjango.
Binary packages
~~~~~~~~~~~~~~~
The following command will install acceptable binary packages, as well as
the development tools necessary to build the rest of the requirements:
.. code-block:: bash
$ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 \
postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools
Required package information:
* ``binutils``: for ctypes to find libraries
* ``bzip2``: for decompressing the source packages
* ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries
* ``flex``: required to build PostGIS
* ``postgresql-8.1``
* ``postgresql-server-dev-8.1``: for ``pg_config``
* ``python-psycopg2``
Optional packages:
* ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support
Source packages
~~~~~~~~~~~~~~~
You will still have to install :ref:`geosbuild`, :ref:`proj4`,
:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the
directions carefully.
.. _lenny:
5.0 (Lenny)
@@ -1316,8 +1251,8 @@ may be executed from the SQL Shell as the ``postgres`` user::
.. rubric:: Footnotes
.. [#] The datum shifting files are needed for converting data to and from
certain projections.
For example, the PROJ.4 string for the `Google projection (900913)
<http://spatialreference.org/ref/epsg/900913/proj4>`_ requires the
For example, the PROJ.4 string for the `Google projection (900913 or 3857)
<http://spatialreference.org/ref/sr-org/6864/prj/>`_ requires the
``null`` grid file only included in the extra datum shifting files.
It is easier to install the shifting files now, then to have debug a
problem caused by their absence later.

8
docs/ref/contrib/gis/model-api.txt
View File

@@ -142,7 +142,7 @@ __ http://en.wikipedia.org/wiki/Geodesy
__ http://en.wikipedia.org/wiki/Great_circle
__ http://www.spatialreference.org/ref/epsg/2796/
__ http://spatialreference.org/
__ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html
__ http://web.archive.org/web/20080302095452/http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html
``spatial_index``
-----------------
@@ -163,8 +163,6 @@ field.
``dim``
-------
.. versionadded:: 1.2
.. attribute:: GeometryField.dim
This option may be used for customizing the coordinate dimension of the
@@ -180,8 +178,6 @@ three-dimensonal support.
``geography``
-------------
.. versionadded:: 1.2
.. attribute:: GeometryField.geography
If set to ``True``, this option will create a database column of
@@ -256,7 +252,7 @@ for example::
qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
.. rubric:: Footnotes
.. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999).
.. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengeospatial.org/standards/sfs>`_.
.. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).
.. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table.
.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems.

9
docs/ref/contrib/gis/sitemaps.txt
View File

@@ -2,10 +2,10 @@
Geographic Sitemaps
===================
Google's sitemap protocol has been recently extended to support geospatial
content. [#]_ This includes the addition of the ``<url>`` child element
Google's sitemap protocol used to include geospatial content support. [#]_
This included the addition of the ``<url>`` child element
``<geo:geo>``, which tells Google that the content located at the URL is
geographic in nature. [#]_
geographic in nature. This is now obsolete.
Example
=======
@@ -23,5 +23,4 @@ Reference
-----------------
.. rubric:: Footnotes
.. [#] Google, Inc., `What is a Geo Sitemap? <http://www.google.com/support/webmasters/bin/answer.py?answer=94554>`_.
.. [#] Google, Inc., `Submit Your Geo Content to Google <http://code.google.com/apis/kml/documentation/kmlSearch.html>`_.
.. [#] Google, Inc., `What is a Geo Sitemap? <http://support.google.com/webmasters/bin/answer.py?answer=94555>`_.

15
docs/ref/contrib/gis/testing.txt
View File

@@ -2,12 +2,6 @@
Testing GeoDjango apps
======================
.. versionchanged:: 1.2
In Django 1.2, the addition of :ref:`spatial-backends` simplified the
process of testing GeoDjango applications. The process is now the
same as :doc:`/topics/testing`.
Included in this documentation are some additional notes and settings
for :ref:`testing-postgis` and :ref:`testing-spatialite` users.
@@ -28,11 +22,9 @@ Settings
``POSTGIS_TEMPLATE``
^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 1.2
This setting may be used to customize the name of the PostGIS template
database to use. In Django versions 1.2 and above, it automatically
defaults to ``'template_postgis'`` (the same name used in the
database to use. It automatically defaults to ``'template_postgis'``
(the same name used in the
:ref:`installation documentation <spatialdb_template>`).
.. setting:: POSTGIS_VERSION
@@ -129,7 +121,8 @@ Settings
Only relevant when using a SpatiaLite version older than 3.0.
By default, the GeoDjango test runner looks for the SpatiaLite SQL in the
By default, the GeoDjango test runner looks for the :ref:`file containing the
SpatiaLite dababase-initialization SQL code <create_spatialite_db>` in the
same directory where it was invoked (by default the same directory where
``manage.py`` is located). To use a different location, add the following to
your settings::

2
docs/ref/contrib/gis/tutorial.txt
View File

@@ -784,4 +784,4 @@ option class in your ``admin.py`` file::
.. [#] Special thanks to Bjørn Sandvik of `thematicmapping.org <http://thematicmapping.org>`_ for providing and maintaining this data set.
.. [#] GeoDjango basic apps was written by Dane Springmeyer, Josh Livni, and Christopher Schmidt.
.. [#] Here the point is for the `University of Houston Law Center <http://www.law.uh.edu/>`_.
.. [#] Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049.
.. [#] Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengeospatial.org/standards/sfs>`_.

9
docs/ref/contrib/humanize.txt
View File

@@ -103,9 +103,9 @@ naturaltime
.. versionadded:: 1.4
For datetime values, returns a string representing how many seconds,
minutes or hours ago it was -- falling back to a longer date format if the
value is more than a day old. In case the datetime value is in the future
the return value will automatically use an appropriate phrase.
minutes or hours ago it was -- falling back to the :tfilter:`timesince`
format if the value is more than a day old. In case the datetime value is in
the future the return value will automatically use an appropriate phrase.
Examples (when 'now' is 17 Feb 2007 16:30:00):
@@ -115,13 +115,14 @@ Examples (when 'now' is 17 Feb 2007 16:30:00):
* ``17 Feb 2007 16:25:35`` becomes ``4 minutes ago``.
* ``17 Feb 2007 15:30:29`` becomes ``an hour ago``.
* ``17 Feb 2007 13:31:29`` becomes ``2 hours ago``.
* ``16 Feb 2007 13:31:29`` becomes ``1 day ago``.
* ``16 Feb 2007 13:31:29`` becomes ``1 day, 3 hours ago``.
* ``17 Feb 2007 16:30:30`` becomes ``29 seconds from now``.
* ``17 Feb 2007 16:31:00`` becomes ``a minute from now``.
* ``17 Feb 2007 16:34:35`` becomes ``4 minutes from now``.
* ``17 Feb 2007 16:30:29`` becomes ``an hour from now``.
* ``17 Feb 2007 18:31:29`` becomes ``2 hours from now``.
* ``18 Feb 2007 16:31:29`` becomes ``1 day from now``.
* ``26 Feb 2007 18:31:29`` becomes ``1 week, 2 days from now``.
.. templatefilter:: ordinal

3
docs/ref/contrib/index.txt
View File

@@ -142,9 +142,6 @@ See the :doc:`markup documentation </ref/contrib/markup>`.
messages
========
.. versionchanged:: 1.2
The messages framework was added.
A framework for storing and retrieving temporary cookie- or session-based
messages

6
docs/ref/contrib/localflavor.txt
View File

@@ -93,7 +93,7 @@ Here's an example of how to use them::
class MyForm(forms.Form):
my_date_field = generic.forms.DateField()
.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes.htm
.. _Argentina: `Argentina (ar)`_
.. _Australia: `Australia (au)`_
.. _Austria: `Austria (at)`_
@@ -158,7 +158,7 @@ any code you'd like to contribute. One thing we ask is that you please use
Unicode objects (``u'mystring'``) for strings, rather than setting the encoding
in the file. See any of the existing flavors for examples.
.. _create a ticket: https://code.djangoproject.com/simpleticket
.. _create a ticket: https://code.djangoproject.com/newticket
Localflavor and backwards compatibility
=======================================
@@ -713,7 +713,7 @@ Italy (``it``)
A form field that validates input as an Italian social security number
(`codice fiscale`_).
.. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche
.. _codice fiscale: http://www.agenziaentrate.gov.it/wps/content/Nsilib/Nsi/Home/CosaDeviFare/Richiedere/Codice+fiscale+e+tessera+sanitaria/Richiesta+TS_CF/SchedaI/Informazioni+codificazione+pf/
.. class:: it.forms.ITVatNumberField

24
docs/ref/contrib/messages.txt
View File

@@ -5,15 +5,14 @@ The messages framework
.. module:: django.contrib.messages
:synopsis: Provides cookie- and session-based temporary message storage.
Django provides full support for cookie- and session-based messaging, for
both anonymous and authenticated clients. The messages framework allows you
to temporarily store messages in one request and retrieve them for display
in a subsequent request (usually the next one). Every message is tagged
with a specific ``level`` that determines its priority (e.g., ``info``,
``warning``, or ``error``).
.. versionadded:: 1.2
The messages framework was added.
Quite commonly in web applications, you may need to display a one-time
notification message (also know as "flash message") to the user after
processing a form or some other types of user input. For this, Django provides
full support for cookie- and session-based messaging, for both anonymous and
authenticated users. The messages framework allows you to temporarily store
messages in one request and retrieve them for display in a subsequent request
(usually the next one). Every message is tagged with a specific ``level`` that
determines its priority (e.g., ``info``, ``warning``, or ``error``).
Enabling messages
=================
@@ -57,7 +56,8 @@ Storage backends
----------------
The messages framework can use different backends to store temporary messages.
To change which backend is being used, add a `MESSAGE_STORAGE`_ to your
If the default FallbackStorage isn't suitable to your needs, you can change
which backend is being used by adding a `MESSAGE_STORAGE`_ to your
settings, referencing the module and class of the storage class. For
example::
@@ -65,7 +65,7 @@ example::
The value should be the full path of the desired storage class.
Four storage classes are included:
Three storage classes are available:
``'django.contrib.messages.storage.session.SessionStorage'``
This class stores all messages inside of the request's session. It
@@ -77,6 +77,8 @@ Four storage classes are included:
messages are dropped if the cookie data size would exceed 4096 bytes.
``'django.contrib.messages.storage.fallback.FallbackStorage'``
This is the default storage class.
This class first uses CookieStorage for all messages, falling back to using
SessionStorage for the messages that could not fit in a single cookie.

2
docs/ref/contrib/sitemaps.txt
View File

@@ -410,7 +410,7 @@ generate a Google News compatible sitemap:
{% endspaceless %}
</urlset>
.. _`Google news sitemaps`: http://www.google.com/support/webmasters/bin/answer.py?hl=en&answer=74288
.. _`Google news sitemaps`: http://support.google.com/webmasters/bin/answer.py?hl=en&answer=74288
Pinging Google
==============

15
docs/ref/contrib/staticfiles.txt
View File

@@ -380,13 +380,24 @@ full URL for the given relative path, e.g.:
.. code-block:: html+django
{% load static from staticfiles %}
<img src="{% static "css/base.css" %}" />
<img src="{% static "images/hi.jpg" %}" alt="Hi!" />
The previous example is equal to calling the ``url`` method of an instance of
:setting:`STATICFILES_STORAGE` with ``"css/base.css"``. This is especially
:setting:`STATICFILES_STORAGE` with ``"images/hi.jpg"``. This is especially
useful when using a non-local storage backend to deploy files as documented
in :ref:`staticfiles-from-cdn`.
.. versionadded:: 1.5
If you'd like to retrieve a static URL without displaying it, you can use a
slightly different call:
.. code-block:: html+django
{% load static from staticfiles %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}" alt="Hi!" />
Other Helpers
=============

7
docs/ref/contrib/syndication.txt
View File

@@ -22,10 +22,6 @@ lower-level way.
The high-level framework
========================
.. versionchanged:: 1.2
The high-level feeds framework was refactored in Django 1.2. The
pre-1.2 interface has been removed in Django 1.4.
Overview
--------
@@ -176,9 +172,6 @@ These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::
Like a view, the arguments in the URL are passed to the ``get_object()``
method along with the request object.
.. versionchanged:: 1.2
Prior to version 1.2, ``get_object()`` only accepted a ``bits`` argument.
Here's the code for these beat-specific feeds::
from django.contrib.syndication.views import FeedDoesNotExist

27
docs/ref/databases.txt
View File

@@ -31,7 +31,7 @@ attempt to use the ``StdDev(sample=False)`` or ``Variance(sample=False)``
aggregate with a database backend that falls within the affected release range.
.. _known to be faulty: http://archives.postgresql.org/pgsql-bugs/2007-07/msg00046.php
.. _Release 8.2.5: http://developer.postgresql.org/pgdocs/postgres/release-8-2-5.html
.. _Release 8.2.5: http://www.postgresql.org/docs/devel/static/release-8-2-5.html
Optimizing PostgreSQL's configuration
-------------------------------------
@@ -56,10 +56,10 @@ will do some additional queries to set these parameters.
Transaction handling
---------------------
:doc:`By default </topics/db/transactions>`, Django starts a transaction when a
database connection is first used and commits the result at the end of the
request/response handling. The PostgreSQL backends normally operate the same
as any other Django backend in this respect.
:doc:`By default </topics/db/transactions>`, Django runs with an open
transaction which it commits automatically when any built-in, data-altering
model function is called. The PostgreSQL backends normally operate the same as
any other Django backend in this respect.
.. _postgresql-autocommit-mode:
@@ -111,7 +111,7 @@ outputs a single ``CREATE INDEX`` statement. However, if the database type
for the field is either ``varchar`` or ``text`` (e.g., used by ``CharField``,
``FileField``, and ``TextField``), then Django will create
an additional index that uses an appropriate `PostgreSQL operator class`_
for the column. The extra index is necessary to correctly perfrom
for the column. The extra index is necessary to correctly perform
lookups that use the ``LIKE`` operator in their SQL, as is done with the
``contains`` and ``startswith`` lookup types.
@@ -238,7 +238,7 @@ to you, the developer, to handle the fact that you will receive bytestrings if
you configure your table(s) to use ``utf8_bin`` collation. Django itself should
mostly work smoothly with such columns (except for the ``contrib.sessions``
``Session`` and ``contrib.admin`` ``LogEntry`` tables described below), but
your code must be prepared to call ``django.utils.encoding.smart_unicode()`` at
your code must be prepared to call ``django.utils.encoding.smart_text()`` at
times if it really wants to work with consistent data -- Django will not do
this for you (the database backend layer and the model population layer are
separated internally so the database layer doesn't know it needs to make this
@@ -335,7 +335,9 @@ storage engine, you have a couple of options.
}
This sets the default storage engine upon connecting to the database.
After your tables have been created, you should remove this option.
After your tables have been created, you should remove this option as it
adds a query that is only needed during table creation to each database
connection.
* Another method for changing the storage engine is described in
AlterModelOnSyncDB_.
@@ -373,15 +375,6 @@ these methods in no-op's based in the results of such detection.
Notes on specific fields
------------------------
Boolean fields
~~~~~~~~~~~~~~
.. versionchanged:: 1.2
In previous versions of Django when running under MySQL ``BooleanFields`` would
return their data as ``ints``, instead of true ``bools``. See the release
notes for a complete description of the change.
Character fields
~~~~~~~~~~~~~~~~

82
docs/ref/django-admin.txt
View File

@@ -109,7 +109,7 @@ If not provided, all locales are processed.
Example usage::
django-admin.py compilemessages --locale=br_PT
django-admin.py compilemessages --locale=pt_BR
createcachetable
----------------
@@ -119,8 +119,6 @@ createcachetable
Creates a cache table named ``tablename`` for use with the database cache
backend. See :doc:`/topics/cache` for more information.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database
onto which the cachetable will be installed.
@@ -142,8 +140,6 @@ the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in
the right place. There's no way to specify the location of the program
manually.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database
onto which to open a shell.
@@ -212,15 +208,11 @@ name to ``dumpdata``, the dumped output will be restricted to that model,
rather than the entire application. You can also mix application names and
model names.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database
from which data will be dumped.
.. django-admin-option:: --natural
.. versionadded:: 1.2
Use :ref:`natural keys <topics-serialization-natural-keys>` to represent
any foreign key and many-to-many relationship with a model that provides
a natural key definition. If you are dumping ``contrib.auth`` ``Permission``
@@ -232,19 +224,25 @@ flush
.. django-admin:: flush
Returns the database to the state it was in immediately after syncdb was
executed. This means that all data will be removed from the database, any
Returns the database to the state it was in immediately after :djadmin:`syncdb`
was executed. This means that all data will be removed from the database, any
post-synchronization handlers will be re-executed, and the ``initial_data``
fixture will be re-installed.
The :djadminopt:`--noinput` option may be provided to suppress all user
prompts.
.. versionadded:: 1.2
The :djadminopt:`--database` option may be used to specify the database
to flush.
--no-initial-data
~~~~~~~~~~~~~~~~~
.. versionadded:: 1.5
Use ``--no-initial-data`` to avoid loading the initial_data fixture.
inspectdb
---------
@@ -288,8 +286,6 @@ needed.
``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
only works in PostgreSQL and with certain types of MySQL tables.
.. versionadded:: 1.2
The :djadminopt:`--database` option may be used to specify the
database to introspect.
@@ -300,8 +296,6 @@ loaddata <fixture fixture ...>
Searches for and loads the contents of the named fixture into the database.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database
onto which the data will be loaded.
@@ -432,7 +426,7 @@ Use the :djadminopt:`--locale` option to specify the locale to process.
Example usage::
django-admin.py makemessages --locale=br_PT
django-admin.py makemessages --locale=pt_BR
.. django-admin-option:: --domain
@@ -444,8 +438,6 @@ Currently supported:
.. django-admin-option:: --symlinks
.. versionadded:: 1.2
Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when
looking for new translation strings.
@@ -676,6 +668,7 @@ Example usage::
.. versionadded:: 1.4
Since version 1.4, the development server is multithreaded by default.
Use the ``--nothreading`` option to disable the use of threading in the
development server.
@@ -750,6 +743,24 @@ use the ``--plain`` option, like so::
django-admin.py shell --plain
.. versionchanged:: 1.5
If you would like to specify either IPython or bpython as your interpreter if
you have both installed you can specify an alternative interpreter interface
with the ``-i`` or ``--interface`` options like so:
IPython::
django-admin.py shell -i ipython
django-admin.py shell --interface ipython
bpython::
django-admin.py shell -i bpython
django-admin.py shell --interface bpython
.. _IPython: http://ipython.scipy.org/
.. _bpython: http://bpython-interpreter.org/
@@ -760,8 +771,6 @@ sql <appname appname ...>
Prints the CREATE TABLE SQL statements for the given app name(s).
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -775,8 +784,6 @@ Prints the CREATE TABLE and initial-data SQL statements for the given app name(s
Refer to the description of ``sqlcustom`` for an explanation of how to
specify initial data.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -787,8 +794,6 @@ sqlclear <appname appname ...>
Prints the DROP TABLE SQL statements for the given app name(s).
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -813,8 +818,6 @@ table modifications, or insert any SQL functions into the database.
Note that the order in which the SQL files are processed is undefined.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -826,8 +829,6 @@ sqlflush
Prints the SQL statements that would be executed for the :djadmin:`flush`
command.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -838,8 +839,6 @@ sqlindexes <appname appname ...>
Prints the CREATE INDEX SQL statements for the given app name(s).
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -856,8 +855,6 @@ number for automatically incremented fields.
Use this command to generate SQL which will fix cases where a sequence is out
of sync with its automatically incremented field data.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database for
which to print the SQL.
@@ -909,7 +906,8 @@ through the template engine: the files whose extensions match the
with the ``--name`` option. The :class:`template context
<django.template.Context>` used is:
- Any option passed to the startapp command
- Any option passed to the startapp command (among the command's supported
options)
- ``app_name`` -- the app name as passed to the command
- ``app_directory`` -- the full path of the newly created app
@@ -1019,11 +1017,16 @@ data files.
The :djadminopt:`--noinput` option may be provided to suppress all user
prompts.
.. versionadded:: 1.2
The :djadminopt:`--database` option can be used to specify the database to
synchronize.
--no-initial-data
~~~~~~~~~~~~~~~~~
.. versionadded:: 1.5
Use ``--no-initial-data`` to avoid loading the initial_data fixture.
test <app or test identifier>
-----------------------------
@@ -1032,7 +1035,6 @@ test <app or test identifier>
Runs tests for all installed models. See :doc:`/topics/testing` for more
information.
.. versionadded:: 1.2
.. django-admin-option:: --failfast
The ``--failfast`` option can be used to stop running tests and report the
@@ -1140,8 +1142,6 @@ changepassword
.. django-admin:: changepassword
.. versionadded:: 1.2
This command is only available if Django's :doc:`authentication system
</topics/auth>` (``django.contrib.auth``) is installed.
@@ -1302,8 +1302,6 @@ to a number of commands.
.. django-admin-option:: --database
.. versionadded:: 1.2
Used to specify the database on which a command will operate. If not
specified, this option will default to an alias of ``default``.

3
docs/ref/files/file.txt
View File

@@ -94,10 +94,11 @@ The ``ContentFile`` Class
but unlike :class:`~django.core.files.File` it operates on string content,
rather than an actual file. For example::
from __future__ import unicode_literals
from django.core.files.base import ContentFile
f1 = ContentFile(b"my string content")
f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8'))
f2 = ContentFile("my unicode content encoded as UTF-8".encode('UTF-8'))
.. currentmodule:: django.core.files.images

25
docs/ref/forms/api.txt
View File

@@ -199,8 +199,8 @@ Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
always cleans the input into a Unicode string. We'll cover the encoding
implications later in this document.
If your data does *not* validate, your ``Form`` instance will not have a
``cleaned_data`` attribute::
If your data does *not* validate, the ``cleaned_data`` dictionary contains
only the valid fields::
>>> data = {'subject': '',
... 'message': 'Hi there',
@@ -210,9 +210,12 @@ If your data does *not* validate, your ``Form`` instance will not have a
>>> f.is_valid()
False
>>> f.cleaned_data
Traceback (most recent call last):
...
AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
{'cc_myself': True, 'message': u'Hi there'}
.. versionchanged:: 1.5
Until Django 1.5, the ``cleaned_data`` attribute wasn't defined at all when
the ``Form`` didn't validate.
``cleaned_data`` will always *only* contain a key for fields defined in the
``Form``, even if you pass extra data when you define the ``Form``. In this
@@ -232,9 +235,9 @@ but ``cleaned_data`` contains only the form's fields::
>>> f.cleaned_data # Doesn't contain extra_field_1, etc.
{'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
``cleaned_data`` will include a key and value for *all* fields defined in the
``Form``, even if the data didn't include a value for fields that are not
required. In this example, the data dictionary doesn't include a value for the
When the ``Form`` is valid, ``cleaned_data`` will include a key and value for
*all* its fields, even if the data didn't include a value for some optional
fields. In this example, the data dictionary doesn't include a value for the
``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::
>>> class OptionalPersonForm(Form):
@@ -377,8 +380,6 @@ a form object, and each rendering method returns a Unicode object.
Styling required or erroneous form rows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.2
It's pretty common to style form rows and fields that are required or have
errors. For example, you might want to present required form rows in bold and
highlight errors in red.
@@ -585,7 +586,7 @@ lazy developers -- they're not the only way a form object can be displayed.
Used to display HTML or access attributes for a single field of a
:class:`Form` instance.
The :meth:`__unicode__` and :meth:`__str__` methods of this object displays
the HTML for this field.
@@ -638,8 +639,6 @@ For a field's list of errors, access the field's ``errors`` attribute.
.. method:: BoundField.css_classes()
.. versionadded:: 1.2
When you use Django's rendering shortcuts, CSS classes are used to
indicate required form fields or fields that contain errors. If you're
manually rendering a form, you can access these CSS classes using the

22
docs/ref/forms/fields.txt
View File

@@ -25,8 +25,6 @@ exception or returns the clean value::
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
u'foo@example.com'
>>> f.clean(u'foo@example.com')
u'foo@example.com'
>>> f.clean('invalid email address')
Traceback (most recent call last):
...
@@ -256,8 +254,6 @@ error message keys it uses.
``validators``
~~~~~~~~~~~~~~
.. versionadded:: 1.2
.. attribute:: Field.validators
The ``validators`` argument lets you provide a list of validation functions
@@ -268,8 +264,6 @@ See the :doc:`validators documentation </ref/validators>` for more information.
``localize``
~~~~~~~~~~~~
.. versionadded:: 1.2
.. attribute:: Field.localize
The ``localize`` argument enables the localization of form data, input as well
@@ -492,11 +486,6 @@ For each field, we describe the default widget used if you don't specify
If provided, these arguments ensure that the string is at most or at least the
given length.
.. versionchanged:: 1.2
The EmailField previously did not recognize email addresses as valid that
contained an IDN (Internationalized Domain Name; a domain containing
unicode characters) domain part. This has now been corrected.
``FileField``
~~~~~~~~~~~~~
@@ -602,7 +591,11 @@ For each field, we describe the default widget used if you don't specify
* Error message keys: ``required``, ``invalid``, ``missing``, ``empty``,
``invalid_image``
Using an ImageField requires that the `Python Imaging Library`_ is installed.
Using an ``ImageField`` requires that the `Python Imaging Library`_ (PIL)
is installed and supports the image formats you use. If you encounter a
``corrupt image`` error when you upload an image, it usually means PIL
doesn't understand its format. To fix this, install the appropriate
library and reinstall PIL.
When you use an ``ImageField`` on a form, you must also remember to
:ref:`bind the file data to the form <binding-uploaded-files>`.
@@ -815,11 +808,6 @@ For each field, we describe the default widget used if you don't specify
These are the same as ``CharField.max_length`` and ``CharField.min_length``.
.. versionchanged:: 1.2
The URLField previously did not recognize URLs as valid that contained an IDN
(Internationalized Domain Name; a domain name containing unicode characters)
domain name. This has now been corrected.
Slightly complex built-in ``Field`` classes
-------------------------------------------

19
docs/ref/forms/validation.txt
View File

@@ -1,8 +1,8 @@
.. _form-and-field-validation:
Form and field validation
=========================
.. versionchanged:: 1.2
Form validation happens when the data is cleaned. If you want to customize
this process, there are various places you can change, each one serving a
different purpose. Three types of cleaning methods are run during form
@@ -175,7 +175,6 @@ previous features.
Using validators
~~~~~~~~~~~~~~~~
.. versionadded:: 1.2
Django's form (and model) fields support use of simple utility functions and
classes known as validators. These can be passed to a field's constructor, via
@@ -187,7 +186,7 @@ a look at Django's ``EmailField``::
class EmailField(CharField):
default_error_messages = {
'invalid': _(u'Enter a valid e-mail address.'),
'invalid': _('Enter a valid e-mail address.'),
}
default_validators = [validators.validate_email]
@@ -200,7 +199,7 @@ on field definition so::
is equivalent to::
email = forms.CharField(validators=[validators.validate_email],
error_messages={'invalid': _(u'Enter a valid e-mail address.')})
error_messages={'invalid': _('Enter a valid e-mail address.')})
Form field default cleaning
@@ -363,7 +362,9 @@ Secondly, once we have decided that the combined data in the two fields we are
considering aren't valid, we must remember to remove them from the
``cleaned_data``.
In fact, Django will currently completely wipe out the ``cleaned_data``
dictionary if there are any errors in the form. However, this behavior may
change in the future, so it's not a bad idea to clean up after yourself in the
first place.
.. versionchanged:: 1.5
Django used to remove the ``cleaned_data`` attribute entirely if there were
any errors in the form. Since version 1.5, ``cleaned_data`` is present even if
the form doesn't validate, but it contains only field values that did
validate.

4
docs/ref/forms/widgets.txt
View File

@@ -47,14 +47,12 @@ widget on the field. In the following example, the
from django.forms.extras.widgets import SelectDateWidget
BIRTH_YEAR_CHOICES = ('1980', '1981', '1982')
GENDER_CHOICES = (('m', 'Male'), ('f', 'Female'))
FAVORITE_COLORS_CHOICES = (('blue', 'Blue'),
('green', 'Green'),
('black', 'Black'))
class SimpleForm(forms.Form):
birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES))
gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES)
favorite_colors = forms.MultipleChoiceField(required=False,
widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES)
@@ -77,7 +75,7 @@ changing :attr:`ChoiceField.choices` will update :attr:`Select.choices`. For
example::
>>> from django import forms
>>> CHOICES = (('1', 'First',), ('2', 'Second',)))
>>> CHOICES = (('1', 'First',), ('2', 'Second',))
>>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
>>> choice_field.choices
[('1', 'First'), ('2', 'Second')]

2
docs/ref/index.txt
View File

@@ -6,6 +6,7 @@ API Reference
:maxdepth: 1
authbackends
class-based-views/index
clickjacking
contrib/index
databases
@@ -13,7 +14,6 @@ API Reference
exceptions
files/index
forms/index
class-based-views
middleware
models/index
request-response

5
docs/ref/middleware.txt
View File

@@ -146,7 +146,7 @@ Locale middleware
Enables language selection based on data from the request. It customizes
content for each user. See the :doc:`internationalization documentation
</topics/i18n/index>`.
</topics/i18n/translation>`.
Message middleware
------------------
@@ -156,9 +156,6 @@ Message middleware
.. class:: MessageMiddleware
.. versionadded:: 1.2
``MessageMiddleware`` was added.
Enables cookie- and session-based message support. See the
:doc:`messages documentation </ref/contrib/messages>`.

96
docs/ref/models/fields.txt
View File

@@ -86,36 +86,43 @@ field.
If this is given, Django's admin will use a select box instead of the standard
text field and will limit choices to the choices given.
A choices list looks like this::
A choices list is an iterable of 2-tuples; the first element in each
tuple is the actual value to be stored, and the second element is the
human-readable name. For example::
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
('GR', 'Graduate'),
)
The first element in each tuple is the actual value to be stored. The second
element is the human-readable name for the option.
Generally, it's best to define choices inside a model class, and to
define a suitably-named constant for each value::
The choices list can be defined either as part of your model class::
class Foo(models.Model):
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
class Student(models.Model):
FRESHMAN = 'FR'
SOPHOMORE = 'SO'
JUNIOR = 'JR'
SENIOR = 'SR'
YEAR_IN_SCHOOL_CHOICES = (
(FRESHMAN, 'Freshman'),
(SOPHOMORE, 'Sophomore'),
(JUNIOR, 'Junior'),
(SENIOR, 'Senior'),
)
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
year_in_school = models.CharField(max_length=2,
choices=YEAR_IN_SCHOOL_CHOICES,
default=FRESHMAN)
or outside your model class altogether::
def is_upperclass(self):
return self.year_in_school in (self.JUNIOR, self.SENIOR)
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
class Foo(models.Model):
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
Though you can define a choices list outside of a model class and then
refer to it, defining the choices and names for each choice inside the
model class keeps all of that information with the class that uses it,
and makes the choices easy to reference (e.g, ``Student.SOPHOMORE``
will work anywhere that the ``Student`` model has been imported).
You can also collect your available choices into named groups that can
be used for organizational purposes::
@@ -202,8 +209,6 @@ automatically generated from the model class. Default is ``True``.
``error_messages``
------------------
.. versionadded:: 1.2
.. attribute:: Field.error_messages
The ``error_messages`` argument lets you override the default messages that the
@@ -303,8 +308,6 @@ underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`.
``validators``
-------------------
.. versionadded:: 1.2
.. attribute:: Field.validators
A list of validators to run for this field. See the :doc:`validators
@@ -330,8 +333,6 @@ otherwise. See :ref:`automatic-primary-key-fields`.
``BigIntegerField``
-------------------
.. versionadded:: 1.2
.. class:: BigIntegerField([**options])
A 64 bit integer, much like an :class:`IntegerField` except that it is
@@ -351,11 +352,6 @@ The admin represents this as a checkbox.
If you need to accept :attr:`~Field.null` values then use
:class:`NullBooleanField` instead.
.. versionchanged:: 1.2
In previous versions of Django when running under MySQL ``BooleanFields``
would return their data as ``ints``, instead of true ``bools``. See the
release notes for a complete description of the change.
``CharField``
-------------
@@ -683,7 +679,7 @@ directory on the filesystem. Has three special arguments, of which the first is
Optional. A regular expression, as a string, that :class:`FilePathField`
will use to filter filenames. Note that the regex will be applied to the
base filename, not the full path. Example: ``"foo.*\.txt$"``, which will
match a file called ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.
match a file called ``foo23.txt`` but not ``bar.txt`` or ``foo23.png``.
.. attribute:: FilePathField.recursive
@@ -714,9 +710,9 @@ base filename, not the full path. So, this example::
FilePathField(path="/home/images", match="foo.*", recursive=True)
...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``
...will match ``/home/images/foo.png`` but not ``/home/images/foo/bar.png``
because the :attr:`~FilePathField.match` applies to the base filename
(``foo.gif`` and ``bar.gif``).
(``foo.png`` and ``bar.png``).
By default, :class:`FilePathField` instances are
created as ``varchar(100)`` columns in your database. As with other fields, you
@@ -1007,9 +1003,10 @@ define the details of how the relation works.
<abstract-base-classes>`; and when you do so
:ref:`some special syntax <abstract-related-name>` is available.
If you'd prefer Django didn't create a backwards relation, set ``related_name``
to ``'+'``. For example, this will ensure that the ``User`` model won't get a
backwards relation to this model::
If you'd prefer Django not to create a backwards relation, set
``related_name`` to ``'+'`` or end it with ``'+'``. For example, this will
ensure that the ``User`` model won't have a backwards relation to this
model::
user = models.ForeignKey(User, related_name='+')
@@ -1079,15 +1076,14 @@ the model is related. This works exactly the same as it does for
Database Representation
~~~~~~~~~~~~~~~~~~~~~~~
Behind the scenes, Django creates an intermediary join table to
represent the many-to-many relationship. By default, this table name
is generated using the name of the many-to-many field and the model
that contains it. Since some databases don't support table names above
a certain length, these table names will be automatically truncated to
64 characters and a uniqueness hash will be used. This means you might
see table names like ``author_books_9cdf4``; this is perfectly normal.
You can manually provide the name of the join table using the
:attr:`~ManyToManyField.db_table` option.
Behind the scenes, Django creates an intermediary join table to represent the
many-to-many relationship. By default, this table name is generated using the
name of the many-to-many field and the name of the table for the model that
contains it. Since some databases don't support table names above a certain
length, these table names will be automatically truncated to 64 characters and a
uniqueness hash will be used. This means you might see table names like
``author_books_9cdf4``; this is perfectly normal. You can manually provide the
name of the join table using the :attr:`~ManyToManyField.db_table` option.
.. _manytomany-arguments:
@@ -1101,6 +1097,13 @@ that control how the relationship functions.
Same as :attr:`ForeignKey.related_name`.
If you have more than one ``ManyToManyField`` pointing to the same model
and want to suppress the backwards relations, set each ``related_name``
to a unique value ending with ``'+'``::
users = models.ManyToManyField(User, related_name='u+')
referents = models.ManyToManyField(User, related_name='ref+')
.. attribute:: ManyToManyField.limit_choices_to
Same as :attr:`ForeignKey.limit_choices_to`.
@@ -1143,8 +1146,9 @@ that control how the relationship functions.
.. attribute:: ManyToManyField.db_table
The name of the table to create for storing the many-to-many data. If this
is not provided, Django will assume a default name based upon the names of
the two tables being joined.
is not provided, Django will assume a default name based upon the names of:
the table for the model defining the relationship and the name of the field
itself.
.. _ref-onetoone:

90
docs/ref/models/instances.txt
View File

@@ -25,13 +25,46 @@ The keyword arguments are simply the names of the fields you've defined on your
model. Note that instantiating a model in no way touches your database; for
that, you need to :meth:`~Model.save()`.
.. note::
You may be tempted to customize the model by overriding the ``__init__``
method. If you do so, however, take care not to change the calling
signature as any change may prevent the model instance from being saved.
Rather than overriding ``__init__``, try using one of these approaches:
1. Add a classmethod on the model class::
class Book(models.Model):
title = models.CharField(max_length=100)
@classmethod
def create(cls, title):
book = cls(title=title)
# do something with the book
return book
book = Book.create("Pride and Prejudice")
2. Add a method on a custom manager (usually preferred)::
class BookManager(models.Manager):
def create_book(title):
book = self.create(title=title)
# do something with the book
return book
class Book(models.Model):
title = models.CharField(max_length=100)
objects = BookManager()
book = Book.objects.create_book("Pride and Prejudice")
.. _validating-objects:
Validating objects
==================
.. versionadded:: 1.2
There are three steps involved in validating a model:
1. Validate the model fields
@@ -137,9 +170,6 @@ To save an object back to the database, call ``save()``:
.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None])
.. versionadded:: 1.2
The ``using`` argument was added.
If you want customized saving behavior, you can override this ``save()``
method. See :ref:`overriding-model-methods` for more details.
@@ -356,14 +386,17 @@ perform an update on all fields.
Specifying ``update_fields`` will force an update.
When saving a model fetched through deferred model loading
(:meth:`~Model.only()` or :meth:`~Model.defer()`) only the fields loaded from
the DB will get updated. In effect there is an automatic ``update_fields`` in
this case. If you assign or change any deferred field value, these fields will
be added to the updated fields.
Deleting objects
================
.. method:: Model.delete([using=DEFAULT_DB_ALIAS])
.. versionadded:: 1.2
The ``using`` argument was added.
Issues a SQL ``DELETE`` for the object. This only deletes the object in the
database; the Python instance will still exist and will still have data in
its fields.
@@ -426,9 +459,9 @@ using ``__str__()`` like this::
last_name = models.CharField(max_length=50)
def __str__(self):
# Note use of django.utils.encoding.smart_str() here because
# Note use of django.utils.encoding.smart_bytes() here because
# first_name and last_name will be unicode strings.
return smart_str('%s %s' % (self.first_name, self.last_name))
return smart_bytes('%s %s' % (self.first_name, self.last_name))
``get_absolute_url``
--------------------
@@ -572,25 +605,29 @@ might have some of the following methods:
For every field that has :attr:`~django.db.models.Field.choices` set, the
object will have a ``get_FOO_display()`` method, where ``FOO`` is the name of
the field. This method returns the "human-readable" value of the field. For
example, in the following model::
the field. This method returns the "human-readable" value of the field.
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
class Person(models.Model):
name = models.CharField(max_length=20)
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
For example::
...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
from django.db import models
>>> p = Person(name='John', gender='M')
>>> p.save()
>>> p.gender
'M'
>>> p.get_gender_display()
'Male'
class Person(models.Model):
SHIRT_SIZES = (
(u'S', u'Small'),
(u'M', u'Medium'),
(u'L', u'Large'),
)
name = models.CharField(max_length=60)
shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
::
>>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
>>> p.shirt_size
u'L'
>>> p.get_shirt_size_display()
u'Large'
.. method:: Model.get_next_by_FOO(\**kwargs)
.. method:: Model.get_previous_by_FOO(\**kwargs)
@@ -608,4 +645,3 @@ described in :ref:`Field lookups <field-lookups>`.
Note that in the case of identical date values, these methods will use the
primary key as a tie-breaker. This guarantees that no records are skipped or
duplicated. That also means you cannot use those methods on unsaved objects.

4
docs/ref/models/options.txt
View File

@@ -244,12 +244,12 @@ Django quotes column and table names behind the scenes.
unique_together = (("driver", "restaurant"),)
This is a list of lists of fields that must be unique when considered together.
This is a tuple of tuples that must be unique when considered together.
It's used in the Django admin and is enforced at the database level (i.e., the
appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE``
statement).
For convenience, unique_together can be a single list when dealing with a single
For convenience, unique_together can be a single tuple when dealing with a single
set of fields::
unique_together = ("driver", "restaurant")

69
docs/ref/models/querysets.txt
View File

@@ -727,8 +727,6 @@ passed to ``select_related()``. This includes foreign keys that have
It's an error to use both a list of fields and the ``depth`` parameter in the
same ``select_related()`` call; they are conflicting options.
.. versionchanged:: 1.2
You can also refer to the reverse direction of a
:class:`~django.db.models.OneToOneField` in the list of fields passed to
``select_related`` — that is, you can traverse a
@@ -1083,11 +1081,13 @@ to ``defer()``::
# Load all fields immediately.
my_queryset.defer(None)
.. versionchanged:: 1.5
Some fields in a model won't be deferred, even if you ask for them. You can
never defer the loading of the primary key. If you are using
:meth:`select_related()` to retrieve related models, you shouldn't defer the
loading of the field that connects from the primary model to the related one
(at the moment, that doesn't raise an error, but it will eventually).
loading of the field that connects from the primary model to the related
one, doing so will result in an error.
.. note::
@@ -1110,6 +1110,14 @@ loading of the field that connects from the primary model to the related one
reader, is slightly faster and consumes a little less memory in the Python
process.
.. versionchanged:: 1.5
.. note::
When calling :meth:`~Model.save()` for instances with deferred fields,
only the loaded fields will be saved. See :meth:`~Model.save()` for more
details.
only
~~~~
@@ -1147,17 +1155,26 @@ logically::
# existing set of fields).
Entry.objects.defer("body").only("headline", "body")
.. versionchanged:: 1.5
All of the cautions in the note for the :meth:`defer` documentation apply to
``only()`` as well. Use it cautiously and only after exhausting your other
options.
options. Also note that using :meth:`only` and omitting a field requested
using :meth:`select_related` is an error as well.
.. versionchanged:: 1.5
.. note::
When calling :meth:`~Model.save()` for instances with deferred fields,
only the loaded fields will be saved. See :meth:`~Model.save()` for more
details.
using
~~~~~
.. method:: using(alias)
.. versionadded:: 1.2
This method is for controlling which database the ``QuerySet`` will be
evaluated against if you are using more than one database. The only argument
this method takes is the alias of a database, as defined in
@@ -1349,7 +1366,7 @@ has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
bulk_create
~~~~~~~~~~~
.. method:: bulk_create(objs)
.. method:: bulk_create(objs, batch_size=None)
.. versionadded:: 1.4
@@ -1371,20 +1388,12 @@ This has a number of caveats though:
* If the model's primary key is an :class:`~django.db.models.AutoField` it
does not retrieve and set the primary key attribute, as ``save()`` does.
.. admonition:: Limits of SQLite
The ``batch_size`` parameter controls how many objects are created in single
query. The default is to create all objects in one batch, except for SQLite
where the default is such that at maximum 999 variables per query is used.
SQLite sets a limit on the number of parameters per SQL statement. The
maximum is defined by the SQLITE_MAX_VARIABLE_NUMBER_ compilation option,
which defaults to 999. For instance, if your model has 8 fields (including
the primary key), you cannot create more than 999 // 8 = 124 instances at
a time. If you exceed this limit, you'll get an exception::
django.db.utils.DatabaseError: too many SQL variables
If your application's performance requirements exceed SQLite's limits, you
should switch to another database engine, such as PostgreSQL.
.. _SQLITE_MAX_VARIABLE_NUMBER: http://sqlite.org/limits.html#max_variable_number
.. versionadded:: 1.5
The ``batch_size`` parameter was added in version 1.5.
count
~~~~~
@@ -1512,8 +1521,6 @@ exists
.. method:: exists()
.. versionadded:: 1.2
Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``
if not. This tries to perform the query in the simplest and fastest way
possible, but it *does* execute nearly the same query. This means that calling
@@ -1769,22 +1776,6 @@ This queryset will be evaluated as subselect statement::
SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')
The above code fragment could also be written as follows::
inner_q = Blog.objects.filter(name__contains='Cheddar').values('pk').query
entries = Entry.objects.filter(blog__in=inner_q)
.. warning::
This ``query`` attribute should be considered an opaque internal attribute.
It's fine to use it like above, but its API may change between Django
versions.
This second form is a bit less readable and unnatural to write, since it
accesses the internal ``query`` attribute and requires a ``ValuesQuerySet``.
If your code doesn't require compatibility with Django 1.0, use the first
form, passing in a queryset directly.
If you pass in a ``ValuesQuerySet`` or ``ValuesListQuerySet`` (the result of
calling ``values()`` or ``values_list()`` on a queryset) as the value to an
``__in`` lookup, you need to ensure you are only extracting one field in the

26
docs/ref/request-response.txt
View File

@@ -28,7 +28,8 @@ HttpRequest objects
Attributes
----------
All attributes except ``session`` should be considered read-only.
All attributes should be considered read-only, unless stated otherwise below.
``session`` is a notable exception.
.. attribute:: HttpRequest.body
@@ -605,11 +606,10 @@ Attributes
Methods
-------
.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE)
.. method:: HttpResponse.__init__(content='', content_type=None, status=200)
Instantiates an ``HttpResponse`` object with the given page content (a
string) and MIME type. The :setting:`DEFAULT_CONTENT_TYPE` is
``'text/html'``.
Instantiates an ``HttpResponse`` object with the given page content and
content type.
``content`` should be an iterator or a string. If it's an
iterator, it should return strings, and those strings will be
@@ -617,15 +617,15 @@ Methods
an iterator or a string, it will be converted to a string when
accessed.
``content_type`` is the MIME type optionally completed by a character set
encoding and is used to fill the HTTP ``Content-Type`` header. If not
specified, it is formed by the :setting:`DEFAULT_CONTENT_TYPE` and
:setting:`DEFAULT_CHARSET` settings, by default: "`text/html; charset=utf-8`".
Historically, this parameter was called ``mimetype`` (now deprecated).
``status`` is the `HTTP Status code`_ for the response.
``content_type`` is an alias for ``mimetype``. Historically, this parameter
was only called ``mimetype``, but since this is actually the value included
in the HTTP ``Content-Type`` header, it can also include the character set
encoding, which makes it more than just a MIME type specification.
If ``mimetype`` is specified (not ``None``), that value is used.
Otherwise, ``content_type`` is used. If neither is given, the
:setting:`DEFAULT_CONTENT_TYPE` setting is used.
.. method:: HttpResponse.__setitem__(header, value)
@@ -683,7 +683,7 @@ Methods
risk of client side script accessing the protected cookie
data.
.. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly
.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
.. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=True)

142
docs/ref/settings.txt
View File

@@ -192,7 +192,7 @@ compose a prefix, version and key into a final cache key. The default
implementation is equivalent to the function::
def make_key(key, key_prefix, version):
return ':'.join([key_prefix, str(version), smart_str(key)])
return ':'.join([key_prefix, str(version), smart_bytes(key)])
You may use any key function you want, as long as it has the same
argument signature.
@@ -316,14 +316,12 @@ See :doc:`/topics/cache`.
CSRF_COOKIE_DOMAIN
------------------
.. versionadded:: 1.2
Default: ``None``
The domain to be used when setting the CSRF cookie. This can be useful for
easily allowing cross-subdomain requests to be excluded from the normal cross
site request forgery protection. It should be set to a string such as
``".lawrence.com"`` to allow a POST request from a form on one subdomain to be
``".example.com"`` to allow a POST request from a form on one subdomain to be
accepted by accepted by a view served from another subdomain.
Please note that the presence of this setting does not imply that Django's CSRF
@@ -335,8 +333,6 @@ protection is safe from cross-subdomain attacks by default - please see the
CSRF_COOKIE_NAME
----------------
.. versionadded:: 1.2
Default: ``'csrftoken'``
The name of the cookie to use for the CSRF authentication token. This can be whatever you
@@ -376,8 +372,6 @@ cookie is only sent under an HTTPS connection.
CSRF_FAILURE_VIEW
-----------------
.. versionadded:: 1.2
Default: ``'django.views.csrf.csrf_failure'``
A dotted path to the view function to be used when an incoming request
@@ -395,8 +389,6 @@ end users) indicating the reason the request was rejected. See
DATABASES
---------
.. versionadded:: 1.2
Default: ``{}`` (Empty dictionary)
A dictionary containing the settings for all databases to be used with
@@ -439,12 +431,6 @@ You can use a database backend that doesn't ship with Django by setting
scratch is left as an exercise to the reader; see the other backends for
examples.
.. note::
Prior to Django 1.2, you could use a short version of the backend name
to reference the built-in database backends (e.g., you could use
``'sqlite3'`` to refer to the SQLite backend). This format has been
deprecated, and will be removed in Django 1.4.
.. setting:: HOST
HOST
@@ -673,8 +659,6 @@ not provided, Django will use ``'test_' + NAME + '_temp'``.
DATABASE_ROUTERS
----------------
.. versionadded:: 1.2
Default: ``[]`` (Empty list)
The list of routers that will be used to determine which database
@@ -695,9 +679,6 @@ system. Note that if :setting:`USE_L10N` is set to ``True``, then the
locale-dictated format has higher precedence and will be applied instead. See
:tfilter:`allowed date format strings <date>`.
.. versionchanged:: 1.2
This setting can now be overriden by setting :setting:`USE_L10N` to ``True``.
See also :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATE_FORMAT`.
.. setting:: DATE_INPUT_FORMATS
@@ -705,8 +686,6 @@ See also :setting:`DATETIME_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_
DATE_INPUT_FORMATS
------------------
.. versionadded:: 1.2
Default::
('%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', '%b %d %Y',
@@ -737,9 +716,6 @@ system. Note that if :setting:`USE_L10N` is set to ``True``, then the
locale-dictated format has higher precedence and will be applied instead. See
:tfilter:`allowed date format strings <date>`.
.. versionchanged:: 1.2
This setting can now be overriden by setting :setting:`USE_L10N` to ``True``.
See also :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
.. setting:: DATETIME_INPUT_FORMATS
@@ -747,8 +723,6 @@ See also :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT` and :setting:`SHORT_DATE
DATETIME_INPUT_FORMATS
----------------------
.. versionadded:: 1.2
Default::
('%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d',
@@ -782,14 +756,15 @@ Did you catch that? NEVER deploy a site into production with :setting:`DEBUG`
turned on.
One of the main features of debug mode is the display of detailed error pages.
If your app raises an exception when ``DEBUG`` is ``True``, Django will display
a detailed traceback, including a lot of metadata about your environment, such
as all the currently defined Django settings (from ``settings.py``).
If your app raises an exception when :setting:`DEBUG` is ``True``, Django will
display a detailed traceback, including a lot of metadata about your
environment, such as all the currently defined Django settings (from
``settings.py``).
As a security measure, Django will *not* include settings that might be
sensitive (or offensive), such as ``SECRET_KEY`` or ``PROFANITIES_LIST``.
Specifically, it will exclude any setting whose name includes any of the
following:
sensitive (or offensive), such as :setting:`SECRET_KEY` or
:setting:`PROFANITIES_LIST`. Specifically, it will exclude any setting whose
name includes any of the following:
* API
* KEY
@@ -832,8 +807,6 @@ site.
DECIMAL_SEPARATOR
-----------------
.. versionadded:: 1.2
Default: ``'.'`` (Dot)
Default decimal separator used when formatting decimal numbers.
@@ -935,8 +908,6 @@ This is only used if ``CommonMiddleware`` is installed (see
EMAIL_BACKEND
-------------
.. versionadded:: 1.2
Default: ``'django.core.mail.backends.smtp.EmailBackend'``
The backend to use for sending emails. For the list of available backends see
@@ -947,8 +918,6 @@ The backend to use for sending emails. For the list of available backends see
EMAIL_FILE_PATH
---------------
.. versionadded:: 1.2
Default: Not defined
The directory used by the ``file`` email backend to store output files.
@@ -1095,8 +1064,6 @@ See :doc:`/topics/files` for details.
FIRST_DAY_OF_WEEK
-----------------
.. versionadded:: 1.2
Default: ``0`` (Sunday)
Number representing the first day of the week. This is especially useful
@@ -1136,8 +1103,6 @@ of the preferred value or not supplied at all.
FORMAT_MODULE_PATH
------------------
.. versionadded:: 1.2
Default: ``None``
A full Python path to a Python package that contains format definitions for
@@ -1401,7 +1366,7 @@ MANAGERS
Default: ``()`` (Empty tuple)
A tuple in the same format as :setting:`ADMINS` that specifies who should get
broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``.
broken-link notifications when :setting:`SEND_BROKEN_LINK_EMAILS` is ``True``.
.. setting:: MEDIA_ROOT
@@ -1413,7 +1378,7 @@ Default: ``''`` (Empty string)
Absolute path to the directory that holds media for this installation, used
for :doc:`managing stored files </topics/files>`.
Example: ``"/home/media/media.lawrence.com/"``
Example: ``"/var/www/example.com/media/"``
See also :setting:`MEDIA_URL`.
@@ -1427,7 +1392,7 @@ Default: ``''`` (Empty string)
URL that handles the media served from :setting:`MEDIA_ROOT`, used
for :doc:`managing stored files </topics/files>`.
Example: ``"http://media.lawrence.com/"``
Example: ``"http://media.example.com/"``
.. versionchanged:: 1.3
It must end in a slash if set to a non-empty value.
@@ -1435,8 +1400,6 @@ Example: ``"http://media.lawrence.com/"``
MESSAGE_LEVEL
-------------
.. versionadded:: 1.2
Default: `messages.INFO`
Sets the minimum message level that will be recorded by the messages
@@ -1446,8 +1409,6 @@ more details.
MESSAGE_STORAGE
---------------
.. versionadded:: 1.2
Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'``
Controls where Django stores message data. See the
@@ -1456,8 +1417,6 @@ Controls where Django stores message data. See the
MESSAGE_TAGS
------------
.. versionadded:: 1.2
Default::
{messages.DEBUG: 'debug',
@@ -1484,11 +1443,6 @@ Default::
A tuple of middleware classes to use. See :doc:`/topics/http/middleware`.
.. versionchanged:: 1.2
``'django.contrib.messages.middleware.MessageMiddleware'`` was added to the
default. For more information, see the :doc:`messages documentation
</ref/contrib/messages>`.
.. setting:: MONTH_DAY_FORMAT
MONTH_DAY_FORMAT
@@ -1514,8 +1468,6 @@ See :tfilter:`allowed date format strings <date>`. See also
NUMBER_GROUPING
----------------
.. versionadded:: 1.2
Default: ``0``
Number of digits grouped together on the integer part of a number.
@@ -1595,9 +1547,23 @@ SECRET_KEY
Default: ``''`` (Empty string)
A secret key for this particular Django installation. Used to provide a seed in
secret-key hashing algorithms. Set this to a random string -- the longer, the
better. ``django-admin.py startproject`` creates one automatically.
A secret key for a particular Django installation. This is used to provide
:doc:`cryptographic signing </topics/signing>`, and should be set to a unique,
unpredictable value.
:djadmin:`django-admin.py startproject <startproject>` automatically adds a
randomly-generated ``SECRET_KEY`` to each new project.
.. warning::
**Keep this value secret.**
Running Django with a known :setting:`SECRET_KEY` defeats many of Django's
security protections, and can lead to privilege escalation and remote code
execution vulnerabilities.
.. versionchanged:: 1.5
Django will now refuse to start if :setting:`SECRET_KEY` is not set.
.. setting:: SECURE_PROXY_SSL_HEADER
@@ -1614,7 +1580,8 @@ method.
This takes some explanation. By default, ``is_secure()`` is able to determine
whether a request is secure by looking at whether the requested URL uses
"https://".
"https://". This is important for Django's CSRF protection, and may be used
by your own code or third-party apps.
If your Django app is behind a proxy, though, the proxy may be "swallowing" the
fact that a request is HTTPS, using a non-HTTPS connection between the proxy
@@ -1644,7 +1611,7 @@ available in ``request.META``.)
.. warning::
**You will probably open security holes in your site if you set this without knowing what you're doing. Seriously.**
**You will probably open security holes in your site if you set this without knowing what you're doing. And if you fail to set it when you should. Seriously.**
Make sure ALL of the following are true before setting this (assuming the
values from the example above):
@@ -1712,7 +1679,7 @@ SESSION_COOKIE_DOMAIN
Default: ``None``
The domain to use for session cookies. Set this to a string such as
``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard
``".example.com"`` for cross-domain cookies, or use ``None`` for a standard
domain cookie. See the :doc:`/topics/http/sessions`.
.. setting:: SESSION_COOKIE_HTTPONLY
@@ -1732,7 +1699,7 @@ consistently by all browsers. However, when it is honored, it can be a
useful way to mitigate the risk of client side script accessing the
protected cookie data.
.. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly
.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
.. versionchanged:: 1.4
The default value of the setting was changed from ``False`` to ``True``.
@@ -1828,8 +1795,6 @@ Whether to save the session data on every request. See
SHORT_DATE_FORMAT
-----------------
.. versionadded:: 1.2
Default: ``m/d/Y`` (e.g. ``12/31/2003``)
An available formatting that can be used for displaying date fields on
@@ -1844,8 +1809,6 @@ See also :setting:`DATE_FORMAT` and :setting:`SHORT_DATETIME_FORMAT`.
SHORT_DATETIME_FORMAT
---------------------
.. versionadded:: 1.2
Default: ``m/d/Y P`` (e.g. ``12/31/2003 4 p.m.``)
An available formatting that can be used for displaying datetime fields on
@@ -1893,7 +1856,7 @@ Default: ``''`` (Empty string)
The absolute path to the directory where :djadmin:`collectstatic` will collect
static files for deployment.
Example: ``"/home/example.com/static/"``
Example: ``"/var/www/example.com/static/"``
If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
(default) the :djadmin:`collectstatic` management command will collect static
@@ -1923,7 +1886,7 @@ Default: ``None``
URL to use when referring to static files located in :setting:`STATIC_ROOT`.
Example: ``"/site_media/static/"`` or ``"http://static.example.com/"``
Example: ``"/static/"`` or ``"http://static.example.com/"``
If not ``None``, this will be used as the base path for
:ref:`media definitions<form-media-paths>` and the
@@ -1952,16 +1915,6 @@ A tuple of callables that are used to populate the context in ``RequestContext``
These callables take a request object as their argument and return a dictionary
of items to be merged into the context.
.. versionchanged:: 1.2
``django.contrib.messages.context_processors.messages`` was added to the
default. For more information, see the :doc:`messages documentation
</ref/contrib/messages>`.
.. versionchanged:: 1.2
The auth context processor was moved in this release from its old location
``django.core.context_processors.auth`` to
``django.contrib.auth.context_processors.auth``.
.. versionadded:: 1.3
The ``django.core.context_processors.static`` context processor
was added in this release.
@@ -2017,12 +1970,6 @@ used instead of a string. The first item in the tuple should be the ``Loader``'s
module, subsequent items are passed to the ``Loader`` during initialization. See
:doc:`/ref/templates/api`.
.. versionchanged:: 1.2
The class-based API for template loaders was introduced in Django 1.2
although the :setting:`TEMPLATE_LOADERS` setting will accept strings
that specify function-based loaders until compatibility with them is
completely removed in Django 1.4.
.. setting:: TEMPLATE_STRING_IF_INVALID
TEMPLATE_STRING_IF_INVALID
@@ -2040,9 +1987,6 @@ TEST_RUNNER
Default: ``'django.test.simple.DjangoTestSuiteRunner'``
.. versionchanged:: 1.2
Prior to 1.2, test runners were a function, not a class.
The name of the class to use for starting the test suite. See
:doc:`/topics/testing`.
@@ -2053,8 +1997,6 @@ The name of the class to use for starting the test suite. See
THOUSAND_SEPARATOR
------------------
.. versionadded:: 1.2
Default: ``,`` (Comma)
Default thousand separator used when formatting numbers. This setting is
@@ -2079,9 +2021,6 @@ system. Note that if :setting:`USE_L10N` is set to ``True``, then the
locale-dictated format has higher precedence and will be applied instead. See
:tfilter:`allowed date format strings <date>`.
.. versionchanged:: 1.2
This setting can now be overriden by setting :setting:`USE_L10N` to ``True``.
See also :setting:`DATE_FORMAT` and :setting:`DATETIME_FORMAT`.
.. setting:: TIME_INPUT_FORMATS
@@ -2089,8 +2028,6 @@ See also :setting:`DATE_FORMAT` and :setting:`DATETIME_FORMAT`.
TIME_INPUT_FORMATS
------------------
.. versionadded:: 1.2
Default: ``('%H:%M:%S', '%H:%M')``
A tuple of formats that will be accepted when inputting data on a time field.
@@ -2112,9 +2049,6 @@ TIME_ZONE
Default: ``'America/Chicago'``
.. versionchanged:: 1.2
``None`` was added as an allowed value.
.. versionchanged:: 1.4
The meaning of this setting now depends on the value of :setting:`USE_TZ`.
@@ -2191,8 +2125,6 @@ See also :setting:`LANGUAGE_CODE`, :setting:`USE_L10N` and :setting:`USE_TZ`.
USE_L10N
--------
.. versionadded:: 1.2
Default: ``False``
A boolean that specifies if localized formatting of data will be enabled by
@@ -2211,8 +2143,6 @@ See also :setting:`LANGUAGE_CODE`, :setting:`USE_I18N` and :setting:`USE_TZ`.
USE_THOUSAND_SEPARATOR
----------------------
.. versionadded:: 1.2
Default: ``False``
A boolean that specifies whether to display numbers using a thousand separator.

5
docs/ref/signals.txt
View File

@@ -220,8 +220,6 @@ m2m_changed
.. data:: django.db.models.signals.m2m_changed
:module:
.. versionadded:: 1.2
Sent when a :class:`ManyToManyField` is changed on a model instance.
Strictly speaking, this is not a model signal since it is sent by the
:class:`ManyToManyField`, but since it complements the
@@ -544,9 +542,6 @@ connection_created
.. data:: django.db.backends.signals.connection_created
:module:
.. versionchanged:: 1.2
The connection argument was added
Sent when the database wrapper makes the initial connection to the
database. This is particularly useful if you'd like to send any post
connection commands to the SQL backend.

67
docs/ref/templates/api.txt
View File

@@ -198,6 +198,8 @@ straight lookups. Here are some things to keep in mind:
* A variable can only be called if it has no required arguments. Otherwise,
the system will return an empty string.
.. _alters-data-description:
* Obviously, there can be side effects when calling some variables, and
it'd be either foolish or a security hole to allow the template system
to access them.
@@ -370,23 +372,14 @@ and return a dictionary of items to be merged into the context. By default,
"django.core.context_processors.i18n",
"django.core.context_processors.media",
"django.core.context_processors.static",
"django.core.context_processors.tz",
"django.contrib.messages.context_processors.messages")
.. versionadded:: 1.2
In addition to these, ``RequestContext`` always uses
``django.core.context_processors.csrf``. This is a security
related context processor required by the admin and other contrib apps, and,
in case of accidental misconfiguration, it is deliberately hardcoded in and
cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
.. versionadded:: 1.2
The ``'messages'`` context processor was added. For more information, see
the :doc:`messages documentation </ref/contrib/messages>`.
.. versionchanged:: 1.2
The auth context processor was moved in this release from its old location
``django.core.context_processors.auth`` to
``django.contrib.auth.context_processors.auth``.
In addition to these, ``RequestContext`` always uses
``django.core.context_processors.csrf``. This is a security
related context processor required by the admin and other contrib apps, and,
in case of accidental misconfiguration, it is deliberately hardcoded in and
cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting.
Each processor is applied in order. That means, if one processor adds a
variable to the context and a second processor adds a variable with the same
@@ -447,10 +440,6 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
``django.contrib.auth.context_processors.PermWrapper``, representing the
permissions that the currently logged-in user has.
.. versionchanged:: 1.2
This context processor was moved in this release from
``django.core.context_processors.auth`` to its current location.
.. versionchanged:: 1.3
Prior to version 1.3, ``PermWrapper`` was located in
``django.contrib.auth.context_processors``.
@@ -503,8 +492,6 @@ value of the :setting:`STATIC_URL` setting.
django.core.context_processors.csrf
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.2
This processor adds a token that is needed by the :ttag:`csrf_token` template
tag for protection against :doc:`Cross Site Request Forgeries
</ref/contrib/csrf>`.
@@ -527,15 +514,6 @@ If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every
via the user model (using ``user.message_set.create``) or through
the :doc:`messages framework </ref/contrib/messages>`.
.. versionadded:: 1.2
This template context variable was previously supplied by the ``'auth'``
context processor. For backwards compatibility the ``'auth'`` context
processor will continue to supply the ``messages`` variable until Django
1.4. If you use the ``messages`` variable, your project will work with
either (or both) context processors, but it is recommended to add
``django.contrib.messages.context_processors.messages`` so your project
will be prepared for the future upgrade.
Writing your own context processors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -657,11 +635,6 @@ by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS`
should be a tuple of strings, where each string represents a template loader
class. Here are the template loaders that come with Django:
.. versionchanged:: 1.2
Template loaders were based on callables (usually functions) before Django
1.2, starting with the 1.2 release there is a new class-based API, all the
loaders described below implement this new API.
``django.template.loaders.filesystem.Loader``
Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`.
This loader is enabled by default.
@@ -678,14 +651,24 @@ class. Here are the template loaders that come with Django:
INSTALLED_APPS = ('myproject.polls', 'myproject.music')
...then ``get_template('foo.html')`` will look for templates in these
...then ``get_template('foo.html')`` will look for ``foo.html`` in these
directories, in this order:
* ``/path/to/myproject/polls/templates/foo.html``
* ``/path/to/myproject/music/templates/foo.html``
* ``/path/to/myproject/polls/templates/``
* ``/path/to/myproject/music/templates/``
Note that the loader performs an optimization when it is first imported: It
caches a list of which :setting:`INSTALLED_APPS` packages have a
... and will use the one it finds first.
The order of :setting:`INSTALLED_APPS` is significant! For example, if you
want to customize the Django admin, you might choose to override the
standard ``admin/base_site.html`` template, from ``django.contrib.admin``,
with your own ``admin/base_site.html`` in ``myproject.polls``. You must
then make sure that your ``myproject.polls`` comes *before*
``django.contrib.admin`` in :setting:`INSTALLED_APPS`, otherwise
``django.contrib.admin``'s will be loaded first and yours will be ignored.
Note that the loader performs an optimization when it is first imported:
it caches a list of which :setting:`INSTALLED_APPS` packages have a
``templates`` subdirectory.
This loader is enabled by default.
@@ -800,12 +783,10 @@ and any setting starting with ``TEMPLATE_`` is of obvious interest.
Using an alternative template language
======================================
.. versionadded:: 1.2
The Django ``Template`` and ``Loader`` classes implement a simple API for
loading and rendering templates. By providing some simple wrapper classes that
implement this API we can use third party template systems like `Jinja2
<http://jinja.pocoo.org/2/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
<http://jinja.pocoo.org/docs/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This
allows us to use third-party template libraries without giving up useful Django
features like the Django ``Context`` object and handy shortcuts like
:func:`~django.shortcuts.render_to_response()`.

212
docs/ref/templates/builtins.txt
View File

@@ -58,10 +58,8 @@ Ignores everything between ``{% comment %}`` and ``{% endcomment %}``.
csrf_token
^^^^^^^^^^
In the Django 1.1.X series, this is a no-op tag that returns an empty string
for future compatibility purposes. In Django 1.2 and later, it is used for
CSRF protection, as described in the documentation for :doc:`Cross Site Request
Forgeries </ref/contrib/csrf>`.
This tag is used for CSRF protection, as described in the documentation for
:doc:`Cross Site Request Forgeries </ref/contrib/csrf>`.
.. templatetag:: cycle
@@ -410,8 +408,6 @@ variables or to negate a given variable::
There are some athletes and absolutely no coaches.
{% endif %}
.. versionchanged:: 1.2
Use of both ``and`` and ``or`` clauses within the same tag is allowed, with
``and`` having higher precedence than ``or`` e.g.::
@@ -423,12 +419,9 @@ will be interpreted like:
if (athlete_list and coach_list) or cheerleader_list
Use of actual brackets in the :ttag:`if` tag is invalid syntax. If you need
Use of actual parentheses in the :ttag:`if` tag is invalid syntax. If you need
them to indicate precedence, you should use nested :ttag:`if` tags.
.. versionadded:: 1.2
:ttag:`if` tags may also use the operators ``==``, ``!=``, ``<``, ``>``,
``<=``, ``>=`` and ``in`` which work as follows:
@@ -637,9 +630,8 @@ You cannot check for equality with Python objects such as ``True`` or
``False``. If you need to test if something is true or false, use the
:ttag:`if` tag instead.
.. versionadded:: 1.2
An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the
``==`` operator.
An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the
``==`` operator.
.. templatetag:: ifnotequal
@@ -649,9 +641,8 @@ ifnotequal
Just like :ttag:`ifequal`, except it tests that the two arguments are not
equal.
.. versionadded:: 1.2
An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and
the ``!=`` operator.
An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and
the ``!=`` operator.
.. templatetag:: include
@@ -771,48 +762,41 @@ regroup
Regroups a list of alike objects by a common attribute.
This complex tag is best illustrated by use of an example: say that ``people``
is a list of people represented by dictionaries with ``first_name``,
``last_name``, and ``gender`` keys:
This complex tag is best illustrated by way of an example: say that "places" is a list of cities represented by dictionaries containing ``"name"``, ``"population"``, and ``"country"`` keys:
.. code-block:: python
people = [
{'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
{'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
{'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
{'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
{'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
cities = [
{'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
{'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
{'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
{'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
{'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]
...and you'd like to display a hierarchical list that is ordered by gender,
like this:
...and you'd like to display a hierarchical list that is ordered by country, like this:
* Male:
* India
* Mumbai: 19,000,000
* Calcutta: 15,000,000
* USA
* New York: 20,000,000
* Chicago: 7,000,000
* Japan
* Tokyo: 33,000,000
* George Bush
* Bill Clinton
* Female:
* Margaret Thatcher
* Condoleezza Rice
* Unknown:
* Pat Smith
You can use the ``{% regroup %}`` tag to group the list of people by gender.
You can use the ``{% regroup %}`` tag to group the list of cities by country.
The following snippet of template code would accomplish this::
{% regroup people by gender as gender_list %}
{% regroup cities by country as country_list %}
<ul>
{% for gender in gender_list %}
<li>{{ gender.grouper }}
{% for country in country_list %}
<li>{{ country.grouper }}
<ul>
{% for item in gender.list %}
<li>{{ item.first_name }} {{ item.last_name }}</li>
{% for item in country.list %}
<li>{{ item.name }}: {{ item.population }}</li>
{% endfor %}
</ul>
</li>
@@ -821,56 +805,45 @@ The following snippet of template code would accomplish this::
Let's walk through this example. ``{% regroup %}`` takes three arguments: the
list you want to regroup, the attribute to group by, and the name of the
resulting list. Here, we're regrouping the ``people`` list by the ``gender``
attribute and calling the result ``gender_list``.
resulting list. Here, we're regrouping the ``cities`` list by the ``country``
attribute and calling the result ``country_list``.
``{% regroup %}`` produces a list (in this case, ``gender_list``) of
``{% regroup %}`` produces a list (in this case, ``country_list``) of
**group objects**. Each group object has two attributes:
* ``grouper`` -- the item that was grouped by (e.g., the string "Male" or
"Female").
* ``list`` -- a list of all items in this group (e.g., a list of all people
with gender='Male').
* ``grouper`` -- the item that was grouped by (e.g., the string "India" or
"Japan").
* ``list`` -- a list of all items in this group (e.g., a list of all cities
with country='India').
Note that ``{% regroup %}`` does not order its input! Our example relies on
the fact that the ``people`` list was ordered by ``gender`` in the first place.
If the ``people`` list did *not* order its members by ``gender``, the
regrouping would naively display more than one group for a single gender. For
example, say the ``people`` list was set to this (note that the males are not
the fact that the ``cities`` list was ordered by ``country`` in the first place.
If the ``cities`` list did *not* order its members by ``country``, the
regrouping would naively display more than one group for a single country. For
example, say the ``cities`` list was set to this (note that the countries are not
grouped together):
.. code-block:: python
people = [
{'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
{'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
{'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
{'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
{'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
cities = [
{'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
{'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
{'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
{'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
{'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]
With this input for ``people``, the example ``{% regroup %}`` template code
With this input for ``cities``, the example ``{% regroup %}`` template code
above would result in the following output:
* Male:
* Bill Clinton
* Unknown:
* Pat Smith
* Female:
* Margaret Thatcher
* Male:
* George Bush
* Female:
* Condoleezza Rice
* India
* Mumbai: 19,000,000
* USA
* New York: 20,000,000
* India
* Calcutta: 15,000,000
* Japan
* Tokyo: 33,000,000
The easiest solution to this gotcha is to make sure in your view code that the
data is ordered according to how you want to display it.
@@ -878,27 +851,26 @@ data is ordered according to how you want to display it.
Another solution is to sort the data in the template using the
:tfilter:`dictsort` filter, if your data is in a list of dictionaries::
{% regroup people|dictsort:"gender" by gender as gender_list %}
{% regroup cities|dictsort:"country" by country as country_list %}
Grouping on other properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Any valid template lookup is a legal grouping attribute for the regroup
tag, including methods, attributes, dictionary keys and list items. For
example, if the "gender" field is a foreign key to a class with
example, if the "country" field is a foreign key to a class with
an attribute "description," you could use::
{% regroup people by gender.description as gender_list %}
{% regroup cities by country.description as country_list %}
Or, if ``gender`` is a field with ``choices``, it will have a
Or, if ``country`` is a field with ``choices``, it will have a
:meth:`^django.db.models.Model.get_FOO_display` method available as an
attribute, allowing you to group on the display string rather than the
``choices`` key::
{% regroup people by get_gender_display as gender_list %}
{% regroup cities by get_country_display as country_list %}
``{{ gender.grouper }}`` will now display the value fields from the
``{{ country.grouper }}`` will now display the value fields from the
``choices`` set rather than the keys.
.. templatetag:: spaceless
@@ -1059,6 +1031,29 @@ This will follow the normal :ref:`namespaced URL resolution strategy
<topics-http-reversing-url-namespaces>`, including using any hints provided
by the context as to the current application.
.. templatetag:: verbatim
verbatim
^^^^^^^^
.. versionadded:: 1.5
Stops the template engine from rendering the contents of this block tag.
A common use is to allow a Javascript template layer that collides with
Django's syntax. For example::
{% verbatim %}
{{if dying}}Still alive.{{/if}}
{% endverbatim %}
You can also designate a specific closing tag, allowing the use of
``{% endverbatim %}`` as part of the unrendered contents::
{% verbatim myblock %}
Avoid template rendering via the {% verbatim %}{% endverbatim %} block.
{% endverbatim myblock %}
.. templatetag:: widthratio
widthratio
@@ -1069,7 +1064,8 @@ value to a maximum value, and then applies that ratio to a constant.
For example::
<img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" />
<img src="bar.png" alt="Bar"
height="10" width="{% widthratio this_value max_value 100 %}" />
Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the
above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5
@@ -1122,9 +1118,6 @@ For example::
If ``value`` is ``4``, then the output will be ``6``.
.. versionchanged:: 1.2
The following behavior didn't exist in previous Django versions.
This filter will first try to coerce both values to integers. If this fails,
it'll attempt to add the values together anyway. This will work on some data
types (strings, list, etc.) and fail on others. If it fails, the result will
@@ -1191,7 +1184,7 @@ Removes all values of arg from the given string.
For example::
{{ value|cut:" "}}
{{ value|cut:" " }}
If ``value`` is ``"String with spaces"``, the output will be
``"Stringwithspaces"``.
@@ -1284,10 +1277,6 @@ Z Time zone offset in seconds. The ``-43200`` to ``4320
UTC is always positive.
================ ======================================== =====================
.. versionadded:: 1.2
The ``c`` and ``u`` format specification characters were added in Django 1.2.
.. versionadded:: 1.4
The ``e`` and ``o`` format specification characters were added in Django 1.4.
@@ -1321,9 +1310,6 @@ When used without a format string::
...the formatting string defined in the :setting:`DATE_FORMAT` setting will be
used, without applying any localization.
.. versionchanged:: 1.2
Predefined formats can now be influenced by the current locale.
.. templatefilter:: default
default
@@ -1980,9 +1966,6 @@ When used without a format string::
...the formatting string defined in the :setting:`TIME_FORMAT` setting will be
used, without applying any localization.
.. versionchanged:: 1.2
Predefined formats can now be influenced by the current locale.
.. templatefilter:: timesince
timesince
@@ -2361,7 +2344,7 @@ using :class:`~django.template.RequestContext` or not.
.. code-block:: html+django
{% load static %}
<img src="{% static "images/hi.jpg" %}" />
<img src="{% static "images/hi.jpg" %}" alt="Hi!" />
It is also able to consume standard context variables, e.g. assuming a
``user_stylesheet`` variable is passed to the template:
@@ -2371,6 +2354,17 @@ It is also able to consume standard context variables, e.g. assuming a
{% load static %}
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />
If you'd like to retrieve a static URL without displaying it, you can use a
slightly different call::
.. versionadded:: 1.5
.. code-block:: html+django
{% load static %}
{% static "images/hi.jpg" as myphoto %}
<img src="{{ myphoto }}"></img>
.. note::
The :mod:`staticfiles<django.contrib.staticfiles>` contrib app also ships
@@ -2380,7 +2374,7 @@ It is also able to consume standard context variables, e.g. assuming a
:ref:`using a cloud service to serve static files<staticfiles-from-cdn>`::
{% load static from staticfiles %}
<img src="{% static "images/hi.jpg" %}" />
<img src="{% static "images/hi.jpg" %}" alt="Hi!" />
.. templatetag:: get_static_prefix
@@ -2395,7 +2389,7 @@ into the template, you can use the :ttag:`get_static_prefix` template tag
instead::
{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" />
<img src="{% get_static_prefix %}images/hi.jpg" alt="Hi!" />
There's also a second form you can use to avoid extra processing if you need
the value multiple times::
@@ -2403,8 +2397,8 @@ the value multiple times::
{% load static %}
{% get_static_prefix as STATIC_PREFIX %}
<img src="{{ STATIC_PREFIX }}images/hi.jpg" />
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
<img src="{{ STATIC_PREFIX }}images/hi.jpg" alt="Hi!" />
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" alt="Hello!" />
.. templatetag:: get_media_prefix

Some files were not shown because too many files have changed in this diff Show More