Ticket #14758: fix-queryset-headers.diff

File fix-queryset-headers.diff, 12.2 KB (added by Adam Vandenberg, 14 years ago)

Update queryset headers on page (haven't checked cross-links yet)

  • docs/ref/models/querysets.txt

    diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
    index ccea588..8efcc31 100644
    a b Though you usually won't create one manually -- you'll go through a :class:`Mana  
    126126Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining
    127127filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.
    128128
    129 QuerySet methods that return new QuerySets
    130 ------------------------------------------
     129Methods that return new QuerySets
     130---------------------------------
    131131
    132132Django provides a range of ``QuerySet`` refinement methods that modify either
    133133the types of results returned by the ``QuerySet`` or the way its SQL query is
    134134executed.
    135135
    136 ``filter(**kwargs)``
    137 ~~~~~~~~~~~~~~~~~~~~
     136filter
     137~~~~~~
    138138
    139139.. method:: filter(**kwargs)
    140140
    The lookup parameters (``**kwargs``) should be in the format described in  
    145145`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
    146146underlying SQL statement.
    147147
    148 ``exclude(**kwargs)``
    149 ~~~~~~~~~~~~~~~~~~~~~
     148exclude
     149~~~~~~~
    150150
    151151.. method:: exclude(**kwargs)
    152152
    In SQL terms, that evaluates to::  
    180180
    181181Note the second example is more restrictive.
    182182
    183 ``annotate(*args, **kwargs)``
    184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     183annotate
     184~~~~~~~~
    185185
    186186.. method:: annotate(*args, **kwargs)
    187187
    control the name of the annotation::  
    224224For an in-depth discussion of aggregation, see :doc:`the topic guide on
    225225Aggregation </topics/db/aggregation>`.
    226226
    227 ``order_by(*fields)``
    228 ~~~~~~~~~~~~~~~~~~~~~
     227order_by
     228~~~~~~~~
    229229
    230230.. method:: order_by(*fields)
    231231
    primary key if there is no ``Meta.ordering`` specified. For example::  
    267267...since the ``Blog`` model has no default ordering specified.
    268268
    269269Be cautious when ordering by fields in related models if you are also using
    270 ``distinct()``. See the note in the `distinct()`_ section for an explanation
    271 of how related model ordering can change the expected results.
     270``distinct()``. See the note in :meth:`distinct` for an explanation of how
     271related model ordering can change the expected results.
    272272
    273273It is permissible to specify a multi-valued field to order the results by (for
    274274example, a ``ManyToMany`` field). Normally this won't be a sensible thing to
    fields with care and make sure the results are what you expect.  
    280280
    281281.. versionadded:: 1.0
    282282
    283 If you don't want any ordering to be applied to a query, not even the default
    284 ordering, call ``order_by()`` with no parameters.
    285 
    286 .. versionadded:: 1.0
    287 
    288283The syntax for ordering across related models has changed. See the `Django 0.96
    289284documentation`_ for the old behaviour.
    290285
    There's no way to specify whether ordering should be case sensitive. With  
    294289respect to case-sensitivity, Django will order results however your database
    295290backend normally orders them.
    296291
     292If you don't want any ordering to be applied to a query, not even the default
     293ordering, call ``order_by()`` with no parameters.
     294
    297295.. versionadded:: 1.1
    298296
    299297You can tell if a query is ordered or not by checking the
    300298:attr:`QuerySet.ordered` attribute, which will be ``True`` if the
    301299``QuerySet`` has been ordered in any way.
    302300
    303 ``reverse()``
    304 ~~~~~~~~~~~~~
     301reverse
     302~~~~~~~
    305303
    306304.. method:: reverse()
    307305
    a model which defines a default ordering, or when using  
    330328ordering was undefined prior to calling ``reverse()``, and will remain
    331329undefined afterward).
    332330
    333 ``distinct()``
    334 ~~~~~~~~~~~~~~
     331distinct
     332~~~~~~~~
    335333
    336334.. method:: distinct()
    337335
    query spans multiple tables, it's possible to get duplicate results when a  
    345343``QuerySet`` is evaluated. That's when you'd use ``distinct()``.
    346344
    347345.. note::
    348     Any fields used in an `order_by(*fields)`_ call are included in the SQL
     346    Any fields used in an :meth:`order_by` call are included in the SQL
    349347    ``SELECT`` columns. This can sometimes lead to unexpected results when
    350348    used in conjunction with ``distinct()``. If you order by fields from a
    351349    related model, those fields will be added to the selected columns and they
    query spans multiple tables, it's possible to get duplicate results when a  
    363361    ``values()`` together, be careful when ordering by fields not in the
    364362    ``values()`` call.
    365363
    366 ``values(*fields)``
    367 ~~~~~~~~~~~~~~~~~~~
     364values
     365~~~~~~
    368366
    369367.. method:: values(*fields)
    370368
    A few subtleties that are worth mentioning:  
    419417
    420418        >>> Entry.objects.values('blog_id')
    421419        [{'blog_id': 1}, ...]
     420
    422421    * When using ``values()`` together with ``distinct()``, be aware that
    423       ordering can affect the results. See the note in the `distinct()`_
    424       section, above, for details.
     422      ordering can affect the results. See the note in :meth:`distinct` for
     423      details.
     424
    425425    * If you use a ``values()`` clause after an ``extra()`` clause,
    426426      any fields defined by a ``select`` argument in the ``extra()``
    427427      must be explicitly included in the ``values()`` clause. However,
    and ``ManyToManyField`` attributes::  
    472472   pronounced if you include multiple such fields in your ``values()`` query,
    473473   in which case all possible combinations will be returned.
    474474
    475 ``values_list(*fields)``
    476 ~~~~~~~~~~~~~~~~~~~~~~~~
     475values_list
     476~~~~~~~~~~~
    477477
    478478.. method:: values_list(*fields)
    479479
    It is an error to pass in ``flat`` when there is more than one field.  
    502502If you don't pass any values to ``values_list()``, it will return all the
    503503fields in the model, in the order they were declared.
    504504
    505 ``dates(field, kind, order='ASC')``
    506 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     505dates
     506~~~~~
    507507
    508508.. method:: dates(field, kind, order='ASC')
    509509
    Examples::  
    538538    >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
    539539    [datetime.datetime(2005, 3, 20)]
    540540
    541 ``none()``
    542 ~~~~~~~~~~
     541none
     542~~~~
    543543
    544544.. method:: none()
    545545
    Examples::  
    555555    >>> Entry.objects.none()
    556556    []
    557557
    558 ``all()``
    559 ~~~~~~~~~
     558all
     559~~~
    560560
    561561.. method:: all()
    562562
    definitely have a ``QuerySet`` to work with.  
    570570
    571571.. _select-related:
    572572
    573 ``select_related()``
    574 ~~~~~~~~~~~~~~~~~~~~
     573select_related
     574~~~~~~~~~~~~~~
    575575
    576576.. method:: select_related()
    577577
    related object.  
    691691``OneToOneFields`` will not be traversed in the reverse direction if you
    692692are performing a depth-based ``select_related``.
    693693
    694 ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
    695 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     694extra
     695~~~~~
    696696
    697697.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)
    698698
    of the arguments is required, but you should use at least one of them.  
    854854
    855855        Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
    856856
    857 ``defer(*fields)``
    858 ~~~~~~~~~~~~~~~~~~
     857defer
     858~~~~~
    859859
    860860.. method:: defer(*fields)
    861861
    eventually).  
    914914    bother using ``defer()``; leave it until your query construction has
    915915    settled down and you understand where the hot-points are.
    916916
    917 ``only(*fields)``
    918 ~~~~~~~~~~~~~~~~~
     917only
     918~~~~
    919919
    920920.. method:: only(*fields)
    921921
    logically::  
    952952    # existing set of fields).
    953953    Entry.objects.defer("body").only("headline", "body")
    954954
    955 ``using(alias)``
    956 ~~~~~~~~~~~~~~~~
     955using
     956~~~~~
    957957
    958958.. method:: using(alias)
    959959
    For example::  
    973973    >>> Entry.objects.using('backup')
    974974
    975975
    976 QuerySet methods that do not return QuerySets
    977 ---------------------------------------------
     976Methods that do not return QuerySets
     977------------------------------------
    978978
    979979The following ``QuerySet`` methods evaluate the ``QuerySet`` and return
    980980something *other than* a ``QuerySet``.
    something *other than* a ``QuerySet``.  
    982982These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
    983983they query the database each time they're called.
    984984
    985 ``get(**kwargs)``
    986 ~~~~~~~~~~~~~~~~~
     985get
     986~~~
    987987
    988988.. method:: get(**kwargs)
    989989
    The ``DoesNotExist`` exception inherits from  
    10111011    except ObjectDoesNotExist:
    10121012        print "Either the entry or blog doesn't exist."
    10131013
    1014 ``create(**kwargs)``
    1015 ~~~~~~~~~~~~~~~~~~~~
     1014create
     1015~~~~~~
    10161016
    10171017.. method:: create(**kwargs)
    10181018
    database, a call to ``create()`` will fail with an ``IntegrityError`` since  
    10351035primary keys must be unique. So remember to be prepared to handle the
    10361036exception if you are using manual primary keys.
    10371037
    1038 ``get_or_create(**kwargs)``
    1039 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1038get_or_create
     1039~~~~~~~~~~~~~
    10401040
    10411041.. method:: get_or_create(**kwargs)
    10421042
    has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.  
    11051105
    11061106.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
    11071107
    1108 ``count()``
    1109 ~~~~~~~~~~~
     1108count
     1109~~~~~
    11101110
    11111111.. method:: count()
    11121112
    Depending on which database you're using (e.g. PostgreSQL vs. MySQL),  
    11311131is an underlying implementation quirk that shouldn't pose any real-world
    11321132problems.
    11331133
    1134 ``in_bulk(id_list)``
    1135 ~~~~~~~~~~~~~~~~~~~~
     1134in_bulk
     1135~~~~~~~
    11361136
    11371137.. method:: in_bulk(id_list)
    11381138
    Example::  
    11501150
    11511151If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
    11521152
    1153 ``iterator()``
    1154 ~~~~~~~~~~~~~~
     1153iterator
     1154~~~~~~~~
    11551155
    11561156.. method:: iterator()
    11571157
    been evaluated will force it to evaluate again, repeating the query.  
    11681168
    11691169.. _iterator: http://www.python.org/dev/peps/pep-0234/
    11701170
    1171 ``latest(field_name=None)``
    1172 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1171latest
     1172~~~~~~
    11731173
    11741174.. method:: latest(field_name=None)
    11751175
    exist with the given parameters.  
    11901190
    11911191Note ``latest()`` exists purely for convenience and readability.
    11921192
    1193 ``aggregate(*args, **kwargs)``
    1194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1193aggregate
     1194~~~~~~~~~
    11951195
    11961196.. method:: aggregate(*args, **kwargs)
    11971197
    control the name of the aggregation value that is returned::  
    12241224For an in-depth discussion of aggregation, see :doc:`the topic guide on
    12251225Aggregation </topics/db/aggregation>`.
    12261226
    1227 ``exists()``
    1228 ~~~~~~~~~~~~
     1227exists
     1228~~~~~~
    12291229
    12301230.. method:: exists()
    12311231
    that it will be at some point, then using ``some_query_set.exists()`` will do  
    12401240more overall work (an additional query) than simply using
    12411241``bool(some_query_set)``.
    12421242
    1243 ``update(**kwargs)``
    1244 ~~~~~~~~~~~~~~~~~~~~
     1243update
     1244~~~~~~
    12451245
    12461246.. method:: update(**kwargs)
    12471247
    The ``update()`` method does a bulk update and does not call any ``save()``  
    12651265methods on your models, nor does it emit the ``pre_save`` or ``post_save``
    12661266signals (which are a consequence of calling ``save()``).
    12671267
    1268 ``delete()``
    1269 ~~~~~~~~~~~~~~~~~~~~
     1268delete
     1269~~~~~~
    12701270
    12711271.. method:: delete()
    12721272
    Django provides the following aggregation functions in the  
    18051805aggregate functions, see
    18061806:doc:`the topic guide on aggregation </topics/db/aggregation>`.
    18071807
    1808 ``Avg``
    1809 ~~~~~~~
     1808Avg
     1809~~~
    18101810
    18111811.. class:: Avg(field)
    18121812
    Returns the mean value of the given field.  
    18151815    * Default alias: ``<field>__avg``
    18161816    * Return type: float
    18171817
    1818 ``Count``
    1819 ~~~~~~~~~
     1818Count
     1819~~~~~
    18201820
    18211821.. class:: Count(field, distinct=False)
    18221822
    Has one optional argument:  
    18321832    If distinct=True, the count will only include unique instances. This has
    18331833    the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
    18341834
    1835 ``Max``
    1836 ~~~~~~~
     1835Max
     1836~~~
    18371837
    18381838.. class:: Max(field)
    18391839
    Returns the maximum value of the given field.  
    18421842    * Default alias: ``<field>__max``
    18431843    * Return type: same as input field
    18441844
    1845 ``Min``
    1846 ~~~~~~~
     1845Min
     1846~~~
    18471847
    18481848.. class:: Min(field)
    18491849
    Returns the minimum value of the given field.  
    18521852    * Default alias: ``<field>__min``
    18531853    * Return type: same as input field
    18541854
    1855 ``StdDev``
    1856 ~~~~~~~~~~
     1855StdDev
     1856~~~~~~
    18571857
    18581858.. class:: StdDev(field, sample=False)
    18591859
    Has one optional argument:  
    18751875    available as an extension module for SQLite. Consult the SQlite
    18761876    documentation for instructions on obtaining and installing this extension.
    18771877
    1878 ``Sum``
    1879 ~~~~~~~
     1878Sum
     1879~~~
    18801880
    18811881.. class:: Sum(field)
    18821882
    Computes the sum of all values of the given field.  
    18851885    * Default alias: ``<field>__sum``
    18861886    * Return type: same as input field
    18871887
    1888 ``Variance``
    1889 ~~~~~~~~~~~~
     1888Variance
     1889~~~~~~~~
    18901890
    18911891.. class:: Variance(field, sample=False)
    18921892
Back to Top