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

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

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/ref/applications.txt
View File

@@ -271,7 +271,7 @@ Methods
Requires the app registry to be fully populated unless the
``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()
@@ -309,12 +309,12 @@ Methods
.. warning::
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
(:meth:`~django.db.models.Model.save()`,
:meth:`~django.db.models.Model.delete()`, manager methods etc.), and
(:meth:`~django.db.models.Model.save`,
:meth:`~django.db.models.Model.delete`, manager methods etc.), and
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
separate from the production settings, ``manage.py test`` would still
execute some queries against your **production** database!
@@ -416,7 +416,7 @@ Initialization process
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.
.. currentmodule:: django
@@ -463,7 +463,7 @@ processes all applications in the order of :setting:`INSTALLED_APPS`.
import any models at this stage.
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,
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.
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.
.. _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
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
import time, you need :func:`~django.utils.translation.gettext_lazy()`
instead. (Using :func:`~django.utils.translation.gettext()` would be a bug,
import time, you need :func:`~django.utils.translation.gettext_lazy`
instead. (Using :func:`~django.utils.translation.gettext` would be a bug,
because the translation would happen at import time, rather than at each
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
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.
* ``ImportError: cannot import name ...`` This happens if the import sequence

24
docs/ref/class-based-views/base.txt
View File

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

36
docs/ref/class-based-views/generic-display.txt
View File

@@ -25,17 +25,17 @@ many projects they are typically the most commonly used views.
**Method Flowchart**
#. :meth:`~django.views.generic.base.View.setup()`
#. :meth:`~django.views.generic.base.View.dispatch()`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
#. :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_queryset()`
#. :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_data()`
#. :meth:`~django.views.generic.base.View.setup`
#. :meth:`~django.views.generic.base.View.dispatch`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed`
#. :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_queryset`
#. :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_data`
#. :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**::
@@ -116,15 +116,15 @@ many projects they are typically the most commonly used views.
**Method Flowchart**
#. :meth:`~django.views.generic.base.View.setup()`
#. :meth:`~django.views.generic.base.View.dispatch()`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
#. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
#. :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_data()`
#. :meth:`~django.views.generic.base.View.setup`
#. :meth:`~django.views.generic.base.View.dispatch`
#. :meth:`~django.views.generic.base.View.http_method_not_allowed`
#. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`
#. :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_data`
#. :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**::

4
docs/ref/class-based-views/index.txt
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 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 = [
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
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
previous example, this means that every request on ``MyView`` is able to use
``self.size``. Arguments must correspond to attributes that already exist on

2
docs/ref/class-based-views/mixins-simple.txt
View File

@@ -95,7 +95,7 @@ Simple mixins
If any keyword arguments are provided, they will be passed to the
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.
.. method:: get_template_names()

2
docs/ref/class-based-views/mixins-single-object.txt
View File

@@ -53,7 +53,7 @@ Single object mixins
.. 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``.
This attribute can help mitigate `insecure direct object reference`_

6
docs/ref/contrib/admin/actions.txt
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
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::
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
a name -- good if you later want to programmatically :ref:`remove the action
<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")
@@ -318,7 +318,7 @@ Disabling a site-wide action
.. method:: AdminSite.disable_action(name)
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
objects" action::

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

@@ -154,12 +154,12 @@ application and imports it.
.. class:: apps.AdminConfig
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
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
@@ -3119,7 +3119,7 @@ Hooking ``AdminSite`` instances into your URLconf
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
``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
``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
: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
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.
.. note::

20
docs/ref/contrib/auth.txt
View File

@@ -159,7 +159,7 @@ Methods
When the ``raw_password`` is ``None``, the password will be set to an
unusable password, as if
:meth:`~django.contrib.auth.models.User.set_unusable_password()`
:meth:`~django.contrib.auth.models.User.set_unusable_password`
were used.
.. method:: check_password(raw_password)
@@ -176,7 +176,7 @@ Methods
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 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
:class:`~django.contrib.auth.models.User` object.
@@ -192,7 +192,7 @@ Methods
.. method:: has_usable_password()
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.
.. method:: get_user_permissions(obj=None)
@@ -293,7 +293,7 @@ Methods
Sends an email to the user. If ``from_email`` is ``None``, Django uses
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
---------------
@@ -319,7 +319,7 @@ Manager methods
:attr:`~django.contrib.auth.models.User.is_active` set to ``True``.
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.
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``.
* :attr:`~django.contrib.auth.models.User.username` is always the empty
string.
* :meth:`~django.contrib.auth.models.User.get_username()` always returns
* :meth:`~django.contrib.auth.models.User.get_username` always returns
the empty string.
* :attr:`~django.contrib.auth.models.User.is_anonymous` is ``True``
instead of ``False``.
@@ -393,10 +393,10 @@ Manager methods
* :attr:`~django.contrib.auth.models.User.groups` and
:attr:`~django.contrib.auth.models.User.user_permissions` are always
empty.
* :meth:`~django.contrib.auth.models.User.set_password()`,
:meth:`~django.contrib.auth.models.User.check_password()`,
* :meth:`~django.contrib.auth.models.User.set_password`,
:meth:`~django.contrib.auth.models.User.check_password`,
: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
: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``
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,
(including password) will not be sent in the clear as part of the signal.

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

@@ -220,7 +220,7 @@ The ``ContentTypeManager``
referenced via a :ref:`natural key<topics-serialization-natural-keys>`
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
: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

2
docs/ref/contrib/postgres/functions.txt
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
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
return; nested calls create savepoints which do not affect the transaction
time.

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

@@ -121,7 +121,7 @@ Note:
attributes corresponding to ``<changefreq>`` and ``<priority>`` elements,
respectively. They can be made callable as functions, as
: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
methods corresponding to a sitemap property (:attr:`~Sitemap.location`,
:attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and
@@ -129,7 +129,7 @@ Note:
* :attr:`~Sitemap.lastmod` should return a :class:`~datetime.datetime`.
* 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,
:attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object
:attr:`~Sitemap.location` calls ``get_absolute_url()`` on each object
and returns the result.
``Sitemap`` class reference
@@ -144,19 +144,19 @@ Note:
**Required.** A method that returns a :term:`sequence` or ``QuerySet``
of objects. The framework doesn't care what *type* of objects they are;
all that matters is that these objects get passed to the
:attr:`~Sitemap.location()`, :attr:`~Sitemap.lastmod()`,
:attr:`~Sitemap.changefreq()` and :attr:`~Sitemap.priority()` methods.
:attr:`~Sitemap.location`, :attr:`~Sitemap.lastmod`,
:attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` methods.
.. attribute:: Sitemap.location
**Optional.** Either a method or attribute.
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
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
protocol or domain. Examples:
@@ -167,7 +167,7 @@ Note:
If :attr:`~Sitemap.location` isn't provided, the framework will call
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
:attr:`~Sitemap.protocol`.
@@ -177,12 +177,12 @@ Note:
**Optional.** Either a method or attribute.
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`.
If it's an attribute, its value should be a :class:`~datetime.datetime`
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
generated by :func:`views.sitemap` will have a ``Last-Modified``
@@ -196,7 +196,7 @@ Note:
**Optional.**
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
``items()`` calls.
@@ -205,11 +205,11 @@ Note:
**Optional.** Either a method or attribute.
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.
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
method or attribute, are:
@@ -227,12 +227,12 @@ Note:
**Optional.** Either a method or attribute.
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.
If it's an attribute, its value should be either a string or float
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
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
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
generate a Google News compatible sitemap:

2
docs/ref/contrib/sites.txt
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
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
the ``domain`` and ``name`` by looking at the request's domain. It has
``save()`` and ``delete()`` methods to match the interface of

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

@@ -311,7 +311,7 @@ Language
Feeds created by the syndication framework automatically include the
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.
URLs

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

@@ -1051,12 +1051,12 @@ together:
.. django-admin-option:: --managers
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
Mails the email addresses specified in :setting:`ADMINS` using
:meth:`~django.core.mail.mail_admins()`.
:meth:`~django.core.mail.mail_admins`.
``shell``
---------
@@ -1524,7 +1524,7 @@ Runs tests in separate parallel processes. Since modern processors have
multiple cores, this allows running tests significantly faster.
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.
``--parallel 4``, or by setting the :envvar:`DJANGO_TEST_PROCESSES` environment
variable.
@@ -1597,7 +1597,7 @@ as :option:`unittest's --buffer option<unittest.-b>`.
.. 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
``--no-faulthandler`` to disable this behavior.

8
docs/ref/exceptions.txt
View File

@@ -31,7 +31,7 @@ Django core exception classes are defined in ``django.core.exceptions``.
``ObjectDoesNotExist`` will catch
: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``
--------------------
@@ -45,7 +45,7 @@ Django core exception classes are defined in ``django.core.exceptions``.
``ObjectNotUpdated`` will catch
: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``
------------------
@@ -85,7 +85,7 @@ Django core exception classes are defined in ``django.core.exceptions``.
:exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all
models.
See :meth:`~django.db.models.query.QuerySet.get()`.
See :meth:`~django.db.models.query.QuerySet.get`.
``SuspiciousOperation``
-----------------------
@@ -239,7 +239,7 @@ URL Resolver exceptions are defined in ``django.urls``.
.. exception:: Resolver404
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`.
``NoReverseMatch``

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

@@ -50,7 +50,7 @@ The ``File`` class
Open or reopen the file (which also does ``File.seek(0)``).
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`.
When reopening a file, ``mode`` will override whatever mode the file

4
docs/ref/files/storage.txt
View File

@@ -201,12 +201,12 @@ The ``Storage`` class
.. 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.
The ``filename`` argument may include a path as returned by
: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.
The default implementation uses :mod:`os.path` operations. Override

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

@@ -157,7 +157,7 @@ instances.
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
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()``.
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)
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.
The ``escape_html`` parameter behaves as described in
:meth:`Form.errors.as_json()`.
:meth:`Form.errors.as_json`.
.. 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.
It is recommended to use :attr:`BoundField.initial` over
:meth:`~Form.get_initial_for_field()` because ``BoundField.initial`` has a
simpler interface. Also, unlike :meth:`~Form.get_initial_for_field()`,
:meth:`~Form.get_initial_for_field` because ``BoundField.initial`` has a
simpler interface. Also, unlike :meth:`~Form.get_initial_for_field`,
:attr:`BoundField.initial` caches its values. This is useful especially when
dealing with callables whose return values can change (e.g. ``datetime.now`` or
``uuid.uuid4``):
@@ -1315,7 +1315,7 @@ Attributes of ``BoundField``
datetime.datetime(2021, 7, 27, 9, 5, 54)
Using :attr:`BoundField.initial` is recommended over
:meth:`~Form.get_initial_for_field()`.
:meth:`~Form.get_initial_for_field`.
.. attribute:: BoundField.is_hidden
@@ -1517,7 +1517,7 @@ If not defined as a class variable, ``bound_field_class`` can be set via the
constructor.
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.
You may want to use a custom :class:`.BoundField` if you need to access some

4
docs/ref/forms/fields.txt
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
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:
@@ -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
: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``:
.. method:: Field.get_bound_field(form, field_name)

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

@@ -83,12 +83,12 @@ overridden:
called, you also have access to the form's ``errors`` attribute which
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
"field" (called ``__all__``), which you can access via the
: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
:meth:`~django.forms.Form.add_error()`.
:meth:`~django.forms.Form.add_error`.
Also note that there are special considerations when overriding
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
definition), the ``Field.clean()`` method (or its override) is run, then
``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.
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``
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
: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
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

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

@@ -226,7 +226,7 @@ foundation for custom widgets.
This abstract class cannot be rendered, but provides the basic attribute
: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

6
docs/ref/middleware.txt
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`.
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
--------------------------
@@ -154,7 +154,7 @@ header, the middleware adds one if needed. If the response has an ``ETag`` or
:class:`~django.http.HttpResponseNotModified`.
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
-----------------
@@ -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>`.
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
------------------------------

12
docs/ref/models/expressions.txt
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
be used with ``update()`` to perform bulk updates on a ``QuerySet``. This
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.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
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::
@@ -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
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.
``F()`` assignments persist after ``Model.save()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``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.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``,
the final value will be ``3``. This persistence can be avoided by reloading the
model object after saving it, for example, by using
:meth:`~Model.refresh_from_db()`.
:meth:`~Model.refresh_from_db`.
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
``NULLS FIRST``. Modifications are only required for expressions that
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.
.. _writing-your-own-query-expressions:

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

@@ -292,7 +292,7 @@ modifications:
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
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
<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
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
: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.
``unique_for_month``
@@ -1316,8 +1316,8 @@ materialized view.
.. admonition:: Refresh the data
Since the database computes the value, the object must be reloaded to
access the new value after :meth:`~Model.save()`, for example, by using
:meth:`~Model.refresh_from_db()`.
access the new value after :meth:`~Model.save`, for example, by using
:meth:`~Model.refresh_from_db`.
.. admonition:: Database limitations
@@ -1796,7 +1796,7 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in
* .. function:: SET()
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
necessary to avoid executing queries at the time your ``models.py`` is
imported::

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

@@ -23,7 +23,7 @@ class:
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
need to :meth:`~Model.save()`.
need to :meth:`~Model.save`.
.. note::
@@ -226,27 +226,27 @@ Validating objects
There are four steps involved in validating a model:
1. Validate the model fields - :meth:`Model.clean_fields()`
2. Validate the model as a whole - :meth:`Model.clean()`
3. Validate the field uniqueness - :meth:`Model.validate_unique()`
1. Validate the model fields - :meth:`Model.clean_fields`
2. Validate the model as a whole - :meth:`Model.clean`
3. Validate the field uniqueness - :meth:`Model.validate_unique`
4. Validate the constraints - :meth:`Model.validate_constraints`
All four steps are performed when you call a model's :meth:`~Model.full_clean`
method.
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
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
:class:`~django.forms.ModelForm` that require validation.
.. method:: Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True)
This method calls :meth:`Model.clean_fields()`, :meth:`Model.clean()`,
:meth:`Model.validate_unique()` (if ``validate_unique`` is ``True``), and
:meth:`Model.validate_constraints()` (if ``validate_constraints`` is ``True``)
This method calls :meth:`Model.clean_fields`, :meth:`Model.clean`,
:meth:`Model.validate_unique` (if ``validate_unique`` is ``True``), and
:meth:`Model.validate_constraints` (if ``validate_constraints`` is ``True``)
in that order and raises a :exc:`~django.core.exceptions.ValidationError` that
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.
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
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
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.
.. method:: Model.clean()
@@ -306,8 +306,8 @@ access to more than a single field::
if self.status == "published" and self.pub_date is None:
self.pub_date = datetime.date.today()
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.
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.
In the above example, the :exc:`~django.core.exceptions.ValidationError`
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
: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
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
same time!
@@ -672,8 +672,8 @@ perform an update on all fields.
Specifying ``update_fields`` will force an update.
When saving a model fetched through deferred model loading
(: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.only` or
:meth:`~django.db.models.query.QuerySet.defer`) only the fields loaded
from the DB will get updated. In effect there is an automatic
``update_fields`` in this case. If you assign or change any deferred field
value, 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
======================
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:
.. method:: Model.get_FOO_display()

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

@@ -382,7 +382,7 @@ not be looking at your Django code. For example::
.. attribute:: Options.select_on_save
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.
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
@@ -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
``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.
``indexes``

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

@@ -166,7 +166,7 @@ Here's the formal declaration of a ``QuerySet``:
.. attribute:: ordered
``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.
.. attribute:: db
@@ -401,7 +401,7 @@ expression::
(``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
: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.
.. note::
@@ -445,7 +445,7 @@ ordering::
Entry.objects.order_by(Lower("headline").desc())
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
: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``
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
effect (the ordering was undefined prior to calling ``reverse()``, and will
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
ordering), it sometimes looks like non-distinct results are being returned.
Similarly, if you use a :meth:`values()` query to restrict the columns
selected, the columns used in any :meth:`order_by()` (or default model
Similarly, if you use a :meth:`values` query to restrict the columns
selected, the columns used in any :meth:`order_by` (or default model
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
ordering by related models. Similarly, when using ``distinct()`` and
:meth:`values()` together, be careful when ordering by fields not in the
:meth:`values()` call.
:meth:`values` together, be careful when ordering by fields not in the
:meth:`values` call.
On PostgreSQL only, you can pass positional arguments (``*fields``) in order to
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")
<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
details.
* If you use a ``values()`` clause after an :meth:`extra()` call,
any fields defined by a ``select`` argument in the :meth:`extra()` must
be explicitly included in the ``values()`` call. Any :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
be explicitly included in the ``values()`` call. Any :meth:`extra` call
made after a ``values()`` call will have its extra selected fields
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``.
* 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
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
what operations are allowed in the combined queries. For example, most
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"))
... )
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:
.. 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
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:
* 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``
parameter to ``extra()`` and pass in a sequence of strings. These
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
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).
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::
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
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
one, doing so will result in an error.
Similarly, calling ``defer()`` (or its counterpart :meth:`only()`) including an
argument from an aggregation (e.g. using the result of :meth:`annotate()`)
Similarly, calling ``defer()`` (or its counterpart :meth:`only`) including an
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
will always be fetched into the resulting queryset.
.. 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
your queries closely and understand *exactly* what information 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::
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
:meth:`~django.db.models.Model.save()` for more details.
:meth:`~django.db.models.Model.save` for more details.
``only()``
~~~~~~~~~~
@@ -1880,9 +1880,9 @@ are in your ``only()`` call.
.. 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
:meth:`~django.db.models.Model.save()` for more details.
:meth:`~django.db.models.Model.save` for more details.
.. 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
:class:`~django.test.TestCase` automatically wraps each test in a
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
``select_for_update()`` you should use
: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
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``.
.. 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"})
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
created and the key already exists in the database, an
: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
: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
given parameters.
@@ -2774,7 +2774,7 @@ equivalent to the above example::
*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()``
~~~~~~~~~~~~~~~
@@ -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
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
: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` method, loop over them and call
:meth:`~django.db.models.Model.save`, like this::
for e in Entry.objects.filter(pub_date__year=2010):
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
specified as keyword arguments to the ``QuerySet`` methods :meth:`filter()`,
:meth:`exclude()` and :meth:`get()`.
specified as keyword arguments to the ``QuerySet`` methods :meth:`filter`,
:meth:`exclude` and :meth:`get`.
For an introduction, see :ref:`models and database queries documentation
<field-lookups-intro>`.
@@ -4157,11 +4157,11 @@ such as ``|`` (``OR``), ``&`` (``AND``), and ``^`` (``XOR``). See
.. class:: Prefetch(lookup, queryset=None, to_attr=None)
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
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
@@ -4175,7 +4175,7 @@ as the string based lookups passed to
The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup.
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:
.. 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.
``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
relationship but on the annotation name (``pizzas_vegetarian`` in example
below).

2
docs/ref/models/relations.txt
View File

@@ -132,7 +132,7 @@ Related objects reference
>>> e = Entry.objects.get(id=234)
>>> 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
relationship, however, will delete the relationships using
:meth:`QuerySet.delete()<django.db.models.query.QuerySet.delete>` which

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

@@ -225,7 +225,7 @@ application.
.. attribute:: HttpRequest.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
@@ -264,7 +264,7 @@ middleware class is listed in :setting:`MIDDLEWARE`.
From the :class:`~django.contrib.sites.middleware.CurrentSiteMiddleware`:
An instance of :class:`~django.contrib.sites.models.Site` or
: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.
.. attribute:: HttpRequest.user
@@ -310,7 +310,7 @@ Methods
:setting:`ALLOWED_HOSTS` or the domain name is invalid according to
: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
the proxy headers, as in the following example::
@@ -337,7 +337,7 @@ Methods
return self.get_response(request)
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.csrf.CsrfViewMiddleware`.
@@ -381,7 +381,7 @@ Methods
.. note::
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
to redirect users to HTTPS, it's best to let your web server redirect
all HTTP traffic to HTTPS.
@@ -692,7 +692,7 @@ In addition, ``QueryDict`` has the following methods:
.. 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:
.. 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)
Like :meth:`~HttpResponse.set_cookie()`, but
Like :meth:`~HttpResponse.set_cookie`, but
:doc:`cryptographic signing </topics/signing>` the cookie before setting
it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`.
You can use the optional ``salt`` argument for added key strength, but

10
docs/ref/settings.txt
View File

@@ -90,7 +90,7 @@ strips when performing host validation.
If the ``Host`` header (or ``X-Forwarded-Host`` if
: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`.
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
<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
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
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
: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
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
any other session backend than ``django.contrib.sessions.backends.cache``,
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
:class:`~django.contrib.messages.storage.cookie.CookieStorage` or
:class:`~django.contrib.messages.storage.fallback.FallbackStorage`.
@@ -2648,7 +2648,7 @@ protocol.
.. admonition:: Why are my emails sent from a different address?
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`.
.. setting:: SHORT_DATE_FORMAT

12
docs/ref/template-response.txt
View File

@@ -33,7 +33,7 @@ Attributes
The name of the template to be rendered. Accepts 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.
Example: ``['foo.html', 'path/to/bar.html']``
@@ -65,7 +65,7 @@ Methods
``template``
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.
``context``
@@ -105,7 +105,7 @@ Methods
Resolves the template instance to use for rendering. Accepts 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.
Returns the backend-dependent template object instance to be rendered.
@@ -163,7 +163,7 @@ Methods
``template``
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.
``context``
@@ -203,7 +203,7 @@ There are three circumstances under which a ``TemplateResponse`` will be
rendered:
* 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
``response.content``.
@@ -293,7 +293,7 @@ Using ``TemplateResponse`` and ``SimpleTemplateResponse``
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
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
template and a context containing a queryset::

4
docs/ref/unicode.txt
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
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`.
* 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
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`.
An example to demonstrate:

8
docs/ref/urls.txt
View File

@@ -29,7 +29,7 @@ Returns an element for inclusion in ``urlpatterns``. For example::
---------
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
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
@@ -93,7 +93,7 @@ Returns an element for inclusion in ``urlpatterns``. For example::
]
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
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
@@ -107,7 +107,7 @@ When a ``route`` ends with ``$`` the whole requested URL, matching against
pattern (:py:func:`re.fullmatch` is used).
The ``view``, ``kwargs`` and ``name`` arguments are the same as for
:func:`~django.urls.path()`.
:func:`~django.urls.path`.
``include()``
=============
@@ -143,7 +143,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
.. 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.
The ``converter`` argument is a converter class, and ``type_name`` is the

10
docs/ref/utils.txt
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
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.
.. attribute:: media
@@ -977,10 +977,10 @@ appropriate entities.
.. function:: override(timezone)
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
``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.
@@ -1133,8 +1133,8 @@ For a complete discussion on the usage of the following see the
.. function:: get_language()
Returns the currently selected language code. Returns ``None`` if
translations are temporarily deactivated (by :func:`deactivate_all()` or
when ``None`` is passed to :func:`override()`).
translations are temporarily deactivated (by :func:`deactivate_all` or
when ``None`` is passed to :func:`override`).
.. function:: get_language_bidi()