1
0
mirror of https://github.com/django/django.git synced 2025-08-26 19:59:29 +00:00

Refs #36485 -- Removed unnecessary parentheses in :meth: and :func: roles in docs.

This commit is contained in:
David Smith 2025-05-27 17:37:22 +01:00 committed by nessita
parent ef2f16bc48
commit 6f8e23d1c1
95 changed files with 445 additions and 445 deletions

View File

@ -29,7 +29,7 @@ You'll need to follow these steps:
option = settings.CUSTOM_STORAGE_OPTIONS option = settings.CUSTOM_STORAGE_OPTIONS
... ...
#. Your storage class must implement the :meth:`_open()` and :meth:`_save()` #. Your storage class must implement the :meth:`_open` and :meth:`_save`
methods, along with any other methods appropriate to your storage class. See methods, along with any other methods appropriate to your storage class. See
below for more on these methods. below for more on these methods.

View File

@ -509,7 +509,7 @@ Simple block tags
When a section of rendered template needs to be passed into a custom tag, When a section of rendered template needs to be passed into a custom tag,
Django provides the ``simple_block_tag`` helper function to accomplish this. Django provides the ``simple_block_tag`` helper function to accomplish this.
Similar to :meth:`~django.template.Library.simple_tag()`, this function accepts Similar to :meth:`~django.template.Library.simple_tag`, this function accepts
a custom tag function, but with the additional ``content`` argument, which a custom tag function, but with the additional ``content`` argument, which
contains the rendered content as defined inside the tag. This allows dynamic contains the rendered content as defined inside the tag. This allows dynamic
template sections to be easily incorporated into custom tags. template sections to be easily incorporated into custom tags.

View File

@ -37,7 +37,7 @@ attribute::
migrations.RunPython(forwards), migrations.RunPython(forwards),
] ]
You can also provide hints that will be passed to the :meth:`allow_migrate()` You can also provide hints that will be passed to the :meth:`allow_migrate`
method of database routers as ``**hints``: method of database routers as ``**hints``:
.. code-block:: python .. code-block:: python
@ -197,7 +197,7 @@ a transaction by setting the ``atomic`` attribute to ``False``::
Within such a migration, all operations are run without a transaction. It's Within such a migration, all operations are run without a transaction. It's
possible to execute parts of the migration inside a transaction using possible to execute parts of the migration inside a transaction using
:func:`~django.db.transaction.atomic()` or by passing ``atomic=True`` to :func:`~django.db.transaction.atomic` or by passing ``atomic=True`` to
``RunPython``. ``RunPython``.
Here's an example of a non-atomic data migration that updates a large table in Here's an example of a non-atomic data migration that updates a large table in

View File

@ -823,7 +823,7 @@ details on these changes.
:func:`~django.template.loader.get_template` and :func:`~django.template.loader.get_template` and
:func:`~django.template.loader.select_template` won't accept a :func:`~django.template.loader.select_template` won't accept a
:class:`~django.template.Context` in their :class:`~django.template.Context` in their
:meth:`~django.template.backends.base.Template.render()` method anymore. :meth:`~django.template.backends.base.Template.render` method anymore.
* :doc:`Template response APIs </ref/template-response>` will enforce the use * :doc:`Template response APIs </ref/template-response>` will enforce the use
of :class:`dict` and backend-dependent template objects instead of of :class:`dict` and backend-dependent template objects instead of

View File

@ -282,7 +282,7 @@ plug-and-play URLs. Since polls are in their own URLconf
"/fun_polls/", or under "/content/polls/", or any other path root, and the "/fun_polls/", or under "/content/polls/", or any other path root, and the
app will still work. app will still work.
.. admonition:: When to use :func:`~django.urls.include()` .. admonition:: When to use :func:`~django.urls.include`
You should always use ``include()`` when you include other URL patterns. You should always use ``include()`` when you include other URL patterns.
The only exception is ``admin.site.urls``, which is a pre-built URLconf The only exception is ``admin.site.urls``, which is a pre-built URLconf

View File

@ -557,8 +557,8 @@ repetition out of the process of creating questions.
"No polls are available." and verifies the ``latest_question_list`` is empty. "No polls are available." and verifies the ``latest_question_list`` is empty.
Note that the :class:`django.test.TestCase` class provides some additional Note that the :class:`django.test.TestCase` class provides some additional
assertion methods. In these examples, we use assertion methods. In these examples, we use
:meth:`~django.test.SimpleTestCase.assertContains()` and :meth:`~django.test.SimpleTestCase.assertContains` and
:meth:`~django.test.TransactionTestCase.assertQuerySetEqual()`. :meth:`~django.test.TransactionTestCase.assertQuerySetEqual`.
In ``test_past_question``, we create a question and verify that it appears in In ``test_past_question``, we create a question and verify that it appears in
the list. the list.

View File

@ -271,7 +271,7 @@ Methods
Requires the app registry to be fully populated unless the Requires the app registry to be fully populated unless the
``require_ready`` argument is set to ``False``. ``require_ready`` behaves ``require_ready`` argument is set to ``False``. ``require_ready`` behaves
exactly as in :meth:`apps.get_model()`. exactly as in :meth:`apps.get_model`.
.. method:: AppConfig.ready() .. method:: AppConfig.ready()
@ -309,12 +309,12 @@ Methods
.. warning:: .. warning::
Although you can access model classes as described above, avoid Although you can access model classes as described above, avoid
interacting with the database in your :meth:`ready()` implementation. interacting with the database in your :meth:`ready` implementation.
This includes model methods that execute queries This includes model methods that execute queries
(:meth:`~django.db.models.Model.save()`, (:meth:`~django.db.models.Model.save`,
:meth:`~django.db.models.Model.delete()`, manager methods etc.), and :meth:`~django.db.models.Model.delete`, manager methods etc.), and
also raw SQL queries via ``django.db.connection``. Your also raw SQL queries via ``django.db.connection``. Your
:meth:`ready()` method will run during startup of every management :meth:`ready` method will run during startup of every management
command. For example, even though the test database configuration is command. For example, even though the test database configuration is
separate from the production settings, ``manage.py test`` would still separate from the production settings, ``manage.py test`` would still
execute some queries against your **production** database! execute some queries against your **production** database!
@ -416,7 +416,7 @@ Initialization process
How applications are loaded How applications are loaded
--------------------------- ---------------------------
When Django starts, :func:`django.setup()` is responsible for populating the When Django starts, :func:`django.setup` is responsible for populating the
application registry. application registry.
.. currentmodule:: django .. currentmodule:: django
@ -463,7 +463,7 @@ processes all applications in the order of :setting:`INSTALLED_APPS`.
import any models at this stage. import any models at this stage.
Once this stage completes, APIs that operate on application configurations Once this stage completes, APIs that operate on application configurations
such as :meth:`~apps.get_app_config()` become usable. such as :meth:`~apps.get_app_config` become usable.
#. Then Django attempts to import the ``models`` submodule of each application, #. Then Django attempts to import the ``models`` submodule of each application,
if there is one. if there is one.
@ -473,9 +473,9 @@ processes all applications in the order of :setting:`INSTALLED_APPS`.
populated at this point, which could cause the ORM to malfunction. populated at this point, which could cause the ORM to malfunction.
Once this stage completes, APIs that operate on models such as Once this stage completes, APIs that operate on models such as
:meth:`~apps.get_model()` become usable. :meth:`~apps.get_model` become usable.
#. Finally Django runs the :meth:`~AppConfig.ready()` method of each application #. Finally Django runs the :meth:`~AppConfig.ready` method of each application
configuration. configuration.
.. _applications-troubleshooting: .. _applications-troubleshooting:
@ -489,10 +489,10 @@ Here are some common problems that you may encounter during initialization:
importing an application configuration or a models module triggers code that importing an application configuration or a models module triggers code that
depends on the app registry. depends on the app registry.
For example, :func:`~django.utils.translation.gettext()` uses the app For example, :func:`~django.utils.translation.gettext` uses the app
registry to look up translation catalogs in applications. To translate at registry to look up translation catalogs in applications. To translate at
import time, you need :func:`~django.utils.translation.gettext_lazy()` import time, you need :func:`~django.utils.translation.gettext_lazy`
instead. (Using :func:`~django.utils.translation.gettext()` would be a bug, instead. (Using :func:`~django.utils.translation.gettext` would be a bug,
because the translation would happen at import time, rather than at each because the translation would happen at import time, rather than at each
request depending on the active language.) request depending on the active language.)
@ -500,7 +500,7 @@ Here are some common problems that you may encounter during initialization:
will also trigger this exception. The ORM cannot function properly until all will also trigger this exception. The ORM cannot function properly until all
models are available. models are available.
This exception also happens if you forget to call :func:`django.setup()` in This exception also happens if you forget to call :func:`django.setup` in
a standalone Python script. a standalone Python script.
* ``ImportError: cannot import name ...`` This happens if the import sequence * ``ImportError: cannot import name ...`` This happens if the import sequence

View File

@ -24,10 +24,10 @@ MRO is an acronym for Method Resolution Order.
**Method Flowchart** **Method Flowchart**
#. :meth:`setup()` #. :meth:`setup`
#. :meth:`dispatch()` #. :meth:`dispatch`
#. :meth:`http_method_not_allowed()` #. :meth:`http_method_not_allowed`
#. :meth:`options()` #. :meth:`options`
**Example views.py**:: **Example views.py**::
@ -144,10 +144,10 @@ MRO is an acronym for Method Resolution Order.
**Method Flowchart** **Method Flowchart**
#. :meth:`~django.views.generic.base.View.setup()` #. :meth:`~django.views.generic.base.View.setup`
#. :meth:`~django.views.generic.base.View.dispatch()` #. :meth:`~django.views.generic.base.View.dispatch`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()` #. :meth:`~django.views.generic.base.View.http_method_not_allowed`
#. :meth:`~django.views.generic.base.ContextMixin.get_context_data()` #. :meth:`~django.views.generic.base.ContextMixin.get_context_data`
**Example views.py**:: **Example views.py**::
@ -206,10 +206,10 @@ MRO is an acronym for Method Resolution Order.
**Method Flowchart** **Method Flowchart**
#. :meth:`~django.views.generic.base.View.setup()` #. :meth:`~django.views.generic.base.View.setup`
#. :meth:`~django.views.generic.base.View.dispatch()` #. :meth:`~django.views.generic.base.View.dispatch`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()` #. :meth:`~django.views.generic.base.View.http_method_not_allowed`
#. :meth:`get_redirect_url()` #. :meth:`get_redirect_url`
**Example views.py**:: **Example views.py**::

View File

@ -25,17 +25,17 @@ many projects they are typically the most commonly used views.
**Method Flowchart** **Method Flowchart**
#. :meth:`~django.views.generic.base.View.setup()` #. :meth:`~django.views.generic.base.View.setup`
#. :meth:`~django.views.generic.base.View.dispatch()` #. :meth:`~django.views.generic.base.View.dispatch`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()` #. :meth:`~django.views.generic.base.View.http_method_not_allowed`
#. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()` #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field`
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()` #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset`
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object`
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()` #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name`
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()` #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data`
#. :meth:`~django.views.generic.detail.BaseDetailView.get` #. :meth:`~django.views.generic.detail.BaseDetailView.get`
#. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
**Example myapp/views.py**:: **Example myapp/views.py**::
@ -116,15 +116,15 @@ many projects they are typically the most commonly used views.
**Method Flowchart** **Method Flowchart**
#. :meth:`~django.views.generic.base.View.setup()` #. :meth:`~django.views.generic.base.View.setup`
#. :meth:`~django.views.generic.base.View.dispatch()` #. :meth:`~django.views.generic.base.View.dispatch`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()` #. :meth:`~django.views.generic.base.View.http_method_not_allowed`
#. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`
#. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()` #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset`
#. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()` #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name`
#. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()` #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data`
#. :meth:`~django.views.generic.list.BaseListView.get` #. :meth:`~django.views.generic.list.BaseListView.get`
#. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
**Example views.py**:: **Example views.py**::

View File

