mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-23 21:59:11 +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

24
docs/topics/auth/customizing.txt
View File

@@ -46,7 +46,7 @@ Specifying authentication backends
Behind the scenes, Django maintains a list of "authentication backends" that it
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
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.
@@ -187,12 +187,12 @@ Handling authorization in custom backends
Custom auth backends can provide their own permissions.
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_group_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_module_perms()`, and
:meth:`~django.contrib.auth.models.UserManager.with_perm()`) to any
(: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_all_permissions`,
:meth:`~django.contrib.auth.models.User.has_perm`,
:meth:`~django.contrib.auth.models.User.has_module_perms`, and
:meth:`~django.contrib.auth.models.UserManager.with_perm`) to any
authentication backend that implements these functions.
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.
If a backend raises a :class:`~django.core.exceptions.PermissionDenied`
exception in :meth:`~django.contrib.auth.models.User.has_perm()` or
:meth:`~django.contrib.auth.models.User.has_module_perms()`, the authorization
exception in :meth:`~django.contrib.auth.models.User.has_perm` or
:meth:`~django.contrib.auth.models.User.has_module_perms`, the authorization
will immediately fail and Django won't check the backends that follow.
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
unusable password, as if
:meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()`
:meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password`
were used.
.. 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
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
: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()
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.
.. method:: models.AbstractBaseUser.get_session_auth_hash()

46
docs/topics/auth/default.txt
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.
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
@@ -124,7 +124,7 @@ Authenticating users
*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
``password`` for the default case, checks them against each
: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()``
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
: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.
Note that any data set during the anonymous session is retained in the
session after a user logs in.
This example shows how you might use both
:func:`~django.contrib.auth.authenticate()` and
:func:`~django.contrib.auth.login()`::
:func:`~django.contrib.auth.authenticate` and
:func:`~django.contrib.auth.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 ``user.backend`` attribute, if present. This allows
pairing :func:`~django.contrib.auth.authenticate()` and
:func:`~django.contrib.auth.login()`:
:func:`~django.contrib.auth.authenticate()`
pairing :func:`~django.contrib.auth.authenticate` and
:func:`~django.contrib.auth.login`:
:func:`~django.contrib.auth.authenticate`
sets the ``user.backend`` attribute on the user object it returns.
#. Use the ``backend`` in :setting:`AUTHENTICATION_BACKENDS`, if there is only
one.
@@ -470,8 +470,8 @@ How to log a user out
*Asynchronous version*: ``alogout()``
To log out a user who has been logged in via
:func:`django.contrib.auth.login()`, use
:func:`django.contrib.auth.logout()` within your view. It takes an
:func:`django.contrib.auth.login`, use
:func:`django.contrib.auth.logout` within your view. It takes an
:class:`~django.http.HttpRequest` object and has no return value.
Example::
@@ -482,16 +482,16 @@ How to log a user out
logout(request)
# 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.
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
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 put anything into the session that will be available to the user
immediately after logging out, do that *after* calling
:func:`django.contrib.auth.logout()`.
:func:`django.contrib.auth.logout`.
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
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
@@ -785,7 +785,7 @@ The ``permission_required`` decorator
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.
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::
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
execute the decorated view. By default, this returns the result of
calling :meth:`~django.contrib.auth.models.User.has_perms()` with the
list of permissions returned by :meth:`get_permission_required()`.
calling :meth:`~django.contrib.auth.models.User.has_perms` with the
list of permissions returned by :meth:`get_permission_required`.
Redirecting unauthorized requests in class-based views
------------------------------------------------------
@@ -930,7 +930,7 @@ Session invalidation on password change
If your :setting:`AUTH_USER_MODEL` inherits from
: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.
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
@@ -972,7 +972,7 @@ function.
.. note::
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
rotated to avoid invalidating existing sessions when updating your site to
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
:func:`~django.contrib.auth.password_validation.validate_password`, and
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
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
@@ -1696,7 +1696,7 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
validates the password using
:func:`~django.contrib.auth.password_validation.validate_password`, and
sets the user's password using
:meth:`~django.contrib.auth.models.User.set_password()`.
:meth:`~django.contrib.auth.models.User.set_password`.
.. class:: PasswordChangeForm

12
docs/topics/class-based-views/generic-editing.txt
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
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.
* If a :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` is
given, the model for that queryset will be used.
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
special requirements; see below for examples.
You don't even need to provide a ``success_url`` for
:class:`~django.views.generic.edit.CreateView` or
: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
add extra validation), set
@@ -95,7 +95,7 @@ add extra validation), set
even though the :attr:`~django.views.generic.edit.FormMixin.form_class` may
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:
.. 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
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
:caption: ``views.py``
@@ -228,7 +228,7 @@ to edit, and override
: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
handle unauthorized users in :meth:`~.ModelFormMixin.form_valid()`.
handle unauthorized users in :meth:`~.ModelFormMixin.form_valid`.
.. _content-negotiation-example:

