From 55d65d335185f98e0a12b7a0caba6586ee4c594d Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sun, 9 May 2010 05:48:45 +0000 Subject: [PATCH] Fixed #12997 -- Added markup for methods in the queryset docs. Thanks to Ramiro Morales for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@13162 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 56 +++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 3 deletions(-) diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index b9f6656cf6a..23c5a8fc03c 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -138,6 +138,8 @@ executed. ``filter(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~ +.. method:: filter(**kwargs) + Returns a new ``QuerySet`` containing objects that match the given lookup parameters. @@ -148,6 +150,8 @@ underlying SQL statement. ``exclude(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~~ +.. method:: exclude(**kwargs) + Returns a new ``QuerySet`` containing objects that do *not* match the given lookup parameters. @@ -181,6 +185,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 @@ -223,6 +229,8 @@ 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. @@ -297,6 +305,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 @@ -327,6 +337,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. @@ -361,6 +373,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. @@ -449,6 +463,8 @@ individualism. ``values_list(*fields)`` ~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: values_list(*fields) + .. versionadded:: 1.0 This is similar to ``values()`` except that instead of returning dictionaries, @@ -477,6 +493,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``. @@ -511,6 +529,8 @@ Examples:: ``none()`` ~~~~~~~~~~ +.. method:: none() + .. versionadded:: 1.0 Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to @@ -524,7 +544,9 @@ Examples:: [] ``all()`` -~~~~~~~~~~ +~~~~~~~~~ + +.. method:: all() .. versionadded:: 1.0 @@ -539,6 +561,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) @@ -660,6 +684,8 @@ are performing a depth-based ``select_related``. ``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 @@ -822,6 +848,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 @@ -878,7 +906,9 @@ eventually). settled down and you understand where the hot-points are. ``only(*fields)`` -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ + +.. method:: only(*fields) .. versionadded:: 1.1 @@ -914,7 +944,9 @@ logically:: Entry.objects.defer("body").only("headline", "body") ``using(alias)`` -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ + +.. method:: using(alias) .. versionadded:: 1.2 @@ -946,6 +978,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`_. @@ -973,6 +1007,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") @@ -995,6 +1031,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. @@ -1063,6 +1101,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. @@ -1087,6 +1127,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. @@ -1106,6 +1148,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 @@ -1122,6 +1166,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. @@ -1142,6 +1188,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 @@ -1174,6 +1222,8 @@ Aggregation `. ``exists()`` ~~~~~~~~~~~~ +.. method:: exists() + .. versionadded:: 1.2 Returns ``True`` if the :class:`QuerySet` contains any results, and ``False``