@ -23,7 +23,7 @@ it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
a thread-safe operation). a thread-safe operation).
A class-based view is deployed into a URL pattern using the A class-based view is deployed into a URL pattern using the
:meth:`~django.views.generic.base.View.as_view()` classmethod:: :meth:`~django.views.generic.base.View.as_view` classmethod::
urlpatterns = [ urlpatterns = [
path("view/", MyView.as_view(size=42)), path("view/", MyView.as_view(size=42)),
@ -37,7 +37,7 @@ A class-based view is deployed into a URL pattern using the
is modified, the actions of one user visiting your view could have an is modified, the actions of one user visiting your view could have an
effect on subsequent users visiting the same view. effect on subsequent users visiting the same view.
Arguments passed into :meth:`~django.views.generic.base.View.as_view()` will Arguments passed into :meth:`~django.views.generic.base.View.as_view` will
be assigned onto the instance that is used to service a request. Using the be assigned onto the instance that is used to service a request. Using the
previous example, this means that every request on ``MyView`` is able to use previous example, this means that every request on ``MyView`` is able to use
``self.size``. Arguments must correspond to attributes that already exist on ``self.size``. Arguments must correspond to attributes that already exist on

View File

@ -95,7 +95,7 @@ Simple mixins
If any keyword arguments are provided, they will be passed to the If any keyword arguments are provided, they will be passed to the
constructor of the response class. constructor of the response class.
Calls :meth:`get_template_names()` to obtain the list of template names Calls :meth:`get_template_names` to obtain the list of template names
that will be searched looking for an existent template. that will be searched looking for an existent template.
.. method:: get_template_names() .. method:: get_template_names()

View File

@ -53,7 +53,7 @@ Single object mixins
.. attribute:: query_pk_and_slug .. attribute:: query_pk_and_slug
If ``True``, causes :meth:`get_object()` to perform its lookup using If ``True``, causes :meth:`get_object` to perform its lookup using
both the primary key and the slug. Defaults to ``False``. both the primary key and the slug. Defaults to ``False``.
This attribute can help mitigate `insecure direct object reference`_ This attribute can help mitigate `insecure direct object reference`_

View File

@ -288,7 +288,7 @@ Making actions available site-wide
Some actions are best if they're made available to *any* object in the admin Some actions are best if they're made available to *any* object in the admin
site -- the export action defined above would be a good candidate. You can site -- the export action defined above would be a good candidate. You can
make an action globally available using :meth:`AdminSite.add_action()`. For make an action globally available using :meth:`AdminSite.add_action`. For
example:: example::
from django.contrib import admin from django.contrib import admin
@ -299,7 +299,7 @@ Making actions available site-wide
action named "export_selected_objects". You can explicitly give the action action named "export_selected_objects". You can explicitly give the action
a name -- good if you later want to programmatically :ref:`remove the action a name -- good if you later want to programmatically :ref:`remove the action
<disabling-admin-actions>` -- by passing a second argument to <disabling-admin-actions>` -- by passing a second argument to
:meth:`AdminSite.add_action()`:: :meth:`AdminSite.add_action`::
admin.site.add_action(export_selected_objects, "export_selected") admin.site.add_action(export_selected_objects, "export_selected")
@ -318,7 +318,7 @@ Disabling a site-wide action
.. method:: AdminSite.disable_action(name) .. method:: AdminSite.disable_action(name)
If you need to disable a :ref:`site-wide action <adminsite-actions>` you can If you need to disable a :ref:`site-wide action <adminsite-actions>` you can
call :meth:`AdminSite.disable_action()`. call :meth:`AdminSite.disable_action`.
For example, you can use this method to remove the built-in "delete selected For example, you can use this method to remove the built-in "delete selected
objects" action:: objects" action::

View File

@ -154,12 +154,12 @@ application and imports it.
.. class:: apps.AdminConfig .. class:: apps.AdminConfig
This is the default :class:`~django.apps.AppConfig` class for the admin. This is the default :class:`~django.apps.AppConfig` class for the admin.
It calls :func:`~django.contrib.admin.autodiscover()` when Django starts. It calls :func:`~django.contrib.admin.autodiscover` when Django starts.
.. class:: apps.SimpleAdminConfig .. class:: apps.SimpleAdminConfig
This class works like :class:`~django.contrib.admin.apps.AdminConfig`, This class works like :class:`~django.contrib.admin.apps.AdminConfig`,
except it doesn't call :func:`~django.contrib.admin.autodiscover()`. except it doesn't call :func:`~django.contrib.admin.autodiscover`.
.. attribute:: default_site .. attribute:: default_site
@ -3119,7 +3119,7 @@ Hooking ``AdminSite`` instances into your URLconf
The last step in setting up the Django admin is to hook your ``AdminSite`` The last step in setting up the Django admin is to hook your ``AdminSite``
instance into your URLconf. Do this by pointing a given URL at the instance into your URLconf. Do this by pointing a given URL at the
``AdminSite.urls`` method. It is not necessary to use ``AdminSite.urls`` method. It is not necessary to use
:func:`~django.urls.include()`. :func:`~django.urls.include`.
In this example, we register the default ``AdminSite`` instance In this example, we register the default ``AdminSite`` instance
``django.contrib.admin.site`` at the URL ``/admin/`` :: ``django.contrib.admin.site`` at the URL ``/admin/`` ::
@ -3245,10 +3245,10 @@ Adding views to admin sites
--------------------------- ---------------------------
Just like :class:`ModelAdmin`, :class:`AdminSite` provides a Just like :class:`ModelAdmin`, :class:`AdminSite` provides a
:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method :meth:`~django.contrib.admin.ModelAdmin.get_urls` method
that can be overridden to define additional views for the site. To add that can be overridden to define additional views for the site. To add
a new view to your admin site, extend the base a new view to your admin site, extend the base
:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method to include :meth:`~django.contrib.admin.ModelAdmin.get_urls` method to include
a pattern for your new view. a pattern for your new view.
.. note:: .. note::

View File

@ -159,7 +159,7 @@ Methods
When the ``raw_password`` is ``None``, the password will be set to an When the ``raw_password`` is ``None``, the password will be set to an
unusable password, as if unusable password, as if
:meth:`~django.contrib.auth.models.User.set_unusable_password()` :meth:`~django.contrib.auth.models.User.set_unusable_password`
were used. were used.
.. method:: check_password(raw_password) .. method:: check_password(raw_password)
@ -176,7 +176,7 @@ Methods
Marks the user as having no password set by updating the metadata in Marks the user as having no password set by updating the metadata in
the :attr:`~django.contrib.auth.models.User.password` field. This isn't the :attr:`~django.contrib.auth.models.User.password` field. This isn't
the same as having a blank string for a password. the same as having a blank string for a password.
:meth:`~django.contrib.auth.models.User.check_password()` for this user :meth:`~django.contrib.auth.models.User.check_password` for this user
will never return ``True``. Doesn't save the will never return ``True``. Doesn't save the
:class:`~django.contrib.auth.models.User` object. :class:`~django.contrib.auth.models.User` object.
@ -192,7 +192,7 @@ Methods
.. method:: has_usable_password() .. method:: has_usable_password()
Returns ``False`` if Returns ``False`` if
:meth:`~django.contrib.auth.models.User.set_unusable_password()` has :meth:`~django.contrib.auth.models.User.set_unusable_password` has
been called for this user. been called for this user.
.. method:: get_user_permissions(obj=None) .. method:: get_user_permissions(obj=None)
@ -293,7 +293,7 @@ Methods
Sends an email to the user. If ``from_email`` is ``None``, Django uses Sends an email to the user. If ``from_email`` is ``None``, Django uses
the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the
underlying :meth:`~django.core.mail.send_mail()` call. underlying :meth:`~django.core.mail.send_mail` call.
Manager methods Manager methods
--------------- ---------------
@ -319,7 +319,7 @@ Manager methods
:attr:`~django.contrib.auth.models.User.is_active` set to ``True``. :attr:`~django.contrib.auth.models.User.is_active` set to ``True``.
If no password is provided, If no password is provided,
:meth:`~django.contrib.auth.models.User.set_unusable_password()` will :meth:`~django.contrib.auth.models.User.set_unusable_password` will
be called. be called.
If no email is provided, :attr:`~django.contrib.auth.models.User.email` If no email is provided, :attr:`~django.contrib.auth.models.User.email`
@ -380,7 +380,7 @@ Manager methods
* :ref:`id <automatic-primary-key-fields>` is always ``None``. * :ref:`id <automatic-primary-key-fields>` is always ``None``.
* :attr:`~django.contrib.auth.models.User.username` is always the empty * :attr:`~django.contrib.auth.models.User.username` is always the empty
string. string.
* :meth:`~django.contrib.auth.models.User.get_username()` always returns * :meth:`~django.contrib.auth.models.User.get_username` always returns
the empty string. the empty string.
* :attr:`~django.contrib.auth.models.User.is_anonymous` is ``True`` * :attr:`~django.contrib.auth.models.User.is_anonymous` is ``True``
instead of ``False``. instead of ``False``.
@ -393,10 +393,10 @@ Manager methods
* :attr:`~django.contrib.auth.models.User.groups` and * :attr:`~django.contrib.auth.models.User.groups` and
:attr:`~django.contrib.auth.models.User.user_permissions` are always :attr:`~django.contrib.auth.models.User.user_permissions` are always
empty. empty.
* :meth:`~django.contrib.auth.models.User.set_password()`, * :meth:`~django.contrib.auth.models.User.set_password`,
:meth:`~django.contrib.auth.models.User.check_password()`, :meth:`~django.contrib.auth.models.User.check_password`,
:meth:`~django.db.models.Model.save` and :meth:`~django.db.models.Model.save` and
:meth:`~django.db.models.Model.delete()` raise :exc:`NotImplementedError`. :meth:`~django.db.models.Model.delete` raise :exc:`NotImplementedError`.
In practice, you probably won't need to use In practice, you probably won't need to use
:class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but :class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but
@ -524,7 +524,7 @@ can be used for notification when a user logs in or out.
``credentials`` ``credentials``
A dictionary of keyword arguments containing the user credentials that were A dictionary of keyword arguments containing the user credentials that were
passed to :func:`~django.contrib.auth.authenticate()` or your own custom passed to :func:`~django.contrib.auth.authenticate` or your own custom
authentication backend. Credentials matching a set of 'sensitive' patterns, authentication backend. Credentials matching a set of 'sensitive' patterns,
(including password) will not be sent in the clear as part of the signal. (including password) will not be sent in the clear as part of the signal.

View File

@ -220,7 +220,7 @@ The ``ContentTypeManager``
referenced via a :ref:`natural key<topics-serialization-natural-keys>` referenced via a :ref:`natural key<topics-serialization-natural-keys>`
during deserialization. during deserialization.
The :meth:`~ContentTypeManager.get_for_model()` method is especially The :meth:`~ContentTypeManager.get_for_model` method is especially
useful when you know you need to work with a useful when you know you need to work with a
:class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't :class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't
want to go to the trouble of obtaining the model's metadata to perform a manual want to go to the trouble of obtaining the model's metadata to perform a manual

View File

@ -32,7 +32,7 @@ the current statement. This is a complement to
:class:`django.db.models.functions.Now`, which returns the date and time of the :class:`django.db.models.functions.Now`, which returns the date and time of the
current statement. current statement.
Note that only the outermost call to :func:`~django.db.transaction.atomic()` Note that only the outermost call to :func:`~django.db.transaction.atomic`
sets up a transaction and thus sets the time that ``TransactionNow()`` will sets up a transaction and thus sets the time that ``TransactionNow()`` will
return; nested calls create savepoints which do not affect the transaction return; nested calls create savepoints which do not affect the transaction
time. time.

View File

@ -121,7 +121,7 @@ Note:
attributes corresponding to ``<changefreq>`` and ``<priority>`` elements, attributes corresponding to ``<changefreq>`` and ``<priority>`` elements,
respectively. They can be made callable as functions, as respectively. They can be made callable as functions, as
:attr:`~Sitemap.lastmod` was in the example. :attr:`~Sitemap.lastmod` was in the example.
* :attr:`~Sitemap.items()` is a method that returns a :term:`sequence` or * :attr:`~Sitemap.items` is a method that returns a :term:`sequence` or
``QuerySet`` of objects. The objects returned will get passed to any callable ``QuerySet`` of objects. The objects returned will get passed to any callable
methods corresponding to a sitemap property (:attr:`~Sitemap.location`, methods corresponding to a sitemap property (:attr:`~Sitemap.location`,
:attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and
@ -129,7 +129,7 @@ Note:
* :attr:`~Sitemap.lastmod` should return a :class:`~datetime.datetime`. * :attr:`~Sitemap.lastmod` should return a :class:`~datetime.datetime`.
* There is no :attr:`~Sitemap.location` method in this example, but you * There is no :attr:`~Sitemap.location` method in this example, but you
can provide it in order to specify the URL for your object. By default, can provide it in order to specify the URL for your object. By default,
:attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object :attr:`~Sitemap.location` calls ``get_absolute_url()`` on each object
and returns the result. and returns the result.
``Sitemap`` class reference ``Sitemap`` class reference
@ -144,19 +144,19 @@ Note:
**Required.** A method that returns a :term:`sequence` or ``QuerySet`` **Required.** A method that returns a :term:`sequence` or ``QuerySet``
of objects. The framework doesn't care what *type* of objects they are; of objects. The framework doesn't care what *type* of objects they are;
all that matters is that these objects get passed to the all that matters is that these objects get passed to the
:attr:`~Sitemap.location()`, :attr:`~Sitemap.lastmod()`, :attr:`~Sitemap.location`, :attr:`~Sitemap.lastmod`,
:attr:`~Sitemap.changefreq()` and :attr:`~Sitemap.priority()` methods. :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` methods.
.. attribute:: Sitemap.location .. attribute:: Sitemap.location
**Optional.** Either a method or attribute. **Optional.** Either a method or attribute.
If it's a method, it should return the absolute path for a given object If it's a method, it should return the absolute path for a given object
as returned by :attr:`~Sitemap.items()`. as returned by :attr:`~Sitemap.items`.
If it's an attribute, its value should be a string representing an If it's an attribute, its value should be a string representing an
absolute path to use for *every* object returned by absolute path to use for *every* object returned by
:attr:`~Sitemap.items()`. :attr:`~Sitemap.items`.
In both cases, "absolute path" means a URL that doesn't include the In both cases, "absolute path" means a URL that doesn't include the
protocol or domain. Examples: protocol or domain. Examples:
@ -167,7 +167,7 @@ Note:
If :attr:`~Sitemap.location` isn't provided, the framework will call If :attr:`~Sitemap.location` isn't provided, the framework will call
the ``get_absolute_url()`` method on each object as returned by the ``get_absolute_url()`` method on each object as returned by
:attr:`~Sitemap.items()`. :attr:`~Sitemap.items`.
To specify a protocol other than ``'http'``, use To specify a protocol other than ``'http'``, use
:attr:`~Sitemap.protocol`. :attr:`~Sitemap.protocol`.
@ -177,12 +177,12 @@ Note:
**Optional.** Either a method or attribute. **Optional.** Either a method or attribute.
If it's a method, it should take one argument -- an object as returned If it's a method, it should take one argument -- an object as returned
by :attr:`~Sitemap.items()` -- and return that object's last-modified by :attr:`~Sitemap.items` -- and return that object's last-modified
date/time as a :class:`~datetime.datetime`. date/time as a :class:`~datetime.datetime`.
If it's an attribute, its value should be a :class:`~datetime.datetime` If it's an attribute, its value should be a :class:`~datetime.datetime`
representing the last-modified date/time for *every* object returned by representing the last-modified date/time for *every* object returned by
:attr:`~Sitemap.items()`. :attr:`~Sitemap.items`.
If all items in a sitemap have a :attr:`~Sitemap.lastmod`, the sitemap If all items in a sitemap have a :attr:`~Sitemap.lastmod`, the sitemap
generated by :func:`views.sitemap` will have a ``Last-Modified`` generated by :func:`views.sitemap` will have a ``Last-Modified``
@ -196,7 +196,7 @@ Note:
**Optional.** **Optional.**
This property returns a :class:`~django.core.paginator.Paginator` for This property returns a :class:`~django.core.paginator.Paginator` for
:attr:`~Sitemap.items()`. If you generate sitemaps in a batch you may :attr:`~Sitemap.items`. If you generate sitemaps in a batch you may
want to override this as a cached property in order to avoid multiple want to override this as a cached property in order to avoid multiple
``items()`` calls. ``items()`` calls.
@ -205,11 +205,11 @@ Note:
**Optional.** Either a method or attribute. **Optional.** Either a method or attribute.
If it's a method, it should take one argument -- an object as returned If it's a method, it should take one argument -- an object as returned
by :attr:`~Sitemap.items()` -- and return that object's change by :attr:`~Sitemap.items` -- and return that object's change
frequency as a string. frequency as a string.
If it's an attribute, its value should be a string representing the If it's an attribute, its value should be a string representing the
change frequency of *every* object returned by :attr:`~Sitemap.items()`. change frequency of *every* object returned by :attr:`~Sitemap.items`.
Possible values for :attr:`~Sitemap.changefreq`, whether you use a Possible values for :attr:`~Sitemap.changefreq`, whether you use a
method or attribute, are: method or attribute, are:
@ -227,12 +227,12 @@ Note:
**Optional.** Either a method or attribute. **Optional.** Either a method or attribute.
If it's a method, it should take one argument -- an object as returned If it's a method, it should take one argument -- an object as returned
by :attr:`~Sitemap.items()` -- and return that object's priority as by :attr:`~Sitemap.items` -- and return that object's priority as
either a string or float. either a string or float.
If it's an attribute, its value should be either a string or float If it's an attribute, its value should be either a string or float
representing the priority of *every* object returned by representing the priority of *every* object returned by
:attr:`~Sitemap.items()`. :attr:`~Sitemap.items`.
Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The
default priority of a page is ``0.5``. See the `sitemaps.org default priority of a page is ``0.5``. See the `sitemaps.org
@ -554,7 +554,7 @@ URL. Each alternate is a dictionary with ``location`` and ``lang_code`` keys.
The ``item`` attribute has been added for each URL to allow more flexible The ``item`` attribute has been added for each URL to allow more flexible
customization of the templates, such as `Google news sitemaps`_. Assuming customization of the templates, such as `Google news sitemaps`_. Assuming
Sitemap's :attr:`~Sitemap.items()` would return a list of items with Sitemap's :attr:`~Sitemap.items` would return a list of items with
``publication_data`` and a ``tags`` field something like this would ``publication_data`` and a ``tags`` field something like this would
generate a Google News compatible sitemap: generate a Google News compatible sitemap:

View File

@ -485,7 +485,7 @@ a fallback when the database-backed sites framework is not available.
A :class:`~django.contrib.sites.requests.RequestSite` object has a similar A :class:`~django.contrib.sites.requests.RequestSite` object has a similar
interface to a normal :class:`~django.contrib.sites.models.Site` object, interface to a normal :class:`~django.contrib.sites.models.Site` object,
except its :meth:`~django.contrib.sites.requests.RequestSite.__init__()` except its :meth:`~django.contrib.sites.requests.RequestSite.__init__`
method takes an :class:`~django.http.HttpRequest` object. It's able to deduce method takes an :class:`~django.http.HttpRequest` object. It's able to deduce
the ``domain`` and ``name`` by looking at the request's domain. It has the ``domain`` and ``name`` by looking at the request's domain. It has
``save()`` and ``delete()`` methods to match the interface of ``save()`` and ``delete()`` methods to match the interface of

View File

@ -311,7 +311,7 @@ Language
Feeds created by the syndication framework automatically include the Feeds created by the syndication framework automatically include the
appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). By appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). By
default, this is :func:`django.utils.translation.get_language()`. You can change it default, this is :func:`django.utils.translation.get_language`. You can change it
by setting the ``language`` class attribute. by setting the ``language`` class attribute.
URLs URLs

View File

@ -1051,12 +1051,12 @@ together:
.. django-admin-option:: --managers .. django-admin-option:: --managers
Mails the email addresses specified in :setting:`MANAGERS` using Mails the email addresses specified in :setting:`MANAGERS` using
:meth:`~django.core.mail.mail_managers()`. :meth:`~django.core.mail.mail_managers`.
.. django-admin-option:: --admins .. django-admin-option:: --admins
Mails the email addresses specified in :setting:`ADMINS` using Mails the email addresses specified in :setting:`ADMINS` using
:meth:`~django.core.mail.mail_admins()`. :meth:`~django.core.mail.mail_admins`.
``shell`` ``shell``
--------- ---------
@ -1524,7 +1524,7 @@ Runs tests in separate parallel processes. Since modern processors have
multiple cores, this allows running tests significantly faster. multiple cores, this allows running tests significantly faster.
Using ``--parallel`` without a value, or with the value ``auto``, runs one test Using ``--parallel`` without a value, or with the value ``auto``, runs one test
process per core according to :func:`multiprocessing.cpu_count()`. You can process per core according to :func:`multiprocessing.cpu_count`. You can
override this by passing the desired number of processes, e.g. override this by passing the desired number of processes, e.g.
``--parallel 4``, or by setting the :envvar:`DJANGO_TEST_PROCESSES` environment ``--parallel 4``, or by setting the :envvar:`DJANGO_TEST_PROCESSES` environment
variable. variable.
@ -1597,7 +1597,7 @@ as :option:`unittest's --buffer option<unittest.-b>`.
.. django-admin-option:: --no-faulthandler .. django-admin-option:: --no-faulthandler
Django automatically calls :func:`faulthandler.enable()` when starting the Django automatically calls :func:`faulthandler.enable` when starting the
tests, which allows it to print a traceback if the interpreter crashes. Pass tests, which allows it to print a traceback if the interpreter crashes. Pass
``--no-faulthandler`` to disable this behavior. ``--no-faulthandler`` to disable this behavior.

View File

@ -31,7 +31,7 @@ Django core exception classes are defined in ``django.core.exceptions``.
``ObjectDoesNotExist`` will catch ``ObjectDoesNotExist`` will catch
:exc:`~django.db.models.Model.DoesNotExist` exceptions for all models. :exc:`~django.db.models.Model.DoesNotExist` exceptions for all models.
See :meth:`~django.db.models.query.QuerySet.get()`. See :meth:`~django.db.models.query.QuerySet.get`.
``ObjectNotUpdated`` ``ObjectNotUpdated``
-------------------- --------------------
@ -45,7 +45,7 @@ Django core exception classes are defined in ``django.core.exceptions``.
``ObjectNotUpdated`` will catch ``ObjectNotUpdated`` will catch
:exc:`~django.db.models.Model.NotUpdated` exceptions for all models. :exc:`~django.db.models.Model.NotUpdated` exceptions for all models.
See :meth:`~django.db.models.Model.save()`. See :meth:`~django.db.models.Model.save`.
``EmptyResultSet`` ``EmptyResultSet``
------------------ ------------------
@ -85,7 +85,7 @@ Django core exception classes are defined in ``django.core.exceptions``.
:exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all :exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all
models. models.
See :meth:`~django.db.models.query.QuerySet.get()`. See :meth:`~django.db.models.query.QuerySet.get`.
``SuspiciousOperation`` ``SuspiciousOperation``
----------------------- -----------------------
@ -239,7 +239,7 @@ URL Resolver exceptions are defined in ``django.urls``.
.. exception:: Resolver404 .. exception:: Resolver404
The :exc:`Resolver404` exception is raised by The :exc:`Resolver404` exception is raised by
:func:`~django.urls.resolve()` if the path passed to ``resolve()`` doesn't :func:`~django.urls.resolve` if the path passed to ``resolve()`` doesn't
map to a view. It's a subclass of :class:`django.http.Http404`. map to a view. It's a subclass of :class:`django.http.Http404`.
``NoReverseMatch`` ``NoReverseMatch``

View File

@ -50,7 +50,7 @@ The ``File`` class
Open or reopen the file (which also does ``File.seek(0)``). Open or reopen the file (which also does ``File.seek(0)``).
The ``mode`` argument allows the same values The ``mode`` argument allows the same values
as Python's built-in :func:`python:open()`. ``*args`` and ``**kwargs`` as Python's built-in :func:`python:open`. ``*args`` and ``**kwargs``
are passed after ``mode`` to Python's built-in :func:`python:open`. are passed after ``mode`` to Python's built-in :func:`python:open`.
When reopening a file, ``mode`` will override whatever mode the file When reopening a file, ``mode`` will override whatever mode the file

View File

@ -201,12 +201,12 @@ The ``Storage`` class
.. method:: generate_filename(filename) .. method:: generate_filename(filename)
Validates the ``filename`` by calling :attr:`get_valid_name()` and Validates the ``filename`` by calling :attr:`get_valid_name` and
returns a filename to be passed to the :meth:`save` method. returns a filename to be passed to the :meth:`save` method.
The ``filename`` argument may include a path as returned by The ``filename`` argument may include a path as returned by
:attr:`FileField.upload_to <django.db.models.FileField.upload_to>`. :attr:`FileField.upload_to <django.db.models.FileField.upload_to>`.
In that case, the path won't be passed to :attr:`get_valid_name()` but In that case, the path won't be passed to :attr:`get_valid_name` but
will be prepended back to the resulting name. will be prepended back to the resulting name.
The default implementation uses :mod:`os.path` operations. Override The default implementation uses :mod:`os.path` operations. Override

View File

@ -157,7 +157,7 @@ instances.
Use this method anytime you need to identify an error by its ``code``. This Use this method anytime you need to identify an error by its ``code``. This
enables things like rewriting the error's message or writing custom logic in a enables things like rewriting the error's message or writing custom logic in a
view when a given error is present. It can also be used to serialize the errors view when a given error is present. It can also be used to serialize the errors
in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json()` in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json`
relies on ``as_data()``. relies on ``as_data()``.
The need for the ``as_data()`` method is due to backwards compatibility. The need for the ``as_data()`` method is due to backwards compatibility.
@ -193,11 +193,11 @@ directly in HTML.
.. method:: Form.errors.get_json_data(escape_html=False) .. method:: Form.errors.get_json_data(escape_html=False)
Returns the errors as a dictionary suitable for serializing to JSON. Returns the errors as a dictionary suitable for serializing to JSON.
:meth:`Form.errors.as_json()` returns serialized JSON, while this returns the :meth:`Form.errors.as_json` returns serialized JSON, while this returns the
error data before it's serialized. error data before it's serialized.
The ``escape_html`` parameter behaves as described in The ``escape_html`` parameter behaves as described in
:meth:`Form.errors.as_json()`. :meth:`Form.errors.as_json`.
.. method:: Form.add_error(field, error) .. method:: Form.add_error(field, error)
@ -298,8 +298,8 @@ Returns the initial data for a form field. It retrieves the data from
Callable values are evaluated. Callable values are evaluated.
It is recommended to use :attr:`BoundField.initial` over It is recommended to use :attr:`BoundField.initial` over
:meth:`~Form.get_initial_for_field()` because ``BoundField.initial`` has a :meth:`~Form.get_initial_for_field` because ``BoundField.initial`` has a
simpler interface. Also, unlike :meth:`~Form.get_initial_for_field()`, simpler interface. Also, unlike :meth:`~Form.get_initial_for_field`,
:attr:`BoundField.initial` caches its values. This is useful especially when :attr:`BoundField.initial` caches its values. This is useful especially when
dealing with callables whose return values can change (e.g. ``datetime.now`` or dealing with callables whose return values can change (e.g. ``datetime.now`` or
``uuid.uuid4``): ``uuid.uuid4``):
@ -1315,7 +1315,7 @@ Attributes of ``BoundField``
datetime.datetime(2021, 7, 27, 9, 5, 54) datetime.datetime(2021, 7, 27, 9, 5, 54)
Using :attr:`BoundField.initial` is recommended over Using :attr:`BoundField.initial` is recommended over
:meth:`~Form.get_initial_for_field()`. :meth:`~Form.get_initial_for_field`.
.. attribute:: BoundField.is_hidden .. attribute:: BoundField.is_hidden
@ -1517,7 +1517,7 @@ If not defined as a class variable, ``bound_field_class`` can be set via the
constructor. constructor.
For compatibility reasons, a custom form field can still override For compatibility reasons, a custom form field can still override
:meth:`.Field.get_bound_field()` to use a custom class, though any of the :meth:`.Field.get_bound_field` to use a custom class, though any of the
previous options are preferred. previous options are preferred.
You may want to use a custom :class:`.BoundField` if you need to access some You may want to use a custom :class:`.BoundField` if you need to access some

View File

@ -414,7 +414,7 @@ Checking if the field data has changed
The ``has_changed()`` method is used to determine if the field value has changed The ``has_changed()`` method is used to determine if the field value has changed
from the initial value. Returns ``True`` or ``False``. from the initial value. Returns ``True`` or ``False``.
See the :class:`Form.has_changed()` documentation for more information. See the :class:`Form.has_changed` documentation for more information.
.. _built-in-fields: .. _built-in-fields:
@ -1631,7 +1631,7 @@ only requirements are that it implement a ``clean()`` method and that its
You can also customize how a field will be accessed by overriding You can also customize how a field will be accessed by overriding
:attr:`~django.forms.Field.bound_field_class` or override :attr:`~django.forms.Field.bound_field_class` or override
:meth:`.Field.get_bound_field()` if you need more flexibility when creating :meth:`.Field.get_bound_field` if you need more flexibility when creating
the ``BoundField``: the ``BoundField``:
.. method:: Field.get_bound_field(form, field_name) .. method:: Field.get_bound_field(form, field_name)

View File

@ -83,12 +83,12 @@ overridden:
called, you also have access to the form's ``errors`` attribute which called, you also have access to the form's ``errors`` attribute which
contains all the errors raised by cleaning of individual fields. contains all the errors raised by cleaning of individual fields.
Note that any errors raised by your :meth:`Form.clean()` override will not Note that any errors raised by your :meth:`Form.clean` override will not
be associated with any field in particular. They go into a special be associated with any field in particular. They go into a special
"field" (called ``__all__``), which you can access via the "field" (called ``__all__``), which you can access via the
:meth:`~django.forms.Form.non_field_errors` method if you need to. If you :meth:`~django.forms.Form.non_field_errors` method if you need to. If you
want to attach errors to a specific field in the form, you need to call want to attach errors to a specific field in the form, you need to call
:meth:`~django.forms.Form.add_error()`. :meth:`~django.forms.Form.add_error`.
Also note that there are special considerations when overriding Also note that there are special considerations when overriding
the ``clean()`` method of a ``ModelForm`` subclass. (see the the ``clean()`` method of a ``ModelForm`` subclass. (see the
@ -99,7 +99,7 @@ These methods are run in the order given above, one field at a time. That is,
for each field in the form (in the order they are declared in the form for each field in the form (in the order they are declared in the form
definition), the ``Field.clean()`` method (or its override) is run, then definition), the ``Field.clean()`` method (or its override) is run, then
``clean_<fieldname>()``. Finally, once those two methods are run for every ``clean_<fieldname>()``. Finally, once those two methods are run for every
field, the :meth:`Form.clean()` method, or its override, is executed whether field, the :meth:`Form.clean` method, or its override, is executed whether
or not the previous methods have raised errors. or not the previous methods have raised errors.
Examples of each of these methods are provided below. Examples of each of these methods are provided below.
@ -335,7 +335,7 @@ Cleaning and validating fields that depend on each other
Suppose we add another requirement to our contact form: if the ``cc_myself`` Suppose we add another requirement to our contact form: if the ``cc_myself``
field is ``True``, the ``subject`` must contain the word ``"help"``. We are field is ``True``, the ``subject`` must contain the word ``"help"``. We are
performing validation on more than one field at a time, so the form's performing validation on more than one field at a time, so the form's
:meth:`~Form.clean()` method is a good spot to do this. Notice that we are :meth:`~Form.clean` method is a good spot to do this. Notice that we are
talking about the ``clean()`` method on the form here, whereas earlier we were talking about the ``clean()`` method on the form here, whereas earlier we were
writing a ``clean()`` method on a field. It's important to keep the field and writing a ``clean()`` method on a field. It's important to keep the field and
form difference clear when working out where to validate things. Fields are form difference clear when working out where to validate things. Fields are

View File

@ -226,7 +226,7 @@ foundation for custom widgets.
This abstract class cannot be rendered, but provides the basic attribute This abstract class cannot be rendered, but provides the basic attribute
:attr:`~Widget.attrs`. You may also implement or override the :attr:`~Widget.attrs`. You may also implement or override the
:meth:`~Widget.render()` method on custom widgets. :meth:`~Widget.render` method on custom widgets.
.. attribute:: Widget.attrs .. attribute:: Widget.attrs

View File

@ -137,7 +137,7 @@ If the response has an ``ETag`` header, the ETag is made weak to comply with
:rfc:`9110#section-8.8.1`. :rfc:`9110#section-8.8.1`.
You can apply GZip compression to individual views using the You can apply GZip compression to individual views using the
:func:`~django.views.decorators.gzip.gzip_page()` decorator. :func:`~django.views.decorators.gzip.gzip_page` decorator.
Conditional GET middleware Conditional GET middleware
-------------------------- --------------------------
@ -154,7 +154,7 @@ header, the middleware adds one if needed. If the response has an ``ETag`` or
:class:`~django.http.HttpResponseNotModified`. :class:`~django.http.HttpResponseNotModified`.
You can handle conditional GET operations with individual views using the You can handle conditional GET operations with individual views using the
:func:`~django.views.decorators.http.conditional_page()` decorator. :func:`~django.views.decorators.http.conditional_page` decorator.
Locale middleware Locale middleware
----------------- -----------------
@ -596,7 +596,7 @@ fields to POST forms and checking requests for the correct value. See the
:doc:`Cross Site Request Forgery protection documentation </ref/csrf>`. :doc:`Cross Site Request Forgery protection documentation </ref/csrf>`.
You can add Cross Site Request Forgery protection to individual views using the You can add Cross Site Request Forgery protection to individual views using the
:func:`~django.views.decorators.csrf.csrf_protect()` decorator. :func:`~django.views.decorators.csrf.csrf_protect` decorator.
``X-Frame-Options`` middleware ``X-Frame-Options`` middleware
------------------------------ ------------------------------

View File

@ -166,12 +166,12 @@ To access the new value saved this way, the object must be reloaded::
As well as being used in operations on single instances as above, ``F()`` can As well as being used in operations on single instances as above, ``F()`` can
be used with ``update()`` to perform bulk updates on a ``QuerySet``. This be used with ``update()`` to perform bulk updates on a ``QuerySet``. This
reduces the two queries we were using above - the ``get()`` and the reduces the two queries we were using above - the ``get()`` and the
:meth:`~Model.save()` - to just one:: :meth:`~Model.save` - to just one::
reporter = Reporters.objects.filter(name="Tintin") reporter = Reporters.objects.filter(name="Tintin")
reporter.update(stories_filed=F("stories_filed") + 1) reporter.update(stories_filed=F("stories_filed") + 1)
We can also use :meth:`~django.db.models.query.QuerySet.update()` to increment We can also use :meth:`~django.db.models.query.QuerySet.update` to increment
the field value on multiple objects - which could be very much faster than the field value on multiple objects - which could be very much faster than
pulling them all into Python from the database, looping over them, incrementing pulling them all into Python from the database, looping over them, incrementing
the field value of each one, and saving each one back to the database:: the field value of each one, and saving each one back to the database::
@ -218,14 +218,14 @@ based on the original value; the work of the first thread will be lost.
If the database is responsible for updating the field, the process is more If the database is responsible for updating the field, the process is more
robust: it will only ever update the field based on the value of the field in robust: it will only ever update the field based on the value of the field in
the database when the :meth:`~Model.save()` or ``update()`` is executed, rather the database when the :meth:`~Model.save` or ``update()`` is executed, rather
than based on its value when the instance was retrieved. than based on its value when the instance was retrieved.
``F()`` assignments persist after ``Model.save()`` ``F()`` assignments persist after ``Model.save()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``F()`` objects assigned to model fields persist after saving the model ``F()`` objects assigned to model fields persist after saving the model
instance and will be applied on each :meth:`~Model.save()`. For example:: instance and will be applied on each :meth:`~Model.save`. For example::
reporter = Reporters.objects.get(name="Tintin") reporter = Reporters.objects.get(name="Tintin")
reporter.stories_filed = F("stories_filed") + 1 reporter.stories_filed = F("stories_filed") + 1
@ -237,7 +237,7 @@ instance and will be applied on each :meth:`~Model.save()`. For example::
``stories_filed`` will be updated twice in this case. If it's initially ``1``, ``stories_filed`` will be updated twice in this case. If it's initially ``1``,
the final value will be ``3``. This persistence can be avoided by reloading the the final value will be ``3``. This persistence can be avoided by reloading the
model object after saving it, for example, by using model object after saving it, for example, by using
:meth:`~Model.refresh_from_db()`. :meth:`~Model.refresh_from_db`.
Using ``F()`` in filters Using ``F()`` in filters
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
@ -1199,7 +1199,7 @@ calling the appropriate methods on the wrapped expression.
implementing ``NULLS LAST`` would change its value to be implementing ``NULLS LAST`` would change its value to be
``NULLS FIRST``. Modifications are only required for expressions that ``NULLS FIRST``. Modifications are only required for expressions that
implement sort order like ``OrderBy``. This method is called when implement sort order like ``OrderBy``. This method is called when
:meth:`~django.db.models.query.QuerySet.reverse()` is called on a :meth:`~django.db.models.query.QuerySet.reverse` is called on a
queryset. queryset.
.. _writing-your-own-query-expressions: .. _writing-your-own-query-expressions:

View File

@ -292,7 +292,7 @@ modifications:
These property names cannot be used as member names as they would conflict. These property names cannot be used as member names as they would conflict.
* The use of :func:`enum.unique()` is enforced to ensure that values cannot be * The use of :func:`enum.unique` is enforced to ensure that values cannot be
defined multiple times. This is unlikely to be expected in choices for a defined multiple times. This is unlikely to be expected in choices for a
field. field.
@ -603,11 +603,11 @@ portion of the field will be considered. Besides, when :setting:`USE_TZ` is
``True``, the check will be performed in the :ref:`current time zone ``True``, the check will be performed in the :ref:`current time zone
<default-current-time-zone>` at the time the object gets saved. <default-current-time-zone>` at the time the object gets saved.
This is enforced by :meth:`Model.validate_unique()` during model validation This is enforced by :meth:`Model.validate_unique` during model validation
but not at the database level. If any :attr:`~Field.unique_for_date` constraint but not at the database level. If any :attr:`~Field.unique_for_date` constraint
involves fields that are not part of a :class:`~django.forms.ModelForm` (for involves fields that are not part of a :class:`~django.forms.ModelForm` (for
example, if one of the fields is listed in ``exclude`` or has example, if one of the fields is listed in ``exclude`` or has
:attr:`editable=False<Field.editable>`), :meth:`Model.validate_unique()` will :attr:`editable=False<Field.editable>`), :meth:`Model.validate_unique` will
skip validation for that particular constraint. skip validation for that particular constraint.
``unique_for_month`` ``unique_for_month``
@ -1316,8 +1316,8 @@ materialized view.
.. admonition:: Refresh the data .. admonition:: Refresh the data
Since the database computes the value, the object must be reloaded to Since the database computes the value, the object must be reloaded to
access the new value after :meth:`~Model.save()`, for example, by using access the new value after :meth:`~Model.save`, for example, by using
:meth:`~Model.refresh_from_db()`. :meth:`~Model.refresh_from_db`.
.. admonition:: Database limitations .. admonition:: Database limitations
@ -1796,7 +1796,7 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in
* .. function:: SET() * .. function:: SET()
Set the :class:`ForeignKey` to the value passed to Set the :class:`ForeignKey` to the value passed to
:func:`~django.db.models.SET()`, or if a callable is passed in, :func:`~django.db.models.SET`, or if a callable is passed in,
the result of calling it. In most cases, passing a callable will be the result of calling it. In most cases, passing a callable will be
necessary to avoid executing queries at the time your ``models.py`` is necessary to avoid executing queries at the time your ``models.py`` is
imported:: imported::

View File

@ -23,7 +23,7 @@ class:
The keyword arguments are the names of the fields you've defined on your model. The keyword arguments are the names of the fields you've defined on your model.
Note that instantiating a model in no way touches your database; for that, you Note that instantiating a model in no way touches your database; for that, you
need to :meth:`~Model.save()`. need to :meth:`~Model.save`.
.. note:: .. note::
@ -226,27 +226,27 @@ Validating objects
There are four steps involved in validating a model: There are four steps involved in validating a model:
1. Validate the model fields - :meth:`Model.clean_fields()` 1. Validate the model fields - :meth:`Model.clean_fields`
2. Validate the model as a whole - :meth:`Model.clean()` 2. Validate the model as a whole - :meth:`Model.clean`
3. Validate the field uniqueness - :meth:`Model.validate_unique()` 3. Validate the field uniqueness - :meth:`Model.validate_unique`
4. Validate the constraints - :meth:`Model.validate_constraints` 4. Validate the constraints - :meth:`Model.validate_constraints`
All four steps are performed when you call a model's :meth:`~Model.full_clean` All four steps are performed when you call a model's :meth:`~Model.full_clean`
method. method.
When you use a :class:`~django.forms.ModelForm`, the call to When you use a :class:`~django.forms.ModelForm`, the call to
:meth:`~django.forms.Form.is_valid()` will perform these validation steps for :meth:`~django.forms.Form.is_valid` will perform these validation steps for
all the fields that are included on the form. See the :doc:`ModelForm all the fields that are included on the form. See the :doc:`ModelForm
documentation </topics/forms/modelforms>` for more information. You should only documentation </topics/forms/modelforms>` for more information. You should only
need to call a model's :meth:`~Model.full_clean()` method if you plan to handle need to call a model's :meth:`~Model.full_clean` method if you plan to handle
validation errors yourself, or if you have excluded fields from the validation errors yourself, or if you have excluded fields from the
:class:`~django.forms.ModelForm` that require validation. :class:`~django.forms.ModelForm` that require validation.
.. method:: Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True) .. method:: Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True)
This method calls :meth:`Model.clean_fields()`, :meth:`Model.clean()`, This method calls :meth:`Model.clean_fields`, :meth:`Model.clean`,
:meth:`Model.validate_unique()` (if ``validate_unique`` is ``True``), and :meth:`Model.validate_unique` (if ``validate_unique`` is ``True``), and
:meth:`Model.validate_constraints()` (if ``validate_constraints`` is ``True``) :meth:`Model.validate_constraints` (if ``validate_constraints`` is ``True``)
in that order and raises a :exc:`~django.core.exceptions.ValidationError` that in that order and raises a :exc:`~django.core.exceptions.ValidationError` that
has a ``message_dict`` attribute containing errors from all four stages. has a ``message_dict`` attribute containing errors from all four stages.
@ -257,7 +257,7 @@ aren't present on your form from being validated since any errors raised could
not be corrected by the user. not be corrected by the user.
Note that ``full_clean()`` will *not* be called automatically when you call Note that ``full_clean()`` will *not* be called automatically when you call
your model's :meth:`~Model.save()` method. You'll need to call it manually your model's :meth:`~Model.save` method. You'll need to call it manually
when you want to run one-step model validation for your own manually created when you want to run one-step model validation for your own manually created
models. For example:: models. For example::
@ -279,7 +279,7 @@ argument lets you provide a ``set`` of field names to exclude from validation.
It will raise a :exc:`~django.core.exceptions.ValidationError` if any fields It will raise a :exc:`~django.core.exceptions.ValidationError` if any fields
fail validation. fail validation.
The second step ``full_clean()`` performs is to call :meth:`Model.clean()`. The second step ``full_clean()`` performs is to call :meth:`Model.clean`.
This method should be overridden to perform custom validation on your model. This method should be overridden to perform custom validation on your model.
.. method:: Model.clean() .. method:: Model.clean()
@ -306,8 +306,8 @@ access to more than a single field::
if self.status == "published" and self.pub_date is None: if self.status == "published" and self.pub_date is None:
self.pub_date = datetime.date.today() self.pub_date = datetime.date.today()
Note, however, that like :meth:`Model.full_clean()`, a model's ``clean()`` Note, however, that like :meth:`Model.full_clean`, a model's ``clean()``
method is not invoked when you call your model's :meth:`~Model.save()` method. method is not invoked when you call your model's :meth:`~Model.save` method.
In the above example, the :exc:`~django.core.exceptions.ValidationError` In the above example, the :exc:`~django.core.exceptions.ValidationError`
exception raised by ``Model.clean()`` was instantiated with a string, so it exception raised by ``Model.clean()`` was instantiated with a string, so it
@ -582,10 +582,10 @@ Forcing an INSERT or UPDATE
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some rare circumstances, it's necessary to be able to force the In some rare circumstances, it's necessary to be able to force the
:meth:`~Model.save()` method to perform an SQL ``INSERT`` and not fall back to :meth:`~Model.save` method to perform an SQL ``INSERT`` and not fall back to
doing an ``UPDATE``. Or vice-versa: update, if possible, but not insert a new doing an ``UPDATE``. Or vice-versa: update, if possible, but not insert a new
row. In these cases you can pass the ``force_insert=True`` or row. In these cases you can pass the ``force_insert=True`` or
``force_update=True`` parameters to the :meth:`~Model.save()` method. ``force_update=True`` parameters to the :meth:`~Model.save` method.
Passing both parameters is an error: you cannot both insert *and* update at the Passing both parameters is an error: you cannot both insert *and* update at the
same time! same time!
@ -672,8 +672,8 @@ perform an update on all fields.
Specifying ``update_fields`` will force an update. Specifying ``update_fields`` will force an update.
When saving a model fetched through deferred model loading When saving a model fetched through deferred model loading
(:meth:`~django.db.models.query.QuerySet.only()` or (:meth:`~django.db.models.query.QuerySet.only` or
:meth:`~django.db.models.query.QuerySet.defer()`) only the fields loaded :meth:`~django.db.models.query.QuerySet.defer`) only the fields loaded
from the DB will get updated. In effect there is an automatic from the DB will get updated. In effect there is an automatic
``update_fields`` in this case. If you assign or change any deferred field ``update_fields`` in this case. If you assign or change any deferred field
value, the field will be added to the updated fields. value, the field will be added to the updated fields.
@ -894,7 +894,7 @@ track down every place that the URL might be created. Specify it once, in
Extra instance methods Extra instance methods
====================== ======================
In addition to :meth:`~Model.save()`, :meth:`~Model.delete()`, a model object In addition to :meth:`~Model.save`, :meth:`~Model.delete`, a model object
might have some of the following methods: might have some of the following methods:
.. method:: Model.get_FOO_display() .. method:: Model.get_FOO_display()

View File

@ -382,7 +382,7 @@ not be looking at your Django code. For example::
.. attribute:: Options.select_on_save .. attribute:: Options.select_on_save
Determines if Django will use the pre-1.6 Determines if Django will use the pre-1.6
:meth:`django.db.models.Model.save()` algorithm. The old algorithm :meth:`django.db.models.Model.save` algorithm. The old algorithm
uses ``SELECT`` to determine if there is an existing row to be updated. uses ``SELECT`` to determine if there is an existing row to be updated.
The new algorithm tries an ``UPDATE`` directly. In some rare cases the The new algorithm tries an ``UPDATE`` directly. In some rare cases the
``UPDATE`` of an existing row isn't visible to Django. An example is the ``UPDATE`` of an existing row isn't visible to Django. An example is the
@ -393,7 +393,7 @@ not be looking at your Django code. For example::
Usually there is no need to set this attribute. The default is Usually there is no need to set this attribute. The default is
``False``. ``False``.
See :meth:`django.db.models.Model.save()` for more about the old and See :meth:`django.db.models.Model.save` for more about the old and
new saving algorithm. new saving algorithm.
``indexes`` ``indexes``

View File

@ -166,7 +166,7 @@ Here's the formal declaration of a ``QuerySet``:
.. attribute:: ordered .. attribute:: ordered
``True`` if the ``QuerySet`` is ordered — i.e. has an ``True`` if the ``QuerySet`` is ordered — i.e. has an
:meth:`order_by()` clause or a default ordering on the model. :meth:`order_by` clause or a default ordering on the model.
``False`` otherwise. ``False`` otherwise.
.. attribute:: db .. attribute:: db
@ -401,7 +401,7 @@ expression::
(``nulls_first`` and ``nulls_last``) that control how null values are sorted. (``nulls_first`` and ``nulls_last``) that control how null values are sorted.
Be cautious when ordering by fields in related models if you are also using Be cautious when ordering by fields in related models if you are also using
:meth:`distinct()`. See the note in :meth:`distinct` for an explanation of how :meth:`distinct`. See the note in :meth:`distinct` for an explanation of how
related model ordering can change the expected results. related model ordering can change the expected results.
.. note:: .. note::
@ -445,7 +445,7 @@ ordering::
Entry.objects.order_by(Lower("headline").desc()) Entry.objects.order_by(Lower("headline").desc())
If you don't want any ordering to be applied to a query, not even the default If you don't want any ordering to be applied to a query, not even the default
ordering, call :meth:`order_by()` with no parameters. ordering, call :meth:`order_by` with no parameters.
You can tell if a query is ordered or not by checking the You can tell if a query is ordered or not by checking the
:attr:`.QuerySet.ordered` attribute, which will be ``True`` if the :attr:`.QuerySet.ordered` attribute, which will be ``True`` if the
@ -490,7 +490,7 @@ efficiently in SQL.
Also, note that ``reverse()`` should generally only be called on a ``QuerySet`` Also, note that ``reverse()`` should generally only be called on a ``QuerySet``
which has a defined ordering (e.g., when querying against a model which defines which has a defined ordering (e.g., when querying against a model which defines
a default ordering, or when using :meth:`order_by()`). If no such ordering is a default ordering, or when using :meth:`order_by`). If no such ordering is
defined for a given ``QuerySet``, calling ``reverse()`` on it has no real defined for a given ``QuerySet``, calling ``reverse()`` on it has no real
effect (the ordering was undefined prior to calling ``reverse()``, and will effect (the ordering was undefined prior to calling ``reverse()``, and will
remain undefined afterward). remain undefined afterward).
@ -518,14 +518,14 @@ query spans multiple tables, it's possible to get duplicate results when a
don't appear in the returned results (they are only there to support don't appear in the returned results (they are only there to support
ordering), it sometimes looks like non-distinct results are being returned. ordering), it sometimes looks like non-distinct results are being returned.
Similarly, if you use a :meth:`values()` query to restrict the columns Similarly, if you use a :meth:`values` query to restrict the columns
selected, the columns used in any :meth:`order_by()` (or default model selected, the columns used in any :meth:`order_by` (or default model
ordering) will still be involved and may affect uniqueness of the results. ordering) will still be involved and may affect uniqueness of the results.
The moral here is that if you are using ``distinct()`` be careful about The moral here is that if you are using ``distinct()`` be careful about
ordering by related models. Similarly, when using ``distinct()`` and ordering by related models. Similarly, when using ``distinct()`` and
:meth:`values()` together, be careful when ordering by fields not in the :meth:`values` together, be careful when ordering by fields not in the
:meth:`values()` call. :meth:`values` call.
On PostgreSQL only, you can pass positional arguments (``*fields``) in order to On PostgreSQL only, you can pass positional arguments (``*fields``) in order to
specify the names of fields to which the ``DISTINCT`` should apply. This specify the names of fields to which the ``DISTINCT`` should apply. This
@ -675,17 +675,17 @@ A few subtleties that are worth mentioning:
>>> Entry.objects.values("blog_id") >>> Entry.objects.values("blog_id")
<QuerySet [{'blog_id': 1}, ...]> <QuerySet [{'blog_id': 1}, ...]>
* When using ``values()`` together with :meth:`distinct()`, be aware that * When using ``values()`` together with :meth:`distinct`, be aware that
ordering can affect the results. See the note in :meth:`distinct` for ordering can affect the results. See the note in :meth:`distinct` for
details. details.
* If you use a ``values()`` clause after an :meth:`extra()` call, * If you use a ``values()`` clause after an :meth:`extra` call,
any fields defined by a ``select`` argument in the :meth:`extra()` must any fields defined by a ``select`` argument in the :meth:`extra` must
be explicitly included in the ``values()`` call. Any :meth:`extra()` call be explicitly included in the ``values()`` call. Any :meth:`extra` call
made after a ``values()`` call will have its extra selected fields made after a ``values()`` call will have its extra selected fields
ignored. ignored.
* Calling :meth:`only()` and :meth:`defer()` after ``values()`` doesn't make * Calling :meth:`only` and :meth:`defer` after ``values()`` doesn't make
sense, so doing so will raise a ``TypeError``. sense, so doing so will raise a ``TypeError``.
* Combining transforms and aggregates requires the use of two :meth:`annotate` * Combining transforms and aggregates requires the use of two :meth:`annotate`
@ -998,7 +998,7 @@ resulting ``QuerySet``. For example:
In addition, only ``LIMIT``, ``OFFSET``, ``COUNT(*)``, ``ORDER BY``, and In addition, only ``LIMIT``, ``OFFSET``, ``COUNT(*)``, ``ORDER BY``, and
specifying columns (i.e. slicing, :meth:`count`, :meth:`exists`, specifying columns (i.e. slicing, :meth:`count`, :meth:`exists`,
:meth:`order_by`, and :meth:`values()`/:meth:`values_list()`) are allowed :meth:`order_by`, and :meth:`values`/:meth:`values_list`) are allowed
on the resulting ``QuerySet``. Further, databases place restrictions on on the resulting ``QuerySet``. Further, databases place restrictions on
what operations are allowed in the combined queries. For example, most what operations are allowed in the combined queries. For example, most
databases don't allow ``LIMIT`` or ``OFFSET`` in the combined queries. databases don't allow ``LIMIT`` or ``OFFSET`` in the combined queries.
@ -1363,7 +1363,7 @@ This can be used to change the default ordering of the queryset:
... Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name")) ... Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name"))
... ) ... )
Or to call :meth:`~django.db.models.query.QuerySet.select_related()` when Or to call :meth:`~django.db.models.query.QuerySet.select_related` when
applicable to reduce the number of queries even further: applicable to reduce the number of queries even further:
.. code-block:: pycon .. code-block:: pycon
@ -1418,7 +1418,7 @@ less ambiguous than storing a filtered result in the related manager's cache:
Custom prefetching also works with single related relations like Custom prefetching also works with single related relations like
forward ``ForeignKey`` or ``OneToOneField``. Generally you'll want to use forward ``ForeignKey`` or ``OneToOneField``. Generally you'll want to use
:meth:`select_related()` for these relations, but there are a number of cases :meth:`select_related` for these relations, but there are a number of cases
where prefetching with a custom ``QuerySet`` is useful: where prefetching with a custom ``QuerySet`` is useful:
* You want to use a ``QuerySet`` that performs further prefetching * You want to use a ``QuerySet`` that performs further prefetching
@ -1665,7 +1665,7 @@ of the arguments is required, but you should use at least one of them.
fields or tables you have included via ``extra()`` use the ``order_by`` fields or tables you have included via ``extra()`` use the ``order_by``
parameter to ``extra()`` and pass in a sequence of strings. These parameter to ``extra()`` and pass in a sequence of strings. These
strings should either be model fields (as in the normal strings should either be model fields (as in the normal
:meth:`order_by()` method on querysets), of the form :meth:`order_by` method on querysets), of the form
``table_name.column_name`` or an alias for a column that you specified ``table_name.column_name`` or an alias for a column that you specified
in the ``select`` parameter to ``extra()``. in the ``select`` parameter to ``extra()``.
@ -1753,7 +1753,7 @@ Calling ``defer()`` with a field name that has already been deferred is
harmless (the field will still be deferred). harmless (the field will still be deferred).
You can defer loading of fields in related models (if the related models are You can defer loading of fields in related models (if the related models are
loading via :meth:`select_related()`) by using the standard double-underscore loading via :meth:`select_related`) by using the standard double-underscore
notation to separate related fields:: notation to separate related fields::
Blog.objects.select_related().defer("entry__headline", "entry__body") Blog.objects.select_related().defer("entry__headline", "entry__body")
@ -1766,18 +1766,18 @@ to ``defer()``::
Some fields in a model won't be deferred, even if you ask for them. You can Some fields in a model won't be deferred, even if you ask for them. You can
never defer the loading of the primary key. If you are using never defer the loading of the primary key. If you are using
:meth:`select_related()` to retrieve related models, you shouldn't defer the :meth:`select_related` to retrieve related models, you shouldn't defer the
loading of the field that connects from the primary model to the related loading of the field that connects from the primary model to the related
one, doing so will result in an error. one, doing so will result in an error.
Similarly, calling ``defer()`` (or its counterpart :meth:`only()`) including an Similarly, calling ``defer()`` (or its counterpart :meth:`only`) including an
argument from an aggregation (e.g. using the result of :meth:`annotate()`) argument from an aggregation (e.g. using the result of :meth:`annotate`)
doesn't make sense: doing so will raise an exception. The aggregated values doesn't make sense: doing so will raise an exception. The aggregated values
will always be fetched into the resulting queryset. will always be fetched into the resulting queryset.
.. note:: .. note::
The ``defer()`` method (and its cousin, :meth:`only()`, below) are only for The ``defer()`` method (and its cousin, :meth:`only`, below) are only for
advanced use-cases. They provide an optimization for when you have analyzed advanced use-cases. They provide an optimization for when you have analyzed
your queries closely and understand *exactly* what information you need and your queries closely and understand *exactly* what information you need and
have measured that the difference between returning the fields you need and have measured that the difference between returning the fields you need and
@ -1824,9 +1824,9 @@ will always be fetched into the resulting queryset.
.. note:: .. note::
When calling :meth:`~django.db.models.Model.save()` for instances with When calling :meth:`~django.db.models.Model.save` for instances with
deferred fields, only the loaded fields will be saved. See deferred fields, only the loaded fields will be saved. See
:meth:`~django.db.models.Model.save()` for more details. :meth:`~django.db.models.Model.save` for more details.
``only()`` ``only()``
~~~~~~~~~~ ~~~~~~~~~~
@ -1880,9 +1880,9 @@ are in your ``only()`` call.
.. note:: .. note::
When calling :meth:`~django.db.models.Model.save()` for instances with When calling :meth:`~django.db.models.Model.save` for instances with
deferred fields, only the loaded fields will be saved. See deferred fields, only the loaded fields will be saved. See
:meth:`~django.db.models.Model.save()` for more details. :meth:`~django.db.models.Model.save` for more details.
.. note:: .. note::
@ -2014,7 +2014,7 @@ raised if ``select_for_update()`` is used in autocommit mode.
Although ``select_for_update()`` normally fails in autocommit mode, since Although ``select_for_update()`` normally fails in autocommit mode, since
:class:`~django.test.TestCase` automatically wraps each test in a :class:`~django.test.TestCase` automatically wraps each test in a
transaction, calling ``select_for_update()`` in a ``TestCase`` even outside transaction, calling ``select_for_update()`` in a ``TestCase`` even outside
an :func:`~django.db.transaction.atomic()` block will (perhaps unexpectedly) an :func:`~django.db.transaction.atomic` block will (perhaps unexpectedly)
pass without raising a ``TransactionManagementError``. To properly test pass without raising a ``TransactionManagementError``. To properly test
``select_for_update()`` you should use ``select_for_update()`` you should use
:class:`~django.test.TransactionTestCase`. :class:`~django.test.TransactionTestCase`.
@ -2245,7 +2245,7 @@ example can be rewritten using ``get_or_create()`` like so::
) )
Any keyword arguments passed to ``get_or_create()`` — *except* an optional one Any keyword arguments passed to ``get_or_create()`` — *except* an optional one
called ``defaults`` — will be used in a :meth:`get()` call. If an object is called ``defaults`` — will be used in a :meth:`get` call. If an object is
found, ``get_or_create()`` returns a tuple of that object and ``False``. found, ``get_or_create()`` returns a tuple of that object and ``False``.
.. warning:: .. warning::
@ -2293,7 +2293,7 @@ If you have a field named ``defaults`` and want to use it as an exact lookup in
Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"}) Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"})
The ``get_or_create()`` method has similar error behavior to :meth:`create()` The ``get_or_create()`` method has similar error behavior to :meth:`create`
when you're using manually specified primary keys. If an object needs to be when you're using manually specified primary keys. If an object needs to be
created and the key already exists in the database, an created and the key already exists in the database, an
:exc:`~django.db.IntegrityError` will be raised. :exc:`~django.db.IntegrityError` will be raised.
@ -2712,7 +2712,7 @@ If your model's :ref:`Meta <meta-options>` specifies
``earliest()`` or ``latest()``. The fields specified in ``earliest()`` or ``latest()``. The fields specified in
:attr:`~django.db.models.Options.get_latest_by` will be used by default. :attr:`~django.db.models.Options.get_latest_by` will be used by default.
Like :meth:`get()`, ``earliest()`` and ``latest()`` raise Like :meth:`get`, ``earliest()`` and ``latest()`` raise
:exc:`~django.db.models.Model.DoesNotExist` if there is no object with the :exc:`~django.db.models.Model.DoesNotExist` if there is no object with the
given parameters. given parameters.
@ -2774,7 +2774,7 @@ equivalent to the above example::
*Asynchronous version*: ``alast()`` *Asynchronous version*: ``alast()``
Works like :meth:`first()`, but returns the last object in the queryset. Works like :meth:`first`, but returns the last object in the queryset.
``aggregate()`` ``aggregate()``
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -2975,8 +2975,8 @@ does not call any ``save()`` methods on your models, nor does it emit the
:attr:`~django.db.models.signals.post_save` signals (which are a consequence of :attr:`~django.db.models.signals.post_save` signals (which are a consequence of
calling :meth:`Model.save() <django.db.models.Model.save>`). If you want to calling :meth:`Model.save() <django.db.models.Model.save>`). If you want to
update a bunch of records for a model that has a custom update a bunch of records for a model that has a custom
:meth:`~django.db.models.Model.save()` method, loop over them and call :meth:`~django.db.models.Model.save` method, loop over them and call
:meth:`~django.db.models.Model.save()`, like this:: :meth:`~django.db.models.Model.save`, like this::
for e in Entry.objects.filter(pub_date__year=2010): for e in Entry.objects.filter(pub_date__year=2010):
e.comments_on = False e.comments_on = False
@ -3130,8 +3130,8 @@ there are triggers or if a function is called, even for a ``SELECT`` query.
----------------- -----------------
Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're
specified as keyword arguments to the ``QuerySet`` methods :meth:`filter()`, specified as keyword arguments to the ``QuerySet`` methods :meth:`filter`,
:meth:`exclude()` and :meth:`get()`. :meth:`exclude` and :meth:`get`.
For an introduction, see :ref:`models and database queries documentation For an introduction, see :ref:`models and database queries documentation
<field-lookups-intro>`. <field-lookups-intro>`.
@ -4157,11 +4157,11 @@ such as ``|`` (``OR``), ``&`` (``AND``), and ``^`` (``XOR``). See
.. class:: Prefetch(lookup, queryset=None, to_attr=None) .. class:: Prefetch(lookup, queryset=None, to_attr=None)
The ``Prefetch()`` object can be used to control the operation of The ``Prefetch()`` object can be used to control the operation of
:meth:`~django.db.models.query.QuerySet.prefetch_related()`. :meth:`~django.db.models.query.QuerySet.prefetch_related`.
The ``lookup`` argument describes the relations to follow and works the same The ``lookup`` argument describes the relations to follow and works the same
as the string based lookups passed to as the string based lookups passed to
:meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example: :meth:`~django.db.models.query.QuerySet.prefetch_related`. For example:
.. code-block:: pycon .. code-block:: pycon
@ -4175,7 +4175,7 @@ as the string based lookups passed to
The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup. The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup.
This is useful to further filter down the prefetch operation, or to call This is useful to further filter down the prefetch operation, or to call
:meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched :meth:`~django.db.models.query.QuerySet.select_related` from the prefetched
relation, hence reducing the number of queries even further: relation, hence reducing the number of queries even further:
.. code-block:: pycon .. code-block:: pycon
@ -4243,7 +4243,7 @@ overridden by using a custom queryset in a related lookup.
A :class:`~django.db.models.Q` object to control the filtering. A :class:`~django.db.models.Q` object to control the filtering.
``FilteredRelation`` is used with :meth:`~.QuerySet.annotate()` to create an ``FilteredRelation`` is used with :meth:`~.QuerySet.annotate` to create an
``ON`` clause when a ``JOIN`` is performed. It doesn't act on the default ``ON`` clause when a ``JOIN`` is performed. It doesn't act on the default
relationship but on the annotation name (``pizzas_vegetarian`` in example relationship but on the annotation name (``pizzas_vegetarian`` in example
below). below).

