1
0
mirror of https://github.com/django/django.git synced 2025-04-09 07:56:43 +00:00

Fixed incorrect formatting for inline pluralized code references in docs.

This commit is contained in:
Clifford Gama 2025-03-13 20:18:35 +02:00 committed by GitHub
parent e7a9d756ee
commit efe3ca09e0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 64 additions and 58 deletions

View File

@ -461,11 +461,11 @@ Testing our new view
--------------------
Now you can satisfy yourself that this behaves as expected by firing up
``runserver``, loading the site in your browser, creating ``Questions`` with
dates in the past and future, and checking that only those that have been
published are listed. You don't want to have to do that *every single time you
make any change that might affect this* - so let's also create a test, based on
our :djadmin:`shell` session above.
``runserver``, loading the site in your browser, creating a few ``Question``
entries with dates in the past and future, and checking that only those that
have been published are listed. You don't want to have to do that *every single
time you make any change that might affect this* - so let's also create a test,
based on our :djadmin:`shell` session above.
Add the following to ``polls/tests.py``:
@ -626,14 +626,14 @@ create a new test class for that view. It'll be very similar to what we have
just created; in fact there will be a lot of repetition.
We could also improve our application in other ways, adding tests along the
way. For example, it's silly that ``Questions`` can be published on the site
that have no ``Choices``. So, our views could check for this, and exclude such
``Questions``. Our tests would create a ``Question`` without ``Choices`` and
then test that it's not published, as well as create a similar ``Question``
*with* ``Choices``, and test that it *is* published.
way. For example, it's pointless that a ``Question`` with no related ``Choice``
can be published on the site. So, our views could check for this, and exclude
such ``Question`` objects. Our tests would create a ``Question`` without a
``Choice``, and then test that it's not published, as well as create a similar
``Question`` *with* at least one ``Choice``, and test that it *is* published.
Perhaps logged-in admin users should be allowed to see unpublished
``Questions``, but not ordinary visitors. Again: whatever needs to be added to
Perhaps logged-in admin users should be allowed to see unpublished ``Question``
entries, but not ordinary visitors. Again: whatever needs to be added to
the software to accomplish this should be accompanied by a test, whether you
write the test first and then make the code pass the test, or work out the
logic in your code first and then write a test to prove it.
@ -653,9 +653,10 @@ once and then forget about it. It will continue performing its useful function
as you continue to develop your program.
Sometimes tests will need to be updated. Suppose that we amend our views so that
only ``Questions`` with ``Choices`` are published. In that case, many of our
existing tests will fail - *telling us exactly which tests need to be amended to
bring them up to date*, so to that extent tests help look after themselves.
only ``Question`` entries with associated ``Choice`` instances are published.
In that case, many of our existing tests will fail - *telling us exactly which
tests need to be amended to bring them up to date*, so to that extent tests
help look after themselves.
At worst, as you continue developing, you might find that you have some tests
that are now redundant. Even that's not a problem; in testing redundancy is

View File

@ -97,7 +97,8 @@ The following mixins are used to construct Django's editing views:
.. class:: django.views.generic.edit.ModelFormMixin
A form mixin that works on ``ModelForms``, rather than a standalone form.
A form mixin that provides facilities for working with a ``ModelForm``,
rather than a standalone form.
Since this is a subclass of
:class:`~django.views.generic.detail.SingleObjectMixin`, instances of this

View File

@ -824,7 +824,7 @@ Substring matching and case sensitivity
For all SQLite versions, there is some slightly counterintuitive behavior when
attempting to match some types of strings. These are triggered when using the
:lookup:`iexact` or :lookup:`contains` filters in Querysets. The behavior
:lookup:`iexact` or :lookup:`contains` filters in querysets. The behavior
splits into two cases:
1. For substring matching, all matches are done case-insensitively. That is a
@ -1213,8 +1213,8 @@ string, and the data is silently converted to reflect this assumption.
``TextField`` limitations
-------------------------
The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes
some limitations on the usage of such LOB columns in general:
The Oracle backend stores each ``TextField`` as an ``NCLOB`` column. Oracle
imposes some limitations on the usage of such LOB columns in general:
* LOB columns may not be used as primary keys.

View File

@ -164,8 +164,8 @@ To access the new value saved this way, the object must be reloaded::
reporter.refresh_from_db()
As well as being used in operations on single instances as above, ``F()`` can
be used on ``QuerySets`` of object instances, with ``update()``. This reduces
the two queries we were using above - the ``get()`` and the
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::
reporter = Reporters.objects.filter(name="Tintin")

View File

