mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-11-07 07:15:35 +00:00
Code Issues 32 Releases Wiki Activity

Fixed #36329 -- Removed non-code custom link text when cross-referencing Python objects.

Browse Source 
Thanks Bruno Alla, Sarah Boyce, and Jacob Walls for reviews.

Co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>
This commit is contained in:
Clifford Gama
2025-10-29 17:32:12 +02:00
committed by GitHub
parent 1aa69a7491
commit 01f8460653
26 changed files with 168 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/topics/auth/default.txt
View File

@@ -37,8 +37,8 @@ The primary attributes of the default user are:
* :attr:`~django.contrib.auth.models.User.first_name`
* :attr:`~django.contrib.auth.models.User.last_name`
See the :class:`full API documentation <django.contrib.auth.models.User>` for
full reference, the documentation that follows is more task oriented.
See the :class:`~django.contrib.auth.models.User` API documentation for a
complete reference. The documentation that follows is more task-oriented.
.. _topics-auth-creating-users:
@@ -368,7 +368,7 @@ Authentication in web requests
==============================
Django uses :doc:`sessions </topics/http/sessions>` and middleware to hook the
authentication system into :class:`request objects <django.http.HttpRequest>`.
authentication system into :class:`~django.http.HttpRequest` objects.
These provide a :attr:`request.user <django.http.HttpRequest.user>` attribute
and a :meth:`request.auser <django.http.HttpRequest.auser>` async method
@@ -1619,9 +1619,9 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`:
.. class:: AdminPasswordChangeForm
A form used in the admin interface to change a user's password, including
the ability to set an :meth:`unusable password
<django.contrib.auth.models.User.set_unusable_password>`, which blocks the
user from logging in with password-based authentication.
the ability to set an unusable password (via
:meth:`~django.contrib.auth.models.User.set_unusable_password`), which
blocks the user from logging in with password-based authentication.
Takes the ``user`` as the first positional argument.

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

@@ -156,12 +156,13 @@ it.
To make a :class:`~django.template.response.TemplateResponse`,
:class:`ListView` then uses
:class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`; as
with :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
above, this overrides ``get_template_names()`` to provide :meth:`a range of
options <django.views.generic.list.MultipleObjectTemplateResponseMixin>`, with
the most commonly-used being ``<app_label>/<model_name>_list.html``, with the
``_list`` part again being taken from the
:class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`.
As with :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
above, this overrides
:meth:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.get_template_names`
to provide a range of options, with the most commonly-used being
``<app_label>/<model_name>_list.html``, with the ``_list`` part again
being taken from the
:attr:`~django.views.generic.list.MultipleObjectTemplateResponseMixin.template_name_suffix`
attribute. (The date based generic views use suffixes such as ``_archive``,
``_archive_year`` and so on to use different templates for the various

11
docs/topics/composite-primary-key.txt
View File

@@ -199,8 +199,7 @@ Building composite primary key ready applications
Prior to the introduction of composite primary keys, the single field composing
the primary key of a model could be retrieved by introspecting the
:attr:`primary key <django.db.models.Field.primary_key>` attribute of its
fields:
:attr:`~django.db.models.Field.primary_key` attribute of its fields:
.. code-block:: pycon
@@ -214,10 +213,10 @@ fields:
<django.db.models.fields.AutoField: id>
Now that a primary key can be composed of multiple fields the
:attr:`primary key <django.db.models.Field.primary_key>` attribute can no
longer be relied upon to identify members of the primary key as it will be set
to ``False`` to maintain the invariant that at most one field per model will
have this attribute set to ``True``:
:attr:`~django.db.models.Field.primary_key` attribute can no longer be relied
upon to identify members of the primary key as it will be set to ``False`` to
maintain the invariant that at most one field per model will have this
attribute set to ``True``:
.. code-block:: pycon

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

@@ -968,8 +968,8 @@ See :ref:`ref-models-update-fields` for more details.
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
QuerySet <topics-db-queries-delete>` or as a result of a cascading delete
(see :attr:`~django.db.models.ForeignKey.on_delete`). To ensure customized
delete logic gets executed, you can use
:data:`~django.db.models.signals.pre_delete` and/or
:data:`~django.db.models.signals.post_delete` signals.

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

@@ -133,8 +133,8 @@ For instance:
* At the most basic level, use :ref:`filter and exclude <queryset-api>` to do
filtering in the database.
* Use :class:`F expressions <django.db.models.F>` to filter
based on other fields within the same model.
* Use :ref:`f-expressions` to filter based on other fields within the same
model.
* Use :doc:`annotate to do aggregation in the database
</topics/db/aggregation>`.
@@ -396,9 +396,8 @@ number of SQL queries. For example::
Entry.objects.create(headline="This is a test")
Entry.objects.create(headline="This is only a test")
Note that there are a number of :meth:`caveats to this method
<django.db.models.query.QuerySet.bulk_create>`, so make sure it's appropriate
for your use case.
Note that :meth:`~django.db.models.query.QuerySet.bulk_create` has several
caveats, so ensure it's appropriate for your use case.
Update in bulk
--------------
@@ -427,9 +426,8 @@ The following example::
entries[1].headline = "This is no longer a test"
entries[1].save()
Note that there are a number of :meth:`caveats to this method
<django.db.models.query.QuerySet.bulk_update>`, so make sure it's appropriate
for your use case.
Note that :meth:`~django.db.models.query.QuerySet.bulk_update` has several
caveats, so ensure it's appropriate for your use case.
Insert in bulk
--------------
@@ -491,12 +489,12 @@ objects to reduce the number of SQL queries. For example::
...where ``Band`` and ``Artist`` are models with a many-to-many relationship.
When removing different pairs of objects from :class:`ManyToManyFields
<django.db.models.ManyToManyField>`, use
:meth:`~django.db.models.query.QuerySet.delete` on a
:class:`~django.db.models.Q` expression with multiple
:attr:`~django.db.models.ManyToManyField.through` model instances to reduce
the number of SQL queries. For example::
When removing multiple many-to-many relationships involving several instances
of the related models, use the :meth:`~django.db.models.query.QuerySet.delete`
method on a filtered queryset of the field's
:attr:`~django.db.models.ManyToManyField.through` model. By combining multiple
conditions with :ref:`q-objects`, you can delete several relationships in a
single query. For example::
from django.db.models import Q

32
docs/topics/db/queries.txt
View File

@@ -541,9 +541,10 @@ is ``'Beatles Blog'``:
This spanning can be as deep as you'd like.
It works backwards, too. While it :attr:`can be customized
<.ForeignKey.related_query_name>`, by default you refer to a "reverse"
relationship in a lookup using the lowercase name of the model.
It works backwards, too. While it can be customized by setting
:class:`~django.db.models.ForeignKey.related_query_name`, by default you
refer to a "reverse" relationship in a lookup using the lowercase name of the
model.
This example retrieves all ``Blog`` objects which have at least one ``Entry``
whose ``headline`` contains ``'Lennon'``:
@@ -692,10 +693,10 @@ In the examples given so far, we have constructed filters that compare
the value of a model field with a constant. But what if you want to compare
the value of a model field with another field on the same model?
Django provides :class:`F expressions <django.db.models.F>` to allow such
comparisons. Instances of ``F()`` act as a reference to a model field within a
query. These references can then be used in query filters to compare the values
of two different fields on the same model instance.
Django provides :ref:`f-expressions` to allow such comparisons. Instances of
``F()`` act as a reference to a model field within a query. These references
can then be used in query filters to compare the values of two different fields
on the same model instance.
For example, to find a list of all blog entries that have had more comments
than pingbacks, we construct an ``F()`` object to reference the pingback count,
@@ -1370,12 +1371,11 @@ Complex lookups with ``Q`` objects
Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.filter`,
etc. -- are "AND"ed together. If you need to execute more complex queries (for
example, queries with ``OR`` statements), you can use
:class:`Q objects <django.db.models.Q>`.
example, queries with ``OR`` statements), you can use :ref:`q-objects`.
A :class:`Q object <django.db.models.Q>` (``django.db.models.Q``) is an object
used to encapsulate a collection of keyword arguments. These keyword arguments
are specified as in "Field lookups" above.
A :ref:`Q object <q-objects>` (``django.db.models.Q``) is an object used to
encapsulate a collection of keyword arguments. These keyword arguments are
specified as in "Field lookups" above.
For example, this ``Q`` object encapsulates a single ``LIKE`` query::
@@ -1659,10 +1659,10 @@ them and call :meth:`~django.db.models.Model.save`::
for item in my_queryset:
item.save()
Calls to update can also use :class:`F expressions <django.db.models.F>` to
update one field based on the value of another field in the model. This is
especially useful for incrementing counters based upon their current value. For
example, to increment the pingback count for every entry in the blog:
Calls to update can also use :ref:`f-expressions` to update one field based on
the value of another field in the model. This is especially useful for
incrementing counters based upon their current value. For example, to increment
the pingback count for every entry in the blog:
.. code-block:: pycon

