Ticket #12997: 12997.patch

File 12997.patch, 8.0 KB (added by Derek Willis, 14 years ago)

  • docs/ref/models/querysets.txt 

    From 0f2c4bf2256aa645d3d954e3cd99921171b829ca Mon Sep 17 00:00:00 2001
From: Derek Willis <dwillis@gmail.com>
Date: Sun, 28 Feb 2010 21:15:37 -0500
Subject: [PATCH] added metadata targets to querysets ref

---
 docs/ref/models/querysets.txt |   72 +++++++++++++---------------------------
 1 files changed, 24 insertions(+), 48 deletions(-)

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index b334240..96462b3 100644
    a b Django provides a range of ``QuerySet`` refinement methods that modify either  
    135135the types of results returned by the ``QuerySet`` or the way its SQL query is
    136136executed.
    137137
    138 ``filter(**kwargs)``
    139 ~~~~~~~~~~~~~~~~~~~~
     138.. method:: filter(**kwargs)
    140139
    141140Returns a new ``QuerySet`` containing objects that match the given lookup
    142141parameters.
    … … The lookup parameters (``**kwargs``) should be in the format described in  
    145144`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
    146145underlying SQL statement.
    147146
    148 ``exclude(**kwargs)``
    149 ~~~~~~~~~~~~~~~~~~~~~
     147.. method:: exclude(**kwargs)
    150148
    151149Returns a new ``QuerySet`` containing objects that do *not* match the given
    152150lookup parameters.
    … … In SQL terms, that evaluates to::  
    178176
    179177Note the second example is more restrictive.
    180178
    181 ``annotate(*args, **kwargs)``
    182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     179.. method:: annotate(*args, **kwargs)
    183180
    184181.. versionadded:: 1.1
    185182
    … … control the name of the annotation::  
    220217For an in-depth discussion of aggregation, see :ref:`the topic guide on
    221218Aggregation <topics-db-aggregation>`.
    222219
    223 ``order_by(*fields)``
    224 ~~~~~~~~~~~~~~~~~~~~~
     220.. method:: order_by(*fields)
    225221
    226222By default, results returned by a ``QuerySet`` are ordered by the ordering
    227223tuple given by the ``ordering`` option in the model's ``Meta``. You can
    … … undefined afterward).  
    324320
    325321.. _queryset-distinct:
    326322
    327 ``distinct()``
    328 ~~~~~~~~~~~~~~
     323.. method:: distinct()
    329324
    330325Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This
    331326eliminates duplicate rows from the query results.
    … … query spans multiple tables, it's possible to get duplicate results when a  
    358353
    359354.. _queryset-values:
    360355
    361 ``values(*fields)``
    362 ~~~~~~~~~~~~~~~~~~~
     356.. method:: values(*fields)
    363357
    364358Returns a ``ValuesQuerySet`` -- a ``QuerySet`` that evaluates to a list of
    365359dictionaries instead of model-instance objects.
    … … followed (optionally) by any output-affecting methods (such as ``values()``),  
    441435but it doesn't really matter. This is your chance to really flaunt your
    442436individualism.
    443437
    444 ``values_list(*fields)``
    445 ~~~~~~~~~~~~~~~~~~~~~~~~
     438.. method:: values_list(*fields)
    446439
    447440.. versionadded:: 1.0
    448441
    … … It is an error to pass in ``flat`` when there is more than one field.  
    469462If you don't pass any values to ``values_list()``, it will return all the
    470463fields in the model, in the order they were declared.
    471464
    472 ``dates(field, kind, order='ASC')``
    473 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     465.. method:: dates(field, kind, order='ASC')
    474466
    475467Returns a ``DateQuerySet`` -- a ``QuerySet`` that evaluates to a list of
    476468``datetime.datetime`` objects representing all available dates of a particular
    … … Examples::  
    503495    >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
    504496    [datetime.datetime(2005, 3, 20)]
    505497
    506 ``none()``
    507 ~~~~~~~~~~
     498.. method:: none()
    508499
    509500.. versionadded:: 1.0
    510501
    … … Examples::  
    518509    >>> Entry.objects.none()
    519510    []
    520511
    521 ``all()``
    522 ~~~~~~~~~~
     512.. method:: all()
    523513
    524514.. versionadded:: 1.0
    525515
    … … definitely have a ``QuerySet`` to work with.  
    531521
    532522.. _select-related:
    533523
    534 ``select_related()``
    535 ~~~~~~~~~~~~~~~~~~~~
     524.. method:: select_related()
    536525
    537526Returns a ``QuerySet`` that will automatically "follow" foreign-key
    538527relationships, selecting that additional related-object data when it executes
    … … are performing a depth-based ``select_related``.  
    652641
    653642.. _queryset-extra:
    654643
    655 ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
    656 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     644.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)
    657645
    658646Sometimes, the Django query syntax by itself can't easily express a complex
    659647``WHERE`` clause. For these edge cases, Django provides the ``extra()``
    … … of the arguments is required, but you should use at least one of them.  
    814802
    815803.. _queryset-defer:
    816804
    817 ``defer(*fields)``
    818 ~~~~~~~~~~~~~~~~~~
     805.. method:: defer(*fields)
    819806
    820807.. versionadded:: 1.1
    821808
    … … eventually).  
    872859    bother using ``defer()``; leave it until your query construction has
    873860    settled down and you understand where the hot-points are.
    874861
    875 ``only(*fields)``
    876 ~~~~~~~~~~~~~~~~~~
     862.. method:: only(*fields)
    877863
    878864.. versionadded:: 1.1
    879865
    … … logically::  
    908894    # existing set of fields).
    909895    Entry.objects.defer("body").only("headline", "body")
    910896
    911 ``using(alias)``
    912 ~~~~~~~~~~~~~~~~~~
     897.. method:: using(alias)
    913898
    914899.. versionadded:: 1.2
    915900
    … … they query the database each time they're called.  
    938923
    939924.. _get-kwargs:
    940925
    941 ``get(**kwargs)``
    942 ~~~~~~~~~~~~~~~~~
     926.. method:: get(**kwargs)
    943927
    944928Returns the object matching the given lookup parameters, which should be in
    945929the format described in `Field lookups`_.
    … … The ``DoesNotExist`` exception inherits from  
    965949    except ObjectDoesNotExist:
    966950        print "Either the entry or blog doesn't exist."
    967951
    968 ``create(**kwargs)``
    969 ~~~~~~~~~~~~~~~~~~~~
     952.. method:: create(**kwargs)
    970953
    971954A convenience method for creating an object and saving it all in one step.  Thus::
    972955
    … … database, a call to ``create()`` will fail with an ``IntegrityError`` since  
    987970primary keys must be unique. So remember to be prepared to handle the
    988971exception if you are using manual primary keys.
    989972
    990 ``get_or_create(**kwargs)``
    991 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
     973.. method:: get_or_create(**kwargs)
    992974
    993975A convenience method for looking up an object with the given kwargs, creating
    994976one if necessary.
    … … has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.  
    10551037
    10561038.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
    10571039
    1058 ``count()``
    1059 ~~~~~~~~~~~
     1040.. method:: count()
    10601041
    10611042Returns an integer representing the number of objects in the database matching
    10621043the ``QuerySet``. ``count()`` never raises exceptions.
    … … Depending on which database you're using (e.g. PostgreSQL vs. MySQL),  
    10791060is an underlying implementation quirk that shouldn't pose any real-world
    10801061problems.
    10811062
    1082 ``in_bulk(id_list)``
    1083 ~~~~~~~~~~~~~~~~~~~~
     1063.. method:: in_bulk(id_list)
    10841064
    10851065Takes a list of primary-key values and returns a dictionary mapping each
    10861066primary-key value to an instance of the object with the given ID.
    … … If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.  
    10981078
    10991079.. _queryset-iterator:
    11001080
    1101 ``iterator()``
    1102 ~~~~~~~~~~~~~~
     1081.. method:: iterator()
    11031082
    11041083Evaluates the ``QuerySet`` (by performing the query) and returns an
    11051084`iterator`_ over the results. A ``QuerySet`` typically caches its
    … … been evaluated will force it to evaluate again, repeating the query.  
    11141093
    11151094.. _iterator: http://www.python.org/dev/peps/pep-0234/
    11161095
    1117 ``latest(field_name=None)``
    1118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1096.. method:: latest(field_name=None)
    11191097
    11201098Returns the latest object in the table, by date, using the ``field_name``
    11211099provided as the date field.
    … … exist with the given parameters.  
    11341112
    11351113Note ``latest()`` exists purely for convenience and readability.
    11361114
    1137 ``aggregate(*args, **kwargs)``
    1138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1115.. method:: aggregate(*args, **kwargs)
    11391116
    11401117.. versionadded:: 1.1
    11411118
    … … control the name of the aggregation value that is returned::  
    11661143For an in-depth discussion of aggregation, see :ref:`the topic guide on
    11671144Aggregation <topics-db-aggregation>`.
    11681145
    1169 ``exists()``
    1170 ~~~~~~~~~~~~
     1146.. method:: exists()
    11711147
    11721148.. versionadded:: 1.2
    11731149
Back to Top