@ -1836,8 +1836,9 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in
limit_choices_to={"is_staff": True},
)
causes the corresponding field on the ``ModelForm`` to list only ``Users``
that have ``is_staff=True``. This may be helpful in the Django admin.
causes the corresponding field on the ``ModelForm`` to list only ``User``
instances that have ``is_staff=True``. This may be helpful in the Django
admin.
The callable form can be helpful, for instance, when used in conjunction
with the Python ``datetime`` module to limit selections by date range. For

View File

@ -135,8 +135,8 @@ described here.
.. admonition:: You can't share pickles between versions
Pickles of ``QuerySets`` are only valid for the version of Django that
was used to generate them. If you generate a pickle using Django
Pickles of ``QuerySet`` objects are only valid for the version of Django
that was used to generate them. If you generate a pickle using Django
version N, there is no guarantee that pickle will be readable with
Django version N+1. Pickles should not be used as part of a long-term
archival strategy.
@ -1217,8 +1217,8 @@ the items, it will find them in a prefetched ``QuerySet`` cache that was
populated in a single query.
That is, all the relevant toppings will have been fetched in a single query,
and used to make ``QuerySets`` that have a pre-filled cache of the relevant
results; these ``QuerySets`` are then used in the ``self.toppings.all()`` calls.
and used to make ``QuerySet`` instances that have a pre-filled cache of the
relevant results; these are then used in the ``self.toppings.all()`` calls.
The additional queries in ``prefetch_related()`` are executed after the
``QuerySet`` has begun to be evaluated and the primary query has been executed.
@ -1242,16 +1242,16 @@ function.
Note that the result cache of the primary ``QuerySet`` and all specified related
objects will then be fully loaded into memory. This changes the typical
behavior of ``QuerySets``, which normally try to avoid loading all objects into
memory before they are needed, even after a query has been executed in the
behavior of a ``QuerySet``, which normally tries to avoid loading all objects
into memory before they are needed, even after a query has been executed in the
database.
.. note::
Remember that, as always with ``QuerySets``, any subsequent chained methods
which imply a different database query will ignore previously cached
results, and retrieve data using a fresh database query. So, if you write
the following:
Remember that, as always with ``QuerySet`` objects, any subsequent chained
methods which imply a different database query will ignore previously
cached results, and retrieve data using a fresh database query. So, if you
write the following:
.. code-block:: pycon

View File

@ -36,7 +36,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects:
What follows are examples of operations that can be performed using the Python
API facilities.
Create a few ``Publications``:
Create a few ``Publication`` instances:
.. code-block:: pycon
@ -74,7 +74,7 @@ Associate the ``Article`` with a ``Publication``:
>>> a1.publications.add(p1)
Create another ``Article``, and set it to appear in the ``Publications``:
Create another ``Article``, and set it to appear in its publications:
.. code-block:: pycon
@ -196,7 +196,8 @@ involved is a little complex):
>>> Article.objects.exclude(publications=p2)
<QuerySet [<Article: Django lets you build web apps easily>]>
If we delete a ``Publication``, its ``Articles`` won't be able to access it:
If we delete a ``Publication``, its related ``Article`` instances won't be able
to access it:
.. code-block:: pycon
@ -207,7 +208,8 @@ If we delete a ``Publication``, its ``Articles`` won't be able to access it:
>>> a1.publications.all()
<QuerySet []>
If we delete an ``Article``, its ``Publications`` won't be able to access it:
If we delete an ``Article``, its related ``Publication`` instances won't be
able to access it:
.. code-block:: pycon
@ -303,8 +305,8 @@ Recreate the ``Article`` and ``Publication`` we have deleted:
>>> a2.save()
>>> a2.publications.add(p1, p2, p3)
Bulk delete some ``Publications`` - references to deleted publications should
go:
Bulk delete some ``Publication`` instances, and the references to deleted
publications will no longer be included in the related entries:
.. code-block:: pycon

View File

@ -427,7 +427,7 @@ objects to reduce the number of SQL queries. For example::
my_band.members.add(me)
my_band.members.add(my_friend)
...where ``Bands`` and ``Artists`` have a many-to-many relationship.
...where ``Band`` and ``Artist`` are models with a many-to-many relationship.
When inserting different pairs of objects into
:class:`~django.db.models.ManyToManyField` or when the custom
@ -470,7 +470,7 @@ objects to reduce the number of SQL queries. For example::
my_band.members.remove(me)
my_band.members.remove(my_friend)
...where ``Bands`` and ``Artists`` have a many-to-many relationship.
...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

View File