5
docs/topics/forms/formsets.txt
View File

@@ -50,8 +50,9 @@ following example will create a formset class to display two blank forms:
Formsets can be iterated and indexed, accessing forms in the order they were
created. You can reorder the forms by overriding the default
:meth:`iteration <object.__iter__>` and
:meth:`indexing <object.__getitem__>` behavior if needed.
:meth:`~object.__iter__` and :meth:`~object.__getitem__` methods if needed.
(For more information on implementing these methods, see the
:term:`Python documentation on sequences <sequence>`.)
.. _formsets-initial-data:

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

@@ -299,14 +299,14 @@ for more information on the model's ``clean()`` hook.
Considerations regarding model's ``error_messages``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Error messages defined at the
:attr:`form field <django.forms.Field.error_messages>` level or at the
Error messages defined at the form field level (
:attr:`django.forms.Field.error_messages`) or at the
:ref:`form Meta <modelforms-overriding-default-fields>` level always take
precedence over the error messages defined at the
:attr:`model field <django.db.models.Field.error_messages>` level.
precedence over the error messages defined at the model field level
(:attr:`django.db.models.Field.error_messages`).
Error messages defined on :attr:`model fields
<django.db.models.Field.error_messages>` are only used when the
Error messages defined on model fields
(:attr:`django.db.models.Field.error_messages`) are only used when the
``ValidationError`` is raised during the :ref:`model validation
<validating-objects>` step and no corresponding error messages are defined at
the form level.

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