View File

@ -132,7 +132,7 @@ Related objects reference
>>> e = Entry.objects.get(id=234) >>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
Similar to :meth:`add()`, ``e.save()`` is called in the example above Similar to :meth:`add`, ``e.save()`` is called in the example above
to perform the update. Using ``remove()`` with a many-to-many to perform the update. Using ``remove()`` with a many-to-many
relationship, however, will delete the relationships using relationship, however, will delete the relationships using
:meth:`QuerySet.delete()<django.db.models.query.QuerySet.delete>` which :meth:`QuerySet.delete()<django.db.models.query.QuerySet.delete>` which

View File

@ -225,7 +225,7 @@ application.
.. attribute:: HttpRequest.current_app .. attribute:: HttpRequest.current_app
The :ttag:`url` template tag will use its value as the ``current_app`` The :ttag:`url` template tag will use its value as the ``current_app``
argument to :func:`~django.urls.reverse()`. argument to :func:`~django.urls.reverse`.
.. attribute:: HttpRequest.urlconf .. attribute:: HttpRequest.urlconf
@ -264,7 +264,7 @@ middleware class is listed in :setting:`MIDDLEWARE`.
From the :class:`~django.contrib.sites.middleware.CurrentSiteMiddleware`: From the :class:`~django.contrib.sites.middleware.CurrentSiteMiddleware`:
An instance of :class:`~django.contrib.sites.models.Site` or An instance of :class:`~django.contrib.sites.models.Site` or
:class:`~django.contrib.sites.requests.RequestSite` as returned by :class:`~django.contrib.sites.requests.RequestSite` as returned by
:func:`~django.contrib.sites.shortcuts.get_current_site()` :func:`~django.contrib.sites.shortcuts.get_current_site`
representing the current site. representing the current site.
.. attribute:: HttpRequest.user .. attribute:: HttpRequest.user
@ -310,7 +310,7 @@ Methods
:setting:`ALLOWED_HOSTS` or the domain name is invalid according to :setting:`ALLOWED_HOSTS` or the domain name is invalid according to
:rfc:`1034`/:rfc:`1035 <1035>`. :rfc:`1034`/:rfc:`1035 <1035>`.
.. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is .. note:: The :meth:`~HttpRequest.get_host` method fails when the host is
behind multiple proxies. One solution is to use middleware to rewrite behind multiple proxies. One solution is to use middleware to rewrite
the proxy headers, as in the following example:: the proxy headers, as in the following example::
@ -337,7 +337,7 @@ Methods
return self.get_response(request) return self.get_response(request)
This middleware should be positioned before any other middleware that This middleware should be positioned before any other middleware that
relies on the value of :meth:`~HttpRequest.get_host()` -- for instance, relies on the value of :meth:`~HttpRequest.get_host` -- for instance,
:class:`~django.middleware.common.CommonMiddleware` or :class:`~django.middleware.common.CommonMiddleware` or
:class:`~django.middleware.csrf.CsrfViewMiddleware`. :class:`~django.middleware.csrf.CsrfViewMiddleware`.
@ -381,7 +381,7 @@ Methods
.. note:: .. note::
Mixing HTTP and HTTPS on the same site is discouraged, therefore Mixing HTTP and HTTPS on the same site is discouraged, therefore
:meth:`~HttpRequest.build_absolute_uri()` will always generate an :meth:`~HttpRequest.build_absolute_uri` will always generate an
absolute URI with the same scheme the current request has. If you need absolute URI with the same scheme the current request has. If you need
to redirect users to HTTPS, it's best to let your web server redirect to redirect users to HTTPS, it's best to let your web server redirect
all HTTP traffic to HTTPS. all HTTP traffic to HTTPS.
@ -692,7 +692,7 @@ In addition, ``QueryDict`` has the following methods:
.. method:: QueryDict.lists() .. method:: QueryDict.lists()
Like :meth:`items()`, except it includes all values, as a list, for each Like :meth:`items`, except it includes all values, as a list, for each
member of the dictionary. For example: member of the dictionary. For example:
.. code-block:: pycon .. code-block:: pycon
@ -1040,7 +1040,7 @@ Methods
.. method:: HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None) .. method:: HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)
Like :meth:`~HttpResponse.set_cookie()`, but Like :meth:`~HttpResponse.set_cookie`, but
:doc:`cryptographic signing </topics/signing>` the cookie before setting :doc:`cryptographic signing </topics/signing>` the cookie before setting
it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`. it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`.
You can use the optional ``salt`` argument for added key strength, but You can use the optional ``salt`` argument for added key strength, but