@ -178,11 +178,11 @@ model class, like so:
.. note::
``Managers`` are accessible only via model classes, rather than from model
A ``Manager`` is accessible only via model classes, rather than from model
instances, to enforce a separation between "table-level" operations and
"record-level" operations.
The :class:`~django.db.models.Manager` is the main source of ``QuerySets`` for
The :class:`~django.db.models.Manager` is the main source of querysets for
a model. For example, ``Blog.objects.all()`` returns a
:class:`~django.db.models.query.QuerySet` that contains all ``Blog`` objects in
the database.
@ -274,7 +274,7 @@ Example:
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
>>> q3 = q1.filter(pub_date__gte=datetime.date.today())
These three ``QuerySets`` are separate. The first is a base
These three querysets are separate. The first is a base
:class:`~django.db.models.query.QuerySet` containing all entries that contain a
headline starting with "What". The second is a subset of the first, with an
additional criteria that excludes records whose ``pub_date`` is today or in the
@ -288,7 +288,7 @@ refinement process.
``QuerySet``\s are lazy
~~~~~~~~~~~~~~~~~~~~~~~
``QuerySets`` are lazy -- the act of creating a
``QuerySet`` objects are lazy -- the act of creating a
:class:`~django.db.models.query.QuerySet` doesn't involve any database
activity. You can stack filters together all day long, and Django won't
actually run the query until the :class:`~django.db.models.query.QuerySet` is
@ -1725,8 +1725,8 @@ foreign-key model will have access to a :class:`~django.db.models.Manager` that
returns all instances of the first model. By default, this
:class:`~django.db.models.Manager` is named ``FOO_set``, where ``FOO`` is the
source model name, lowercased. This :class:`~django.db.models.Manager` returns
``QuerySets``, which can be filtered and manipulated as described in the
"Retrieving objects" section above.
``QuerySet`` instances, which can be filtered and manipulated as described in
the "Retrieving objects" section above.
Example:
@ -1750,7 +1750,7 @@ related_name='entries')``, the above example code would look like this:
>>> b = Blog.objects.get(id=1)
>>> b.entries.all() # Returns all Entry objects related to Blog.
# b.entries is a Manager that returns QuerySets.
# b.entries is a Manager that returns ``QuerySet`` instances.
>>> b.entries.filter(headline__contains="Lennon")
>>> b.entries.count()

View File

@ -700,10 +700,10 @@ will be localized.
Form inheritance
----------------
As with basic forms, you can extend and reuse ``ModelForms`` by inheriting
them. This is useful if you need to declare extra fields or extra methods on a
parent class for use in a number of forms derived from models. For example,
using the previous ``ArticleForm`` class:
As with basic forms, you can extend and reuse ``ModelForm`` classes by
inheriting them. This is useful if you need to declare extra fields or extra
methods on a parent class for use in a number of forms derived from models.
For example, using the previous ``ArticleForm`` class:
.. code-block:: pycon
@ -983,7 +983,7 @@ value (``instances``, in the above example).
When fields are missing from the form (for example because they have been
excluded), these fields will not be set by the ``save()`` method. You can find
more information about this restriction, which also holds for regular
``ModelForms``, in `Selecting the fields to use`_.
model forms, in `Selecting the fields to use`_.
Pass ``commit=False`` to return the unsaved model instances:
@ -1104,7 +1104,7 @@ above, in :ref:`saving-objects-in-the-formset`.)
Overriding ``clean()`` on a ``ModelFormSet``
--------------------------------------------
Just like with ``ModelForms``, by default the ``clean()`` method of a
Just like with a ``ModelForm``, by default the ``clean()`` method of a
``ModelFormSet`` will validate that none of the items in the formset violate
the unique constraints on your model (either ``unique``, ``unique_together`` or
``unique_for_date|month|year``). If you want to override the ``clean()`` method

View File

@ -212,11 +212,12 @@ Laziness in Django
------------------
Django is itself quite lazy. A good example of this can be found in the
evaluation of ``QuerySets``. :ref:`QuerySets are lazy <querysets-are-lazy>`.
evaluation of a ``QuerySet``. :ref:`QuerySets are lazy <querysets-are-lazy>`.
Thus a ``QuerySet`` can be created, passed around and combined with other
``QuerySets``, without actually incurring any trips to the database to fetch
the items it describes. What gets passed around is the ``QuerySet`` object, not
the collection of items that - eventually - will be required from the database.
``QuerySet`` instances, without actually incurring any trips to the database
to fetch the items it describes. What gets passed around is the ``QuerySet``
object, not the collection of items that - eventually - will be required from
the database.
On the other hand, :ref:`certain operations will force the evaluation of a
QuerySet <when-querysets-are-evaluated>`. Avoiding the premature evaluation of