22
docs/topics/class-based-views/mixins.txt
View File

@@ -34,7 +34,7 @@ interface to working with templates in class-based views.
:class:`~django.views.generic.base.TemplateResponseMixin`
Every built in view which returns a
: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
will be called for you (for instance, it is called by the ``get()`` method
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`
Every built in view which needs context data, such as for rendering a
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.
``get_context_data()`` returns a dictionary; in ``ContextMixin`` it
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
:attr:`~django.views.generic.detail.SingleObjectMixin.queryset`
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
context data for template renders.
@@ -115,7 +115,7 @@ To then make a :class:`~django.template.response.TemplateResponse`,
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`,
which extends :class:`~django.views.generic.base.TemplateResponseMixin`,
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,
but the main one that most people are going to use is
``<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.
: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
dummies if pagination is disabled). It relies on ``object_list`` being
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
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
correct ``Publisher`` object.
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})
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
based view, so we can do that at the point we choose between the two subviews.
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``
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.
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
``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
:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`,
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
that the user requested::
@@ -691,5 +691,5 @@ that the user requested::
Because of the way that Python resolves method overloading, the call to
``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`.

4
docs/topics/db/models.txt
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
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
QuerySet <topics-db-queries-delete>` or as a result of a :attr:`cascading
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
:meth:`creating<django.db.models.query.QuerySet.bulk_create>` or
: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.post_save` are called.

22
docs/topics/db/optimization.txt
View File

@@ -40,9 +40,9 @@ Use standard DB optimization techniques
:attr:`Meta.indexes <django.db.models.Options.indexes>` or
: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
:meth:`~django.db.models.query.QuerySet.filter()`,
: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.filter`,
:meth:`~django.db.models.query.QuerySet.exclude`,
: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
database-dependent topic that will depend on your particular application.
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
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()``
-----------------
@@ -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
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
the dicts you supply have the same attributes as those used in the template,
you are fine.
@@ -235,8 +235,8 @@ you are fine.
Use ``QuerySet.defer()`` and ``only()``
---------------------------------------
Use :meth:`~django.db.models.query.QuerySet.defer()` and
:meth:`~django.db.models.query.QuerySet.only()` if there are database columns
Use :meth:`~django.db.models.query.QuerySet.defer` and
: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
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.
@@ -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
<django.db.models.Options.ordering>`) and you don't need it, remove
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.
@@ -362,7 +362,7 @@ Create in bulk
--------------
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::
Entry.objects.bulk_create(
@@ -385,7 +385,7 @@ Update in bulk
--------------
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::
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
:class:`~django.db.models.ManyToManyField` or when the custom
: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::
PizzaToppingRelationship = Pizza.toppings.through

2
docs/topics/db/queries.txt
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.
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
=========================

4
docs/topics/db/sql.txt
View File

@@ -5,7 +5,7 @@ Performing raw SQL queries
.. currentmodule:: django.db.models
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`__.
__ `performing raw queries`_
@@ -170,7 +170,7 @@ Fields may also be left out:
>>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person")
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:
.. code-block:: pycon

26
docs/topics/email.txt
View File