View File

@ -90,7 +90,7 @@ strips when performing host validation.
If the ``Host`` header (or ``X-Forwarded-Host`` if If the ``Host`` header (or ``X-Forwarded-Host`` if
:setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this :setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this
list, the :meth:`django.http.HttpRequest.get_host()` method will raise list, the :meth:`django.http.HttpRequest.get_host` method will raise
:exc:`~django.core.exceptions.SuspiciousOperation`. :exc:`~django.core.exceptions.SuspiciousOperation`.
When :setting:`DEBUG` is ``True`` and ``ALLOWED_HOSTS`` is empty, the host When :setting:`DEBUG` is ``True`` and ``ALLOWED_HOSTS`` is empty, the host
@ -99,7 +99,7 @@ is validated against ``['.localhost', '127.0.0.1', '[::1]']``.
``ALLOWED_HOSTS`` is also :ref:`checked when running tests ``ALLOWED_HOSTS`` is also :ref:`checked when running tests
<topics-testing-advanced-multiple-hosts>`. <topics-testing-advanced-multiple-hosts>`.
This validation only applies via :meth:`~django.http.HttpRequest.get_host()`; This validation only applies via :meth:`~django.http.HttpRequest.get_host`;
if your code accesses the ``Host`` header directly from ``request.META`` you if your code accesses the ``Host`` header directly from ``request.META`` you
are bypassing this security protection. are bypassing this security protection.
@ -1684,7 +1684,7 @@ If not ``None``, this will be used as the value of the ``SCRIPT_NAME``
environment variable in any HTTP request. This setting can be used to override environment variable in any HTTP request. This setting can be used to override
the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version
of the preferred value or not supplied at all. It is also used by of the preferred value or not supplied at all. It is also used by
:func:`django.setup()` to set the URL resolver script prefix outside of the :func:`django.setup` to set the URL resolver script prefix outside of the
request/response cycle (e.g. in management commands and standalone scripts) to request/response cycle (e.g. in management commands and standalone scripts) to
generate correct URLs when ``FORCE_SCRIPT_NAME`` is provided. generate correct URLs when ``FORCE_SCRIPT_NAME`` is provided.
@ -2292,7 +2292,7 @@ The secret key is used for:
* All :doc:`sessions </topics/http/sessions>` if you are using * All :doc:`sessions </topics/http/sessions>` if you are using
any other session backend than ``django.contrib.sessions.backends.cache``, any other session backend than ``django.contrib.sessions.backends.cache``,
or are using the default or are using the default
:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()`. :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`.
* All :doc:`messages </ref/contrib/messages>` if you are using * All :doc:`messages </ref/contrib/messages>` if you are using
:class:`~django.contrib.messages.storage.cookie.CookieStorage` or :class:`~django.contrib.messages.storage.cookie.CookieStorage` or
:class:`~django.contrib.messages.storage.fallback.FallbackStorage`. :class:`~django.contrib.messages.storage.fallback.FallbackStorage`.
@ -2648,7 +2648,7 @@ protocol.
.. admonition:: Why are my emails sent from a different address? .. admonition:: Why are my emails sent from a different address?
This address is used only for error messages. It is *not* the address that This address is used only for error messages. It is *not* the address that
regular email messages sent with :meth:`~django.core.mail.send_mail()` regular email messages sent with :meth:`~django.core.mail.send_mail`
come from; for that, see :setting:`DEFAULT_FROM_EMAIL`. come from; for that, see :setting:`DEFAULT_FROM_EMAIL`.
.. setting:: SHORT_DATE_FORMAT .. setting:: SHORT_DATE_FORMAT

View File

@ -33,7 +33,7 @@ Attributes
The name of the template to be rendered. Accepts a backend-dependent The name of the template to be rendered. Accepts a backend-dependent
template object (such as those returned by template object (such as those returned by
:func:`~django.template.loader.get_template()`), the name of a template, :func:`~django.template.loader.get_template`), the name of a template,
or a list of template names. or a list of template names.
Example: ``['foo.html', 'path/to/bar.html']`` Example: ``['foo.html', 'path/to/bar.html']``
@ -65,7 +65,7 @@ Methods
``template`` ``template``
A backend-dependent template object (such as those returned by A backend-dependent template object (such as those returned by
:func:`~django.template.loader.get_template()`), the name of a template, :func:`~django.template.loader.get_template`), the name of a template,
or a list of template names. or a list of template names.
``context`` ``context``
@ -105,7 +105,7 @@ Methods
Resolves the template instance to use for rendering. Accepts a Resolves the template instance to use for rendering. Accepts a
backend-dependent template object (such as those returned by backend-dependent template object (such as those returned by
:func:`~django.template.loader.get_template()`), the name of a template, :func:`~django.template.loader.get_template`), the name of a template,
or a list of template names. or a list of template names.
Returns the backend-dependent template object instance to be rendered. Returns the backend-dependent template object instance to be rendered.
@ -163,7 +163,7 @@ Methods
``template`` ``template``
A backend-dependent template object (such as those returned by A backend-dependent template object (such as those returned by
:func:`~django.template.loader.get_template()`), the name of a template, :func:`~django.template.loader.get_template`), the name of a template,
or a list of template names. or a list of template names.
``context`` ``context``
@ -203,7 +203,7 @@ There are three circumstances under which a ``TemplateResponse`` will be
rendered: rendered:
* When the ``TemplateResponse`` instance is explicitly rendered, using * When the ``TemplateResponse`` instance is explicitly rendered, using
the :meth:`SimpleTemplateResponse.render()` method. the :meth:`SimpleTemplateResponse.render` method.
* When the content of the response is explicitly set by assigning * When the content of the response is explicitly set by assigning
``response.content``. ``response.content``.
@ -293,7 +293,7 @@ Using ``TemplateResponse`` and ``SimpleTemplateResponse``
A :class:`TemplateResponse` object can be used anywhere that a normal A :class:`TemplateResponse` object can be used anywhere that a normal
:class:`django.http.HttpResponse` can be used. It can also be used as an :class:`django.http.HttpResponse` can be used. It can also be used as an
alternative to calling :func:`~django.shortcuts.render()`. alternative to calling :func:`~django.shortcuts.render`.
For example, the following view returns a :class:`TemplateResponse` with a For example, the following view returns a :class:`TemplateResponse` with a
template and a context containing a queryset:: template and a context containing a queryset::

View File

@ -150,7 +150,7 @@ URL from an :rfc:`IRI <3987>` -- very loosely speaking, a :rfc:`URI <3986>`
that can contain Unicode characters. Use these functions for quoting and that can contain Unicode characters. Use these functions for quoting and
converting an IRI to a URI: converting an IRI to a URI:
* The :func:`django.utils.encoding.iri_to_uri()` function, which implements the * The :func:`django.utils.encoding.iri_to_uri` function, which implements the
conversion from IRI to URI as required by :rfc:`3987#section-3.1`. conversion from IRI to URI as required by :rfc:`3987#section-3.1`.
* The :func:`urllib.parse.quote` and :func:`urllib.parse.quote_plus` * The :func:`urllib.parse.quote` and :func:`urllib.parse.quote_plus`
@ -192,7 +192,7 @@ you can construct your IRI without worrying about whether it contains
non-ASCII characters and then, right at the end, call ``iri_to_uri()`` on the non-ASCII characters and then, right at the end, call ``iri_to_uri()`` on the
result. result.
Similarly, Django provides :func:`django.utils.encoding.uri_to_iri()` which Similarly, Django provides :func:`django.utils.encoding.uri_to_iri` which
implements the conversion from URI to IRI as per :rfc:`3987#section-3.2`. implements the conversion from URI to IRI as per :rfc:`3987#section-3.2`.
An example to demonstrate: An example to demonstrate:

View File

@ -29,7 +29,7 @@ Returns an element for inclusion in ``urlpatterns``. For example::
--------- ---------
The ``route`` argument should be a string or The ``route`` argument should be a string or
:func:`~django.utils.translation.gettext_lazy()` (see :func:`~django.utils.translation.gettext_lazy` (see
:ref:`translating-urlpatterns`) that contains a URL pattern. The string :ref:`translating-urlpatterns`) that contains a URL pattern. The string
may contain angle brackets (like ``<username>`` above) to capture part of the may contain angle brackets (like ``<username>`` above) to capture part of the
URL and send it as a keyword argument to the view. The angle brackets may URL and send it as a keyword argument to the view. The angle brackets may
@ -93,7 +93,7 @@ Returns an element for inclusion in ``urlpatterns``. For example::
] ]
The ``route`` argument should be a string or The ``route`` argument should be a string or
:func:`~django.utils.translation.gettext_lazy()` (see :func:`~django.utils.translation.gettext_lazy` (see
:ref:`translating-urlpatterns`) that contains a regular expression compatible :ref:`translating-urlpatterns`) that contains a regular expression compatible
with Python's :py:mod:`re` module. Strings typically use raw string syntax with Python's :py:mod:`re` module. Strings typically use raw string syntax
(``r''``) so that they can contain sequences like ``\d`` without the need to (``r''``) so that they can contain sequences like ``\d`` without the need to
@ -107,7 +107,7 @@ When a ``route`` ends with ``$`` the whole requested URL, matching against
pattern (:py:func:`re.fullmatch` is used). pattern (:py:func:`re.fullmatch` is used).
The ``view``, ``kwargs`` and ``name`` arguments are the same as for The ``view``, ``kwargs`` and ``name`` arguments are the same as for
:func:`~django.urls.path()`. :func:`~django.urls.path`.
``include()`` ``include()``
============= =============
@ -143,7 +143,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
.. function:: register_converter(converter, type_name) .. function:: register_converter(converter, type_name)
The function for registering a converter for use in :func:`~django.urls.path()` The function for registering a converter for use in :func:`~django.urls.path`
``route``\s. ``route``\s.
The ``converter`` argument is a converter class, and ``type_name`` is the The ``converter`` argument is a converter class, and ``type_name`` is the

View File

@ -348,7 +348,7 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
An optional string containing the MIME type of the stylesheet. If not An optional string containing the MIME type of the stylesheet. If not
specified, Django will attempt to guess it by using Python's specified, Django will attempt to guess it by using Python's
:py:func:`mimetypes.guess_type()`. Use ``mimetype=None`` if you don't :py:func:`mimetypes.guess_type`. Use ``mimetype=None`` if you don't
want your stylesheet to have a MIME type specified. want your stylesheet to have a MIME type specified.
.. attribute:: media .. attribute:: media
@ -977,10 +977,10 @@ appropriate entities.
.. function:: override(timezone) .. function:: override(timezone)
This is a Python context manager that sets the :ref:`current time zone This is a Python context manager that sets the :ref:`current time zone
<default-current-time-zone>` on entry with :func:`activate()`, and restores <default-current-time-zone>` on entry with :func:`activate`, and restores
the previously active time zone on exit. If the ``timezone`` argument is the previously active time zone on exit. If the ``timezone`` argument is
``None``, the :ref:`current time zone <default-current-time-zone>` is unset ``None``, the :ref:`current time zone <default-current-time-zone>` is unset
on entry with :func:`deactivate()` instead. on entry with :func:`deactivate` instead.
``override`` is also usable as a function decorator. ``override`` is also usable as a function decorator.
@ -1133,8 +1133,8 @@ For a complete discussion on the usage of the following see the
.. function:: get_language() .. function:: get_language()
Returns the currently selected language code. Returns ``None`` if Returns the currently selected language code. Returns ``None`` if
translations are temporarily deactivated (by :func:`deactivate_all()` or translations are temporarily deactivated (by :func:`deactivate_all` or
when ``None`` is passed to :func:`override()`). when ``None`` is passed to :func:`override`).
.. function:: get_language_bidi() .. function:: get_language_bidi()

View File

@ -445,8 +445,8 @@ Requests and Responses
* Added ``request.user`` to the debug view. * Added ``request.user`` to the debug view.
* Added :class:`~django.http.HttpResponse` methods * Added :class:`~django.http.HttpResponse` methods
:meth:`~django.http.HttpResponse.readable()` and :meth:`~django.http.HttpResponse.readable` and
:meth:`~django.http.HttpResponse.seekable()` to make an instance a :meth:`~django.http.HttpResponse.seekable` to make an instance a
stream-like object and allow wrapping it with :py:class:`io.TextIOWrapper`. stream-like object and allow wrapping it with :py:class:`io.TextIOWrapper`.
* Added the :attr:`HttpRequest.content_type * Added the :attr:`HttpRequest.content_type
@ -498,7 +498,7 @@ Tests
URLs URLs
~~~~ ~~~~
* An addition in :func:`django.setup()` allows URL resolving that happens * An addition in :func:`django.setup` allows URL resolving that happens
outside of the request/response cycle (e.g. in management commands and outside of the request/response cycle (e.g. in management commands and
standalone scripts) to take :setting:`FORCE_SCRIPT_NAME` into account when it standalone scripts) to take :setting:`FORCE_SCRIPT_NAME` into account when it
is set. is set.
@ -839,9 +839,9 @@ Miscellaneous
in :setting:`AUTHENTICATION_BACKENDS` instead. in :setting:`AUTHENTICATION_BACKENDS` instead.
* In light of the previous change, the test client's * In light of the previous change, the test client's
:meth:`~django.test.Client.login()` method no longer always rejects inactive :meth:`~django.test.Client.login` method no longer always rejects inactive
users but instead delegates this decision to the authentication backend. users but instead delegates this decision to the authentication backend.
:meth:`~django.test.Client.force_login()` also delegates the decision to the :meth:`~django.test.Client.force_login` also delegates the decision to the
authentication backend, so if you're using the default backends, you need to authentication backend, so if you're using the default backends, you need to
use an active user. use an active user.
@ -1317,7 +1317,7 @@ to remove usage of these features.
:func:`~django.template.loader.get_template` and :func:`~django.template.loader.get_template` and
:func:`~django.template.loader.select_template` no longer accept a :func:`~django.template.loader.select_template` no longer accept a
:class:`~django.template.Context` in their :class:`~django.template.Context` in their
:meth:`~django.template.backends.base.Template.render()` method. :meth:`~django.template.backends.base.Template.render` method.
* :doc:`Template response APIs </ref/template-response>` enforce the use of * :doc:`Template response APIs </ref/template-response>` enforce the use of
:class:`dict` and backend-dependent template objects instead of :class:`dict` and backend-dependent template objects instead of

View File

@ -9,7 +9,7 @@ Django 1.11.1 adds a minor feature and fixes several bugs in 1.11.
Allowed disabling server-side cursors on PostgreSQL Allowed disabling server-side cursors on PostgreSQL
=================================================== ===================================================
The change in Django 1.11 to make :meth:`.QuerySet.iterator()` use server-side The change in Django 1.11 to make :meth:`.QuerySet.iterator` use server-side
cursors on PostgreSQL prevents running Django with PgBouncer in transaction cursors on PostgreSQL prevents running Django with PgBouncer in transaction
pooling mode. To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS pooling mode. To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS
<DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting in :setting:`DATABASES`. <DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting in :setting:`DATABASES`.

View File

