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

[soc2009/model-validation] Merged to trunk at r11791

Browse Source 
git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@11798 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Honza Král
2009-12-07 01:41:26 +00:00
parent 30ea350dab
commit 3b895d4a9a
78 changed files with 2154 additions and 1252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/index.txt
View File

@@ -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

13
docs/internals/committers.txt
View File

@@ -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
-----------

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

@@ -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

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

@@ -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 ...>
---------------------------
.. django-admin:: reset
Executes the equivalent of ``sqlreset`` for the given app name(s).
--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.
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.

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

@@ -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

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

@@ -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

36
docs/releases/1.1.2.txt Normal file
View File

@@ -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.

8
docs/releases/1.1.txt
View File

@@ -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
==========================

157
docs/releases/1.2.txt Normal file
View File

@@ -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>`.

69
docs/releases/index.txt
View File

@@ -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
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.
1.0.2
1.0.1
1.0
.. _backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
Pre-1.0 releases
----------------
.. toctree::
:maxdepth: 1
0.96
0.95
Development releases
====================
These notes are retained for historical purposes. If you are upgrading
between formal Django releases, you don't need to worry about these
notes.
.. 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

20
docs/topics/cache.txt
View File

@@ -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

64
docs/topics/email.txt
View File

@@ -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

3
docs/topics/http/urls.txt
View File

@@ -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

7
docs/topics/testing.txt
View File

@@ -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.