@@ -133,11 +133,11 @@ can be ``0`` or ``1`` since it can only send one message).
(subject, message, from_email, recipient_list)
``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.
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'
"To:" field.
@@ -169,12 +169,12 @@ The return value will be the number of successfully delivered messages.
``send_mass_mail()`` vs. ``send_mail()``
----------------------------------------
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()` opens a connection to the mail server
each time it's executed, while :meth:`~django.core.mail.send_mass_mail()` uses
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` opens a connection to the mail server
each time it's executed, while :meth:`~django.core.mail.send_mass_mail` uses
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()``
=================
@@ -248,7 +248,7 @@ scripts generate.
The Django email functions outlined above all protect against header injection
by forbidding newlines in header values. If any ``subject``, ``from_email`` or
``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
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
==========================
Django's :meth:`~django.core.mail.send_mail()` and
:meth:`~django.core.mail.send_mass_mail()` functions are actually thin
Django's :meth:`~django.core.mail.send_mail` and
:meth:`~django.core.mail.send_mass_mail` functions are actually thin
wrappers that make use of the :class:`~django.core.mail.EmailMessage` class.
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
recipients, file attachments, or multi-part email, you'll need to create
:class:`~django.core.mail.EmailMessage` instances directly.
.. 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.
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
@@ -714,7 +714,7 @@ SMTP backend
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
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:

2
docs/topics/forms/index.txt
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
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
fields contain valid data, it will:

8
docs/topics/forms/modelforms.txt
View File

@@ -237,17 +237,17 @@ There are two main steps involved in validating a ``ModelForm``:
2. :ref:`Validating the model instance <validating-objects>`
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
``full_clean()``, although you will typically not use the latter method in
practice.
``Model`` validation is triggered from within the form validation step right
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
: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_unique` and
:meth:`~django.db.models.Model.validate_constraints` methods are called in
order.
.. warning::

8
docs/topics/http/sessions.txt
View File

@@ -253,7 +253,7 @@ You can edit it multiple times.
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
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:: aset_test_cookie()
@@ -380,7 +380,7 @@ You can edit it multiple times.
*Asynchronous version*: ``acycle_key()``
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_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.
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.
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)
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
format:

8
docs/topics/http/shortcuts.txt
View File

@@ -23,7 +23,7 @@ introduce controlled coupling for convenience's sake.
Django does not provide a shortcut function which returns a
:class:`~django.template.response.TemplateResponse` because the constructor
of :class:`~django.template.response.TemplateResponse` offers the same level
of convenience as :func:`render()`.
of convenience as :func:`render`.
Required arguments
------------------
@@ -98,7 +98,7 @@ This example is equivalent to::
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.
* 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()``
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
: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()``
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`
if the resulting list is empty.

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

@@ -377,7 +377,7 @@ itself. It includes a number of other URLconfs::
# ... 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
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
applications' choice of names. If you call your URL pattern ``comment``
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.
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
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``,
: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
included at all).
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
converters can also raise ``ValueError`` to indicate no match, see
: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
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.
The :ttag:`url` template tag uses the namespace of the currently resolved

32
docs/topics/i18n/translation.txt
View File

@@ -180,7 +180,7 @@ more details.
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
translated from a variable.
@@ -192,7 +192,7 @@ such as when the string is presented to the user.
Pluralization
-------------
Use the function :func:`django.utils.translation.ngettext()` to specify
Use the function :func:`django.utils.translation.ngettext` to specify
pluralized messages.
``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
refers to a month name and to a verb. To enable translators to translate
these words correctly in different contexts, you can use the
:func:`django.utils.translation.pgettext()` function, or the
:func:`django.utils.translation.npgettext()` function if the string needs
:func:`django.utils.translation.pgettext` function, or the
:func:`django.utils.translation.npgettext` function if the string needs
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
@@ -502,10 +502,10 @@ directly with the ``number`` argument::
Formatting strings: ``format_lazy()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Python's :meth:`str.format()` method will not work when either the
``format_string`` or any of the arguments to :meth:`str.format()`
Python's :meth:`str.format` method will not work when either the
``format_string`` or any of the arguments to :meth:`str.format`
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
in a string. For example::
@@ -1224,7 +1224,7 @@ in the future.
~~~~~~~~~~~~
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::
document.write(pgettext("month name", "May"))
@@ -1233,7 +1233,7 @@ translated word::
~~~~~~~~~~~~~
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:
.. code-block:: javascript
@@ -1365,7 +1365,7 @@ Django provides two mechanisms to internationalize URL patterns:
the language to activate from the requested URL.
* Making URL patterns themselves translatable via the
:func:`django.utils.translation.gettext_lazy()` function.
:func:`django.utils.translation.gettext_lazy` function.
.. warning::
@@ -1931,7 +1931,7 @@ Explicitly setting the active language
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.
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
session in a cookie, set the :setting:`LANGUAGE_COOKIE_NAME` cookie on the
response::
@@ -1945,7 +1945,7 @@ response::
response = HttpResponse(...)
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
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.
Functions of particular interest are
:func:`django.utils.translation.get_language()` which returns the language used
in the current thread, :func:`django.utils.translation.activate()` which
:func:`django.utils.translation.get_language` which returns the language used
in the current thread, :func:`django.utils.translation.activate` which
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.
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::
from django.utils import translation