@ -249,14 +249,14 @@ CSRF
Database backends Database backends
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
* Added the ``skip_locked`` argument to :meth:`.QuerySet.select_for_update()` * Added the ``skip_locked`` argument to :meth:`.QuerySet.select_for_update`
on PostgreSQL 9.5+ and Oracle to execute queries with on PostgreSQL 9.5+ and Oracle to execute queries with
``FOR UPDATE SKIP LOCKED``. ``FOR UPDATE SKIP LOCKED``.
* Added the :setting:`TEST['TEMPLATE'] <TEST_TEMPLATE>` setting to let * Added the :setting:`TEST['TEMPLATE'] <TEST_TEMPLATE>` setting to let
PostgreSQL users specify a template for creating the test database. PostgreSQL users specify a template for creating the test database.
* :meth:`.QuerySet.iterator()` now uses `server-side cursors`_ on PostgreSQL. * :meth:`.QuerySet.iterator` now uses `server-side cursors`_ on PostgreSQL.
This feature transfers some of the worker memory load (used to hold query This feature transfers some of the worker memory load (used to hold query
results) to the database and might increase database memory usage. results) to the database and might increase database memory usage.
@ -646,7 +646,7 @@ described in :ref:`writing your own migration operation
Server-side cursors on PostgreSQL Server-side cursors on PostgreSQL
--------------------------------- ---------------------------------
The change to make :meth:`.QuerySet.iterator()` use server-side cursors on The change to make :meth:`.QuerySet.iterator` use server-side cursors on
PostgreSQL prevents running Django with PgBouncer in transaction pooling mode. PostgreSQL prevents running Django with PgBouncer in transaction pooling mode.
To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS
<DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting (added in Django 1.11.1) in <DATABASE-DISABLE_SERVER_SIDE_CURSORS>` setting (added in Django 1.11.1) in

View File

