From 3b895d4a9a68a841ec517b84451da496bb258b3f Mon Sep 17 00:00:00 2001 From: Honza Král Date: Mon, 7 Dec 2009 01:41:26 +0000 Subject: [soc2009/model-validation] Merged to trunk at r11791 git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@11798 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/index.txt | 4 +- docs/internals/committers.txt | 13 +++ docs/ref/contrib/csrf.txt | 12 +-- docs/ref/django-admin.txt | 174 ++++++++++++++++++++++------------------ docs/ref/models/options.txt | 7 +- docs/ref/templates/builtins.txt | 12 +++ docs/releases/1.1.2.txt | 36 +++++++++ docs/releases/1.1.txt | 8 +- docs/releases/1.2.txt | 157 ++++++++++++++++++++++++++++++++++++ docs/releases/index.txt | 69 +++++++++++----- docs/topics/cache.txt | 20 ++--- docs/topics/email.txt | 64 ++++++++------- docs/topics/http/urls.txt | 3 +- docs/topics/testing.txt | 7 +- 14 files changed, 436 insertions(+), 150 deletions(-) create mode 100644 docs/releases/1.1.2.txt create mode 100644 docs/releases/1.2.txt (limited to 'docs') 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 ` | - :ref:`Archive of release notes ` | `Backwards-incompatible changes`_ | + :ref:`Release notes and upgrading instructions ` | :ref:`Deprecation Timeline ` - -.. _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 ``
`` element if the form is for an internal URL, e.g.:: {% 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 - -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 `. +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 +.. 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 +-------------------------------------------- -.. django-admin:: dumpdata +.. 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 - 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 - 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 ------------------------------ +.. 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 ` 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 --------------------------- -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 ` 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 ------------------------- +.. django-admin:: sql + Prints the CREATE TABLE SQL statements for the given app name(s). sqlall ---------------------------- +.. 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 ------------------------------ +.. django-admin:: sqlclear + Prints the DROP TABLE SQL statements for the given app name(s). sqlcustom ------------------------------- +.. 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 -------------------------------- +.. django-admin:: sqlindexes + Prints the CREATE INDEX SQL statements for the given app name(s). sqlreset ------------------------------ +.. django-admin:: sqlreset + Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s). sqlsequencereset -------------------------------------- +.. 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 ------------------ +.. django-admin:: startapp + Creates a Django app directory structure for the given app name in the current directory. startproject -------------------------- +.. 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 +----------------------------- -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 -------------------------------- +.. 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 -` 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 `. + .. 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 `. 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 `. 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 ` 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 `. + +``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`. 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 +`. 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` 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`, to the +:ref:`console`, or to +:ref:`memory` - you can even configure all +e-mail to be :ref:`thrown away`. + 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 ` for more details. @@ -215,8 +215,8 @@ message itself. The :ref:`e-mail backend ` 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 `. 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 `. +testing and development. If you have special e-mail sending requirements, you +can :ref:`write your own e-mail 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 `), 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` 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. -- cgit v1.3