mirror of
https://github.com/django/django.git
synced 2025-06-05 03:29:12 +00:00
Fixed incorrect formatting for inline pluralized code references in docs.
This commit is contained in:
parent
e7a9d756ee
commit
efe3ca09e0
@ -461,11 +461,11 @@ Testing our new view
|
|||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
Now you can satisfy yourself that this behaves as expected by firing up
|
Now you can satisfy yourself that this behaves as expected by firing up
|
||||||
``runserver``, loading the site in your browser, creating ``Questions`` with
|
``runserver``, loading the site in your browser, creating a few ``Question``
|
||||||
dates in the past and future, and checking that only those that have been
|
entries with dates in the past and future, and checking that only those that
|
||||||
published are listed. You don't want to have to do that *every single time you
|
have been published are listed. You don't want to have to do that *every single
|
||||||
make any change that might affect this* - so let's also create a test, based on
|
time you make any change that might affect this* - so let's also create a test,
|
||||||
our :djadmin:`shell` session above.
|
based on our :djadmin:`shell` session above.
|
||||||
|
|
||||||
Add the following to ``polls/tests.py``:
|
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.
|
just created; in fact there will be a lot of repetition.
|
||||||
|
|
||||||
We could also improve our application in other ways, adding tests along the
|
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
|
way. For example, it's pointless that a ``Question`` with no related ``Choice``
|
||||||
that have no ``Choices``. So, our views could check for this, and exclude such
|
can be published on the site. So, our views could check for this, and exclude
|
||||||
``Questions``. Our tests would create a ``Question`` without ``Choices`` and
|
such ``Question`` objects. Our tests would create a ``Question`` without a
|
||||||
then test that it's not published, as well as create a similar ``Question``
|
``Choice``, and then test that it's not published, as well as create a similar
|
||||||
*with* ``Choices``, and test that it *is* published.
|
``Question`` *with* at least one ``Choice``, and test that it *is* published.
|
||||||
|
|
||||||
Perhaps logged-in admin users should be allowed to see unpublished
|
Perhaps logged-in admin users should be allowed to see unpublished ``Question``
|
||||||
``Questions``, but not ordinary visitors. Again: whatever needs to be added to
|
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
|
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
|
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.
|
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.
|
as you continue to develop your program.
|
||||||
|
|
||||||
Sometimes tests will need to be updated. Suppose that we amend our views so that
|
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
|
only ``Question`` entries with associated ``Choice`` instances are published.
|
||||||
existing tests will fail - *telling us exactly which tests need to be amended to
|
In that case, many of our existing tests will fail - *telling us exactly which
|
||||||
bring them up to date*, so to that extent tests help look after themselves.
|
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
|
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
|
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
|
.. 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
|
Since this is a subclass of
|
||||||
:class:`~django.views.generic.detail.SingleObjectMixin`, instances of this
|
: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
|
For all SQLite versions, there is some slightly counterintuitive behavior when
|
||||||
attempting to match some types of strings. These are triggered when using the
|
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:
|
splits into two cases:
|
||||||
|
|
||||||
1. For substring matching, all matches are done case-insensitively. That is a
|
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
|
``TextField`` limitations
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes
|
The Oracle backend stores each ``TextField`` as an ``NCLOB`` column. Oracle
|
||||||
some limitations on the usage of such LOB columns in general:
|
imposes some limitations on the usage of such LOB columns in general:
|
||||||
|
|
||||||
* LOB columns may not be used as primary keys.
|
* 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()
|
reporter.refresh_from_db()
|
||||||
|
|
||||||
As well as being used in operations on single instances as above, ``F()`` can
|
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
|
be used with ``update()`` to perform bulk updates on a ``QuerySet``. This
|
||||||
the two queries we were using above - the ``get()`` and the
|
reduces the two queries we were using above - the ``get()`` and the
|
||||||
:meth:`~Model.save()` - to just one::
|
:meth:`~Model.save()` - to just one::
|
||||||
|
|
||||||
reporter = Reporters.objects.filter(name="Tintin")
|
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},
|
limit_choices_to={"is_staff": True},
|
||||||
)
|
)
|
||||||
|
|
||||||
causes the corresponding field on the ``ModelForm`` to list only ``Users``
|
causes the corresponding field on the ``ModelForm`` to list only ``User``
|
||||||
that have ``is_staff=True``. This may be helpful in the Django admin.
|
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
|
The callable form can be helpful, for instance, when used in conjunction
|
||||||
with the Python ``datetime`` module to limit selections by date range. For
|
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
|
.. admonition:: You can't share pickles between versions
|
||||||
|
|
||||||
Pickles of ``QuerySets`` are only valid for the version of Django that
|
Pickles of ``QuerySet`` objects are only valid for the version of Django
|
||||||
was used to generate them. If you generate a pickle using 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
|
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
|
Django version N+1. Pickles should not be used as part of a long-term
|
||||||
archival strategy.
|
archival strategy.
|
||||||
@ -1217,8 +1217,8 @@ the items, it will find them in a prefetched ``QuerySet`` cache that was
|
|||||||
populated in a single query.
|
populated in a single query.
|
||||||
|
|
||||||
That is, all the relevant toppings will have been fetched 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
|
and used to make ``QuerySet`` instances that have a pre-filled cache of the
|
||||||
results; these ``QuerySets`` are then used in the ``self.toppings.all()`` calls.
|
relevant results; these are then used in the ``self.toppings.all()`` calls.
|
||||||
|
|
||||||
The additional queries in ``prefetch_related()`` are executed after the
|
The additional queries in ``prefetch_related()`` are executed after the
|
||||||
``QuerySet`` has begun to be evaluated and the primary query has been executed.
|
``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
|
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
|
objects will then be fully loaded into memory. This changes the typical
|
||||||
behavior of ``QuerySets``, which normally try to avoid loading all objects into
|
behavior of a ``QuerySet``, which normally tries to avoid loading all objects
|
||||||
memory before they are needed, even after a query has been executed in the
|
into memory before they are needed, even after a query has been executed in the
|
||||||
database.
|
database.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Remember that, as always with ``QuerySets``, any subsequent chained methods
|
Remember that, as always with ``QuerySet`` objects, any subsequent chained
|
||||||
which imply a different database query will ignore previously cached
|
methods which imply a different database query will ignore previously
|
||||||
results, and retrieve data using a fresh database query. So, if you write
|
cached results, and retrieve data using a fresh database query. So, if you
|
||||||
the following:
|
write the following:
|
||||||
|
|
||||||
.. code-block:: pycon
|
.. 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
|
What follows are examples of operations that can be performed using the Python
|
||||||
API facilities.
|
API facilities.
|
||||||
|
|
||||||
Create a few ``Publications``:
|
Create a few ``Publication`` instances:
|
||||||
|
|
||||||
.. code-block:: pycon
|
.. code-block:: pycon
|
||||||
|
|
||||||
@ -74,7 +74,7 @@ Associate the ``Article`` with a ``Publication``:
|
|||||||
|
|
||||||
>>> a1.publications.add(p1)
|
>>> 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
|
.. code-block:: pycon
|
||||||
|
|
||||||
@ -196,7 +196,8 @@ involved is a little complex):
|
|||||||
>>> Article.objects.exclude(publications=p2)
|
>>> Article.objects.exclude(publications=p2)
|
||||||
<QuerySet [<Article: Django lets you build web apps easily>]>
|
<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
|
.. code-block:: pycon
|
||||||
|
|
||||||
@ -207,7 +208,8 @@ If we delete a ``Publication``, its ``Articles`` won't be able to access it:
|
|||||||
>>> a1.publications.all()
|
>>> a1.publications.all()
|
||||||
<QuerySet []>
|
<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
|
.. code-block:: pycon
|
||||||
|
|
||||||
@ -303,8 +305,8 @@ Recreate the ``Article`` and ``Publication`` we have deleted:
|
|||||||
>>> a2.save()
|
>>> a2.save()
|
||||||
>>> a2.publications.add(p1, p2, p3)
|
>>> a2.publications.add(p1, p2, p3)
|
||||||
|
|
||||||
Bulk delete some ``Publications`` - references to deleted publications should
|
Bulk delete some ``Publication`` instances, and the references to deleted
|
||||||
go:
|
publications will no longer be included in the related entries:
|
||||||
|
|
||||||
.. code-block:: pycon
|
.. 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(me)
|
||||||
my_band.members.add(my_friend)
|
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
|
When inserting different pairs of objects into
|
||||||
:class:`~django.db.models.ManyToManyField` or when the custom
|
: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(me)
|
||||||
my_band.members.remove(my_friend)
|
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
|
When removing different pairs of objects from :class:`ManyToManyFields
|
||||||
<django.db.models.ManyToManyField>`, use
|
<django.db.models.ManyToManyField>`, use
|
||||||
|
@ -178,11 +178,11 @@ model class, like so:
|
|||||||
|
|
||||||
.. note::
|
.. 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
|
instances, to enforce a separation between "table-level" operations and
|
||||||
"record-level" operations.
|
"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
|
a model. For example, ``Blog.objects.all()`` returns a
|
||||||
:class:`~django.db.models.query.QuerySet` that contains all ``Blog`` objects in
|
:class:`~django.db.models.query.QuerySet` that contains all ``Blog`` objects in
|
||||||
the database.
|
the database.
|
||||||
@ -274,7 +274,7 @@ Example:
|
|||||||
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
|
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
|
||||||
>>> q3 = q1.filter(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
|
: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
|
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
|
additional criteria that excludes records whose ``pub_date`` is today or in the
|
||||||
@ -288,7 +288,7 @@ refinement process.
|
|||||||
``QuerySet``\s are lazy
|
``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
|
:class:`~django.db.models.query.QuerySet` doesn't involve any database
|
||||||
activity. You can stack filters together all day long, and Django won't
|
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
|
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
|
returns all instances of the first model. By default, this
|
||||||
:class:`~django.db.models.Manager` is named ``FOO_set``, where ``FOO`` is the
|
:class:`~django.db.models.Manager` is named ``FOO_set``, where ``FOO`` is the
|
||||||
source model name, lowercased. This :class:`~django.db.models.Manager` returns
|
source model name, lowercased. This :class:`~django.db.models.Manager` returns
|
||||||
``QuerySets``, which can be filtered and manipulated as described in the
|
``QuerySet`` instances, which can be filtered and manipulated as described in
|
||||||
"Retrieving objects" section above.
|
the "Retrieving objects" section above.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
@ -1750,7 +1750,7 @@ related_name='entries')``, the above example code would look like this:
|
|||||||
>>> b = Blog.objects.get(id=1)
|
>>> b = Blog.objects.get(id=1)
|
||||||
>>> b.entries.all() # Returns all Entry objects related to Blog.
|
>>> 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.filter(headline__contains="Lennon")
|
||||||
>>> b.entries.count()
|
>>> b.entries.count()
|
||||||
|
|
||||||
|
@ -700,10 +700,10 @@ will be localized.
|
|||||||
Form inheritance
|
Form inheritance
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
As with basic forms, you can extend and reuse ``ModelForms`` by inheriting
|
As with basic forms, you can extend and reuse ``ModelForm`` classes by
|
||||||
them. This is useful if you need to declare extra fields or extra methods on a
|
inheriting them. This is useful if you need to declare extra fields or extra
|
||||||
parent class for use in a number of forms derived from models. For example,
|
methods on a parent class for use in a number of forms derived from models.
|
||||||
using the previous ``ArticleForm`` class:
|
For example, using the previous ``ArticleForm`` class:
|
||||||
|
|
||||||
.. code-block:: pycon
|
.. 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
|
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
|
excluded), these fields will not be set by the ``save()`` method. You can find
|
||||||
more information about this restriction, which also holds for regular
|
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:
|
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``
|
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
|
``ModelFormSet`` will validate that none of the items in the formset violate
|
||||||
the unique constraints on your model (either ``unique``, ``unique_together`` or
|
the unique constraints on your model (either ``unique``, ``unique_together`` or
|
||||||
``unique_for_date|month|year``). If you want to override the ``clean()`` method
|
``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
|
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
|
Thus a ``QuerySet`` can be created, passed around and combined with other
|
||||||
``QuerySets``, without actually incurring any trips to the database to fetch
|
``QuerySet`` instances, without actually incurring any trips to the database
|
||||||
the items it describes. What gets passed around is the ``QuerySet`` object, not
|
to fetch the items it describes. What gets passed around is the ``QuerySet``
|
||||||
the collection of items that - eventually - will be required from the database.
|
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
|
On the other hand, :ref:`certain operations will force the evaluation of a
|
||||||
QuerySet <when-querysets-are-evaluated>`. Avoiding the premature evaluation of
|
QuerySet <when-querysets-are-evaluated>`. Avoiding the premature evaluation of
|
||||||
|
Loading…
x
Reference in New Issue
Block a user