mirror of
				https://github.com/django/django.git
				synced 2025-10-31 09:41:08 +00:00 
			
		
		
		
	Fixed incorrect formatting for inline pluralized code references in docs.
This commit is contained in:
		| @@ -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 | ||||
|   | ||||
| @@ -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 | ||||
|   | ||||
| @@ -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. | ||||
|  | ||||
|   | ||||
| @@ -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") | ||||
|   | ||||
| @@ -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 | ||||
|   | ||||
| @@ -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 | ||||
|  | ||||
|   | ||||
| @@ -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 | ||||
|  | ||||
|   | ||||
| @@ -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 | ||||
|   | ||||
| @@ -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() | ||||
|  | ||||
|   | ||||
| @@ -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 | ||||
|   | ||||
| @@ -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 | ||||
|   | ||||
		Reference in New Issue
	
	Block a user