mirror of
https://github.com/django/django.git
synced 2025-08-31 07:47:37 +00:00
Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty.
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
This commit is contained in:
parent
addabc492b
commit
4a954cfd11
149 changed files with 1101 additions and 1157 deletions
|
@ -96,7 +96,7 @@ A ``Case()`` expression is like the :keyword:`if` ... :keyword:`elif` ...
|
|||
truthful value. The ``result`` expression from the matching ``When()`` object
|
||||
is returned.
|
||||
|
||||
A simple example::
|
||||
An example::
|
||||
|
||||
>>>
|
||||
>>> from datetime import date, timedelta
|
||||
|
|
|
@ -98,8 +98,7 @@ into Python memory.
|
|||
Instead, Django uses the ``F()`` object to generate an SQL expression that
|
||||
describes the required operation at the database level.
|
||||
|
||||
This is easiest to understand through an example. Normally, one might do
|
||||
something like this::
|
||||
Let's try this with an example. Normally, one might do something like this::
|
||||
|
||||
# Tintin filed a news story!
|
||||
reporter = Reporters.objects.get(name='Tintin')
|
||||
|
@ -167,7 +166,7 @@ Python - update a field's value avoids a *race condition*.
|
|||
If two Python threads execute the code in the first example above, one thread
|
||||
could retrieve, increment, and save a field's value after the other has
|
||||
retrieved it from the database. The value that the second thread saves will be
|
||||
based on the original value; the work of the first thread will simply be lost.
|
||||
based on the original value; the work of the first thread will be lost.
|
||||
|
||||
If the database is responsible for updating the field, the process is more
|
||||
robust: it will only ever update the field based on the value of the field in
|
||||
|
@ -443,9 +442,9 @@ into the ``template`` attribute.
|
|||
Creating your own Aggregate Functions
|
||||
-------------------------------------
|
||||
|
||||
Creating your own aggregate is extremely easy. At a minimum, you need
|
||||
to define ``function``, but you can also completely customize the
|
||||
SQL that is generated. Here's a brief example::
|
||||
You can create your own aggregate functions, too. At a minimum, you need to
|
||||
define ``function``, but you can also completely customize the SQL that is
|
||||
generated. Here's a brief example::
|
||||
|
||||
from django.db.models import Aggregate
|
||||
|
||||
|
@ -496,8 +495,8 @@ output value.
|
|||
|
||||
.. class:: ExpressionWrapper(expression, output_field)
|
||||
|
||||
``ExpressionWrapper`` simply surrounds another expression and provides access
|
||||
to properties, such as ``output_field``, that may not be available on other
|
||||
``ExpressionWrapper`` surrounds another expression and provides access to
|
||||
properties, such as ``output_field``, that may not be available on other
|
||||
expressions. ``ExpressionWrapper`` is necessary when using arithmetic on
|
||||
``F()`` expressions with different types as described in
|
||||
:ref:`using-f-with-annotations`.
|
||||
|
@ -754,8 +753,8 @@ The ``order_by`` argument accepts a sequence of expressions on which you can
|
|||
call :meth:`~django.db.models.Expression.asc` and
|
||||
:meth:`~django.db.models.Expression.desc`. The ordering controls the order in
|
||||
which the expression is applied. For example, if you sum over the rows in a
|
||||
partition, the first result is just the value of the first row, the second is
|
||||
the sum of first and second row.
|
||||
partition, the first result is the value of the first row, the second is the
|
||||
sum of first and second row.
|
||||
|
||||
The ``frame`` parameter specifies which other rows that should be used in the
|
||||
computation. See :ref:`window-frames` for details.
|
||||
|
@ -773,7 +772,7 @@ the same studio in the same genre and release year::
|
|||
>>> ),
|
||||
>>> )
|
||||
|
||||
This makes it easy to check if a movie is rated better or worse than its peers.
|
||||
This allows you to check if a movie is rated better or worse than its peers.
|
||||
|
||||
You may want to apply multiple expressions over the same window, i.e., the
|
||||
same partition and frame. For example, you could modify the previous example
|
||||
|
@ -1061,7 +1060,7 @@ We do some basic validation on the parameters, including requiring at least
|
|||
the eventual result to.
|
||||
|
||||
Now we implement the pre-processing and validation. Since we do not have
|
||||
any of our own validation at this point, we just delegate to the nested
|
||||
any of our own validation at this point, we delegate to the nested
|
||||
expressions::
|
||||
|
||||
def resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False):
|
||||
|
|
|
@ -127,7 +127,7 @@ define a suitably-named constant for each value::
|
|||
Though you can define a choices list outside of a model class and then
|
||||
refer to it, defining the choices and names for each choice inside the
|
||||
model class keeps all of that information with the class that uses it,
|
||||
and makes the choices easy to reference (e.g, ``Student.SOPHOMORE``
|
||||
and helps reference the choices (e.g, ``Student.SOPHOMORE``
|
||||
will work anywhere that the ``Student`` model has been imported).
|
||||
|
||||
In addition, Django provides enumeration types that you can subclass to define
|
||||
|
@ -634,10 +634,10 @@ Any combination of these options will result in an error.
|
|||
The ``auto_now`` and ``auto_now_add`` options will always use the date in
|
||||
the :ref:`default timezone <default-current-time-zone>` at the moment of
|
||||
creation or update. If you need something different, you may want to
|
||||
consider simply using your own callable default or overriding ``save()``
|
||||
instead of using ``auto_now`` or ``auto_now_add``; or using a
|
||||
``DateTimeField`` instead of a ``DateField`` and deciding how to handle the
|
||||
conversion from datetime to date at display time.
|
||||
consider using your own callable default or overriding ``save()`` instead
|
||||
of using ``auto_now`` or ``auto_now_add``; or using a ``DateTimeField``
|
||||
instead of a ``DateField`` and deciding how to handle the conversion from
|
||||
datetime to date at display time.
|
||||
|
||||
``DateTimeField``
|
||||
-----------------
|
||||
|
@ -1582,7 +1582,7 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in
|
|||
if it is a profile model designed specifically for your custom user model.
|
||||
|
||||
Setting it to ``False`` does not mean you can reference a swappable model
|
||||
even if it is swapped out - ``False`` just means that the migrations made
|
||||
even if it is swapped out - ``False`` means that the migrations made
|
||||
with this ForeignKey will always reference the exact model you specify
|
||||
(so it will fail hard if the user tries to run with a User model you don't
|
||||
support, for example).
|
||||
|
|
|
@ -16,14 +16,14 @@ Throughout this reference we'll use the :ref:`example Weblog models
|
|||
Creating objects
|
||||
================
|
||||
|
||||
To create a new instance of a model, just instantiate it like any other Python
|
||||
To create a new instance of a model, instantiate it like any other Python
|
||||
class:
|
||||
|
||||
.. class:: Model(**kwargs)
|
||||
|
||||
The keyword arguments are simply the names of the fields you've defined on your
|
||||
model. Note that instantiating a model in no way touches your database; for
|
||||
that, you need to :meth:`~Model.save()`.
|
||||
The keyword arguments are the names of the fields you've defined on your model.
|
||||
Note that instantiating a model in no way touches your database; for that, you
|
||||
need to :meth:`~Model.save()`.
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -116,8 +116,8 @@ are loaded from the database::
|
|||
super().save(*args, **kwargs)
|
||||
|
||||
The example above shows a full ``from_db()`` implementation to clarify how that
|
||||
is done. In this case it would of course be possible to just use ``super()`` call
|
||||
in the ``from_db()`` method.
|
||||
is done. In this case it would of course be possible to use ``super()`` call in
|
||||
the ``from_db()`` method.
|
||||
|
||||
Refreshing objects from database
|
||||
================================
|
||||
|
@ -396,8 +396,8 @@ Explicitly specifying auto-primary-key values
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If a model has an :class:`~django.db.models.AutoField` but you want to define a
|
||||
new object's ID explicitly when saving, just define it explicitly before
|
||||
saving, rather than relying on the auto-assignment of the ID::
|
||||
new object's ID explicitly when saving, define it explicitly before saving,
|
||||
rather than relying on the auto-assignment of the ID::
|
||||
|
||||
>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
|
||||
>>> b3.id # Returns 3.
|
||||
|
@ -500,8 +500,8 @@ In some rare circumstances, it's necessary to be able to force the
|
|||
doing an ``UPDATE``. Or vice-versa: update, if possible, but not insert a new
|
||||
row. In these cases you can pass the ``force_insert=True`` or
|
||||
``force_update=True`` parameters to the :meth:`~Model.save()` method.
|
||||
Obviously, passing both parameters is an error: you cannot both insert *and*
|
||||
update at the same time!
|
||||
Passing both parameters is an error: you cannot both insert *and* update at the
|
||||
same time!
|
||||
|
||||
It should be very rare that you'll need to use these parameters. Django will
|
||||
almost always do the right thing and trying to override that will lead to
|
||||
|
@ -749,9 +749,9 @@ This template code is much better:
|
|||
<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
|
||||
|
||||
The logic here is that if you change the URL structure of your objects, even
|
||||
for something simple such as correcting a spelling error, you don't want to
|
||||
have to track down every place that the URL might be created. Specify it once,
|
||||
in ``get_absolute_url()`` and have all your other code call that one place.
|
||||
for something small like correcting a spelling error, you don't want to have to
|
||||
track down every place that the URL might be created. Specify it once, in
|
||||
``get_absolute_url()`` and have all your other code call that one place.
|
||||
|
||||
.. note::
|
||||
The string you return from ``get_absolute_url()`` **must** contain only
|
||||
|
|
|
@ -151,8 +151,8 @@ Here's the formal declaration of a ``QuerySet``:
|
|||
The ``query`` parameter to :class:`QuerySet` exists so that specialized
|
||||
query subclasses can reconstruct internal query state. The value of the
|
||||
parameter is an opaque representation of that query state and is not
|
||||
part of a public API. To put it simply: if you need to ask, you don't
|
||||
need to use it.
|
||||
part of a public API. To put it another way: if you need to ask, you
|
||||
don't need to use it.
|
||||
|
||||
.. currentmodule:: django.db.models.query.QuerySet
|
||||
|
||||
|
@ -1943,7 +1943,7 @@ details. The internal implementation has some more error-checking than this and
|
|||
handles some extra edge-conditions; if you're interested, read the code.
|
||||
|
||||
If you have a field named ``defaults`` and want to use it as an exact lookup in
|
||||
``get_or_create()``, just use ``'defaults__exact'``, like so::
|
||||
``get_or_create()``, use ``'defaults__exact'``, like so::
|
||||
|
||||
Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})
|
||||
|
||||
|
@ -2418,8 +2418,8 @@ gains).
|
|||
Additionally, if a ``some_queryset`` has not yet been evaluated, but you know
|
||||
that it will be at some point, then using ``some_queryset.exists()`` will do
|
||||
more overall work (one query for the existence check plus an extra one to later
|
||||
retrieve the results) than simply using ``bool(some_queryset)``, which
|
||||
retrieves the results and then checks if any were returned.
|
||||
retrieve the results) than using ``bool(some_queryset)``, which retrieves the
|
||||
results and then checks if any were returned.
|
||||
|
||||
``update()``
|
||||
~~~~~~~~~~~~
|
||||
|
|
|
@ -91,7 +91,7 @@ Related objects reference
|
|||
|
||||
# No need to call e.save() at this point -- it's already been saved.
|
||||
|
||||
This is equivalent to (but much simpler than)::
|
||||
This is equivalent to (but simpler than)::
|
||||
|
||||
>>> b = Blog.objects.get(id=1)
|
||||
>>> e = Entry(
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue