From efe3ca09e029c63e25f6e19843cb0c68cc7fa816 Mon Sep 17 00:00:00 2001 From: Clifford Gama <53076065+cliff688@users.noreply.github.com> Date: Thu, 13 Mar 2025 20:18:35 +0200 Subject: [PATCH] Fixed incorrect formatting for inline pluralized code references in docs. --- docs/intro/tutorial05.txt | 31 ++++++++++--------- docs/ref/class-based-views/mixins-editing.txt | 3 +- docs/ref/databases.txt | 6 ++-- docs/ref/models/expressions.txt | 4 +-- docs/ref/models/fields.txt | 5 +-- docs/ref/models/querysets.txt | 20 ++++++------ docs/topics/db/examples/many_to_many.txt | 14 +++++---- docs/topics/db/optimization.txt | 4 +-- docs/topics/db/queries.txt | 14 ++++----- docs/topics/forms/modelforms.txt | 12 +++---- docs/topics/performance.txt | 9 +++--- 11 files changed, 64 insertions(+), 58 deletions(-) diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt index 219b7b3130..034c37ea54 100644 --- a/docs/intro/tutorial05.txt +++ b/docs/intro/tutorial05.txt @@ -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 diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt index aebbae04ae..f17253dfa7 100644 --- a/docs/ref/class-based-views/mixins-editing.txt +++ b/docs/ref/class-based-views/mixins-editing.txt @@ -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 diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 8a36ac9bad..36a541f212 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -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. diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index c3c9ebba7a..060450b6d8 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -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") diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index c45688184d..6d4ca657fc 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -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 diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index f824b3050f..cb3f75afca 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -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 diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt index 2c22faaf9a..38838bb1b8 100644 --- a/docs/topics/db/examples/many_to_many.txt +++ b/docs/topics/db/examples/many_to_many.txt @@ -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) ]> -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() -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 diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 6b2733643f..8e54ad4ff8 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -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 `, use diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 2c2314198f..dfd439db8c 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -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() diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index ef916d882d..b320d7fc04 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -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 diff --git a/docs/topics/performance.txt b/docs/topics/performance.txt index f3342453cc..c6231a41c8 100644 --- a/docs/topics/performance.txt +++ b/docs/topics/performance.txt @@ -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 `. +evaluation of a ``QuerySet``. :ref:`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 `. Avoiding the premature evaluation of