@ -878,7 +878,7 @@ of an SMTPConnection::
messages = get_notification_email() messages = get_notification_email()
connection.send_messages(messages) connection.send_messages(messages)
...should now call :meth:`~django.core.mail.get_connection()` to ...should now call :meth:`~django.core.mail.get_connection` to
instantiate a generic email connection:: instantiate a generic email connection::
from django.core.mail import get_connection from django.core.mail import get_connection
@ -900,7 +900,7 @@ SMTP connection::
If your call to construct an instance of ``SMTPConnection`` required If your call to construct an instance of ``SMTPConnection`` required
additional arguments, those arguments can be passed to the additional arguments, those arguments can be passed to the
:meth:`~django.core.mail.get_connection()` call:: :meth:`~django.core.mail.get_connection` call::
connection = get_connection( connection = get_connection(
"django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234 "django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234

View File

@ -292,8 +292,8 @@ requests. These include:
* Support for HttpOnly_ cookies. * Support for HttpOnly_ cookies.
* :meth:`~django.core.mail.mail_admins()` and * :meth:`~django.core.mail.mail_admins` and
:meth:`~django.core.mail.mail_managers()` now support easily attaching :meth:`~django.core.mail.mail_managers` now support easily attaching
HTML content to messages. HTML content to messages.
* :class:`~django.core.mail.EmailMessage` now supports CC's. * :class:`~django.core.mail.EmailMessage` now supports CC's.
@ -305,7 +305,7 @@ requests. These include:
``takes_context`` argument, making it easier to write simple ``takes_context`` argument, making it easier to write simple
template tags that require access to template context. template tags that require access to template context.
* A new :meth:`~django.shortcuts.render()` shortcut -- an alternative * A new :meth:`~django.shortcuts.render` shortcut -- an alternative
to ``django.shortcuts.render_to_response()`` providing a to ``django.shortcuts.render_to_response()`` providing a
:class:`~django.template.RequestContext` by default. :class:`~django.template.RequestContext` by default.

View File

@ -10,4 +10,4 @@ Bugfixes
======== ========
* Restored the ability to ``reverse()`` views created using * Restored the ability to ``reverse()`` views created using
:func:`functools.partial()` (:ticket:`22486`). :func:`functools.partial` (:ticket:`22486`).

View File

@ -1348,7 +1348,7 @@ actually provided the body of the HTTP request. It's been renamed to
In previous versions, ``Paginator`` objects used in sitemap classes were In previous versions, ``Paginator`` objects used in sitemap classes were
cached, which could result in stale site maps. We've removed the caching, so cached, which could result in stale site maps. We've removed the caching, so
each request to a site map now creates a new Paginator object and calls the each request to a site map now creates a new Paginator object and calls the
:attr:`~django.contrib.sitemaps.Sitemap.items()` method of the :attr:`~django.contrib.sitemaps.Sitemap.items` method of the
:class:`~django.contrib.sitemaps.Sitemap` subclass. Depending on what your :class:`~django.contrib.sitemaps.Sitemap` subclass. Depending on what your
``items()`` method is doing, this may have a negative performance impact. ``items()`` method is doing, this may have a negative performance impact.
To mitigate the performance impact, consider using the :doc:`caching To mitigate the performance impact, consider using the :doc:`caching

View File

@ -10,4 +10,4 @@ Bugfixes
======== ========
* Restored the ability to ``reverse()`` views created using * Restored the ability to ``reverse()`` views created using
:func:`functools.partial()` (:ticket:`22486`). :func:`functools.partial` (:ticket:`22486`).

View File

@ -219,8 +219,8 @@ GeoDjango
* :class:`~django.contrib.gis.geos.LineString` and * :class:`~django.contrib.gis.geos.LineString` and
:class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the :class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the
:meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and :meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate` and
:meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods :meth:`~django.contrib.gis.geos.GEOSGeometry.project` methods
(so-called linear referencing). (so-called linear referencing).
* The ``wkb`` and ``hex`` properties of * The ``wkb`` and ``hex`` properties of
@ -365,7 +365,7 @@ Backwards incompatible changes in 1.5
The new :setting:`ALLOWED_HOSTS` setting validates the request's ``Host`` The new :setting:`ALLOWED_HOSTS` setting validates the request's ``Host``
header and protects against host-poisoning attacks. This setting is now header and protects against host-poisoning attacks. This setting is now
required whenever :setting:`DEBUG` is ``False``, or else required whenever :setting:`DEBUG` is ``False``, or else
:meth:`django.http.HttpRequest.get_host()` will raise :meth:`django.http.HttpRequest.get_host` will raise
:exc:`~django.core.exceptions.SuspiciousOperation`. For more details see the :exc:`~django.core.exceptions.SuspiciousOperation`. For more details see the
:setting:`full documentation<ALLOWED_HOSTS>` for the new setting. :setting:`full documentation<ALLOWED_HOSTS>` for the new setting.
@ -624,7 +624,7 @@ fragile, and must now be changed to be able to run independently.
The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present
after form validation. When the form doesn't validate, it contains only the after form validation. When the form doesn't validate, it contains only the
fields that passed validation. You should test the success of the validation fields that passed validation. You should test the success of the validation
with the :meth:`~django.forms.Form.is_valid()` method and not with the with the :meth:`~django.forms.Form.is_valid` method and not with the
presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute
on the form. on the form.

View File

@ -110,7 +110,7 @@ perform appropriate manual type conversions prior to executing queries.
============================================== ==============================================
Historically, queries that use Historically, queries that use
:meth:`~django.db.models.query.QuerySet.select_for_update()` could be :meth:`~django.db.models.query.QuerySet.select_for_update` could be
executed in autocommit mode, outside of a transaction. Before Django executed in autocommit mode, outside of a transaction. Before Django
1.6, Django's automatic transactions mode allowed this to be used to 1.6, Django's automatic transactions mode allowed this to be used to
lock records until the next write operation. Django 1.6 introduced lock records until the next write operation. Django 1.6 introduced

View File

@ -14,7 +14,7 @@ Bugfixes
1.4 (:ticket:`22426`). 1.4 (:ticket:`22426`).
* Restored the ability to ``reverse()`` views created using * Restored the ability to ``reverse()`` views created using
:func:`functools.partial()` (:ticket:`22486`). :func:`functools.partial` (:ticket:`22486`).
* Fixed the ``object_id`` of the ``LogEntry`` that's created after a user * Fixed the ``object_id`` of the ``LogEntry`` that's created after a user
password change in the admin (:ticket:`22515`). password change in the admin (:ticket:`22515`).

View File

@ -693,7 +693,7 @@ Notably most database backends did fetch all the rows in one go already in
1.5. 1.5.
It is still possible to convert the fetched rows to ``Model`` objects It is still possible to convert the fetched rows to ``Model`` objects
lazily by using the :meth:`~django.db.models.query.QuerySet.iterator()` lazily by using the :meth:`~django.db.models.query.QuerySet.iterator`
method. method.
:meth:`BoundField.label_tag<django.forms.BoundField.label_tag>` now includes the form's :attr:`~django.forms.Form.label_suffix` :meth:`BoundField.label_tag<django.forms.BoundField.label_tag>` now includes the form's :attr:`~django.forms.Form.label_suffix`
@ -941,10 +941,10 @@ Miscellaneous
* In Django 1.4 and 1.5, a blank string was unintentionally not considered to * In Django 1.4 and 1.5, a blank string was unintentionally not considered to
be a valid password. This meant be a valid password. This meant
:meth:`~django.contrib.auth.models.User.set_password()` would save a blank :meth:`~django.contrib.auth.models.User.set_password` would save a blank
password as an unusable password like password as an unusable password like
:meth:`~django.contrib.auth.models.User.set_unusable_password()` does, and :meth:`~django.contrib.auth.models.User.set_unusable_password` does, and
thus :meth:`~django.contrib.auth.models.User.check_password()` always thus :meth:`~django.contrib.auth.models.User.check_password` always
returned ``False`` for blank passwords. This has been corrected in this returned ``False`` for blank passwords. This has been corrected in this
release: blank passwords are now valid. release: blank passwords are now valid.

View File

@ -62,9 +62,9 @@ Bugfixes
* Fixed renaming of models with a self-referential many-to-many field * Fixed renaming of models with a self-referential many-to-many field
(``ManyToManyField('self')``) (:ticket:`23503`). (``ManyToManyField('self')``) (:ticket:`23503`).
* Added the :meth:`~django.contrib.admin.InlineModelAdmin.get_extra()`, * Added the :meth:`~django.contrib.admin.InlineModelAdmin.get_extra`,
:meth:`~django.contrib.admin.InlineModelAdmin.get_max_num()`, and :meth:`~django.contrib.admin.InlineModelAdmin.get_max_num`, and
:meth:`~django.contrib.admin.InlineModelAdmin.get_min_num()` hooks to :meth:`~django.contrib.admin.InlineModelAdmin.get_min_num` hooks to
:class:`~django.contrib.contenttypes.admin.GenericInlineModelAdmin` :class:`~django.contrib.contenttypes.admin.GenericInlineModelAdmin`
(:ticket:`23539`). (:ticket:`23539`).

View File

@ -109,7 +109,7 @@ Improvements thus far include:
* The name of applications can be customized in the admin with the * The name of applications can be customized in the admin with the
:attr:`~django.apps.AppConfig.verbose_name` of application configurations. :attr:`~django.apps.AppConfig.verbose_name` of application configurations.
* The admin automatically calls :func:`~django.contrib.admin.autodiscover()` * The admin automatically calls :func:`~django.contrib.admin.autodiscover`
when Django starts. You can consequently remove this line from your when Django starts. You can consequently remove this line from your
URLconf. URLconf.
@ -233,9 +233,9 @@ You can specify the ``QuerySet`` used to traverse a given relation
or customize the storage location of prefetch results. or customize the storage location of prefetch results.
This enables things like filtering prefetched relations, calling This enables things like filtering prefetched relations, calling
:meth:`~django.db.models.query.QuerySet.select_related()` from a prefetched :meth:`~django.db.models.query.QuerySet.select_related` from a prefetched
relation, or prefetching the same relation multiple times with different relation, or prefetching the same relation multiple times with different
querysets. See :meth:`~django.db.models.query.QuerySet.prefetch_related()` querysets. See :meth:`~django.db.models.query.QuerySet.prefetch_related`
for more details. for more details.
Admin shortcuts support time zones Admin shortcuts support time zones
@ -316,7 +316,7 @@ automatically process them. This remains the canonical way of adding errors
when possible. However the latter was fiddly and error-prone, since the burden when possible. However the latter was fiddly and error-prone, since the burden
of handling edge cases fell on the user. of handling edge cases fell on the user.
The new :meth:`~django.forms.Form.add_error()` method allows adding errors The new :meth:`~django.forms.Form.add_error` method allows adding errors
to specific form fields from anywhere without having to worry about the details to specific form fields from anywhere without having to worry about the details
such as creating instances of ``django.forms.utils.ErrorList`` or dealing with such as creating instances of ``django.forms.utils.ErrorList`` or dealing with
``Form.cleaned_data``. This new API replaces manipulating ``Form._errors`` ``Form.cleaned_data``. This new API replaces manipulating ``Form._errors``
@ -416,8 +416,8 @@ Minor features
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
* Any ``**kwargs`` passed to * Any ``**kwargs`` passed to
:meth:`~django.contrib.auth.models.User.email_user()` are passed to the :meth:`~django.contrib.auth.models.User.email_user` are passed to the
underlying :meth:`~django.core.mail.send_mail()` call. underlying :meth:`~django.core.mail.send_mail` call.
* The :func:`~django.contrib.auth.decorators.permission_required` decorator can * The :func:`~django.contrib.auth.decorators.permission_required` decorator can
take a list of permissions as well as a single permission. take a list of permissions as well as a single permission.
@ -847,9 +847,9 @@ Templates
* The following functions now accept a ``dirs`` parameter which is a list or * The following functions now accept a ``dirs`` parameter which is a list or
tuple to override ``TEMPLATE_DIRS``: tuple to override ``TEMPLATE_DIRS``:
* :func:`django.template.loader.get_template()` * :func:`django.template.loader.get_template`
* :func:`django.template.loader.select_template()` * :func:`django.template.loader.select_template`
* :func:`django.shortcuts.render()` * :func:`django.shortcuts.render`
* ``django.shortcuts.render_to_response()`` * ``django.shortcuts.render_to_response()``
* The :tfilter:`time` filter now accepts timezone-related :ref:`format * The :tfilter:`time` filter now accepts timezone-related :ref:`format
@ -1252,7 +1252,7 @@ has been set to the more regular ``invalid_login`` key.
---------------------------------------------- ----------------------------------------------
Historically, queries that use Historically, queries that use
:meth:`~django.db.models.query.QuerySet.select_for_update()` could be :meth:`~django.db.models.query.QuerySet.select_for_update` could be
executed in autocommit mode, outside of a transaction. Before Django executed in autocommit mode, outside of a transaction. Before Django
1.6, Django's automatic transactions mode allowed this to be used to 1.6, Django's automatic transactions mode allowed this to be used to
lock records until the next write operation. Django 1.6 introduced lock records until the next write operation. Django 1.6 introduced
@ -1296,7 +1296,7 @@ project's needs. You should also check for any code that accesses
Miscellaneous Miscellaneous
------------- -------------
* The :meth:`django.core.files.uploadhandler.FileUploadHandler.new_file()` * The :meth:`django.core.files.uploadhandler.FileUploadHandler.new_file`
method is now passed an additional ``content_type_extra`` parameter. If you method is now passed an additional ``content_type_extra`` parameter. If you
have a custom :class:`~django.core.files.uploadhandler.FileUploadHandler` have a custom :class:`~django.core.files.uploadhandler.FileUploadHandler`
that implements ``new_file()``, be sure it accepts this new parameter. that implements ``new_file()``, be sure it accepts this new parameter.
@ -1344,7 +1344,7 @@ Miscellaneous
#) Use :djadmin:`loaddata` to import the fixtures you exported in (1). #) Use :djadmin:`loaddata` to import the fixtures you exported in (1).
* ``django.contrib.auth.models.AbstractUser`` no longer defines a * ``django.contrib.auth.models.AbstractUser`` no longer defines a
:meth:`~django.db.models.Model.get_absolute_url()` method. The old definition :meth:`~django.db.models.Model.get_absolute_url` method. The old definition
returned ``"/users/%s/" % urlquote(self.username)`` which was arbitrary returned ``"/users/%s/" % urlquote(self.username)`` which was arbitrary
since applications may or may not define such a url in ``urlpatterns``. since applications may or may not define such a url in ``urlpatterns``.
Define a ``get_absolute_url()`` method on your own custom user object or use Define a ``get_absolute_url()`` method on your own custom user object or use

View File

@ -123,7 +123,7 @@ initialization at the class level using transactions and savepoints. Database
backends which do not support transactions, like MySQL with the MyISAM storage backends which do not support transactions, like MySQL with the MyISAM storage
engine, will still be able to run these tests but won't benefit from the engine, will still be able to run these tests but won't benefit from the
improvements. Tests are now run within two nested improvements. Tests are now run within two nested
:func:`~django.db.transaction.atomic()` blocks: one for the whole class and one :func:`~django.db.transaction.atomic` blocks: one for the whole class and one
for each test. for each test.
* The class method * The class method
@ -242,7 +242,7 @@ Minor features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Session cookie is now deleted after * Session cookie is now deleted after
:meth:`~django.contrib.sessions.backends.base.SessionBase.flush()` is called. :meth:`~django.contrib.sessions.backends.base.SessionBase.flush` is called.
:mod:`django.contrib.sitemaps` :mod:`django.contrib.sitemaps`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -327,7 +327,7 @@ Forms
* Form widgets now render attributes with a value of ``True`` or ``False`` * Form widgets now render attributes with a value of ``True`` or ``False``
as HTML5 boolean attributes. as HTML5 boolean attributes.
* The new :meth:`~django.forms.Form.has_error()` method allows checking * The new :meth:`~django.forms.Form.has_error` method allows checking
if a specific error has happened. if a specific error has happened.
* If :attr:`~django.forms.Form.required_css_class` is defined on a form, then * If :attr:`~django.forms.Form.required_css_class` is defined on a form, then
@ -366,21 +366,21 @@ Generic Views
may now specify the ordering applied to the may now specify the ordering applied to the
:attr:`~django.views.generic.list.MultipleObjectMixin.queryset` by setting :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` by setting
:attr:`~django.views.generic.list.MultipleObjectMixin.ordering` or overriding :attr:`~django.views.generic.list.MultipleObjectMixin.ordering` or overriding
:meth:`~django.views.generic.list.MultipleObjectMixin.get_ordering()`. :meth:`~django.views.generic.list.MultipleObjectMixin.get_ordering`.
* The new :attr:`SingleObjectMixin.query_pk_and_slug * The new :attr:`SingleObjectMixin.query_pk_and_slug
<django.views.generic.detail.SingleObjectMixin.query_pk_and_slug>` <django.views.generic.detail.SingleObjectMixin.query_pk_and_slug>`
attribute allows changing the behavior of attribute allows changing the behavior of
:meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` :meth:`~django.views.generic.detail.SingleObjectMixin.get_object`
so that it'll perform its lookup using both the primary key and the slug. so that it'll perform its lookup using both the primary key and the slug.
* The :meth:`~django.views.generic.edit.FormMixin.get_form()` method doesn't * The :meth:`~django.views.generic.edit.FormMixin.get_form` method doesn't
require a ``form_class`` to be provided anymore. If not provided ``form_class`` require a ``form_class`` to be provided anymore. If not provided ``form_class``
defaults to :meth:`~django.views.generic.edit.FormMixin.get_form_class()`. defaults to :meth:`~django.views.generic.edit.FormMixin.get_form_class`.
* Placeholders in :attr:`ModelFormMixin.success_url * Placeholders in :attr:`ModelFormMixin.success_url
<django.views.generic.edit.ModelFormMixin.success_url>` now support the Python <django.views.generic.edit.ModelFormMixin.success_url>` now support the Python
:py:meth:`str.format()` syntax. The legacy ``%(<foo>)s`` syntax is still :py:meth:`str.format` syntax. The legacy ``%(<foo>)s`` syntax is still
supported but will be removed in Django 1.10. supported but will be removed in Django 1.10.
Internationalization Internationalization
@ -675,7 +675,7 @@ Related object operations are run in a transaction
-------------------------------------------------- --------------------------------------------------
Some operations on related objects such as Some operations on related objects such as
:meth:`~django.db.models.fields.related.RelatedManager.add()` or direct :meth:`~django.db.models.fields.related.RelatedManager.add` or direct
assignment ran multiple data modifying queries without wrapping them in assignment ran multiple data modifying queries without wrapping them in
transactions. To reduce the risk of data corruption, all data modifying methods transactions. To reduce the risk of data corruption, all data modifying methods
that affect multiple related objects (i.e. ``add()``, ``remove()``, that affect multiple related objects (i.e. ``add()``, ``remove()``,
@ -1182,7 +1182,7 @@ Miscellaneous
this will not happen any longer. It might be that new database migrations are this will not happen any longer. It might be that new database migrations are
generated (once) after migrating to 1.8. generated (once) after migrating to 1.8.
* :func:`django.utils.translation.get_language()` now returns ``None`` instead * :func:`django.utils.translation.get_language` now returns ``None`` instead
of :setting:`LANGUAGE_CODE` when translations are temporarily deactivated. of :setting:`LANGUAGE_CODE` when translations are temporarily deactivated.
* When a translation doesn't exist for a specific literal, the fallback is now * When a translation doesn't exist for a specific literal, the fallback is now
@ -1521,10 +1521,10 @@ to construct the "view on site" URL. This URL is now accessible using the
sure to provide a default value for the ``form_class`` argument since it's sure to provide a default value for the ``form_class`` argument since it's
now optional. now optional.
Rendering templates loaded by :func:`~django.template.loader.get_template()` with a :class:`~django.template.Context` Rendering templates loaded by :func:`~django.template.loader.get_template` with a :class:`~django.template.Context`
--------------------------------------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------------------------------------
The return type of :func:`~django.template.loader.get_template()` has changed The return type of :func:`~django.template.loader.get_template` has changed
in Django 1.8: instead of a :class:`django.template.Template`, it returns a in Django 1.8: instead of a :class:`django.template.Template`, it returns a
``Template`` instance whose exact type depends on which backend loaded it. ``Template`` instance whose exact type depends on which backend loaded it.
@ -1533,7 +1533,7 @@ Both classes provide a ``render()`` method, however, the former takes a
:class:`dict`. This change is enforced through a deprecation path for Django :class:`dict`. This change is enforced through a deprecation path for Django
templates. templates.
All this also applies to :func:`~django.template.loader.select_template()`. All this also applies to :func:`~django.template.loader.select_template`.
:class:`~django.template.Template` and :class:`~django.template.Context` classes in template responses :class:`~django.template.Template` and :class:`~django.template.Context` classes in template responses
------------------------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------
@ -1589,9 +1589,9 @@ pass a :class:`dict` in the ``context`` parameter instead. If you're passing a
The following functions will no longer accept a ``dirs`` parameter to override The following functions will no longer accept a ``dirs`` parameter to override
``TEMPLATE_DIRS`` in Django 1.10: ``TEMPLATE_DIRS`` in Django 1.10:
* :func:`django.template.loader.get_template()` * :func:`django.template.loader.get_template`
* :func:`django.template.loader.select_template()` * :func:`django.template.loader.select_template`
* :func:`django.shortcuts.render()` * :func:`django.shortcuts.render`
* ``django.shortcuts.render_to_response()`` * ``django.shortcuts.render_to_response()``
The parameter didn't work consistently across different template loaders and The parameter didn't work consistently across different template loaders and

View File

@ -207,7 +207,7 @@ Minor features
Django 1.9). Django 1.9).
* The permission argument of * The permission argument of
:func:`~django.contrib.auth.decorators.permission_required()` accepts all :func:`~django.contrib.auth.decorators.permission_required` accepts all
kinds of iterables, not only list and tuples. kinds of iterables, not only list and tuples.
* The new :class:`~django.contrib.auth.middleware.PersistentRemoteUserMiddleware` * The new :class:`~django.contrib.auth.middleware.PersistentRemoteUserMiddleware`
@ -364,7 +364,7 @@ Forms
allowing the field widget to be displayed disabled by browsers. allowing the field widget to be displayed disabled by browsers.
* It's now possible to customize bound fields by overriding a field's * It's now possible to customize bound fields by overriding a field's
:meth:`~django.forms.Field.get_bound_field()` method. :meth:`~django.forms.Field.get_bound_field` method.
Generic Views Generic Views
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -642,10 +642,10 @@ Tests
* Added the :meth:`json() <django.test.Response.json>` method to test client * Added the :meth:`json() <django.test.Response.json>` method to test client
responses to give access to the response body as JSON. responses to give access to the response body as JSON.
* Added the :meth:`~django.test.Client.force_login()` method to the test * Added the :meth:`~django.test.Client.force_login` method to the test
client. Use this method to simulate the effect of a user logging into the client. Use this method to simulate the effect of a user logging into the
site while skipping the authentication and verification steps of site while skipping the authentication and verification steps of
:meth:`~django.test.Client.login()`. :meth:`~django.test.Client.login`.
URLs URLs
~~~~ ~~~~

View File

@ -51,7 +51,7 @@ What's new in Django 2.0
Simplified URL routing syntax Simplified URL routing syntax
----------------------------- -----------------------------
The new :func:`django.urls.path()` function allows a simpler, more readable URL The new :func:`django.urls.path` function allows a simpler, more readable URL
routing syntax. For example, this example from previous Django releases:: routing syntax. For example, this example from previous Django releases::
url(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive), url(r"^articles/(?P<year>[0-9]{4})/$", views.year_archive),
@ -266,16 +266,16 @@ Models
:class:`~django.db.models.functions.Extract` now works with :class:`~django.db.models.functions.Extract` now works with
:class:`~django.db.models.DurationField`. :class:`~django.db.models.DurationField`.
* Added the ``of`` argument to :meth:`.QuerySet.select_for_update()`, supported * Added the ``of`` argument to :meth:`.QuerySet.select_for_update`, supported
on PostgreSQL and Oracle, to lock only rows from specific tables rather than on PostgreSQL and Oracle, to lock only rows from specific tables rather than
all selected tables. It may be helpful particularly when all selected tables. It may be helpful particularly when
:meth:`~.QuerySet.select_for_update()` is used in conjunction with :meth:`~.QuerySet.select_for_update` is used in conjunction with
:meth:`~.QuerySet.select_related()`. :meth:`~.QuerySet.select_related`.
* The new ``field_name`` parameter of :meth:`.QuerySet.in_bulk` allows fetching * The new ``field_name`` parameter of :meth:`.QuerySet.in_bulk` allows fetching
results based on any unique model field. results based on any unique model field.
* :meth:`.CursorWrapper.callproc()` now takes an optional dictionary of keyword * :meth:`.CursorWrapper.callproc` now takes an optional dictionary of keyword
parameters, if the backend supports this feature. Of Django's built-in parameters, if the backend supports this feature. Of Django's built-in
backends, only Oracle supports it. backends, only Oracle supports it.

View File

@ -47,7 +47,7 @@ Bugfixes
======== ========
* Fixed a data loss possibility in the * Fixed a data loss possibility in the
:meth:`~django.db.models.query.QuerySet.select_for_update()`. When using :meth:`~django.db.models.query.QuerySet.select_for_update`. When using
``'self'`` in the ``of`` argument with :ref:`multi-table inheritance ``'self'`` in the ``of`` argument with :ref:`multi-table inheritance
<multi-table-inheritance>`, a parent model was locked instead of the <multi-table-inheritance>`, a parent model was locked instead of the
queryset's model (:ticket:`30953`). queryset's model (:ticket:`30953`).

View File

@ -67,7 +67,7 @@ Minor features
* The ``admin_order_field`` attribute for elements in * The ``admin_order_field`` attribute for elements in
:attr:`.ModelAdmin.list_display` may now be a query expression. :attr:`.ModelAdmin.list_display` may now be a query expression.
* The new :meth:`.ModelAdmin.get_deleted_objects()` method allows customizing * The new :meth:`.ModelAdmin.get_deleted_objects` method allows customizing
the deletion process of the delete view and the "delete selected" action. the deletion process of the delete view and the "delete selected" action.
* The ``actions.html``, ``change_list_results.html``, ``date_hierarchy.html``, * The ``actions.html``, ``change_list_results.html``, ``date_hierarchy.html``,

View File

@ -28,7 +28,7 @@ Bugfixes
======== ========
* Fixed a data loss possibility in the * Fixed a data loss possibility in the
:meth:`~django.db.models.query.QuerySet.select_for_update()`. When using :meth:`~django.db.models.query.QuerySet.select_for_update`. When using
related fields pointing to a proxy model in the ``of`` argument, the related fields pointing to a proxy model in the ``of`` argument, the
corresponding model was not locked (:ticket:`31866`). corresponding model was not locked (:ticket:`31866`).

View File

@ -56,7 +56,7 @@ Bugfixes
``default`` entry was empty (:ticket:`31021`). ``default`` entry was empty (:ticket:`31021`).
* Fixed a data loss possibility in the * Fixed a data loss possibility in the
:meth:`~django.db.models.query.QuerySet.select_for_update()`. When using :meth:`~django.db.models.query.QuerySet.select_for_update`. When using
``'self'`` in the ``of`` argument with :ref:`multi-table inheritance ``'self'`` in the ``of`` argument with :ref:`multi-table inheritance
<multi-table-inheritance>`, a parent model was locked instead of the <multi-table-inheritance>`, a parent model was locked instead of the
queryset's model (:ticket:`30953`). queryset's model (:ticket:`30953`).

View File

@ -28,7 +28,7 @@ Bugfixes
======== ========
* Fixed a data loss possibility in the * Fixed a data loss possibility in the
:meth:`~django.db.models.query.QuerySet.select_for_update()`. When using :meth:`~django.db.models.query.QuerySet.select_for_update`. When using
related fields pointing to a proxy model in the ``of`` argument, the related fields pointing to a proxy model in the ``of`` argument, the
corresponding model was not locked (:ticket:`31866`). corresponding model was not locked (:ticket:`31866`).

View File

@ -126,9 +126,9 @@ Minor features
* Added :class:`~django.contrib.auth.backends.BaseBackend` class to ease * Added :class:`~django.contrib.auth.backends.BaseBackend` class to ease
customization of authentication backends. customization of authentication backends.
* Added :meth:`~django.contrib.auth.models.User.get_user_permissions()` method * Added :meth:`~django.contrib.auth.models.User.get_user_permissions` method
to mirror the existing to mirror the existing
:meth:`~django.contrib.auth.models.User.get_group_permissions()` method. :meth:`~django.contrib.auth.models.User.get_group_permissions` method.
* Added HTML ``autocomplete`` attribute to widgets of username, email, and * Added HTML ``autocomplete`` attribute to widgets of username, email, and
password fields in :mod:`django.contrib.auth.forms` for better interaction password fields in :mod:`django.contrib.auth.forms` for better interaction
@ -182,7 +182,7 @@ Minor features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The new * The new
:meth:`~django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age()` :meth:`~django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age`
method allows dynamically specifying the session cookie age. method allows dynamically specifying the session cookie age.
:mod:`django.contrib.syndication` :mod:`django.contrib.syndication`
@ -190,7 +190,7 @@ Minor features
* Added the ``language`` class attribute to the * Added the ``language`` class attribute to the
:class:`django.contrib.syndication.views.Feed` to customize a feed language. :class:`django.contrib.syndication.views.Feed` to customize a feed language.
The default value is :func:`~django.utils.translation.get_language()` instead The default value is :func:`~django.utils.translation.get_language` instead
of :setting:`LANGUAGE_CODE`. of :setting:`LANGUAGE_CODE`.
Cache Cache
@ -213,7 +213,7 @@ Forms
* Formsets may control the widget used when ordering forms via * Formsets may control the widget used when ordering forms via
:attr:`~django.forms.formsets.BaseFormSet.can_order` by setting the :attr:`~django.forms.formsets.BaseFormSet.can_order` by setting the
:attr:`~django.forms.formsets.BaseFormSet.ordering_widget` attribute or :attr:`~django.forms.formsets.BaseFormSet.ordering_widget` attribute or
overriding :attr:`~django.forms.formsets.BaseFormSet.get_ordering_widget()`. overriding :attr:`~django.forms.formsets.BaseFormSet.get_ordering_widget`.
Internationalization Internationalization
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~

View File

@ -40,7 +40,7 @@ Bugfixes
rendering (:ticket:`31865`). rendering (:ticket:`31865`).
* Fixed a data loss possibility in the * Fixed a data loss possibility in the
:meth:`~django.db.models.query.QuerySet.select_for_update()`. When using :meth:`~django.db.models.query.QuerySet.select_for_update`. When using
related fields pointing to a proxy model in the ``of`` argument, the related fields pointing to a proxy model in the ``of`` argument, the
corresponding model was not locked (:ticket:`31866`). corresponding model was not locked (:ticket:`31866`).

View File

@ -654,7 +654,7 @@ Miscellaneous
:attr:`~django.http.HttpResponse.content`. :attr:`~django.http.HttpResponse.content`.
* ``django.utils.decorators.classproperty()`` decorator is made public and * ``django.utils.decorators.classproperty()`` decorator is made public and
moved to :class:`django.utils.functional.classproperty()`. moved to :class:`django.utils.functional.classproperty`.
* :tfilter:`floatformat` template filter now outputs (positive) ``0`` for * :tfilter:`floatformat` template filter now outputs (positive) ``0`` for
negative numbers which round to zero. negative numbers which round to zero.

View File

@ -380,7 +380,7 @@ Migrations
Models Models
~~~~~~ ~~~~~~
* The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update()`, * The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update`,
supported on PostgreSQL, allows acquiring weaker locks that don't block the supported on PostgreSQL, allows acquiring weaker locks that don't block the
creation of rows that reference locked rows through a foreign key. creation of rows that reference locked rows through a foreign key.
@ -400,7 +400,7 @@ Models
* :class:`FilteredRelation() <django.db.models.FilteredRelation>` now supports * :class:`FilteredRelation() <django.db.models.FilteredRelation>` now supports
nested relations. nested relations.
* The ``of`` argument of :meth:`.QuerySet.select_for_update()` is now allowed * The ``of`` argument of :meth:`.QuerySet.select_for_update` is now allowed
on MySQL 8.0.1+. on MySQL 8.0.1+.
* :class:`Value() <django.db.models.Value>` expression now * :class:`Value() <django.db.models.Value>` expression now
@ -422,7 +422,7 @@ Models
* The new :class:`~django.db.models.functions.Collate` function allows * The new :class:`~django.db.models.functions.Collate` function allows
filtering and ordering by specified database collations. filtering and ordering by specified database collations.
* The ``field_name`` argument of :meth:`.QuerySet.in_bulk()` now accepts * The ``field_name`` argument of :meth:`.QuerySet.in_bulk` now accepts
distinct fields if there's only one field specified in distinct fields if there's only one field specified in
:meth:`.QuerySet.distinct`. :meth:`.QuerySet.distinct`.

View File

@ -324,7 +324,7 @@ Models
specifying a value to return when the function is used over an empty result specifying a value to return when the function is used over an empty result
set. set.
* The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now * The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update` is now
allowed on MariaDB 10.6+. allowed on MariaDB 10.6+.
* :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet`` * :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet``

View File

@ -145,7 +145,7 @@ Minor features
:mod:`django.contrib.gis` :mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
* The new :meth:`.GEOSGeometry.make_valid()` method allows converting invalid * The new :meth:`.GEOSGeometry.make_valid` method allows converting invalid
geometries to valid ones. geometries to valid ones.
* The new ``clone`` argument for :meth:`.GEOSGeometry.normalize` allows * The new ``clone`` argument for :meth:`.GEOSGeometry.normalize` allows

View File

@ -17,7 +17,7 @@ brackets.
CVE-2024-39329: Username enumeration through timing difference for users with unusable passwords CVE-2024-39329: Username enumeration through timing difference for users with unusable passwords
================================================================================================ ================================================================================================
The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate()` method The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate` method
allowed remote attackers to enumerate users via a timing attack involving login allowed remote attackers to enumerate users via a timing attack involving login
requests for users with unusable passwords. requests for users with unusable passwords.

View File

@ -17,7 +17,7 @@ brackets.
CVE-2024-39329: Username enumeration through timing difference for users with unusable passwords CVE-2024-39329: Username enumeration through timing difference for users with unusable passwords
================================================================================================ ================================================================================================
The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate()` method The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate` method
allowed remote attackers to enumerate users via a timing attack involving login allowed remote attackers to enumerate users via a timing attack involving login
requests for users with unusable passwords. requests for users with unusable passwords.

View File

@ -73,7 +73,7 @@ See :doc:`/topics/composite-primary-key` for more details.
Simplified override of :class:`~django.forms.BoundField` Simplified override of :class:`~django.forms.BoundField`
-------------------------------------------------------- --------------------------------------------------------
Prior to version 5.2, overriding :meth:`.Field.get_bound_field()` was the only Prior to version 5.2, overriding :meth:`.Field.get_bound_field` was the only
option to use a custom :class:`~django.forms.BoundField`. Django now supports option to use a custom :class:`~django.forms.BoundField`. Django now supports
specifying the following attributes to customize form rendering: specifying the following attributes to customize form rendering:

View File

@ -46,7 +46,7 @@ Specifying authentication backends
Behind the scenes, Django maintains a list of "authentication backends" that it Behind the scenes, Django maintains a list of "authentication backends" that it
checks for authentication. When somebody calls checks for authentication. When somebody calls
:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log :func:`django.contrib.auth.authenticate` -- as described in :ref:`How to log
a user in <how-to-log-a-user-in>` -- Django tries authenticating across a user in <how-to-log-a-user-in>` -- Django tries authenticating across
all of its authentication backends. If the first authentication method fails, all of its authentication backends. If the first authentication method fails,
Django tries the second one, and so on, until all backends have been attempted. Django tries the second one, and so on, until all backends have been attempted.
@ -187,12 +187,12 @@ Handling authorization in custom backends
Custom auth backends can provide their own permissions. Custom auth backends can provide their own permissions.
The user model and its manager will delegate permission lookup functions The user model and its manager will delegate permission lookup functions
(:meth:`~django.contrib.auth.models.User.get_user_permissions()`, (:meth:`~django.contrib.auth.models.User.get_user_permissions`,
:meth:`~django.contrib.auth.models.User.get_group_permissions()`, :meth:`~django.contrib.auth.models.User.get_group_permissions`,
:meth:`~django.contrib.auth.models.User.get_all_permissions()`, :meth:`~django.contrib.auth.models.User.get_all_permissions`,
:meth:`~django.contrib.auth.models.User.has_perm()`, :meth:`~django.contrib.auth.models.User.has_perm`,
:meth:`~django.contrib.auth.models.User.has_module_perms()`, and :meth:`~django.contrib.auth.models.User.has_module_perms`, and
:meth:`~django.contrib.auth.models.UserManager.with_perm()`) to any :meth:`~django.contrib.auth.models.UserManager.with_perm`) to any
authentication backend that implements these functions. authentication backend that implements these functions.
The permissions given to the user will be the superset of all permissions The permissions given to the user will be the superset of all permissions
@ -200,8 +200,8 @@ returned by all backends. That is, Django grants a permission to a user that
any one backend grants. any one backend grants.
If a backend raises a :class:`~django.core.exceptions.PermissionDenied` If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
exception in :meth:`~django.contrib.auth.models.User.has_perm()` or exception in :meth:`~django.contrib.auth.models.User.has_perm` or
:meth:`~django.contrib.auth.models.User.has_module_perms()`, the authorization :meth:`~django.contrib.auth.models.User.has_module_perms`, the authorization
will immediately fail and Django won't check the backends that follow. will immediately fail and Django won't check the backends that follow.
A backend could implement permissions for the magic admin like this:: A backend could implement permissions for the magic admin like this::
@ -694,7 +694,7 @@ The following attributes and methods are available on any subclass of
When the raw_password is ``None``, the password will be set to an When the raw_password is ``None``, the password will be set to an
unusable password, as if unusable password, as if
:meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password`
were used. were used.
.. method:: models.AbstractBaseUser.check_password(raw_password) .. method:: models.AbstractBaseUser.check_password(raw_password)
@ -710,7 +710,7 @@ The following attributes and methods are available on any subclass of
Marks the user as having no password set. This isn't the same as Marks the user as having no password set. This isn't the same as
having a blank string for a password. having a blank string for a password.
:meth:`~django.contrib.auth.models.AbstractBaseUser.check_password()` for this user :meth:`~django.contrib.auth.models.AbstractBaseUser.check_password` for this user
will never return ``True``. Doesn't save the will never return ``True``. Doesn't save the
:class:`~django.contrib.auth.models.AbstractBaseUser` object. :class:`~django.contrib.auth.models.AbstractBaseUser` object.
@ -720,7 +720,7 @@ The following attributes and methods are available on any subclass of
.. method:: models.AbstractBaseUser.has_usable_password() .. method:: models.AbstractBaseUser.has_usable_password()
Returns ``False`` if Returns ``False`` if
:meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` has :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password` has
been called for this user. been called for this user.
.. method:: models.AbstractBaseUser.get_session_auth_hash() .. method:: models.AbstractBaseUser.get_session_auth_hash()

View File

@ -97,7 +97,7 @@ do not supply a user, the command will attempt to change the password
whose username matches the current system user. whose username matches the current system user.
You can also change a password programmatically, using You can also change a password programmatically, using
:meth:`~django.contrib.auth.models.User.set_password()`: :meth:`~django.contrib.auth.models.User.set_password`:
.. code-block:: pycon .. code-block:: pycon
@ -124,7 +124,7 @@ Authenticating users
*Asynchronous version*: ``aauthenticate()`` *Asynchronous version*: ``aauthenticate()``
Use :func:`~django.contrib.auth.authenticate()` to verify a set of Use :func:`~django.contrib.auth.authenticate` to verify a set of
credentials. It takes credentials as keyword arguments, ``username`` and credentials. It takes credentials as keyword arguments, ``username`` and
``password`` for the default case, checks them against each ``password`` for the default case, checks them against each
:ref:`authentication backend <authentication-backends>`, and returns a :ref:`authentication backend <authentication-backends>`, and returns a
@ -410,18 +410,18 @@ If you have an authenticated user you want to attach to the current session
*Asynchronous version*: ``alogin()`` *Asynchronous version*: ``alogin()``
To log a user in, from a view, use :func:`~django.contrib.auth.login()`. It To log a user in, from a view, use :func:`~django.contrib.auth.login`. It
takes an :class:`~django.http.HttpRequest` object and a takes an :class:`~django.http.HttpRequest` object and a
:class:`~django.contrib.auth.models.User` object. :class:`~django.contrib.auth.models.User` object.
:func:`~django.contrib.auth.login()` saves the user's ID in the session, :func:`~django.contrib.auth.login` saves the user's ID in the session,
using Django's session framework. using Django's session framework.
Note that any data set during the anonymous session is retained in the Note that any data set during the anonymous session is retained in the
session after a user logs in. session after a user logs in.
This example shows how you might use both This example shows how you might use both
:func:`~django.contrib.auth.authenticate()` and :func:`~django.contrib.auth.authenticate` and
:func:`~django.contrib.auth.login()`:: :func:`~django.contrib.auth.login`::
from django.contrib.auth import authenticate, login from django.contrib.auth import authenticate, login
@ -449,9 +449,9 @@ is selected as follows:
#. Use the value of the optional ``backend`` argument, if provided. #. Use the value of the optional ``backend`` argument, if provided.
#. Use the value of the ``user.backend`` attribute, if present. This allows #. Use the value of the ``user.backend`` attribute, if present. This allows
pairing :func:`~django.contrib.auth.authenticate()` and pairing :func:`~django.contrib.auth.authenticate` and
:func:`~django.contrib.auth.login()`: :func:`~django.contrib.auth.login`:
:func:`~django.contrib.auth.authenticate()` :func:`~django.contrib.auth.authenticate`
sets the ``user.backend`` attribute on the user object it returns. sets the ``user.backend`` attribute on the user object it returns.
#. Use the ``backend`` in :setting:`AUTHENTICATION_BACKENDS`, if there is only #. Use the ``backend`` in :setting:`AUTHENTICATION_BACKENDS`, if there is only
one. one.
@ -470,8 +470,8 @@ How to log a user out
*Asynchronous version*: ``alogout()`` *Asynchronous version*: ``alogout()``
To log out a user who has been logged in via To log out a user who has been logged in via
:func:`django.contrib.auth.login()`, use :func:`django.contrib.auth.login`, use
:func:`django.contrib.auth.logout()` within your view. It takes an :func:`django.contrib.auth.logout` within your view. It takes an
:class:`~django.http.HttpRequest` object and has no return value. :class:`~django.http.HttpRequest` object and has no return value.
Example:: Example::
@ -482,16 +482,16 @@ How to log a user out
logout(request) logout(request)
# Redirect to a success page. # Redirect to a success page.
Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors if Note that :func:`~django.contrib.auth.logout` doesn't throw any errors if
the user wasn't logged in. the user wasn't logged in.
When you call :func:`~django.contrib.auth.logout()`, the session data for When you call :func:`~django.contrib.auth.logout`, the session data for
the current request is completely cleaned out. All existing data is the current request is completely cleaned out. All existing data is
removed. This is to prevent another person from using the same web browser removed. This is to prevent another person from using the same web browser
to log in and have access to the previous user's session data. If you want to log in and have access to the previous user's session data. If you want
to put anything into the session that will be available to the user to put anything into the session that will be available to the user
immediately after logging out, do that *after* calling immediately after logging out, do that *after* calling
:func:`django.contrib.auth.logout()`. :func:`django.contrib.auth.logout`.
Limiting access to logged-in users Limiting access to logged-in users
---------------------------------- ----------------------------------
@ -769,7 +769,7 @@ The ``permission_required`` decorator
It's a relatively common task to check whether a user has a particular It's a relatively common task to check whether a user has a particular
permission. For that reason, Django provides a shortcut for that case: the permission. For that reason, Django provides a shortcut for that case: the
:func:`~django.contrib.auth.decorators.permission_required()` decorator:: :func:`~django.contrib.auth.decorators.permission_required` decorator::
from django.contrib.auth.decorators import permission_required from django.contrib.auth.decorators import permission_required
@ -785,7 +785,7 @@ The ``permission_required`` decorator
The decorator may also take an iterable of permissions, in which case the The decorator may also take an iterable of permissions, in which case the
user must have all of the permissions in order to access the view. user must have all of the permissions in order to access the view.
Note that :func:`~django.contrib.auth.decorators.permission_required()` Note that :func:`~django.contrib.auth.decorators.permission_required`
also takes an optional ``login_url`` parameter:: also takes an optional ``login_url`` parameter::
from django.contrib.auth.decorators import permission_required from django.contrib.auth.decorators import permission_required
@ -856,8 +856,8 @@ To apply permission checks to :doc:`class-based views
Returns a boolean denoting whether the current user has permission to Returns a boolean denoting whether the current user has permission to
execute the decorated view. By default, this returns the result of execute the decorated view. By default, this returns the result of
calling :meth:`~django.contrib.auth.models.User.has_perms()` with the calling :meth:`~django.contrib.auth.models.User.has_perms` with the
list of permissions returned by :meth:`get_permission_required()`. list of permissions returned by :meth:`get_permission_required`.
Redirecting unauthorized requests in class-based views Redirecting unauthorized requests in class-based views
------------------------------------------------------ ------------------------------------------------------
@ -930,7 +930,7 @@ Session invalidation on password change
If your :setting:`AUTH_USER_MODEL` inherits from If your :setting:`AUTH_USER_MODEL` inherits from
:class:`~django.contrib.auth.models.AbstractBaseUser` or implements its own :class:`~django.contrib.auth.models.AbstractBaseUser` or implements its own
:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()` :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`
method, authenticated sessions will include the hash returned by this function. method, authenticated sessions will include the hash returned by this function.
In the :class:`~django.contrib.auth.models.AbstractBaseUser` case, this is an In the :class:`~django.contrib.auth.models.AbstractBaseUser` case, this is an
HMAC of the password field. Django verifies that the hash in the session for HMAC of the password field. Django verifies that the hash in the session for
@ -972,7 +972,7 @@ function.
.. note:: .. note::
Since Since
:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()` :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`
is based on :setting:`SECRET_KEY`, secret key values must be is based on :setting:`SECRET_KEY`, secret key values must be
rotated to avoid invalidating existing sessions when updating your site to rotated to avoid invalidating existing sessions when updating your site to
use a new secret. See :setting:`SECRET_KEY_FALLBACKS` for details. use a new secret. See :setting:`SECRET_KEY_FALLBACKS` for details.
@ -1635,10 +1635,10 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
``password2`` are non empty and match, validates the password using ``password2`` are non empty and match, validates the password using
:func:`~django.contrib.auth.password_validation.validate_password`, and :func:`~django.contrib.auth.password_validation.validate_password`, and
sets the user's password using sets the user's password using
:meth:`~django.contrib.auth.models.User.set_password()`. :meth:`~django.contrib.auth.models.User.set_password`.
If ``usable_password`` is disabled, no password validation is done, and If ``usable_password`` is disabled, no password validation is done, and
password-based authentication is disabled for the user by calling password-based authentication is disabled for the user by calling
:meth:`~django.contrib.auth.models.User.set_unusable_password()`. :meth:`~django.contrib.auth.models.User.set_unusable_password`.
.. class:: AuthenticationForm .. class:: AuthenticationForm
@ -1696,7 +1696,7 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
validates the password using validates the password using
:func:`~django.contrib.auth.password_validation.validate_password`, and :func:`~django.contrib.auth.password_validation.validate_password`, and
sets the user's password using sets the user's password using
:meth:`~django.contrib.auth.models.User.set_password()`. :meth:`~django.contrib.auth.models.User.set_password`.
.. class:: PasswordChangeForm .. class:: PasswordChangeForm

View File

@ -71,20 +71,20 @@ they can work out which model class to use:
* If the :attr:`~django.views.generic.edit.ModelFormMixin.model` attribute is * If the :attr:`~django.views.generic.edit.ModelFormMixin.model` attribute is
given, that model class will be used. given, that model class will be used.
* If :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` * If :meth:`~django.views.generic.detail.SingleObjectMixin.get_object`
returns an object, the class of that object will be used. returns an object, the class of that object will be used.
* If a :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` is * If a :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` is
given, the model for that queryset will be used. given, the model for that queryset will be used.
Model form views provide a Model form views provide a
:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` implementation :meth:`~django.views.generic.edit.ModelFormMixin.form_valid` implementation
that saves the model automatically. You can override this if you have any that saves the model automatically. You can override this if you have any
special requirements; see below for examples. special requirements; see below for examples.
You don't even need to provide a ``success_url`` for You don't even need to provide a ``success_url`` for
:class:`~django.views.generic.edit.CreateView` or :class:`~django.views.generic.edit.CreateView` or
:class:`~django.views.generic.edit.UpdateView` - they will use :class:`~django.views.generic.edit.UpdateView` - they will use
:meth:`~django.db.models.Model.get_absolute_url()` on the model object if available. :meth:`~django.db.models.Model.get_absolute_url` on the model object if available.
If you want to use a custom :class:`~django.forms.ModelForm` (for instance to If you want to use a custom :class:`~django.forms.ModelForm` (for instance to
add extra validation), set add extra validation), set
@ -95,7 +95,7 @@ add extra validation), set
even though the :attr:`~django.views.generic.edit.FormMixin.form_class` may even though the :attr:`~django.views.generic.edit.FormMixin.form_class` may
be a :class:`~django.forms.ModelForm`. be a :class:`~django.forms.ModelForm`.
First we need to add :meth:`~django.db.models.Model.get_absolute_url()` to our First we need to add :meth:`~django.db.models.Model.get_absolute_url` to our
``Author`` class: ``Author`` class:
.. code-block:: python .. code-block:: python
@ -208,7 +208,7 @@ the foreign key relation to the model:
In the view, ensure that you don't include ``created_by`` in the list of fields In the view, ensure that you don't include ``created_by`` in the list of fields
to edit, and override to edit, and override
:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the user: :meth:`~django.views.generic.edit.ModelFormMixin.form_valid` to add the user:
.. code-block:: python .. code-block:: python
:caption: ``views.py`` :caption: ``views.py``
@ -228,7 +228,7 @@ to edit, and override
:class:`~django.contrib.auth.mixins.LoginRequiredMixin` prevents users who :class:`~django.contrib.auth.mixins.LoginRequiredMixin` prevents users who
aren't logged in from accessing the form. If you omit that, you'll need to aren't logged in from accessing the form. If you omit that, you'll need to
handle unauthorized users in :meth:`~.ModelFormMixin.form_valid()`. handle unauthorized users in :meth:`~.ModelFormMixin.form_valid`.
.. _content-negotiation-example: .. _content-negotiation-example:

View File

@ -34,7 +34,7 @@ interface to working with templates in class-based views.
:class:`~django.views.generic.base.TemplateResponseMixin` :class:`~django.views.generic.base.TemplateResponseMixin`
Every built in view which returns a Every built in view which returns a
:class:`~django.template.response.TemplateResponse` will call the :class:`~django.template.response.TemplateResponse` will call the
:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
method that ``TemplateResponseMixin`` provides. Most of the time this method that ``TemplateResponseMixin`` provides. Most of the time this
will be called for you (for instance, it is called by the ``get()`` method will be called for you (for instance, it is called by the ``get()`` method
implemented by both :class:`~django.views.generic.base.TemplateView` and implemented by both :class:`~django.views.generic.base.TemplateView` and
@ -58,7 +58,7 @@ interface to working with templates in class-based views.
:class:`~django.views.generic.base.ContextMixin` :class:`~django.views.generic.base.ContextMixin`
Every built in view which needs context data, such as for rendering a Every built in view which needs context data, such as for rendering a
template (including ``TemplateResponseMixin`` above), should call template (including ``TemplateResponseMixin`` above), should call
:meth:`~django.views.generic.base.ContextMixin.get_context_data()` passing :meth:`~django.views.generic.base.ContextMixin.get_context_data` passing
any data they want to ensure is in there as keyword arguments. any data they want to ensure is in there as keyword arguments.
``get_context_data()`` returns a dictionary; in ``ContextMixin`` it ``get_context_data()`` returns a dictionary; in ``ContextMixin`` it
returns its keyword arguments, but it is common to override this to add returns its keyword arguments, but it is common to override this to add
@ -106,7 +106,7 @@ URLConf, and looks the object up either from the
on the view, or the on the view, or the
:attr:`~django.views.generic.detail.SingleObjectMixin.queryset` :attr:`~django.views.generic.detail.SingleObjectMixin.queryset`
attribute if that's provided). ``SingleObjectMixin`` also overrides attribute if that's provided). ``SingleObjectMixin`` also overrides
:meth:`~django.views.generic.base.ContextMixin.get_context_data()`, :meth:`~django.views.generic.base.ContextMixin.get_context_data`,
which is used across all Django's built in class-based views to supply which is used across all Django's built in class-based views to supply
context data for template renders. context data for template renders.
@ -115,7 +115,7 @@ To then make a :class:`~django.template.response.TemplateResponse`,
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`, :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`,
which extends :class:`~django.views.generic.base.TemplateResponseMixin`, which extends :class:`~django.views.generic.base.TemplateResponseMixin`,
overriding overriding
:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`
as discussed above. It actually provides a fairly sophisticated set of options, as discussed above. It actually provides a fairly sophisticated set of options,
but the main one that most people are going to use is but the main one that most people are going to use is
``<app_label>/<model_name>_detail.html``. The ``_detail`` part can be changed ``<app_label>/<model_name>_detail.html``. The ``_detail`` part can be changed
@ -151,7 +151,7 @@ here would be to dynamically vary the objects, such as depending on
the current user or to exclude posts in the future for a blog. the current user or to exclude posts in the future for a blog.
:class:`~django.views.generic.list.MultipleObjectMixin` also overrides :class:`~django.views.generic.list.MultipleObjectMixin` also overrides
:meth:`~django.views.generic.base.ContextMixin.get_context_data()` to :meth:`~django.views.generic.base.ContextMixin.get_context_data` to
include appropriate context variables for pagination (providing include appropriate context variables for pagination (providing
dummies if pagination is disabled). It relies on ``object_list`` being dummies if pagination is disabled). It relies on ``object_list`` being
passed in as a keyword argument, which :class:`ListView` arranges for passed in as a keyword argument, which :class:`ListView` arranges for
@ -296,7 +296,7 @@ object. In order to do this, we need to have two different querysets:
override ``get_queryset()`` and use the ``Publisher``s :ref:`reverse override ``get_queryset()`` and use the ``Publisher``s :ref:`reverse
foreign key manager<backwards-related-objects>`. foreign key manager<backwards-related-objects>`.
``Publisher`` queryset for use in :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` ``Publisher`` queryset for use in :meth:`~django.views.generic.detail.SingleObjectMixin.get_object`
We'll rely on the default implementation of ``get_object()`` to fetch the We'll rely on the default implementation of ``get_object()`` to fetch the
correct ``Publisher`` object. correct ``Publisher`` object.
However, we need to explicitly pass a ``queryset`` argument because However, we need to explicitly pass a ``queryset`` argument because
@ -565,12 +565,12 @@ the author we're talking about, and we have to remember to set
return reverse("author-detail", kwargs={"pk": self.object.pk}) return reverse("author-detail", kwargs={"pk": self.object.pk})
Finally we bring this together in a new ``AuthorView`` view. We Finally we bring this together in a new ``AuthorView`` view. We
already know that calling :meth:`~django.views.generic.base.View.as_view()` on already know that calling :meth:`~django.views.generic.base.View.as_view` on
a class-based view gives us something that behaves exactly like a function a class-based view gives us something that behaves exactly like a function
based view, so we can do that at the point we choose between the two subviews. based view, so we can do that at the point we choose between the two subviews.
You can pass through keyword arguments to You can pass through keyword arguments to
:meth:`~django.views.generic.base.View.as_view()` in the same way you :meth:`~django.views.generic.base.View.as_view` in the same way you
would in your URLconf, such as if you wanted the ``AuthorInterestFormView`` would in your URLconf, such as if you wanted the ``AuthorInterestFormView``
behavior to also appear at another URL but using a different template:: behavior to also appear at another URL but using a different template::
@ -636,7 +636,7 @@ For example, a JSON mixin might look something like this::
JSON. JSON.
This mixin provides a ``render_to_json_response()`` method with the same signature This mixin provides a ``render_to_json_response()`` method with the same signature
as :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`. as :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response`.
To use it, we need to mix it into a ``TemplateView`` for example, and override To use it, we need to mix it into a ``TemplateView`` for example, and override
``render_to_response()`` to call ``render_to_json_response()`` instead:: ``render_to_response()`` to call ``render_to_json_response()`` instead::
@ -672,7 +672,7 @@ the HTTP request, such as a query argument or an HTTP header. Mix in both the
``JSONResponseMixin`` and a ``JSONResponseMixin`` and a
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`, :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`,
and override the implementation of and override the implementation of
:func:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
to defer to the appropriate rendering method depending on the type of response to defer to the appropriate rendering method depending on the type of response
that the user requested:: that the user requested::
@ -691,5 +691,5 @@ that the user requested::
Because of the way that Python resolves method overloading, the call to Because of the way that Python resolves method overloading, the call to
``super().render_to_response(context)`` ends up calling the ``super().render_to_response(context)`` ends up calling the
:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
implementation of :class:`~django.views.generic.base.TemplateResponseMixin`. implementation of :class:`~django.views.generic.base.TemplateResponseMixin`.

View File

@ -966,7 +966,7 @@ See :ref:`ref-models-update-fields` for more details.
.. admonition:: Overridden model methods are not called on bulk operations .. admonition:: Overridden model methods are not called on bulk operations
Note that the :meth:`~Model.delete()` method for an object is not Note that the :meth:`~Model.delete` method for an object is not
necessarily called when :ref:`deleting objects in bulk using a necessarily called when :ref:`deleting objects in bulk using a
QuerySet <topics-db-queries-delete>` or as a result of a :attr:`cascading QuerySet <topics-db-queries-delete>` or as a result of a :attr:`cascading
delete <django.db.models.ForeignKey.on_delete>`. To ensure customized delete <django.db.models.ForeignKey.on_delete>`. To ensure customized
@ -977,7 +977,7 @@ See :ref:`ref-models-update-fields` for more details.
Unfortunately, there isn't a workaround when Unfortunately, there isn't a workaround when
:meth:`creating<django.db.models.query.QuerySet.bulk_create>` or :meth:`creating<django.db.models.query.QuerySet.bulk_create>` or
:meth:`updating<django.db.models.query.QuerySet.update>` objects in bulk, :meth:`updating<django.db.models.query.QuerySet.update>` objects in bulk,
since none of :meth:`~Model.save()`, since none of :meth:`~Model.save`,
:data:`~django.db.models.signals.pre_save`, and :data:`~django.db.models.signals.pre_save`, and
:data:`~django.db.models.signals.post_save` are called. :data:`~django.db.models.signals.post_save` are called.

View File

@ -40,9 +40,9 @@ Use standard DB optimization techniques
:attr:`Meta.indexes <django.db.models.Options.indexes>` or :attr:`Meta.indexes <django.db.models.Options.indexes>` or
:attr:`Field.db_index <django.db.models.Field.db_index>` to add these from :attr:`Field.db_index <django.db.models.Field.db_index>` to add these from
Django. Consider adding indexes to fields that you frequently query using Django. Consider adding indexes to fields that you frequently query using
:meth:`~django.db.models.query.QuerySet.filter()`, :meth:`~django.db.models.query.QuerySet.filter`,
:meth:`~django.db.models.query.QuerySet.exclude()`, :meth:`~django.db.models.query.QuerySet.exclude`,
:meth:`~django.db.models.query.QuerySet.order_by()`, etc. as indexes may help :meth:`~django.db.models.query.QuerySet.order_by`, etc. as indexes may help
to speed up lookups. Note that determining the best indexes is a complex to speed up lookups. Note that determining the best indexes is a complex
database-dependent topic that will depend on your particular application. database-dependent topic that will depend on your particular application.
The overhead of maintaining an index may outweigh any gains in query speed. The overhead of maintaining an index may outweigh any gains in query speed.
@ -115,7 +115,7 @@ Use ``iterator()``
When you have a lot of objects, the caching behavior of the ``QuerySet`` can When you have a lot of objects, the caching behavior of the ``QuerySet`` can
cause a large amount of memory to be used. In this case, cause a large amount of memory to be used. In this case,
:meth:`~django.db.models.query.QuerySet.iterator()` may help. :meth:`~django.db.models.query.QuerySet.iterator` may help.
Use ``explain()`` Use ``explain()``
----------------- -----------------
@ -227,7 +227,7 @@ Use ``QuerySet.values()`` and ``values_list()``
When you only want a ``dict`` or ``list`` of values, and don't need ORM model When you only want a ``dict`` or ``list`` of values, and don't need ORM model
objects, make appropriate usage of objects, make appropriate usage of
:meth:`~django.db.models.query.QuerySet.values()`. :meth:`~django.db.models.query.QuerySet.values`.
These can be useful for replacing model objects in template code - as long as These can be useful for replacing model objects in template code - as long as
the dicts you supply have the same attributes as those used in the template, the dicts you supply have the same attributes as those used in the template,
you are fine. you are fine.
@ -235,8 +235,8 @@ you are fine.
Use ``QuerySet.defer()`` and ``only()`` Use ``QuerySet.defer()`` and ``only()``
--------------------------------------- ---------------------------------------
Use :meth:`~django.db.models.query.QuerySet.defer()` and Use :meth:`~django.db.models.query.QuerySet.defer` and
:meth:`~django.db.models.query.QuerySet.only()` if there are database columns :meth:`~django.db.models.query.QuerySet.only` if there are database columns
you know that you won't need (or won't need in most cases) to avoid loading you know that you won't need (or won't need in most cases) to avoid loading
them. Note that if you *do* use them, the ORM will have to go and get them in them. Note that if you *do* use them, the ORM will have to go and get them in
a separate query, making this a pessimization if you use it inappropriately. a separate query, making this a pessimization if you use it inappropriately.
@ -349,7 +349,7 @@ Ordering is not free; each field to order by is an operation the database must
perform. If a model has a default ordering (:attr:`Meta.ordering perform. If a model has a default ordering (:attr:`Meta.ordering
<django.db.models.Options.ordering>`) and you don't need it, remove <django.db.models.Options.ordering>`) and you don't need it, remove
it on a ``QuerySet`` by calling it on a ``QuerySet`` by calling
:meth:`~django.db.models.query.QuerySet.order_by()` with no parameters. :meth:`~django.db.models.query.QuerySet.order_by` with no parameters.
Adding an index to your database may help to improve ordering performance. Adding an index to your database may help to improve ordering performance.
@ -362,7 +362,7 @@ Create in bulk
-------------- --------------
When creating objects, where possible, use the When creating objects, where possible, use the
:meth:`~django.db.models.query.QuerySet.bulk_create()` method to reduce the :meth:`~django.db.models.query.QuerySet.bulk_create` method to reduce the
number of SQL queries. For example:: number of SQL queries. For example::
Entry.objects.bulk_create( Entry.objects.bulk_create(
@ -385,7 +385,7 @@ Update in bulk
-------------- --------------
When updating objects, where possible, use the When updating objects, where possible, use the
:meth:`~django.db.models.query.QuerySet.bulk_update()` method to reduce the :meth:`~django.db.models.query.QuerySet.bulk_update` method to reduce the
number of SQL queries. Given a list or queryset of objects:: number of SQL queries. Given a list or queryset of objects::
entries = Entry.objects.bulk_create( entries = Entry.objects.bulk_create(
@ -432,7 +432,7 @@ objects to reduce the number of SQL queries. For example::
When inserting different pairs of objects into When inserting different pairs of objects into
:class:`~django.db.models.ManyToManyField` or when the custom :class:`~django.db.models.ManyToManyField` or when the custom
:attr:`~django.db.models.ManyToManyField.through` table is defined, use :attr:`~django.db.models.ManyToManyField.through` table is defined, use
:meth:`~django.db.models.query.QuerySet.bulk_create()` method to reduce the :meth:`~django.db.models.query.QuerySet.bulk_create` method to reduce the
number of SQL queries. For example:: number of SQL queries. For example::
PizzaToppingRelationship = Pizza.toppings.through PizzaToppingRelationship = Pizza.toppings.through

View File

@ -83,7 +83,7 @@ The :meth:`~django.db.models.Model.save` method has no return value.
:meth:`~django.db.models.Model.save` for complete details. :meth:`~django.db.models.Model.save` for complete details.
To create and save an object in a single step, use the To create and save an object in a single step, use the
:meth:`~django.db.models.query.QuerySet.create()` method. :meth:`~django.db.models.query.QuerySet.create` method.
Saving changes to objects Saving changes to objects
========================= =========================

View File

@ -5,7 +5,7 @@ Performing raw SQL queries
.. currentmodule:: django.db.models .. currentmodule:: django.db.models
Django gives you two ways of performing raw SQL queries: you can use Django gives you two ways of performing raw SQL queries: you can use
:meth:`Manager.raw()` to `perform raw queries and return model instances`__, or :meth:`Manager.raw` to `perform raw queries and return model instances`__, or
you can avoid the model layer entirely and `execute custom SQL directly`__. you can avoid the model layer entirely and `execute custom SQL directly`__.
__ `performing raw queries`_ __ `performing raw queries`_
@ -170,7 +170,7 @@ Fields may also be left out:
>>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person") >>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person")
The ``Person`` objects returned by this query will be deferred model instances The ``Person`` objects returned by this query will be deferred model instances
(see :meth:`~django.db.models.query.QuerySet.defer()`). This means that the (see :meth:`~django.db.models.query.QuerySet.defer`). This means that the
fields that are omitted from the query will be loaded on demand. For example: fields that are omitted from the query will be loaded on demand. For example:
.. code-block:: pycon .. code-block:: pycon

View File

@ -133,11 +133,11 @@ can be ``0`` or ``1`` since it can only send one message).
(subject, message, from_email, recipient_list) (subject, message, from_email, recipient_list)
``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the ``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the
same functions as in :meth:`~django.core.mail.send_mail()`. They must be given same functions as in :meth:`~django.core.mail.send_mail`. They must be given
as keyword arguments if used. as keyword arguments if used.
Each separate element of ``datatuple`` results in a separate email message. Each separate element of ``datatuple`` results in a separate email message.
As in :meth:`~django.core.mail.send_mail()`, recipients in the same As in :meth:`~django.core.mail.send_mail`, recipients in the same
``recipient_list`` will all see the other addresses in the email messages' ``recipient_list`` will all see the other addresses in the email messages'
"To:" field. "To:" field.
@ -169,12 +169,12 @@ The return value will be the number of successfully delivered messages.
``send_mass_mail()`` vs. ``send_mail()`` ``send_mass_mail()`` vs. ``send_mail()``
---------------------------------------- ----------------------------------------
The main difference between :meth:`~django.core.mail.send_mass_mail()` and The main difference between :meth:`~django.core.mail.send_mass_mail` and
:meth:`~django.core.mail.send_mail()` is that :meth:`~django.core.mail.send_mail` is that
:meth:`~django.core.mail.send_mail()` opens a connection to the mail server :meth:`~django.core.mail.send_mail` opens a connection to the mail server
each time it's executed, while :meth:`~django.core.mail.send_mass_mail()` uses each time it's executed, while :meth:`~django.core.mail.send_mass_mail` uses
a single connection for all of its messages. This makes a single connection for all of its messages. This makes
:meth:`~django.core.mail.send_mass_mail()` slightly more efficient. :meth:`~django.core.mail.send_mass_mail` slightly more efficient.
``mail_admins()`` ``mail_admins()``
================= =================
@ -248,7 +248,7 @@ scripts generate.
The Django email functions outlined above all protect against header injection The Django email functions outlined above all protect against header injection
by forbidding newlines in header values. If any ``subject``, ``from_email`` or by forbidding newlines in header values. If any ``subject``, ``from_email`` or
``recipient_list`` contains a newline (in either Unix, Windows or Mac style), ``recipient_list`` contains a newline (in either Unix, Windows or Mac style),
the email function (e.g. :meth:`~django.core.mail.send_mail()`) will raise the email function (e.g. :meth:`~django.core.mail.send_mail`) will raise
:exc:`ValueError` and, hence, will not send the email. It's your responsibility :exc:`ValueError` and, hence, will not send the email. It's your responsibility
to validate all data before passing it to the email functions. to validate all data before passing it to the email functions.
@ -291,18 +291,18 @@ from the request's POST data, sends that to admin@example.com and redirects to
The ``EmailMessage`` class The ``EmailMessage`` class
========================== ==========================
Django's :meth:`~django.core.mail.send_mail()` and Django's :meth:`~django.core.mail.send_mail` and
:meth:`~django.core.mail.send_mass_mail()` functions are actually thin :meth:`~django.core.mail.send_mass_mail` functions are actually thin
wrappers that make use of the :class:`~django.core.mail.EmailMessage` class. wrappers that make use of the :class:`~django.core.mail.EmailMessage` class.
Not all features of the :class:`~django.core.mail.EmailMessage` class are Not all features of the :class:`~django.core.mail.EmailMessage` class are
available through the :meth:`~django.core.mail.send_mail()` and related available through the :meth:`~django.core.mail.send_mail` and related
wrapper functions. If you wish to use advanced features, such as BCC'ed wrapper functions. If you wish to use advanced features, such as BCC'ed
recipients, file attachments, or multi-part email, you'll need to create recipients, file attachments, or multi-part email, you'll need to create
:class:`~django.core.mail.EmailMessage` instances directly. :class:`~django.core.mail.EmailMessage` instances directly.
.. note:: .. note::
This is a design feature. :meth:`~django.core.mail.send_mail()` and This is a design feature. :meth:`~django.core.mail.send_mail` and
related functions were originally the only interface Django provided. related functions were originally the only interface Django provided.
However, the list of parameters they accepted was slowly growing over However, the list of parameters they accepted was slowly growing over
time. It made sense to move to a more object-oriented design for email time. It made sense to move to a more object-oriented design for email
@ -714,7 +714,7 @@ SMTP backend
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend" EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
If unspecified, the default ``timeout`` will be the one provided by If unspecified, the default ``timeout`` will be the one provided by
:func:`socket.getdefaulttimeout()`, which defaults to ``None`` (no timeout). :func:`socket.getdefaulttimeout`, which defaults to ``None`` (no timeout).
.. _topic-email-console-backend: .. _topic-email-console-backend:

View File

@ -248,7 +248,7 @@ user from entering more than that number of characters in the first place). It
also means that when Django receives the form back from the browser, it will also means that when Django receives the form back from the browser, it will
validate the length of the data. validate the length of the data.
A :class:`Form` instance has an :meth:`~Form.is_valid()` method, which runs A :class:`Form` instance has an :meth:`~Form.is_valid` method, which runs
validation routines for all its fields. When this method is called, if all validation routines for all its fields. When this method is called, if all
fields contain valid data, it will: fields contain valid data, it will:

View File

@ -237,17 +237,17 @@ There are two main steps involved in validating a ``ModelForm``:
2. :ref:`Validating the model instance <validating-objects>` 2. :ref:`Validating the model instance <validating-objects>`
Just like normal form validation, model form validation is triggered implicitly Just like normal form validation, model form validation is triggered implicitly
when calling :meth:`~django.forms.Form.is_valid()` or accessing the when calling :meth:`~django.forms.Form.is_valid` or accessing the
:attr:`~django.forms.Form.errors` attribute and explicitly when calling :attr:`~django.forms.Form.errors` attribute and explicitly when calling
``full_clean()``, although you will typically not use the latter method in ``full_clean()``, although you will typically not use the latter method in
practice. practice.
``Model`` validation is triggered from within the form validation step right ``Model`` validation is triggered from within the form validation step right
after the form's ``clean()`` method is called. First, the model's after the form's ``clean()`` method is called. First, the model's
:meth:`~django.db.models.Model.full_clean()` is called with :meth:`~django.db.models.Model.full_clean` is called with
``validate_unique=False`` and ``validate_constraints=False``, then the model's ``validate_unique=False`` and ``validate_constraints=False``, then the model's
:meth:`~django.db.models.Model.validate_unique()` and :meth:`~django.db.models.Model.validate_unique` and
:meth:`~django.db.models.Model.validate_constraints()` methods are called in :meth:`~django.db.models.Model.validate_constraints` methods are called in
order. order.
.. warning:: .. warning::

View File

@ -253,7 +253,7 @@ You can edit it multiple times.
Deletes the current session data from the session and deletes the session Deletes the current session data from the session and deletes the session
cookie. This is used if you want to ensure that the previous session data cookie. This is used if you want to ensure that the previous session data
can't be accessed again from the user's browser (for example, the can't be accessed again from the user's browser (for example, the
:func:`django.contrib.auth.logout()` function calls it). :func:`django.contrib.auth.logout` function calls it).
.. method:: set_test_cookie() .. method:: set_test_cookie()
.. method:: aset_test_cookie() .. method:: aset_test_cookie()
@ -380,7 +380,7 @@ You can edit it multiple times.
*Asynchronous version*: ``acycle_key()`` *Asynchronous version*: ``acycle_key()``
Creates a new session key while retaining the current session data. Creates a new session key while retaining the current session data.
:func:`django.contrib.auth.login()` calls this method to mitigate against :func:`django.contrib.auth.login` calls this method to mitigate against
session fixation. session fixation.
.. _session_serialization: .. _session_serialization:
@ -519,7 +519,7 @@ is necessary due to the way cookies work. When you set a cookie, you can't
actually tell whether a browser accepted it until the browser's next request. actually tell whether a browser accepted it until the browser's next request.
It's good practice to use It's good practice to use
:meth:`~backends.base.SessionBase.delete_test_cookie()` to clean up after :meth:`~backends.base.SessionBase.delete_test_cookie` to clean up after
yourself. Do this after you've verified that the test cookie worked. yourself. Do this after you've verified that the test cookie worked.
Here's a typical usage example:: Here's a typical usage example::
@ -589,7 +589,7 @@ access sessions using the normal Django database API:
datetime.datetime(2005, 8, 20, 13, 35, 12) datetime.datetime(2005, 8, 20, 13, 35, 12)
Note that you'll need to call Note that you'll need to call
:meth:`~base_session.AbstractBaseSession.get_decoded()` to get the session :meth:`~base_session.AbstractBaseSession.get_decoded` to get the session
dictionary. This is necessary because the dictionary is stored in an encoded dictionary. This is necessary because the dictionary is stored in an encoded
format: format:

View File

@ -23,7 +23,7 @@ introduce controlled coupling for convenience's sake.
Django does not provide a shortcut function which returns a Django does not provide a shortcut function which returns a
:class:`~django.template.response.TemplateResponse` because the constructor :class:`~django.template.response.TemplateResponse` because the constructor
of :class:`~django.template.response.TemplateResponse` offers the same level of :class:`~django.template.response.TemplateResponse` offers the same level
of convenience as :func:`render()`. of convenience as :func:`render`.
Required arguments Required arguments
------------------ ------------------
@ -98,7 +98,7 @@ This example is equivalent to::
The arguments could be: The arguments could be:
* A model: the model's :meth:`~django.db.models.Model.get_absolute_url()` * A model: the model's :meth:`~django.db.models.Model.get_absolute_url`
function will be called. function will be called.
* A view name, possibly with arguments: :func:`~django.urls.reverse` will be * A view name, possibly with arguments: :func:`~django.urls.reverse` will be
@ -196,7 +196,7 @@ original HTTP method::
*Asynchronous version*: ``aget_object_or_404()`` *Asynchronous version*: ``aget_object_or_404()``
Calls :meth:`~django.db.models.query.QuerySet.get()` on a given model Calls :meth:`~django.db.models.query.QuerySet.get` on a given model
manager, but it raises :class:`~django.http.Http404` instead of the model's manager, but it raises :class:`~django.http.Http404` instead of the model's
:class:`~django.db.models.Model.DoesNotExist` exception. :class:`~django.db.models.Model.DoesNotExist` exception.
@ -277,7 +277,7 @@ will be raised if more than one object is found.
*Asynchronous version*: ``aget_list_or_404()`` *Asynchronous version*: ``aget_list_or_404()``
Returns the result of :meth:`~django.db.models.query.QuerySet.filter()` on Returns the result of :meth:`~django.db.models.query.QuerySet.filter` on
a given model manager cast to a list, raising :class:`~django.http.Http404` a given model manager cast to a list, raising :class:`~django.http.Http404`
if the resulting list is empty. if the resulting list is empty.

View File

@ -377,7 +377,7 @@ itself. It includes a number of other URLconfs::
# ... snip ... # ... snip ...
] ]
Whenever Django encounters :func:`~django.urls.include()`, it chops off Whenever Django encounters :func:`~django.urls.include`, it chops off
whatever part of the URL matched up to that point and sends the remaining whatever part of the URL matched up to that point and sends the remaining
string to the included URLconf for further processing. string to the included URLconf for further processing.
@ -658,7 +658,7 @@ characters you like. You are not restricted to valid Python names.
When naming URL patterns, choose names that are unlikely to clash with other When naming URL patterns, choose names that are unlikely to clash with other
applications' choice of names. If you call your URL pattern ``comment`` applications' choice of names. If you call your URL pattern ``comment``
and another application does the same thing, the URL that and another application does the same thing, the URL that
:func:`~django.urls.reverse()` finds depends on whichever pattern is last in :func:`~django.urls.reverse` finds depends on whichever pattern is last in
your project's ``urlpatterns`` list. your project's ``urlpatterns`` list.
Putting a prefix on your URL names, perhaps derived from the application Putting a prefix on your URL names, perhaps derived from the application
@ -670,12 +670,12 @@ want to override a view. For example, a common use case is to override the
:class:`~django.contrib.auth.views.LoginView`. Parts of Django and most :class:`~django.contrib.auth.views.LoginView`. Parts of Django and most
third-party apps assume that this view has a URL pattern with the name third-party apps assume that this view has a URL pattern with the name
``login``. If you have a custom login view and give its URL the name ``login``, ``login``. If you have a custom login view and give its URL the name ``login``,
:func:`~django.urls.reverse()` will find your custom view as long as it's in :func:`~django.urls.reverse` will find your custom view as long as it's in
``urlpatterns`` after ``django.contrib.auth.urls`` is included (if that's ``urlpatterns`` after ``django.contrib.auth.urls`` is included (if that's
included at all). included at all).
You may also use the same name for multiple URL patterns if they differ in You may also use the same name for multiple URL patterns if they differ in
their arguments. In addition to the URL name, :func:`~django.urls.reverse()` their arguments. In addition to the URL name, :func:`~django.urls.reverse`
matches the number of arguments and the names of the keyword arguments. Path matches the number of arguments and the names of the keyword arguments. Path
converters can also raise ``ValueError`` to indicate no match, see converters can also raise ``ValueError`` to indicate no match, see
:ref:`registering-custom-path-converters` for details. :ref:`registering-custom-path-converters` for details.
@ -743,7 +743,7 @@ the fully qualified name into parts and then tries the following lookup:
#. If there is a current application defined, Django finds and returns the URL #. If there is a current application defined, Django finds and returns the URL
resolver for that instance. The current application can be specified with resolver for that instance. The current application can be specified with
the ``current_app`` argument to the :func:`~django.urls.reverse()` the ``current_app`` argument to the :func:`~django.urls.reverse`
function. function.
The :ttag:`url` template tag uses the namespace of the currently resolved The :ttag:`url` template tag uses the namespace of the currently resolved