2
docs/topics/logging.txt
View File

@@ -419,7 +419,7 @@ logger, you can specify your own configuration scheme.
The :setting:`LOGGING_CONFIG` setting defines the callable that will
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
that takes a single argument. The contents of :setting:`LOGGING` will
be provided as the value of that argument when logging is configured.

2
docs/topics/migrations.txt
View File

@@ -189,7 +189,7 @@ You can prevent a migration from running in a transaction by setting the
atomic = False
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
:ref:`non-atomic-migrations` for more details.

4
docs/topics/security.txt
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
``Host`` headers, Django validates ``Host`` headers against 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
are bypassing this security protection.

2
docs/topics/settings.txt
View File

@@ -280,7 +280,7 @@ ORM to fetch some data -- there's one more step you'll need in addition to
configuring settings.
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::
import django

6
docs/topics/templates.txt
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
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
some stories to have custom templates, use something like
``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"})
See also the :func:`~django.shortcuts.render()` shortcut which calls
:func:`render_to_string()` and feeds the result into an
See also the :func:`~django.shortcuts.render` shortcut which calls
:func:`render_to_string` and feeds the result into an
:class:`~django.http.HttpResponse` suitable for returning from a view.
Finally, you can use configured engines directly:

14
docs/topics/testing/advanced.txt
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
restricted subset of the test client API:
* It only has access to the HTTP methods :meth:`~Client.get()`,
:meth:`~Client.post()`, :meth:`~Client.put()`,
:meth:`~Client.delete()`, :meth:`~Client.head()`,
:meth:`~Client.options()`, and :meth:`~Client.trace()`.
* It only has access to the HTTP methods :meth:`~Client.get`,
:meth:`~Client.post`, :meth:`~Client.put`,
:meth:`~Client.delete`, :meth:`~Client.head`,
:meth:`~Client.options`, and :meth:`~Client.trace`.
* These methods accept all the same arguments *except* for
``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", ...]
Another option is to add the required hosts to :setting:`ALLOWED_HOSTS` using
:meth:`~django.test.override_settings()` or
:attr:`~django.test.SimpleTestCase.modify_settings()`. This option may be
:meth:`~django.test.override_settings` or
:attr:`~django.test.SimpleTestCase.modify_settings`. This option may be
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
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
: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.
.. method:: DiscoverRunner.setup_test_environment(**kwargs)

2
docs/topics/testing/overview.txt
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.
This also applies to customized implementations of
:meth:`~django.apps.AppConfig.ready()`.
:meth:`~django.apps.AppConfig.ready`.
.. seealso::

10
docs/topics/testing/tools.txt
View File

@@ -144,8 +144,8 @@ Use the ``django.test.Client`` class to make requests.
but the ``headers`` parameter should be preferred for readability.
The values from the ``headers``, ``query_params``, and ``extra`` keyword
arguments passed to :meth:`~django.test.Client.get()`,
:meth:`~django.test.Client.post()`, etc. have precedence over
arguments passed to :meth:`~django.test.Client.get`,
:meth:`~django.test.Client.post`, etc. have precedence over
the defaults passed to the class constructor.
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
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
: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,
you can't set the user's password by setting the password attribute
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
:meth:`~django.contrib.auth.models.UserManager.create_user` helper
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,
you cannot test that a block of code is executing within a transaction, as is
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``.
``TransactionTestCase`` and ``TestCase`` are identical except for the manner