summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/index.txt4
-rw-r--r--docs/internals/committers.txt13
-rw-r--r--docs/ref/contrib/csrf.txt12
-rw-r--r--docs/ref/django-admin.txt174
-rw-r--r--docs/ref/models/options.txt7
-rw-r--r--docs/ref/templates/builtins.txt12
-rw-r--r--docs/releases/1.1.2.txt36
-rw-r--r--docs/releases/1.1.txt8
-rw-r--r--docs/releases/1.2.txt157
-rw-r--r--docs/releases/index.txt69
-rw-r--r--docs/topics/cache.txt20
-rw-r--r--docs/topics/email.txt64
-rw-r--r--docs/topics/http/urls.txt3
-rw-r--r--docs/topics/testing.txt7
14 files changed, 436 insertions, 150 deletions
diff --git a/docs/index.txt b/docs/index.txt
index d03f90c117..0ba727280c 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -201,7 +201,5 @@ The Django open-source project
* **Django over time:**
:ref:`API stability <misc-api-stability>` |
- :ref:`Archive of release notes <releases-index>` | `Backwards-incompatible changes`_ |
+ :ref:`Release notes and upgrading instructions <releases-index>` |
:ref:`Deprecation Timeline <internals-deprecation>`
-
-.. _Backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
diff --git a/docs/internals/committers.txt b/docs/internals/committers.txt
index 803c3140c7..d2eb80c710 100644
--- a/docs/internals/committers.txt
+++ b/docs/internals/committers.txt
@@ -200,6 +200,19 @@ Karen Tracey
.. _Bauhaus-University Weimar: http://www.uni-weimar.de/
.. _pinax: http://pinaxproject.com/
+`James Tauber`_
+ James is the lead developer of Pinax_ and the CEO and founder of
+ Eldarion_. He has been doing open source software since 1993, Python
+ since 1998 and Django since 2006. He serves on the board of the Python
+ Software Foundation and is currently on a leave of absence from a PhD in
+ linguistics.
+
+ James currently lives in Boston, MA, USA but originally hails from
+ Perth, Western Australia where he attended the same high school as
+ Russell Keith-Magee.
+
+.. _James Tauber: http://jtauber.com/
+
Specialists
-----------
diff --git a/docs/ref/contrib/csrf.txt b/docs/ref/contrib/csrf.txt
index c1bdb59cd1..ea76fc3739 100644
--- a/docs/ref/contrib/csrf.txt
+++ b/docs/ref/contrib/csrf.txt
@@ -46,7 +46,7 @@ To enable CSRF protection for your views, follow these steps:
``django.views.decorators.csrf.csrf_protect`` on particular views you
want to protect (see below).
- 2. In any template that uses a POST form, use the ``csrf_token`` tag inside
+ 2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside
the ``<form>`` element if the form is for an internal URL, e.g.::
<form action="" method="POST">{% csrf_token %}
@@ -123,14 +123,14 @@ as ``CsrfResponseMiddleware``, and it can be used by following these steps:
``CsrfResponseMiddleware`` needs to process the response before things
like compression or setting ofETags happen to the response, so it must
- come after ``GZipMiddleware``, ``CommonMiddleware`` and
+ come after ``GZipMiddleware``, ``CommonMiddleware`` and
``ConditionalGetMiddleware`` in the list. It also must come after
``CsrfViewMiddleware``.
Use of the ``CsrfResponseMiddleware`` is not recommended because of the
performance hit it imposes, and because of a potential security problem (see
below). It can be used as an interim measure until applications have been
-updated to use the ``{% csrf_token %}`` tag. It is deprecated and will be
+updated to use the :ttag:`csrf_token` tag. It is deprecated and will be
removed in Django 1.4.
Django 1.1 and earlier provided a single ``CsrfMiddleware`` class. This is also
@@ -153,6 +153,8 @@ launch a CSRF attack on your site against that user. The
``@csrf_response_exempt`` decorator can be used to fix this, but only if the
page doesn't also contain internal forms that require the token.
+.. _ref-csrf-upgrading-notes:
+
Upgrading notes
---------------
@@ -199,7 +201,7 @@ Note that contrib apps, such as the admin, have been updated to use the
``CsrfViewMiddleware`` to your settings. However, if you have supplied
customised templates to any of the view functions of contrib apps (whether
explicitly via a keyword argument, or by overriding built-in templates), **you
-MUST update them** to include the ``csrf_token`` template tag as described
+MUST update them** to include the :ttag:`csrf_token` template tag as described
above, or they will stop working. (If you cannot update these templates for
some reason, you will be forced to use ``CsrfResponseMiddleware`` for these
views to continue working).
@@ -364,7 +366,7 @@ exactly that.
Caching
=======
-If the ``csrf_token`` template tag is used by a template (or the ``get_token``
+If the :ttag:`csrf_token` template tag is used by a template (or the ``get_token``
function is called some other way), ``CsrfViewMiddleware`` will add a cookie and
a ``Vary: Cookie`` header to the response. Similarly,
``CsrfResponseMiddleware`` will send the ``Vary: Cookie`` header if it inserted
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index f657db20f4..80e368286e 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -78,11 +78,9 @@ Examples of output::
Displaying debug output
-----------------------
-.. django-admin-option:: --verbosity <amount>
-
-Use ``--verbosity`` to specify the amount of notification and debug information
+Use :djadminopt:`--verbosity` to specify the amount of notification and debug information
that ``django-admin.py`` should print to the console. For more details, see the
-documentation for the :ref:`default options for django-admin.py <django-admin-verbosity>`.
+documentation for the :djadminopt:`--verbosity` option.
Available subcommands
=====================
@@ -90,6 +88,8 @@ Available subcommands
cleanup
-------
+.. django-admin:: cleanup
+
.. versionadded:: 1.0
Can be run as a cronjob or directly to clean out old data from the database
@@ -98,17 +98,16 @@ Can be run as a cronjob or directly to clean out old data from the database
compilemessages
---------------
+.. django-admin:: compilemessages
+
.. versionchanged:: 1.0
Before 1.0 this was the "bin/compile-messages.py" command.
Compiles .po files created with ``makemessages`` to .mo files for use with
the builtin gettext support. See :ref:`topics-i18n`.
---locale
-~~~~~~~~
-
-Use the ``--locale`` or ``-l`` option to specify the locale to process.
-If not provided all locales are processed.
+Use the :djadminopt:`--locale`` option to specify the locale to process.
+If not provided, all locales are processed.
Example usage::
@@ -117,7 +116,7 @@ Example usage::
createcachetable
----------------
-.. django-admin:: createcachetable <tablename>
+.. django-admin:: createcachetable
Creates a cache table named ``tablename`` for use with the database cache
backend. See :ref:`topics-cache` for more information.
@@ -183,10 +182,10 @@ example, the default settings don't define ``ROOT_URLCONF``, so
Note that Django's default settings live in ``django/conf/global_settings.py``,
if you're ever curious to see the full list of defaults.
-dumpdata
---------
+dumpdata <appname appname appname.Model ...>
+--------------------------------------------
-.. django-admin:: dumpdata <appname appname appname.Model ...>
+.. django-admin:: dumpdata
Outputs to standard output all data in the database associated with the named
application(s).
@@ -215,18 +214,17 @@ directives::
django-admin.py dumpdata --exclude=auth --exclude=contenttypes
-
.. django-admin-option:: --format <fmt>
- By default, ``dumpdata`` will format its output in JSON, but you can use the
- ``--format`` option to specify another format. Currently supported formats
- are listed in :ref:`serialization-formats`.
+By default, ``dumpdata`` will format its output in JSON, but you can use the
+``--format`` option to specify another format. Currently supported formats
+are listed in :ref:`serialization-formats`.
.. django-admin-option:: --indent <num>
- By default, ``dumpdata`` will output all data on a single line. This isn't
- easy for humans to read, so you can use the ``--indent`` option to
- pretty-print the output with a number of indentation spaces.
+By default, ``dumpdata`` will output all data on a single line. This isn't
+easy for humans to read, so you can use the ``--indent`` option to
+pretty-print the output with a number of indentation spaces.
.. versionadded:: 1.1
@@ -239,22 +237,21 @@ model names.
flush
-----
-.. django-admin: 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
post-synchronization handlers will be re-executed, and the ``initial_data``
fixture will be re-installed.
-.. django-admin-option:: --noinput
-
- Use the ``--noinput`` option to suppress all user prompting, such as "Are
- you sure?" confirmation messages. This is useful if ``django-admin.py`` is
- being executed as an unattended, automated script.
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
inspectdb
---------
+.. django-admin:: inspectdb
+
Introspects the database tables in the database pointed-to by the
``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
file) to standard output.
@@ -296,6 +293,8 @@ only works in PostgreSQL and with certain types of MySQL tables.
loaddata <fixture fixture ...>
------------------------------
+.. django-admin:: loaddata
+
Searches for and loads the contents of the named fixture into the database.
What's a "fixture"?
@@ -382,6 +381,8 @@ installation will be aborted, and any data installed in the call to
makemessages
------------
+.. django-admin:: makemessages
+
.. versionchanged:: 1.0
Before 1.0 this was the ``bin/make-messages.py`` command.
@@ -392,8 +393,7 @@ directory. After making changes to the messages files you need to compile them
with ``compilemessages`` for use with the builtin gettext support. See the
:ref:`i18n documentation <how-to-create-language-files>` for details.
---all
-~~~~~
+.. django-admin-option:: --all
Use the ``--all`` or ``-a`` option to update the message files for all
available languages.
@@ -402,8 +402,7 @@ Example usage::
django-admin.py makemessages --all
---extension
-~~~~~~~~~~~
+.. django-admin-option:: --extension
Use the ``--extension`` or ``-e`` option to specify a list of file extensions
to examine (default: ".html").
@@ -416,17 +415,13 @@ Separate multiple extensions with commas or use -e or --extension multiple times
django-admin.py makemessages --locale=de --extension=html,txt --extension xml
---locale
-~~~~~~~~
-
-Use the ``--locale`` or ``-l`` option to specify the locale to process.
+Use the :djadminopt:`--locale` option to specify the locale to process.
Example usage::
django-admin.py makemessages --locale=br_PT
---domain
-~~~~~~~~
+.. django-admin-option:: --domain
Use the ``--domain`` or ``-d`` option to change the domain of the messages files.
Currently supported:
@@ -434,23 +429,21 @@ Currently supported:
* ``django`` for all ``*.py`` and ``*.html`` files (default)
* ``djangojs`` for ``*.js`` files
-.. _django-admin-reset:
-
reset <appname appname ...>
---------------------------
-Executes the equivalent of ``sqlreset`` for the given app name(s).
+.. django-admin:: reset
---noinput
-~~~~~~~~~
+Executes the equivalent of ``sqlreset`` for the given app name(s).
-Use the ``--noinput`` option to suppress all user prompting, such as
-"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
-is being executed as an unattended, automated script.
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
runfcgi [options]
-----------------
+.. django-admin:: runfcgi
+
Starts a set of FastCGI processes suitable for use with any Web server that
supports the FastCGI protocol. See the :ref:`FastCGI deployment documentation
<howto-deployment-fastcgi>` for details. Requires the Python FastCGI module from
@@ -458,10 +451,10 @@ supports the FastCGI protocol. See the :ref:`FastCGI deployment documentation
.. _flup: http://www.saddi.com/software/flup/
-runserver
----------
+runserver [port or ipaddr:port]
+-------------------------------
-.. django-admin:: runserver [port or ipaddr:port]
+.. django-admin:: runserver
Starts a lightweight development Web server on the local machine. By default,
the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an
@@ -544,6 +537,8 @@ you want to configure Django to serve static media, read :ref:`howto-static-file
shell
-----
+.. django-admin:: shell
+
Starts the Python interactive interpreter.
Django will use IPython_, if it's installed. If you have IPython installed and
@@ -557,11 +552,15 @@ option, like so::
sql <appname appname ...>
-------------------------
+.. django-admin:: sql
+
Prints the CREATE TABLE SQL statements for the given app name(s).
sqlall <appname appname ...>
----------------------------
+.. django-admin:: sqlall
+
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
@@ -570,11 +569,15 @@ specify initial data.
sqlclear <appname appname ...>
------------------------------
+.. django-admin:: sqlclear
+
Prints the DROP TABLE SQL statements for the given app name(s).
sqlcustom <appname appname ...>
-------------------------------
+.. django-admin:: sqlcustom
+
Prints the custom SQL statements for the given app name(s).
For each model in each specified app, this command looks for the file
@@ -594,21 +597,30 @@ Note that the order in which the SQL files are processed is undefined.
sqlflush
--------
-Prints the SQL statements that would be executed for the `flush`_ command.
+.. django-admin:: sqlflush
+
+Prints the SQL statements that would be executed for the :djadmin:`flush`
+command.
sqlindexes <appname appname ...>
--------------------------------
+.. django-admin:: sqlindexes
+
Prints the CREATE INDEX SQL statements for the given app name(s).
sqlreset <appname appname ...>
------------------------------
+.. django-admin:: sqlreset
+
Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s).
sqlsequencereset <appname appname ...>
--------------------------------------
+.. django-admin:: sqlsequencereset
+
Prints the SQL statements for resetting sequences for the given app name(s).
Sequences are indexes used by some database engines to track the next available
@@ -620,12 +632,16 @@ of sync with its automatically incremented field data.
startapp <appname>
------------------
+.. django-admin:: startapp
+
Creates a Django app directory structure for the given app name in the current
directory.
startproject <projectname>
--------------------------
+.. django-admin:: startproject
+
Creates a Django project directory structure for the given project name in the
current directory.
@@ -635,11 +651,11 @@ This command is disabled when the ``--settings`` option to
situations, either omit the ``--settings`` option or unset
``DJANGO_SETTINGS_MODULE``.
-.. _django-admin-syncdb:
-
syncdb
------
+.. django-admin:: syncdb
+
Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables
have not already been created.
@@ -669,29 +685,22 @@ with an appropriate extension (e.g. ``json`` or ``xml``). See the
documentation for ``loaddata`` for details on the specification of fixture
data files.
---noinput
-~~~~~~~~~
+The :djadminopt:`--noinput` option may be provided to suppress all user
+prompts.
-Use the ``--noinput`` option to suppress all user prompting, such as
-"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
-is being executed as an unattended, automated script.
+test <app or test identifier>
+-----------------------------
-test
-----
+.. django-admin:: test
Runs tests for all installed models. See :ref:`topics-testing` for more
information.
---noinput
-~~~~~~~~~
-
-Use the ``--noinput`` option to suppress all user prompting, such as
-"Are you sure?" confirmation messages. This is useful if ``django-admin.py``
-is being executed as an unattended, automated script.
-
testserver <fixture fixture ...>
--------------------------------
+.. django-admin:: testserver
+
.. versionadded:: 1.0
Runs a Django development server (as in ``runserver``) using data from the
@@ -727,8 +736,7 @@ Note that this server does *not* automatically detect changes to your Python
source code (as ``runserver`` does). It does, however, detect changes to
templates.
---addrport [port number or ipaddr:port]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. django-admin-option:: --addrport [port number or ipaddr:port]
Use ``--addrport`` to specify a different port, or IP address and port, from
the default of 127.0.0.1:8000. This value follows exactly the same format and
@@ -752,6 +760,8 @@ To run on 1.2.3.4:7000 with a ``test`` fixture::
validate
--------
+.. django-admin:: validate
+
Validates all installed models (according to the ``INSTALLED_APPS`` setting)
and prints validation errors to standard output.
@@ -761,8 +771,7 @@ Default options
Although some subcommands may allow their own custom options, every subcommand
allows for the following options:
---pythonpath
-------------
+.. django-admin-option:: --pythonpath
Example usage::
@@ -777,8 +786,7 @@ setting the Python path for you.
.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html
---settings
-----------
+.. django-admin-option:: --settings
Example usage::
@@ -792,8 +800,7 @@ variable.
Note that this option is unnecessary in ``manage.py``, because it uses
``settings.py`` from the current project by default.
---traceback
------------
+.. django-admin-option:: --traceback
Example usage::
@@ -803,10 +810,7 @@ By default, ``django-admin.py`` will show a simple error message whenever an
error occurs. If you specify ``--traceback``, ``django-admin.py`` will
output a full stack trace whenever an exception is raised.
-.. _django-admin-verbosity:
-
---verbosity
------------
+.. django-admin-option:: --verbosity
Example usage::
@@ -819,6 +823,23 @@ that ``django-admin.py`` should print to the console.
* ``1`` means normal output (default).
* ``2`` means verbose output.
+Common options
+==============
+
+The following options are not available on every commands, but they are
+common to a number of commands.
+
+.. django-admin-option:: --locale
+
+Use the ``--locale`` or ``-l`` option to specify the locale to process.
+If not provided all locales are processed.
+
+.. django-admin-option:: --noinput
+
+Use the ``--noinput`` option to suppress all user prompting, such as "Are
+you sure?" confirmation messages. This is useful if ``django-admin.py`` is
+being executed as an unattended, automated script.
+
Extra niceties
==============
@@ -844,5 +865,4 @@ distribution. It enables tab-completion of ``django-admin.py`` and
with ``sql``.
-
See :ref:`howto-custom-management-commands` for how to add customized actions.
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index 9bf73f5b85..d74f8350e8 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -94,9 +94,8 @@ See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
.. versionadded:: 1.1
Defaults to ``True``, meaning Django will create the appropriate database
-tables in :ref:`django-admin-syncdb` and remove them as part of a :ref:`reset
-<django-admin-reset>` management command. That is, Django *manages* the
-database tables' lifecycles.
+tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset`
+management command. That is, Django *manages* the database tables' lifecycles.
If ``False``, no database table creation or deletion operations will be
performed for this model. This is useful if the model represents an existing
@@ -114,7 +113,7 @@ model handling are exactly the same as normal. This includes
unmanaged model, then the intermediate table for the many-to-many join
will also not be created. However, a the intermediary table between one
managed and one unmanaged model *will* be created.
-
+
If you need to change this default behavior, create the intermediary
table as an explicit model (with ``managed`` set as needed) and use the
:attr:`ManyToManyField.through` attribute to make the relation use your
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 8266224c39..20591311be 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -51,6 +51,18 @@ comment
Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
+.. templatetag:: csrf_token
+
+csrf_token
+~~~~~~~~~~
+
+.. versionadded:: 1.1.2
+
+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 :ref:`Cross Site Request
+Forgeries <ref-contrib-csrf>`.
+
.. templatetag:: cycle
csrf_token
diff --git a/docs/releases/1.1.2.txt b/docs/releases/1.1.2.txt
new file mode 100644
index 0000000000..64bbdd5dde
--- /dev/null
+++ b/docs/releases/1.1.2.txt
@@ -0,0 +1,36 @@
+.. _releases-1.1.2:
+
+==============================================
+Django 1.1.2 release notes — UNDER DEVELOPMENT
+==============================================
+
+This page documents release notes for the as-yet-unreleased Django
+1.1.2. As such it is tentative and subject to change. It provides
+up-to-date information for those who are following the 1.1.X branch.
+
+This is the second "bugfix" release in the Django 1.1 series,
+improving the stability and performance of the Django 1.1 codebase.
+
+Django 1.1.2 maintains backwards compatibility with Django
+1.1.0, but contain a number of fixes and other
+improvements. Django 1.1.2 is a recommended upgrade for any
+development or deployment currently using or targeting Django 1.1.
+
+For full details on the new features, backwards incompatibilities, and
+deprecated features in the 1.1 branch, see the :ref:`releases-1.1`.
+
+One new feature
+---------------
+
+Ordinarily, a point release would not include new features, but in the
+case of Django 1.1.2, we have made an exception to this rule. Django
+1.2 (the next major release of Django) will contain a feature that
+will improve protection against Cross-Site Request Forgery (CSRF)
+attacks. This feature requires the use of a new :ttag:`csrf_token`
+template tag in all forms that Django renders.
+
+To make it easier to support both 1.1.X and 1.2.X versions of Django with
+the same templates, we have decided to introduce the :ttag:`csrf_token` template
+tag to the 1.1.X branch. In the 1.1.X branch, :ttag:`csrf_token` does nothing -
+it has no effect on templates or form processing. However, it means that the
+same template will work with Django 1.2.
diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt
index cd4bdc5e96..c69a4de2e4 100644
--- a/docs/releases/1.1.txt
+++ b/docs/releases/1.1.txt
@@ -14,8 +14,10 @@ fixes, and an easy upgrade path from Django 1.0.
.. _new features: `What's new in Django 1.1`_
-Backwards-incompatible changes
-==============================
+.. _backwards-incompatible-changes-1.1:
+
+Backwards-incompatible changes in 1.1
+=====================================
Django has a policy of :ref:`API stability <misc-api-stability>`. This means
that, in general, code you develop against Django 1.0 should continue to work
@@ -150,6 +152,8 @@ Django 1.1 adds a ``permanent`` argument to the
backwards-incompatible if you were using the ``redirect_to`` view with a
format-string key called 'permanent', which is highly unlikely.
+.. _deprecated-features-1.1:
+
Features deprecated in 1.1
==========================
diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt
new file mode 100644
index 0000000000..122b2f4927
--- /dev/null
+++ b/docs/releases/1.2.txt
@@ -0,0 +1,157 @@
+.. _releases-1.2:
+
+============================================
+Django 1.2 release notes — UNDER DEVELOPMENT
+============================================
+
+This page documents release notes for the as-yet-unreleased Django 1.2. As such
+it is tentative and subject to change. It provides up-to-date information for
+those who are following trunk.
+
+Django 1.2 includes a number of nifty `new features`_, lots of bug
+fixes, and an easy upgrade path from Django 1.1.
+
+.. _new features: `What's new in Django 1.2`_
+
+.. _backwards-incompatible-changes-1.2:
+
+Backwards-incompatible changes in 1.2
+=====================================
+
+CSRF Protection
+---------------
+
+There have been large changes to the way that CSRF protection works, detailed in
+:ref:`the CSRF documentaton <ref-contrib-csrf>`. The following are the major
+changes that developers must be aware of:
+
+ * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated, and
+ will be removed completely in Django 1.4, in favor of a template tag that
+ should be inserted into forms.
+
+ * All contrib apps use a ``csrf_protect`` decorator to protect the view. This
+ requires the use of the csrf_token template tag in the template, so if you
+ have used custom templates for contrib views, you MUST READ THE :ref:`UPGRADE
+ INSTRUCTIONS <ref-csrf-upgrading-notes>` to fix those templates.
+
+ * ``CsrfViewMiddleware`` is included in :setting:`MIDDLEWARE_CLASSES` by
+ default. This turns on CSRF protection by default, so that views that accept
+ POST requests need to be written to work with the middleware. Instructions
+ on how to do this are found in the CSRF docs.
+
+ * All of the CSRF has moved from contrib to core (with backwards compatible
+ imports in the old locations, which are deprecated).
+
+``LazyObject``
+--------------
+
+``LazyObject`` is an undocumented utility class used for lazily wrapping other
+objects of unknown type. In Django 1.1 and earlier, it handled introspection in
+a non-standard way, depending on wrapped objects implementing a public method
+``get_all_members()``. Since this could easily lead to name clashes, it has been
+changed to use the standard method, involving ``__members__`` and ``__dir__()``.
+If you used ``LazyObject`` in your own code, and implemented the
+``get_all_members()`` method for wrapped objects, you need to make the following
+changes:
+
+ * If your class does not have special requirements for introspection (i.e. you
+ have not implemented ``__getattr__()`` or other methods that allow for
+ attributes not discoverable by normal mechanisms), you can simply remove the
+ ``get_all_members()`` method. The default implementation on ``LazyObject``
+ will do the right thing.
+
+ * If you have more complex requirements for introspection, first rename the
+ ``get_all_members()`` method to ``__dir__()``. This is the standard method,
+ from Python 2.6 onwards, for supporting introspection. If you are require
+ support for Python < 2.6, add the following code to the class::
+
+ __members__ = property(lambda self: self.__dir__())
+
+
+.. _deprecated-features-1.2:
+
+Features deprecated in 1.2
+==========================
+
+CSRF response rewriting middleware
+----------------------------------
+
+``CsrfResponseMiddleware``, the middleware that automatically inserted CSRF
+tokens into POST forms in outgoing pages, has been deprecated in favor of a
+template tag method (see above), and will be removed completely in Django
+1.4. ``CsrfMiddleware``, which includes the functionality of
+``CsrfResponseMiddleware`` and ``CsrfViewMiddleware`` has likewise been
+deprecated.
+
+Also, the CSRF module has moved from contrib to core, and the old imports are
+deprecated, as described in the :ref:`upgrading notes <ref-csrf-upgrading-notes>`.
+
+``SMTPConnection``
+------------------
+
+The ``SMTPConnection`` class has been deprecated in favor of a generic
+E-mail backend API. Old code that explicitly instantiated an instance
+of an SMTPConnection::
+
+ from django.core.mail import SMTPConnection
+ connection = SMTPConnection()
+ messages = get_notification_email()
+ connection.send_messages(messages)
+
+should now call :meth:`~django.core.mail.get_connection()` to
+instantiate a generic e-mail connection::
+
+ from django.core.mail import get_connection
+ connection = get_connection()
+ messages = get_notification_email()
+ connection.send_messages(messages)
+
+Depending on the value of the :setting:`EMAIL_BACKEND` setting, this
+may not return an SMTP connection. If you explicitly require an SMTP
+connection with which to send e-mail, you can explicitly request an
+SMTP connection::
+
+ from django.core.mail import get_connection
+ connection = get_connection('django.core.mail.backends.smtp')
+ messages = get_notification_email()
+ connection.send_messages(messages)
+
+If your call to construct an instance of ``SMTPConnection`` required
+additional arguments, those arguments can be passed to the
+:meth:`~django.core.mail.get_connection()` call::
+
+ connection = get_connection('django.core.mail.backends.smtp', hostname='localhost', port=1234)
+
+What's new in Django 1.2
+========================
+
+CSRF support
+------------
+
+Django now has much improved protection against :ref:`Cross-Site
+Request Forgery (CSRF) attacks<ref-contrib-csrf>`. This type of attack
+occurs when a malicious Web site contains a link, a form button or
+some javascript that is intended to perform some action on your Web
+site, using the credentials of a logged-in user who visits the
+malicious site in their browser. A related type of attack, 'login
+CSRF', where an attacking site tricks a user's browser into logging
+into a site with someone else's credentials, is also covered.
+
+E-mail Backends
+---------------
+
+You can now :ref:`configure the way that Django sends e-mail
+<topic-email-backends>`. Instead of using SMTP to send all e-mail, you
+can now choose a configurable e-mail backend to send messages. If your
+hosting provider uses a sandbox or some other non-SMTP technique for
+sending mail, you can now construct an e-mail backend that will allow
+Django's standard :ref:`mail sending methods<topics-email>` to use
+those facilities.
+
+This also makes it easier to debug mail sending - Django ships with
+backend implementations that allow you to send e-mail to a
+:ref:`file<topic-email-file-backend>`, to the
+:ref:`console<topic-email-console-backend>`, or to
+:ref:`memory<topic-email-memory-backend>` - you can even configure all
+e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.
+
diff --git a/docs/releases/index.txt b/docs/releases/index.txt
index e5c4fde537..868ff5bd63 100644
--- a/docs/releases/index.txt
+++ b/docs/releases/index.txt
@@ -1,5 +1,6 @@
.. _releases-index:
+=============
Release notes
=============
@@ -7,28 +8,60 @@ Release notes for the official Django releases. Each release note will tell you
what's new in each version, and will also describe any backwards-incompatible
changes made in that version.
+For those upgrading to a new version of Django, you will need to check
+all the backwards-incompatible changes and deprecated features for
+each 'final' release from the one after your current Django version,
+up to and including the new version.
+
+Final releases
+==============
+
+1.2 release
+-----------
.. toctree::
:maxdepth: 1
- 0.95
- 0.96
- 1.0-alpha-1
- 1.0-alpha-2
- 1.0-beta
- 1.0-beta-2
- 1.0
- 1.0.1
- 1.0.2
- 1.1-alpha-1
- 1.1-beta-1
- 1.1-rc-1
+ 1.2
+
+1.1 release
+-----------
+.. toctree::
+ :maxdepth: 1
+
+ 1.1.2
1.1
-.. seealso::
+1.0 release
+-----------
+.. toctree::
+ :maxdepth: 1
+
+ 1.0.2
+ 1.0.1
+ 1.0
+
+Pre-1.0 releases
+----------------
+.. toctree::
+ :maxdepth: 1
+
+ 0.96
+ 0.95
+
+Development releases
+====================
- The list of `backwards-incompatible changes`_ made in the current
- development "trunk". If you're running versions of Django newer than an
- official release, you should keep track of new pieces pointed there. It's
- also fun reading if you're looking forward to new versions of Django.
+These notes are retained for historical purposes. If you are upgrading
+between formal Django releases, you don't need to worry about these
+notes.
-.. _backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
+.. toctree::
+ :maxdepth: 1
+
+ 1.1-rc-1
+ 1.1-beta-1
+ 1.1-alpha-1
+ 1.0-beta-2
+ 1.0-beta
+ 1.0-alpha-2
+ 1.0-alpha-1
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 31900cd49f..b0e325b5c5 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -179,9 +179,9 @@ Local-memory caching
If you want the speed advantages of in-memory caching but don't have the
capability of running Memcached, consider the local-memory cache backend. This
cache is multi-process and thread-safe. To use it, set ``CACHE_BACKEND`` to
-``"locmem:///"``. For example::
+``"locmem://"``. For example::
- CACHE_BACKEND = 'locmem:///'
+ CACHE_BACKEND = 'locmem://'
Note that each process will have its own private cache instance, which means no
cross-process caching is possible. This obviously also means the local memory
@@ -199,7 +199,7 @@ various places but a development/test environment where you don't want to cache
and don't want to have to change your code to special-case the latter. To
activate dummy caching, set ``CACHE_BACKEND`` like so::
- CACHE_BACKEND = 'dummy:///'
+ CACHE_BACKEND = 'dummy://'
Using a custom cache backend
----------------------------
@@ -249,7 +249,7 @@ In this example, ``timeout`` is set to ``60``::
In this example, ``timeout`` is ``30`` and ``max_entries`` is ``400``::
- CACHE_BACKEND = "locmem:///?timeout=30&max_entries=400"
+ CACHE_BACKEND = "locmem://?timeout=30&max_entries=400"
Invalid arguments are silently ignored, as are invalid values of known
arguments.
@@ -451,11 +451,11 @@ The low-level cache API
Sometimes, caching an entire rendered page doesn't gain you very much and is,
in fact, inconvenient overkill.
-Perhaps, for instance, your site includes a view whose results depend on
+Perhaps, for instance, your site includes a view whose results depend on
several expensive queries, the results of which change at different intervals.
-In this case, it would not be ideal to use the full-page caching that the
-per-site or per-view cache strategies offer, because you wouldn't want to
-cache the entire result (since some of the data changes often), but you'd still
+In this case, it would not be ideal to use the full-page caching that the
+per-site or per-view cache strategies offer, because you wouldn't want to
+cache the entire result (since some of the data changes often), but you'd still
want to cache the results that rarely change.
For cases like this, Django exposes a simple, low-level cache API. You can use
@@ -757,10 +757,10 @@ Django comes with a few other pieces of middleware that can help optimize your
apps' performance:
* ``django.middleware.http.ConditionalGetMiddleware`` adds support for
- modern browsers to conditionally GET responses based on the ``ETag``
+ modern browsers to conditionally GET responses based on the ``ETag``
and ``Last-Modified`` headers.
- * ``django.middleware.gzip.GZipMiddleware`` compresses responses for all
+ * ``django.middleware.gzip.GZipMiddleware`` compresses responses for all
moderns browsers, saving bandwidth and transfer time.
Order of MIDDLEWARE_CLASSES
diff --git a/docs/topics/email.txt b/docs/topics/email.txt
index 92e3c0263d..eee77cb4a0 100644
--- a/docs/topics/email.txt
+++ b/docs/topics/email.txt
@@ -10,7 +10,7 @@ Sending e-mail
Although Python makes sending e-mail relatively easy via the `smtplib
library`_, Django provides a couple of light wrappers over it. These wrappers
are provided to make sending e-mail extra quick, to make it easy to test
-email sending during development, and to provide support for platforms that
+e-mail sending during development, and to provide support for platforms that
can't use SMTP.
The code lives in the ``django.core.mail`` module.
@@ -64,7 +64,7 @@ are required.
* ``auth_password``: The optional password to use to authenticate to the
SMTP server. If this isn't provided, Django will use the value of the
``EMAIL_HOST_PASSWORD`` setting.
- * ``connection``: The optional email backend to use to send the mail.
+ * ``connection``: The optional e-mail backend to use to send the mail.
If unspecified, an instance of the default backend will be used.
See the documentation on :ref:`E-mail backends <topic-email-backends>`
for more details.
@@ -215,8 +215,8 @@ message itself. The :ref:`e-mail backend <topic-email-backends>` is then
responsible for sending the e-mail.
For convenience, :class:`~django.core.mail.EmailMessage` provides a simple
-``send()`` method for sending a single email. If you need to send multiple
-messages, the email backend API :ref:`provides an alternative
+``send()`` method for sending a single e-mail. If you need to send multiple
+messages, the e-mail backend API :ref:`provides an alternative
<topics-sending-multiple-emails>`.
EmailMessage Objects
@@ -264,7 +264,7 @@ For example::
The class has the following methods:
* ``send(fail_silently=False)`` sends the message. If a connection was
- specified when the email was constructed, that connection will be used.
+ specified when the e-mail was constructed, that connection will be used.
Otherwise, an instance of the default backend will be instantiated and
used. If the keyword argument ``fail_silently`` is ``True``, exceptions
raised while sending the message will be quashed.
@@ -358,9 +358,9 @@ The actual sending of an e-mail is handled by the e-mail backend.
The e-mail backend class has the following methods:
- * ``open()`` instantiates an long-lived email-sending connection.
+ * ``open()`` instantiates an long-lived e-mail-sending connection.
- * ``close()`` closes the current email-sending connection.
+ * ``close()`` closes the current e-mail-sending connection.
* ``send_messages(email_messages)`` sends a list of
:class:`~django.core.mail.EmailMessage` objects. If the connection is
@@ -379,11 +379,11 @@ instance of the e-mail backend that you can use.
.. function:: get_connection(backend=None, fail_silently=False, *args, **kwargs)
By default, a call to ``get_connection()`` will return an instance of the
-email backend specified in :setting:`EMAIL_BACKEND`. If you specify the
+e-mail backend specified in :setting:`EMAIL_BACKEND`. If you specify the
``backend`` argument, an instance of that backend will be instantiated.
The ``fail_silently`` argument controls how the backend should handle errors.
-If ``fail_silently`` is True, exceptions during the email sending process
+If ``fail_silently`` is True, exceptions during the e-mail sending process
will be silently ignored.
All other arguments are passed directly to the constructor of the
@@ -391,8 +391,8 @@ e-mail backend.
Django ships with several e-mail sending backends. With the exception of the
SMTP backend (which is the default), these backends are only useful during
-testing and development. If you have special email sending requirements, you
-can :ref:`write your own email backend <topic-custom-email-backend>`.
+testing and development. If you have special e-mail sending requirements, you
+can :ref:`write your own e-mail backend <topic-custom-email-backend>`.
.. _topic-email-smtp-backend:
@@ -401,7 +401,7 @@ SMTP backend
This is the default backend. E-mail will be sent through a SMTP server.
The server address and authentication credentials are set in the
-:setting:`EMAIL_HOST`, :setting:`EMAIL_POST`, :setting:`EMAIL_HOST_USER`,
+:setting:`EMAIL_HOST`, :setting:`EMAIL_PORT`, :setting:`EMAIL_HOST_USER`,
:setting:`EMAIL_HOST_PASSWORD` and :setting:`EMAIL_USE_TLS` settings in your
settings file.
@@ -414,13 +414,15 @@ want to specify it explicitly, put the following in your settings::
Prior to version 1.2, Django provided a
:class:`~django.core.mail.SMTPConnection` class. This class provided a way
- to directly control the use of SMTP to send email. This class has been
- deprecated in favor of the generic email backend API.
+ to directly control the use of SMTP to send e-mail. This class has been
+ deprecated in favor of the generic e-mail backend API.
For backwards compatibility :class:`~django.core.mail.SMTPConnection` is
still available in ``django.core.mail`` as an alias for the SMTP backend.
New code should use :meth:`~django.core.mail.get_connection` instead.
+.. _topic-email-console-backend:
+
Console backend
~~~~~~~~~~~~~~~
@@ -436,6 +438,8 @@ To specify this backend, put the following in your settings::
This backend is not intended for use in production -- it is provided as a
convenience that can be used during development.
+.. _topic-email-file-backend:
+
File backend
~~~~~~~~~~~~
@@ -453,6 +457,8 @@ To specify this backend, put the following in your settings::
This backend is not intended for use in production -- it is provided as a
convenience that can be used during development.
+.. _topic-email-memory-backend:
+
In-memory backend
~~~~~~~~~~~~~~~~~
@@ -469,6 +475,8 @@ To specify this backend, put the following in your settings::
This backend is not intended for use in production -- it is provided as a
convenience that can be used during development and testing.
+.. _topic-email-dummy-backend:
+
Dummy backend
~~~~~~~~~~~~~
@@ -500,15 +508,15 @@ implementation.
.. _topics-sending-multiple-emails:
-Sending multiple emails
------------------------
+Sending multiple e-mails
+------------------------
Establishing and closing an SMTP connection (or any other network connection,
-for that matter) is an expensive process. If you have a lot of emails to send,
+for that matter) is an expensive process. If you have a lot of e-mails to send,
it makes sense to reuse an SMTP connection, rather than creating and
-destroying a connection every time you want to send an email.
+destroying a connection every time you want to send an e-mail.
-There are two ways you tell an email backend to reuse a connection.
+There are two ways you tell an e-mail backend to reuse a connection.
Firstly, you can use the ``send_messages()`` method. ``send_messages()`` takes
a list of :class:`~django.core.mail.EmailMessage` instances (or subclasses),
@@ -516,11 +524,11 @@ and sends them all using a single connection.
For example, if you have a function called ``get_notification_email()`` that
returns a list of :class:`~django.core.mail.EmailMessage` objects representing
-some periodic e-mail you wish to send out, you could send these emails using
+some periodic e-mail you wish to send out, you could send these e-mails using
a single call to send_messages::
from django.core import mail
- connection = mail.get_connection() # Use default email connection
+ connection = mail.get_connection() # Use default e-mail connection
messages = get_notification_email()
connection.send_messages(messages)
@@ -528,7 +536,7 @@ In this example, the call to ``send_messages()`` opens a connection on the
backend, sends the list of messages, and then closes the connection again.
The second approach is to use the ``open()`` and ``close()`` methods on the
-email backend to manually control the connection. ``send_messages()`` will not
+e-mail backend to manually control the connection. ``send_messages()`` will not
manually open or close the connection if it is already open, so if you
manually open the connection, you can control when it is closed. For example::
@@ -538,10 +546,10 @@ manually open the connection, you can control when it is closed. For example::
# Manually open the connection
connection.open()
- # Construct an email message that uses the connection
+ # Construct an e-mail message that uses the connection
email1 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com',
['to1@example.com'], connection=connection)
- email1.send() # Send the email
+ email1.send() # Send the e-mail
# Construct two more messages
email2 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com',
@@ -549,7 +557,7 @@ manually open the connection, you can control when it is closed. For example::
email3 = mail.EmailMessage('Hello', 'Body goes here', 'from@example.com',
['to3@example.com'])
- # Send the two emails in a single call -
+ # Send the two e-mails in a single call -
connection.send_messages([email2, email3])
# The connection was already open so send_messages() doesn't close it.
# We need to manually close the connection.
@@ -566,10 +574,10 @@ people under the right conditions, and that those e-mails will contain the
correct content.
The easiest way to test your project's use of e-mail is to use the ``console``
-email backend. This backend redirects all email to stdout, allowing you to
+e-mail backend. This backend redirects all e-mail to stdout, allowing you to
inspect the content of mail.
-The ``file`` email backend can also be useful during development -- this backend
+The ``file`` e-mail backend can also be useful during development -- this backend
dumps the contents of every SMTP connection to a file that can be inspected
at your leisure.
@@ -596,7 +604,7 @@ SMTPConnection
.. deprecated:: 1.2
-The ``SMTPConnection`` class has been deprecated in favor of the generic email
+The ``SMTPConnection`` class has been deprecated in favor of the generic e-mail
backend API.
For backwards compatibility ``SMTPConnection`` is still available in
diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 0b2257cefe..fd45e79876 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -40,7 +40,8 @@ algorithm the system follows to determine which Python code to execute:
1. Django determines the root URLconf module to use. Ordinarily,
this is the value of the ``ROOT_URLCONF`` setting, but if the incoming
- ``HttpRequest`` object has an attribute called ``urlconf``, its value
+ ``HttpRequest`` object has an attribute called ``urlconf`` (set by
+ middleware :ref:`request processing <request-middleware>`), its value
will be used in place of the ``ROOT_URLCONF`` setting.
2. Django loads that Python module and looks for the variable
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index 6648461014..a9ba66ece0 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -980,19 +980,21 @@ subclass::
def setUp(self):
# Test definitions as before.
+ call_setup_methods()
def testFluffyAnimals(self):
# A test that uses the fixtures.
+ call_some_test_code()
Here's specifically what will happen:
* At the start of each test case, before ``setUp()`` is run, Django will
flush the database, returning the database to the state it was in
- directly after ``syncdb`` was called.
+ directly after :djadmin:`syncdb` was called.
* Then, all the named fixtures are installed. In this example, Django will
install any JSON fixture named ``mammals``, followed by any fixture named
- ``birds``. See the :djadmin:`loaddata documentation<loaddata>` for more
+ ``birds``. See the :djadmin:`loaddata` documentation for more
details on defining and installing fixtures.
This flush/load procedure is repeated for each test in the test case, so you
@@ -1028,6 +1030,7 @@ For example::
def testIndexPageView(self):
# Here you'd test your view using ``Client``.
+ call_some_test_code()
This test case will use the contents of ``myapp.test_urls`` as the
URLconf for the duration of the test case.
generated by cgit v1.3 (git 2.53.0) at 2026-07-15 03:50:39 +0000