Author: timo
Date: 2010-11-28 12:20:05 -0600 (Sun, 28 Nov 2010)
New Revision: 14738
Modified:
django/branches/releases/1.2.X/docs/ref/models/querysets.txt
Log:
Fixed #14758 - Remove entire method signatures from QuerySet headings - thanks
adamv for the patch.
Backport of r14737 from trunk.
Modified: django/branches/releases/1.2.X/docs/ref/models/querysets.txt
===================================================================
--- django/branches/releases/1.2.X/docs/ref/models/querysets.txt
2010-11-28 18:15:40 UTC (rev 14737)
+++ django/branches/releases/1.2.X/docs/ref/models/querysets.txt
2010-11-28 18:20:05 UTC (rev 14738)
@@ -119,22 +119,23 @@
QuerySet API
============
-Though you usually won't create one manually -- you'll go through a
:class:`Manager` -- here's the formal declaration of a ``QuerySet``:
+Though you usually won't create one manually -- you'll go through a
+:class:`Manager` -- here's the formal declaration of a ``QuerySet``:
.. class:: QuerySet([model=None])
Usually when you'll interact with a ``QuerySet`` you'll use it by
:ref:`chaining
filters <chaining-filters>`. To make this work, most ``QuerySet`` methods
return new querysets.
-QuerySet methods that return new QuerySets
-------------------------------------------
+Methods that return new QuerySets
+---------------------------------
Django provides a range of ``QuerySet`` refinement methods that modify either
the types of results returned by the ``QuerySet`` or the way its SQL query is
executed.
-``filter(**kwargs)``
-~~~~~~~~~~~~~~~~~~~~
+filter
+~~~~~~
.. method:: filter(**kwargs)
@@ -145,8 +146,8 @@
`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
underlying SQL statement.
-``exclude(**kwargs)``
-~~~~~~~~~~~~~~~~~~~~~
+exclude
+~~~~~~~
.. method:: exclude(**kwargs)
@@ -180,8 +181,8 @@
Note the second example is more restrictive.
-``annotate(*args, **kwargs)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+annotate
+~~~~~~~~
.. method:: annotate(*args, **kwargs)
@@ -224,8 +225,8 @@
For an in-depth discussion of aggregation, see :doc:`the topic guide on
Aggregation </topics/db/aggregation>`.
-``order_by(*fields)``
-~~~~~~~~~~~~~~~~~~~~~
+order_by
+~~~~~~~~
.. method:: order_by(*fields)
@@ -267,8 +268,8 @@
...since the ``Blog`` model has no default ordering specified.
Be cautious when ordering by fields in related models if you are also using
-``distinct()``. See the note in the `distinct()`_ section for an explanation
-of how related model ordering can change the expected results.
+``distinct()``. See the note in :meth:`distinct` for an explanation of how
+related model ordering can change the expected results.
It is permissible to specify a multi-valued field to order the results by (for
example, a ``ManyToMany`` field). Normally this won't be a sensible thing to
@@ -280,11 +281,6 @@
.. versionadded:: 1.0
-If you don't want any ordering to be applied to a query, not even the default
-ordering, call ``order_by()`` with no parameters.
-
-.. versionadded:: 1.0
-
The syntax for ordering across related models has changed. See the `Django 0.96
documentation`_ for the old behaviour.
@@ -294,14 +290,17 @@
respect to case-sensitivity, Django will order results however your database
backend normally orders them.
+If you don't want any ordering to be applied to a query, not even the default
+ordering, call ``order_by()`` with no parameters.
+
.. versionadded:: 1.1
You can tell if a query is ordered or not by checking the
:attr:`QuerySet.ordered` attribute, which will be ``True`` if the
``QuerySet`` has been ordered in any way.
-``reverse()``
-~~~~~~~~~~~~~
+reverse
+~~~~~~~
.. method:: reverse()
@@ -330,8 +329,8 @@
ordering was undefined prior to calling ``reverse()``, and will remain
undefined afterward).
-``distinct()``
-~~~~~~~~~~~~~~
+distinct
+~~~~~~~~
.. method:: distinct()
@@ -345,7 +344,7 @@
``QuerySet`` is evaluated. That's when you'd use ``distinct()``.
.. note::
- Any fields used in an `order_by(*fields)`_ call are included in the SQL
+ Any fields used in an :meth:`order_by` call are included in the SQL
``SELECT`` columns. This can sometimes lead to unexpected results when
used in conjunction with ``distinct()``. If you order by fields from a
related model, those fields will be added to the selected columns and they
@@ -363,8 +362,8 @@
``values()`` together, be careful when ordering by fields not in the
``values()`` call.
-``values(*fields)``
-~~~~~~~~~~~~~~~~~~~
+values
+~~~~~~
.. method:: values(*fields)
@@ -422,9 +421,11 @@
>>> Entry.objects.values('blog_id')
[{'blog_id': 1}, ...]
+
* When using ``values()`` together with ``distinct()``, be aware that
- ordering can affect the results. See the note in the `distinct()`_
- section, above, for details.
+ ordering can affect the results. See the note in :meth:`distinct` for
+ details.
+
* If you use a ``values()`` clause after an ``extra()`` clause,
any fields defined by a ``select`` argument in the ``extra()``
must be explicitly included in the ``values()`` clause. However,
@@ -453,8 +454,8 @@
but it doesn't really matter. This is your chance to really flaunt your
individualism.
-``values_list(*fields)``
-~~~~~~~~~~~~~~~~~~~~~~~~
+values_list
+~~~~~~~~~~~
.. method:: values_list(*fields)
@@ -483,8 +484,8 @@
If you don't pass any values to ``values_list()``, it will return all the
fields in the model, in the order they were declared.
-``dates(field, kind, order='ASC')``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+dates
+~~~~~
.. method:: dates(field, kind, order='ASC')
@@ -519,8 +520,8 @@
>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date',
'day')
[datetime.datetime(2005, 3, 20)]
-``none()``
-~~~~~~~~~~
+none
+~~~~
.. method:: none()
@@ -536,14 +537,14 @@
>>> Entry.objects.none()
[]
-``all()``
-~~~~~~~~~
+all
+~~~
.. method:: all()
.. versionadded:: 1.0
-Returns a ''copy'' of the current ``QuerySet`` (or ``QuerySet`` subclass you
+Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you
pass in). This can be useful in some situations where you might want to pass
in either a model manager or a ``QuerySet`` and do further filtering on the
result. You can safely call ``all()`` on either object and then you'll
@@ -551,8 +552,8 @@
.. _select-related:
-``select_related()``
-~~~~~~~~~~~~~~~~~~~~
+select_related
+~~~~~~~~~~~~~~
.. method:: select_related()
@@ -672,8 +673,8 @@
``OneToOneFields`` will not be traversed in the reverse direction if you
are performing a depth-based ``select_related``.
-``extra(select=None, where=None, params=None, tables=None, order_by=None,
select_params=None)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+extra
+~~~~~
.. method:: extra(select=None, where=None, params=None, tables=None,
order_by=None, select_params=None)
@@ -835,8 +836,8 @@
Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
-``defer(*fields)``
-~~~~~~~~~~~~~~~~~~
+defer
+~~~~~
.. method:: defer(*fields)
@@ -863,7 +864,9 @@
# Defers both the body and headline fields.
Entry.objects.defer("body").filter(rating=5).defer("headline")
-The order in which fields are added to the deferred set does not matter.
Calling ``defer()`` with a field name that has already been deferred is
harmless (the field will still be deferred).
+The order in which fields are added to the deferred set does not matter.
+Calling ``defer()`` with a field name that has already been deferred is
+harmless (the field will still be deferred).
You can defer loading of fields in related models (if the related models are
loading via ``select_related()``) by using the standard double-underscore
@@ -895,8 +898,8 @@
bother using ``defer()``; leave it until your query construction has
settled down and you understand where the hot-points are.
-``only(*fields)``
-~~~~~~~~~~~~~~~~~
+only
+~~~~
.. method:: only(*fields)
@@ -933,8 +936,8 @@
# existing set of fields).
Entry.objects.defer("body").only("headline", "body")
-``using(alias)``
-~~~~~~~~~~~~~~~~
+using
+~~~~~
.. method:: using(alias)
@@ -954,8 +957,8 @@
>>> Entry.objects.using('backup')
-QuerySet methods that do not return QuerySets
----------------------------------------------
+Methods that do not return QuerySets
+------------------------------------
The following ``QuerySet`` methods evaluate the ``QuerySet`` and return
something *other than* a ``QuerySet``.
@@ -963,8 +966,8 @@
These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
they query the database each time they're called.
-``get(**kwargs)``
-~~~~~~~~~~~~~~~~~
+get
+~~~
.. method:: get(**kwargs)
@@ -992,8 +995,8 @@
except ObjectDoesNotExist:
print "Either the entry or blog doesn't exist."
-``create(**kwargs)``
-~~~~~~~~~~~~~~~~~~~~
+create
+~~~~~~
.. method:: create(**kwargs)
@@ -1012,12 +1015,12 @@
elsewhere, but all it means is that a new object will always be created.
Normally you won't need to worry about this. However, if your model contains a
manual primary key value that you set and if that value already exists in the
-database, a call to ``create()`` will fail with an ``IntegrityError`` since
-primary keys must be unique. So remember to be prepared to handle the
-exception if you are using manual primary keys.
+database, a call to ``create()`` will fail with an :exc:`IntegrityError` since
+primary keys must be unique. So remember to be prepared to handle the exception
+if you are using manual primary keys.
-``get_or_create(**kwargs)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+get_or_create
+~~~~~~~~~~~~~
.. method:: get_or_create(**kwargs)
@@ -1086,8 +1089,8 @@
.. _Safe methods:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
-``count()``
-~~~~~~~~~~~
+count
+~~~~~
.. method:: count()
@@ -1112,8 +1115,8 @@
is an underlying implementation quirk that shouldn't pose any real-world
problems.
-``in_bulk(id_list)``
-~~~~~~~~~~~~~~~~~~~~
+in_bulk
+~~~~~~~
.. method:: in_bulk(id_list)
@@ -1131,8 +1134,8 @@
If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
-``iterator()``
-~~~~~~~~~~~~~~
+iterator
+~~~~~~~~
.. method:: iterator()
@@ -1149,8 +1152,8 @@
.. _iterator: http://www.python.org/dev/peps/pep-0234/
-``latest(field_name=None)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+latest
+~~~~~~
.. method:: latest(field_name=None)
@@ -1171,8 +1174,8 @@
Note ``latest()`` exists purely for convenience and readability.
-``aggregate(*args, **kwargs)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+aggregate
+~~~~~~~~~
.. method:: aggregate(*args, **kwargs)
@@ -1205,8 +1208,8 @@
For an in-depth discussion of aggregation, see :doc:`the topic guide on
Aggregation </topics/db/aggregation>`.
-``exists()``
-~~~~~~~~~~~~
+exists
+~~~~~~
.. method:: exists()
@@ -1221,8 +1224,8 @@
more overall work (an additional query) than simply using
``bool(some_query_set)``.
-``update(**kwargs)``
-~~~~~~~~~~~~~~~~~~~~
+update
+~~~~~~
.. method:: update(**kwargs)
@@ -1231,7 +1234,7 @@
the only restriction on the :class:`QuerySet` that is updated is that it can
only update columns in the model's main table. Filtering based on related
fields is still possible. You cannot call ``update()`` on a
-:class:`QuerySet` that has had a slice taken or can otherwise no longer be
+:class:`QuerySet` that has had a slice taken or can otherwise no longer be
filtered.
For example, if you wanted to update all the entries in a particular blog
@@ -1246,8 +1249,8 @@
methods on your models, nor does it emit the ``pre_save`` or ``post_save``
signals (which are a consequence of calling ``save()``).
-``delete()``
-~~~~~~~~~~~~~~~~~~~~
+delete
+~~~~~~
.. method:: delete()
@@ -1711,7 +1714,8 @@
Note this is only available in MySQL and requires direct manipulation of the
database to add the full-text index. By default Django uses BOOLEAN MODE for
-full text searches. `Please check MySQL documentation for additional details.
<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
+full text searches. `See the MySQL documentation for additional details.
+<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
.. fieldlookup:: regex
@@ -1780,8 +1784,8 @@
aggregate functions, see
:doc:`the topic guide on aggregation </topics/db/aggregation>`.
-``Avg``
-~~~~~~~
+Avg
+~~~
.. class:: Avg(field)
@@ -1790,8 +1794,8 @@
* Default alias: ``<field>__avg``
* Return type: float
-``Count``
-~~~~~~~~~
+Count
+~~~~~
.. class:: Count(field, distinct=False)
@@ -1807,8 +1811,8 @@
If distinct=True, the count will only include unique instances. This has
the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is
``False``.
-``Max``
-~~~~~~~
+Max
+~~~
.. class:: Max(field)
@@ -1817,8 +1821,8 @@
* Default alias: ``<field>__max``
* Return type: same as input field
-``Min``
-~~~~~~~
+Min
+~~~
.. class:: Min(field)
@@ -1827,8 +1831,8 @@
* Default alias: ``<field>__min``
* Return type: same as input field
-``StdDev``
-~~~~~~~~~~
+StdDev
+~~~~~~
.. class:: StdDev(field, sample=False)
@@ -1850,8 +1854,8 @@
available as an extension module for SQLite. Consult the SQlite
documentation for instructions on obtaining and installing this extension.
-``Sum``
-~~~~~~~
+Sum
+~~~
.. class:: Sum(field)
@@ -1860,8 +1864,8 @@
* Default alias: ``<field>__sum``
* Return type: same as input field
-``Variance``
-~~~~~~~~~~~~
+Variance
+~~~~~~~~
.. class:: Variance(field, sample=False)
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