View File

@ -180,7 +180,7 @@ more details.
Marking strings as no-op Marking strings as no-op
------------------------ ------------------------
Use the function :func:`django.utils.translation.gettext_noop()` to mark a Use the function :func:`django.utils.translation.gettext_noop` to mark a
string as a translation string without translating it. The string is later string as a translation string without translating it. The string is later
translated from a variable. translated from a variable.
@ -192,7 +192,7 @@ such as when the string is presented to the user.
Pluralization Pluralization
------------- -------------
Use the function :func:`django.utils.translation.ngettext()` to specify Use the function :func:`django.utils.translation.ngettext` to specify
pluralized messages. pluralized messages.
``ngettext()`` takes three arguments: the singular translation string, the ``ngettext()`` takes three arguments: the singular translation string, the
@ -290,8 +290,8 @@ Contextual markers
Sometimes words have several meanings, such as ``"May"`` in English, which Sometimes words have several meanings, such as ``"May"`` in English, which
refers to a month name and to a verb. To enable translators to translate refers to a month name and to a verb. To enable translators to translate
these words correctly in different contexts, you can use the these words correctly in different contexts, you can use the
:func:`django.utils.translation.pgettext()` function, or the :func:`django.utils.translation.pgettext` function, or the
:func:`django.utils.translation.npgettext()` function if the string needs :func:`django.utils.translation.npgettext` function if the string needs
pluralization. Both take a context string as the first variable. pluralization. Both take a context string as the first variable.
In the resulting ``.po`` file, the string will then appear as often as there are In the resulting ``.po`` file, the string will then appear as often as there are
@ -502,10 +502,10 @@ directly with the ``number`` argument::
Formatting strings: ``format_lazy()`` Formatting strings: ``format_lazy()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Python's :meth:`str.format()` method will not work when either the Python's :meth:`str.format` method will not work when either the
``format_string`` or any of the arguments to :meth:`str.format()` ``format_string`` or any of the arguments to :meth:`str.format`
contains lazy translation objects. Instead, you can use contains lazy translation objects. Instead, you can use
:func:`django.utils.text.format_lazy()`, which creates a lazy object :func:`django.utils.text.format_lazy`, which creates a lazy object
that runs the ``str.format()`` method only when the result is included that runs the ``str.format()`` method only when the result is included
in a string. For example:: in a string. For example::
@ -1224,7 +1224,7 @@ in the future.
~~~~~~~~~~~~ ~~~~~~~~~~~~
The ``pgettext`` function behaves like the Python variant The ``pgettext`` function behaves like the Python variant
(:func:`~django.utils.translation.pgettext()`), providing a contextually (:func:`~django.utils.translation.pgettext`), providing a contextually
translated word:: translated word::
document.write(pgettext("month name", "May")) document.write(pgettext("month name", "May"))
@ -1233,7 +1233,7 @@ translated word::
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The ``npgettext`` function also behaves like the Python variant The ``npgettext`` function also behaves like the Python variant
(:func:`~django.utils.translation.npgettext()`), providing a **pluralized** (:func:`~django.utils.translation.npgettext`), providing a **pluralized**
contextually translated word: contextually translated word:
.. code-block:: javascript .. code-block:: javascript
@ -1365,7 +1365,7 @@ Django provides two mechanisms to internationalize URL patterns:
the language to activate from the requested URL. the language to activate from the requested URL.
* Making URL patterns themselves translatable via the * Making URL patterns themselves translatable via the
:func:`django.utils.translation.gettext_lazy()` function. :func:`django.utils.translation.gettext_lazy` function.
.. warning:: .. warning::
@ -1931,7 +1931,7 @@ Explicitly setting the active language
You may want to set the active language for the current session explicitly. Perhaps You may want to set the active language for the current session explicitly. Perhaps
a user's language preference is retrieved from another system, for example. a user's language preference is retrieved from another system, for example.
You've already been introduced to :func:`django.utils.translation.activate()`. That You've already been introduced to :func:`django.utils.translation.activate`. That
applies to the current thread only. To persist the language for the entire applies to the current thread only. To persist the language for the entire
session in a cookie, set the :setting:`LANGUAGE_COOKIE_NAME` cookie on the session in a cookie, set the :setting:`LANGUAGE_COOKIE_NAME` cookie on the
response:: response::
@ -1945,7 +1945,7 @@ response::
response = HttpResponse(...) response = HttpResponse(...)
response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language) response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language)
You would typically want to use both: :func:`django.utils.translation.activate()` You would typically want to use both: :func:`django.utils.translation.activate`
changes the language for this thread, and setting the cookie makes this changes the language for this thread, and setting the cookie makes this
preference persist in future requests. preference persist in future requests.
@ -1979,14 +1979,14 @@ Calling this function with the value ``'de'`` will give you ``"Willkommen"``,
regardless of :setting:`LANGUAGE_CODE` and language set by middleware. regardless of :setting:`LANGUAGE_CODE` and language set by middleware.
Functions of particular interest are Functions of particular interest are
:func:`django.utils.translation.get_language()` which returns the language used :func:`django.utils.translation.get_language` which returns the language used
in the current thread, :func:`django.utils.translation.activate()` which in the current thread, :func:`django.utils.translation.activate` which
activates a translation catalog for the current thread, and activates a translation catalog for the current thread, and
:func:`django.utils.translation.check_for_language()` :func:`django.utils.translation.check_for_language`
which checks if the given language is supported by Django. which checks if the given language is supported by Django.
To help write more concise code, there is also a context manager To help write more concise code, there is also a context manager
:func:`django.utils.translation.override()` that stores the current language on :func:`django.utils.translation.override` that stores the current language on
enter and restores it on exit. With it, the above example becomes:: enter and restores it on exit. With it, the above example becomes::
from django.utils import translation from django.utils import translation

