diff options
author | Russell Keith-Magee <russell@keith-magee.com> | 2010-05-09 05:52:38 +0000 |
---|---|---|
committer | Russell Keith-Magee <russell@keith-magee.com> | 2010-05-09 05:52:38 +0000 |
commit | 6df4ffd4f4e6ad6aafe7dc697645de16d14cd797 (patch) | |
tree | 4343c2a5b4e2c505b093e6100651a60a81dca320 | |
parent | 3981355c5c770f80c1590a4d4ba152e78026e14d (diff) | |
download | django-6df4ffd4f4e6ad6aafe7dc697645de16d14cd797.tar.gz |
[1.1.X] Fixed #12997 -- Added markup for methods in the queryset docs. Thanks to Ramiro Morales for the patch.
Backport of r13162 from trunk.
git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@13165 bcc190cf-cafb-0310-a4f2-bffc1f526a37
-rw-r--r-- | docs/ref/models/querysets.txt | 50 |
1 files changed, 48 insertions, 2 deletions
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 7c6c0c17d1..bf461583b2 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -134,6 +134,8 @@ executed. ``filter(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~ +.. method:: filter(**kwargs) + Returns a new ``QuerySet`` containing objects that match the given lookup parameters. @@ -144,6 +146,8 @@ underlying SQL statement. ``exclude(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~~ +.. method:: exclude(**kwargs) + Returns a new ``QuerySet`` containing objects that do *not* match the given lookup parameters. @@ -177,6 +181,8 @@ Note the second example is more restrictive. ``annotate(*args, **kwargs)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: annotate(*args, **kwargs) + .. versionadded:: 1.1 Annotates each object in the ``QuerySet`` with the provided list of @@ -219,6 +225,8 @@ Aggregation <topics-db-aggregation>`. ``order_by(*fields)`` ~~~~~~~~~~~~~~~~~~~~~ +.. method:: order_by(*fields) + By default, results returned by a ``QuerySet`` are ordered by the ordering tuple given by the ``ordering`` option in the model's ``Meta``. You can override this on a per-``QuerySet`` basis by using the ``order_by`` method. @@ -293,6 +301,8 @@ You can tell if a query is ordered or not by checking the ``reverse()`` ~~~~~~~~~~~~~ +.. method:: reverse() + .. versionadded:: 1.0 Use the ``reverse()`` method to reverse the order in which a queryset's @@ -323,6 +333,8 @@ undefined afterward). ``distinct()`` ~~~~~~~~~~~~~~ +.. method:: distinct() + Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This eliminates duplicate rows from the query results. @@ -357,6 +369,8 @@ query spans multiple tables, it's possible to get duplicate results when a ``values(*fields)`` ~~~~~~~~~~~~~~~~~~~ +.. method:: values(*fields) + Returns a ``ValuesQuerySet`` -- a ``QuerySet`` that returns dictionaries when used as an iterable, rather than model-instance objects. @@ -445,6 +459,8 @@ individualism. ``values_list(*fields)`` ~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: values_list(*fields) + .. versionadded:: 1.0 This is similar to ``values()`` except that instead of returning dictionaries, @@ -473,6 +489,8 @@ fields in the model, in the order they were declared. ``dates(field, kind, order='ASC')`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: dates(field, kind, order='ASC') + Returns a ``DateQuerySet`` -- a ``QuerySet`` that evaluates to a list of ``datetime.datetime`` objects representing all available dates of a particular kind within the contents of the ``QuerySet``. @@ -507,6 +525,8 @@ Examples:: ``none()`` ~~~~~~~~~~ +.. method:: none() + .. versionadded:: 1.0 Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to @@ -520,7 +540,9 @@ Examples:: [] ``all()`` -~~~~~~~~~~ +~~~~~~~~~ + +.. method:: all() .. versionadded:: 1.0 @@ -535,6 +557,8 @@ definitely have a ``QuerySet`` to work with. ``select_related()`` ~~~~~~~~~~~~~~~~~~~~ +.. method:: select_related() + Returns a ``QuerySet`` that will automatically "follow" foreign-key relationships, selecting that additional related-object data when it executes its query. This is a performance booster which results in (sometimes much) @@ -644,6 +668,8 @@ to ``select_related()`` are new in Django version 1.0. ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None) + Sometimes, the Django query syntax by itself can't easily express a complex ``WHERE`` clause. For these edge cases, Django provides the ``extra()`` ``QuerySet`` modifier -- a hook for injecting specific clauses into the SQL @@ -806,6 +832,8 @@ of the arguments is required, but you should use at least one of them. ``defer(*fields)`` ~~~~~~~~~~~~~~~~~~ +.. method:: defer(*fields) + .. versionadded:: 1.1 In some complex data-modeling situations, your models might contain a lot of @@ -862,7 +890,9 @@ eventually). settled down and you understand where the hot-points are. ``only(*fields)`` -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ + +.. method:: only(*fields) .. versionadded:: 1.1 @@ -912,6 +942,8 @@ they query the database each time they're called. ``get(**kwargs)`` ~~~~~~~~~~~~~~~~~ +.. method:: get(**kwargs) + Returns the object matching the given lookup parameters, which should be in the format described in `Field lookups`_. @@ -939,6 +971,8 @@ The ``DoesNotExist`` exception inherits from ``create(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~ +.. method:: create(**kwargs) + A convenience method for creating an object and saving it all in one step. Thus:: p = Person.objects.create(first_name="Bruce", last_name="Springsteen") @@ -961,6 +995,8 @@ exception if you are using manual primary keys. ``get_or_create(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: get_or_create(**kwargs) + A convenience method for looking up an object with the given kwargs, creating one if necessary. @@ -1029,6 +1065,8 @@ has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec. ``count()`` ~~~~~~~~~~~ +.. method:: count() + Returns an integer representing the number of objects in the database matching the ``QuerySet``. ``count()`` never raises exceptions. @@ -1052,6 +1090,8 @@ problems. ``in_bulk(id_list)`` ~~~~~~~~~~~~~~~~~~~~ +.. method:: in_bulk(id_list) + Takes a list of primary-key values and returns a dictionary mapping each primary-key value to an instance of the object with the given ID. @@ -1071,6 +1111,8 @@ If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. ``iterator()`` ~~~~~~~~~~~~~~ +.. method:: iterator() + Evaluates the ``QuerySet`` (by performing the query) and returns an `iterator`_ over the results. A ``QuerySet`` typically caches its results internally so that repeated evaluations do not result in @@ -1087,6 +1129,8 @@ been evaluated will force it to evaluate again, repeating the query. ``latest(field_name=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: latest(field_name=None) + Returns the latest object in the table, by date, using the ``field_name`` provided as the date field. @@ -1107,6 +1151,8 @@ Note ``latest()`` exists purely for convenience and readability. ``aggregate(*args, **kwargs)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: aggregate(*args, **kwargs) + .. versionadded:: 1.1 Returns a dictionary of aggregate values (averages, sums, etc) calculated |