Author: russellm Date: 2010-05-09 00:52:38 -0500 (Sun, 09 May 2010) New Revision: 13165
Modified: django/branches/releases/1.1.X/docs/ref/models/querysets.txt Log: [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. Modified: django/branches/releases/1.1.X/docs/ref/models/querysets.txt =================================================================== --- django/branches/releases/1.1.X/docs/ref/models/querysets.txt 2010-05-09 05:51:57 UTC (rev 13164) +++ django/branches/releases/1.1.X/docs/ref/models/querysets.txt 2010-05-09 05:52:38 UTC (rev 13165) @@ -134,6 +134,8 @@ ``filter(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~ +.. method:: filter(**kwargs) + Returns a new ``QuerySet`` containing objects that match the given lookup parameters. @@ -144,6 +146,8 @@ ``exclude(**kwargs)`` ~~~~~~~~~~~~~~~~~~~~~ +.. method:: exclude(**kwargs) + Returns a new ``QuerySet`` containing objects that do *not* match the given lookup parameters. @@ -177,6 +181,8 @@ ``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 @@ ``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 @@ ``reverse()`` ~~~~~~~~~~~~~ +.. method:: reverse() + .. versionadded:: 1.0 Use the ``reverse()`` method to reverse the order in which a queryset's @@ -323,6 +333,8 @@ ``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 @@ ``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 @@ ``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 @@ ``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 @@ ``none()`` ~~~~~~~~~~ +.. method:: none() + .. versionadded:: 1.0 Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to @@ -520,8 +540,10 @@ [] ``all()`` -~~~~~~~~~~ +~~~~~~~~~ +.. method:: all() + .. versionadded:: 1.0 Returns a ''copy'' of the current ``QuerySet`` (or ``QuerySet`` subclass you @@ -535,6 +557,8 @@ ``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 @@ ``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 @@ ``defer(*fields)`` ~~~~~~~~~~~~~~~~~~ +.. method:: defer(*fields) + .. versionadded:: 1.1 In some complex data-modeling situations, your models might contain a lot of @@ -862,8 +890,10 @@ settled down and you understand where the hot-points are. ``only(*fields)`` -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ +.. method:: only(*fields) + .. versionadded:: 1.1 The ``only()`` method is more or less the opposite of ``defer()``. You @@ -912,6 +942,8 @@ ``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 @@ ``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 @@ ``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 @@ ``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 @@ ``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 @@ ``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 @@ ``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 @@ ``aggregate(*args, **kwargs)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: aggregate(*args, **kwargs) + .. versionadded:: 1.1 Returns a dictionary of aggregate values (averages, sums, etc) calculated -- You received this message because you are subscribed to the Google Groups "Django updates" group. To post to this group, send email to django-upda...@googlegroups.com. To unsubscribe from this group, send email to django-updates+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-updates?hl=en.