View File

@ -419,7 +419,7 @@ logger, you can specify your own configuration scheme.
The :setting:`LOGGING_CONFIG` setting defines the callable that will The :setting:`LOGGING_CONFIG` setting defines the callable that will
be used to configure Django's loggers. By default, it points at be used to configure Django's loggers. By default, it points at
Python's :func:`logging.config.dictConfig()` function. However, if you want to Python's :func:`logging.config.dictConfig` function. However, if you want to
use a different configuration process, you can use any other callable use a different configuration process, you can use any other callable
that takes a single argument. The contents of :setting:`LOGGING` will that takes a single argument. The contents of :setting:`LOGGING` will
be provided as the value of that argument when logging is configured. be provided as the value of that argument when logging is configured.

View File

@ -189,7 +189,7 @@ You can prevent a migration from running in a transaction by setting the
atomic = False atomic = False
It's also possible to execute parts of the migration inside a transaction using It's also possible to execute parts of the migration inside a transaction using
:func:`~django.db.transaction.atomic()` or by passing ``atomic=True`` to :func:`~django.db.transaction.atomic` or by passing ``atomic=True`` to
:class:`~django.db.migrations.operations.RunPython`. See :class:`~django.db.migrations.operations.RunPython`. See
:ref:`non-atomic-migrations` for more details. :ref:`non-atomic-migrations` for more details.

View File

@ -188,9 +188,9 @@ cache poisoning attacks, and poisoning links in emails.
Because even seemingly-secure web server configurations are susceptible to fake Because even seemingly-secure web server configurations are susceptible to fake
``Host`` headers, Django validates ``Host`` headers against the ``Host`` headers, Django validates ``Host`` headers against the
:setting:`ALLOWED_HOSTS` setting in the :setting:`ALLOWED_HOSTS` setting in the
:meth:`django.http.HttpRequest.get_host()` method. :meth:`django.http.HttpRequest.get_host` method.
This validation only applies via :meth:`~django.http.HttpRequest.get_host()`; This validation only applies via :meth:`~django.http.HttpRequest.get_host`;
if your code accesses the ``Host`` header directly from ``request.META`` you if your code accesses the ``Host`` header directly from ``request.META`` you
are bypassing this security protection. are bypassing this security protection.

View File

@ -280,7 +280,7 @@ ORM to fetch some data -- there's one more step you'll need in addition to
configuring settings. configuring settings.
After you've either set :envvar:`DJANGO_SETTINGS_MODULE` or called After you've either set :envvar:`DJANGO_SETTINGS_MODULE` or called
``configure()``, you'll need to call :func:`django.setup()` to load your ``configure()``, you'll need to call :func:`django.setup` to load your
settings and populate Django's application registry. For example:: settings and populate Django's application registry. For example::
import django import django

View File

@ -425,7 +425,7 @@ When Django finds a template that exists, it stops looking.
.. admonition:: Use ``django.template.loader.select_template()`` for more flexibility .. admonition:: Use ``django.template.loader.select_template()`` for more flexibility
You can use :func:`~django.template.loader.select_template()` for flexible You can use :func:`~django.template.loader.select_template` for flexible
template loading. For example, if you've written a news story and want template loading. For example, if you've written a news story and want
some stories to have custom templates, use something like some stories to have custom templates, use something like
``select_template(['story_%s_detail.html' % story.id, ``select_template(['story_%s_detail.html' % story.id,
@ -485,8 +485,8 @@ templates, Django provides a shortcut function which automates the process.
rendered = render_to_string("my_template.html", {"foo": "bar"}) rendered = render_to_string("my_template.html", {"foo": "bar"})
See also the :func:`~django.shortcuts.render()` shortcut which calls See also the :func:`~django.shortcuts.render` shortcut which calls
:func:`render_to_string()` and feeds the result into an :func:`render_to_string` and feeds the result into an
:class:`~django.http.HttpResponse` suitable for returning from a view. :class:`~django.http.HttpResponse` suitable for returning from a view.
Finally, you can use configured engines directly: Finally, you can use configured engines directly:

View File

@ -19,10 +19,10 @@ a black box, with exactly known inputs, testing for specific outputs.
The API for the :class:`~django.test.RequestFactory` is a slightly The API for the :class:`~django.test.RequestFactory` is a slightly
restricted subset of the test client API: restricted subset of the test client API:
* It only has access to the HTTP methods :meth:`~Client.get()`, * It only has access to the HTTP methods :meth:`~Client.get`,
:meth:`~Client.post()`, :meth:`~Client.put()`, :meth:`~Client.post`, :meth:`~Client.put`,
:meth:`~Client.delete()`, :meth:`~Client.head()`, :meth:`~Client.delete`, :meth:`~Client.head`,
:meth:`~Client.options()`, and :meth:`~Client.trace()`. :meth:`~Client.options`, and :meth:`~Client.trace`.
* These methods accept all the same arguments *except* for * These methods accept all the same arguments *except* for
``follow``. Since this is just a factory for producing ``follow``. Since this is just a factory for producing
@ -158,8 +158,8 @@ and the settings file includes a list of the domains supported by the project::
ALLOWED_HOSTS = ["www.djangoproject.dev", "docs.djangoproject.dev", ...] ALLOWED_HOSTS = ["www.djangoproject.dev", "docs.djangoproject.dev", ...]
Another option is to add the required hosts to :setting:`ALLOWED_HOSTS` using Another option is to add the required hosts to :setting:`ALLOWED_HOSTS` using
:meth:`~django.test.override_settings()` or :meth:`~django.test.override_settings` or
:attr:`~django.test.SimpleTestCase.modify_settings()`. This option may be :attr:`~django.test.SimpleTestCase.modify_settings`. This option may be
preferable in standalone apps that can't package their own settings file or preferable in standalone apps that can't package their own settings file or
for projects where the list of domains is not static (e.g., subdomains for for projects where the list of domains is not static (e.g., subdomains for
multitenancy). For example, you could write a test for the domain multitenancy). For example, you could write a test for the domain
@ -661,7 +661,7 @@ Methods
Override this class method to add custom arguments accepted by the Override this class method to add custom arguments accepted by the
:djadmin:`test` management command. See :djadmin:`test` management command. See
:py:meth:`argparse.ArgumentParser.add_argument()` for details about adding :py:meth:`argparse.ArgumentParser.add_argument` for details about adding
arguments to a parser. arguments to a parser.
.. method:: DiscoverRunner.setup_test_environment(**kwargs) .. method:: DiscoverRunner.setup_test_environment(**kwargs)

View File

@ -208,7 +208,7 @@ with ability to share the database between threads.
your code* anyway - rewrite your code so that it doesn't do this. your code* anyway - rewrite your code so that it doesn't do this.
This also applies to customized implementations of This also applies to customized implementations of
:meth:`~django.apps.AppConfig.ready()`. :meth:`~django.apps.AppConfig.ready`.
.. seealso:: .. seealso::

View File

@ -144,8 +144,8 @@ Use the ``django.test.Client`` class to make requests.
but the ``headers`` parameter should be preferred for readability. but the ``headers`` parameter should be preferred for readability.
The values from the ``headers``, ``query_params``, and ``extra`` keyword The values from the ``headers``, ``query_params``, and ``extra`` keyword
arguments passed to :meth:`~django.test.Client.get()`, arguments passed to :meth:`~django.test.Client.get`,
:meth:`~django.test.Client.post()`, etc. have precedence over :meth:`~django.test.Client.post`, etc. have precedence over
the defaults passed to the class constructor. the defaults passed to the class constructor.
The ``enforce_csrf_checks`` argument can be used to test CSRF The ``enforce_csrf_checks`` argument can be used to test CSRF
@ -198,7 +198,7 @@ Use the ``django.test.Client`` class to make requests.
...will send the HTTP header ``HTTP_ACCEPT`` to the details view, which ...will send the HTTP header ``HTTP_ACCEPT`` to the details view, which
is a good way to test code paths that use the is a good way to test code paths that use the
:meth:`django.http.HttpRequest.accepts()` method. :meth:`django.http.HttpRequest.accepts` method.
Arbitrary keyword arguments set WSGI Arbitrary keyword arguments set WSGI
:pep:`environ variables <3333#environ-variables>`. For example, headers :pep:`environ variables <3333#environ-variables>`. For example, headers
@ -456,7 +456,7 @@ Use the ``django.test.Client`` class to make requests.
fixture. Remember that if you want your test user to have a password, fixture. Remember that if you want your test user to have a password,
you can't set the user's password by setting the password attribute you can't set the user's password by setting the password attribute
directly -- you must use the directly -- you must use the
:meth:`~django.contrib.auth.models.User.set_password()` function to :meth:`~django.contrib.auth.models.User.set_password` function to
store a correctly hashed password. Alternatively, you can use the store a correctly hashed password. Alternatively, you can use the
:meth:`~django.contrib.auth.models.UserManager.create_user` helper :meth:`~django.contrib.auth.models.UserManager.create_user` helper
method to create a new user with a correctly hashed password. method to create a new user with a correctly hashed password.
@ -882,7 +882,7 @@ end of each test. A consequence of this, however, is that some database
behaviors cannot be tested within a Django ``TestCase`` class. For instance, behaviors cannot be tested within a Django ``TestCase`` class. For instance,
you cannot test that a block of code is executing within a transaction, as is you cannot test that a block of code is executing within a transaction, as is
required when using required when using
:meth:`~django.db.models.query.QuerySet.select_for_update()`. In those cases, :meth:`~django.db.models.query.QuerySet.select_for_update`. In those cases,
you should use ``TransactionTestCase``. you should use ``TransactionTestCase``.
``TransactionTestCase`` and ``TestCase`` are identical except for the manner ``TransactionTestCase`` and ``TestCase`` are identical except for the manner