@@ -206,7 +206,7 @@ Arguments
the object.
``*args``
:class:`Q objects <django.db.models.Q>`.
:ref:`q-objects`.
``**kwargs``
Lookup parameters, which should be in the format accepted by ``get()`` and
@@ -286,7 +286,7 @@ Arguments
list.
``*args``
:class:`Q objects <django.db.models.Q>`.
:ref:`q-objects`.
``**kwargs``
Lookup parameters, which should be in the format accepted by ``get()`` and

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

@@ -1043,7 +1043,7 @@ The ``JavaScriptCatalog`` view
.. attribute:: packages
A list of :attr:`application names <django.apps.AppConfig.name>` among
A list of application names (:attr:`.AppConfig.name`) among the
installed applications. Those apps should contain a ``locale``
directory. All those catalogs plus all catalogs found in
:setting:`LOCALE_PATHS` (which are always included) are merged into one

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

@@ -801,26 +801,21 @@ A subclass of :class:`unittest.TestCase` that adds this functionality:
* Some useful assertions like:
* Checking that a callable :meth:`raises a certain exception
<SimpleTestCase.assertRaisesMessage>`.
* Checking that a callable :meth:`triggers a certain warning
<SimpleTestCase.assertWarnsMessage>`.
* Testing form field :meth:`rendering and error treatment
<SimpleTestCase.assertFieldOutput>`.
* Testing :meth:`HTML responses for the presence/lack of a given fragment
<SimpleTestCase.assertContains>`.
* Verifying that a template :meth:`has/hasn't been used to generate a given
response content <SimpleTestCase.assertTemplateUsed>`.
* Verifying that two :meth:`URLs <SimpleTestCase.assertURLEqual>` are equal.
* Verifying an HTTP :meth:`redirect <SimpleTestCase.assertRedirects>` is
performed by the app.
* Robustly testing two :meth:`HTML fragments
<SimpleTestCase.assertHTMLEqual>` for equality/inequality or
:meth:`containment <SimpleTestCase.assertInHTML>`.
* Robustly testing two :meth:`XML fragments <SimpleTestCase.assertXMLEqual>`
for equality/inequality.
* Robustly testing two :meth:`JSON fragments
<SimpleTestCase.assertJSONEqual>` for equality.
=========================================== ======================================
Assertion What it checks
=========================================== ======================================
:meth:`~SimpleTestCase.assertRaisesMessage` That a callable raises a certain exception
:meth:`~SimpleTestCase.assertWarnsMessage` That a callable triggers a certain warning
:meth:`~SimpleTestCase.assertFieldOutput` Form field rendering and error output
:meth:`~SimpleTestCase.assertContains` Presence or absence of HTML fragments
:meth:`~SimpleTestCase.assertTemplateUsed` Template usage in a response
:meth:`~SimpleTestCase.assertURLEqual` That two URLs are equal
:meth:`~SimpleTestCase.assertRedirects` That an HTTP redirect occurred
:meth:`~SimpleTestCase.assertHTMLEqual` HTML fragment equality
:meth:`~SimpleTestCase.assertInHTML` HTML fragment containment
:meth:`~SimpleTestCase.assertXMLEqual` XML fragment equality or inequality
:meth:`~SimpleTestCase.assertJSONEqual` JSON fragment equality
=========================================== ======================================
* The ability to run tests with :ref:`modified settings <overriding-settings>`.
* Using the :attr:`~SimpleTestCase.client` :class:`~django.test.Client`.
@@ -1688,7 +1683,7 @@ your test suite.
.. method:: SimpleTestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)
Asserts that a :class:`response <django.http.HttpResponse>` produced the
Asserts that an :class:`~django.http.HttpResponse` produced the
given :attr:`~django.http.HttpResponse.status_code` and that ``text``
appears in its :attr:`~django.http.HttpResponse.content`. If ``count``
is provided, ``text`` must occur exactly ``count`` times in the response.
@@ -1701,7 +1696,7 @@ your test suite.
.. method:: SimpleTestCase.assertNotContains(response, text, status_code=200, msg_prefix='', html=False)
Asserts that a :class:`response <django.http.HttpResponse>` produced the
Asserts that an :class:`~django.http.HttpResponse` produced the
given :attr:`~django.http.HttpResponse.status_code` and that ``text`` does
*not* appear in its :attr:`~django.http.HttpResponse.content`.
@@ -1716,8 +1711,8 @@ your test suite.
Asserts that the template with the given name was used in rendering the
response.
``response`` must be a response instance returned by the
:class:`test client <django.test.Response>`.
``response`` must be a :class:`~django.test.Response` instance returned by
the test client.
``template_name`` should be a string such as ``'admin/index.html'``.
@@ -1749,9 +1744,10 @@ your test suite.
.. method:: SimpleTestCase.assertRedirects(response, expected_url, status_code=302, target_status_code=200, msg_prefix='', fetch_redirect_response=True)
Asserts that the :class:`response <django.http.HttpResponse>` returned a
:attr:`~django.http.HttpResponse.status_code` redirect status, redirected
to ``expected_url`` (including any ``GET`` data), and that the final page
Asserts that the :class:`~django.http.HttpResponse` returned a response
with a redirect status (based on its
:attr:`~django.http.HttpResponse.status_code`), redirected to
``expected_url`` (including any ``GET`` data), and that the final response
was received with ``target_status_code``.
If your request used the ``follow`` argument, the ``expected_url`` and