Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #14758 - Remove entire method signatures from QuerySet headings…

… - thanks adamv for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14737 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit b31a956d57d49c3f332b48c807c3bcffdb8eea9b 1 parent 676c28c
Tim Graham authored November 28, 2010

Showing 1 changed file with 93 additions and 89 deletions. Show diff stats Hide diff stats

  1. 182  docs/ref/models/querysets.txt
182  docs/ref/models/querysets.txt
@@ -119,22 +119,23 @@ described here.
119 119
 QuerySet API
120 120
 ============
121 121
 
122  
-Though you usually won't create one manually -- you'll go through a :class:`Manager` -- here's the formal declaration of a ``QuerySet``:
  122
+Though you usually won't create one manually -- you'll go through a
  123
+:class:`Manager` -- here's the formal declaration of a ``QuerySet``:
123 124
 
124 125
 .. class:: QuerySet([model=None])
125 126
 
126 127
 Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining
127 128
 filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.
128 129
 
129  
-QuerySet methods that return new QuerySets
130  
-------------------------------------------
  130
+Methods that return new QuerySets
  131
+---------------------------------
131 132
 
132 133
 Django provides a range of ``QuerySet`` refinement methods that modify either
133 134
 the types of results returned by the ``QuerySet`` or the way its SQL query is
134 135
 executed.
135 136
 
136  
-``filter(**kwargs)``
137  
-~~~~~~~~~~~~~~~~~~~~
  137
+filter
  138
+~~~~~~
138 139
 
139 140
 .. method:: filter(**kwargs)
140 141
 
@@ -145,8 +146,8 @@ The lookup parameters (``**kwargs``) should be in the format described in
145 146
 `Field lookups`_ below. Multiple parameters are joined via ``AND`` in the
146 147
 underlying SQL statement.
147 148
 
148  
-``exclude(**kwargs)``
149  
-~~~~~~~~~~~~~~~~~~~~~
  149
+exclude
  150
+~~~~~~~
150 151
 
151 152
 .. method:: exclude(**kwargs)
152 153
 
@@ -180,8 +181,8 @@ In SQL terms, that evaluates to::
180 181
 
181 182
 Note the second example is more restrictive.
182 183
 
183  
-``annotate(*args, **kwargs)``
184  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  184
+annotate
  185
+~~~~~~~~
185 186
 
186 187
 .. method:: annotate(*args, **kwargs)
187 188
 
@@ -224,8 +225,8 @@ control the name of the annotation::
224 225
 For an in-depth discussion of aggregation, see :doc:`the topic guide on
225 226
 Aggregation </topics/db/aggregation>`.
226 227
 
227  
-``order_by(*fields)``
228  
-~~~~~~~~~~~~~~~~~~~~~
  228
+order_by
  229
+~~~~~~~~
229 230
 
230 231
 .. method:: order_by(*fields)
231 232
 
@@ -267,8 +268,8 @@ primary key if there is no ``Meta.ordering`` specified. For example::
267 268
 ...since the ``Blog`` model has no default ordering specified.
268 269
 
269 270
 Be 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.
  271
+``distinct()``. See the note in :meth:`distinct` for an explanation of how
  272
+related model ordering can change the expected results.
272 273
 
273 274
 It is permissible to specify a multi-valued field to order the results by (for
274 275
 example, a ``ManyToMany`` field). Normally this won't be a sensible thing to
@@ -280,11 +281,6 @@ fields with care and make sure the results are what you expect.
280 281
 
281 282
 .. versionadded:: 1.0
282 283
 
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  
-
288 284
 The syntax for ordering across related models has changed. See the `Django 0.96
289 285
 documentation`_ for the old behaviour.
290 286
 
@@ -294,14 +290,17 @@ There's no way to specify whether ordering should be case sensitive. With
294 290
 respect to case-sensitivity, Django will order results however your database
295 291
 backend normally orders them.
296 292
 
  293
+If you don't want any ordering to be applied to a query, not even the default
  294
+ordering, call ``order_by()`` with no parameters.
  295
+
297 296
 .. versionadded:: 1.1
298 297
 
299 298
 You can tell if a query is ordered or not by checking the
300 299
 :attr:`QuerySet.ordered` attribute, which will be ``True`` if the
301 300
 ``QuerySet`` has been ordered in any way.
302 301
 
303  
-``reverse()``
304  
-~~~~~~~~~~~~~
  302
+reverse
  303
+~~~~~~~
305 304
 
306 305
 .. method:: reverse()
307 306
 
@@ -330,8 +329,8 @@ a model which defines a default ordering, or when using
330 329
 ordering was undefined prior to calling ``reverse()``, and will remain
331 330
 undefined afterward).
332 331
 
333  
-``distinct()``
334  
-~~~~~~~~~~~~~~
  332
+distinct
  333
+~~~~~~~~
335 334
 
336 335
 .. method:: distinct()
337 336
 
@@ -345,7 +344,7 @@ query spans multiple tables, it's possible to get duplicate results when a
345 344
 ``QuerySet`` is evaluated. That's when you'd use ``distinct()``.
346 345
 
347 346
 .. note::
348  
-    Any fields used in an `order_by(*fields)`_ call are included in the SQL
  347
+    Any fields used in an :meth:`order_by` call are included in the SQL
349 348
     ``SELECT`` columns. This can sometimes lead to unexpected results when
350 349
     used in conjunction with ``distinct()``. If you order by fields from a
351 350
     related model, those fields will be added to the selected columns and they
@@ -363,8 +362,8 @@ query spans multiple tables, it's possible to get duplicate results when a
363 362
     ``values()`` together, be careful when ordering by fields not in the
364 363
     ``values()`` call.
365 364
 
366  
-``values(*fields)``
367  
-~~~~~~~~~~~~~~~~~~~
  365
+values
  366
+~~~~~~
368 367
 
369 368
 .. method:: values(*fields)
370 369
 
@@ -419,9 +418,11 @@ A few subtleties that are worth mentioning:
419 418
 
420 419
         >>> Entry.objects.values('blog_id')
421 420
         [{'blog_id': 1}, ...]
  421
+
422 422
     * 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.
  423
+      ordering can affect the results. See the note in :meth:`distinct` for
  424
+      details.
  425
+
425 426
     * If you use a ``values()`` clause after an ``extra()`` clause,
426 427
       any fields defined by a ``select`` argument in the ``extra()``
427 428
       must be explicitly included in the ``values()`` clause. However,
@@ -472,8 +473,8 @@ and ``ManyToManyField`` attributes::
472 473
    pronounced if you include multiple such fields in your ``values()`` query,
473 474
    in which case all possible combinations will be returned.
474 475
 
475  
-``values_list(*fields)``
476  
-~~~~~~~~~~~~~~~~~~~~~~~~
  476
+values_list
  477
+~~~~~~~~~~~
477 478
 
478 479
 .. method:: values_list(*fields)
479 480
 
@@ -502,8 +503,8 @@ It is an error to pass in ``flat`` when there is more than one field.
502 503
 If you don't pass any values to ``values_list()``, it will return all the
503 504
 fields in the model, in the order they were declared.
504 505
 
505  
-``dates(field, kind, order='ASC')``
506  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  506
+dates
  507
+~~~~~
507 508
 
508 509
 .. method:: dates(field, kind, order='ASC')
509 510
 
@@ -538,8 +539,8 @@ Examples::
538 539
     >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
539 540
     [datetime.datetime(2005, 3, 20)]
540 541
 
541  
-``none()``
542  
-~~~~~~~~~~
  542
+none
  543
+~~~~
543 544
 
544 545
 .. method:: none()
545 546
 
@@ -555,14 +556,14 @@ Examples::
555 556
     >>> Entry.objects.none()
556 557
     []
557 558
 
558  
-``all()``
559  
-~~~~~~~~~
  559
+all
  560
+~~~
560 561
 
561 562
 .. method:: all()
562 563
 
563 564
 .. versionadded:: 1.0
564 565
 
565  
-Returns a ''copy'' of the current ``QuerySet`` (or ``QuerySet`` subclass you
  566
+Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you
566 567
 pass in). This can be useful in some situations where you might want to pass
567 568
 in either a model manager or a ``QuerySet`` and do further filtering on the
568 569
 result. You can safely call ``all()`` on either object and then you'll
@@ -570,8 +571,8 @@ definitely have a ``QuerySet`` to work with.
570 571
 
571 572
 .. _select-related:
572 573
 
573  
-``select_related()``
574  
-~~~~~~~~~~~~~~~~~~~~
  574
+select_related
  575
+~~~~~~~~~~~~~~
575 576
 
576 577
 .. method:: select_related()
577 578
 
@@ -691,8 +692,8 @@ related object.
691 692
 ``OneToOneFields`` will not be traversed in the reverse direction if you
692 693
 are performing a depth-based ``select_related``.
693 694
 
694  
-``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
695  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  695
+extra
  696
+~~~~~
696 697
 
697 698
 .. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)
698 699
 
@@ -854,8 +855,8 @@ of the arguments is required, but you should use at least one of them.
854 855
 
855 856
         Entry.objects.extra(where=['headline=%s'], params=['Lennon'])
856 857
 
857  
-``defer(*fields)``
858  
-~~~~~~~~~~~~~~~~~~
  858
+defer
  859
+~~~~~
859 860
 
860 861
 .. method:: defer(*fields)
861 862
 
@@ -882,7 +883,9 @@ deferred set::
882 883
     # Defers both the body and headline fields.
883 884
     Entry.objects.defer("body").filter(rating=5).defer("headline")
884 885
 
885  
-The order in which fields are added to the deferred set does not matter. Calling ``defer()`` with a field name that has already been deferred is harmless (the field will still be deferred).
  886
+The order in which fields are added to the deferred set does not matter.
  887
+Calling ``defer()`` with a field name that has already been deferred is
  888
+harmless (the field will still be deferred).
886 889
 
887 890
 You can defer loading of fields in related models (if the related models are
888 891
 loading via ``select_related()``) by using the standard double-underscore
@@ -914,8 +917,8 @@ eventually).
914 917
     bother using ``defer()``; leave it until your query construction has
915 918
     settled down and you understand where the hot-points are.
916 919
 
917  
-``only(*fields)``
918  
-~~~~~~~~~~~~~~~~~
  920
+only
  921
+~~~~
919 922
 
920 923
 .. method:: only(*fields)
921 924
 
@@ -952,8 +955,8 @@ logically::
952 955
     # existing set of fields).
953 956
     Entry.objects.defer("body").only("headline", "body")
954 957
 
955  
-``using(alias)``
956  
-~~~~~~~~~~~~~~~~
  958
+using
  959
+~~~~~
957 960
 
958 961
 .. method:: using(alias)
959 962
 
@@ -973,8 +976,8 @@ For example::
973 976
     >>> Entry.objects.using('backup')
974 977
 
975 978
 
976  
-QuerySet methods that do not return QuerySets
977  
----------------------------------------------
  979
+Methods that do not return QuerySets
  980
+------------------------------------
978 981
 
979 982
 The following ``QuerySet`` methods evaluate the ``QuerySet`` and return
980 983
 something *other than* a ``QuerySet``.
@@ -982,8 +985,8 @@ something *other than* a ``QuerySet``.
982 985
 These methods do not use a cache (see :ref:`caching-and-querysets`). Rather,
983 986
 they query the database each time they're called.
984 987
 
985  
-``get(**kwargs)``
986  
-~~~~~~~~~~~~~~~~~
  988
+get
  989
+~~~
987 990
 
988 991
 .. method:: get(**kwargs)
989 992
 
@@ -1011,8 +1014,8 @@ The ``DoesNotExist`` exception inherits from
1011 1014
     except ObjectDoesNotExist:
1012 1015
         print "Either the entry or blog doesn't exist."
1013 1016
 
1014  
-``create(**kwargs)``
1015  
-~~~~~~~~~~~~~~~~~~~~
  1017
+create
  1018
+~~~~~~
1016 1019
 
1017 1020
 .. method:: create(**kwargs)
1018 1021
 
@@ -1031,12 +1034,12 @@ The :ref:`force_insert <ref-models-force-insert>` parameter is documented
1031 1034
 elsewhere, but all it means is that a new object will always be created.
1032 1035
 Normally you won't need to worry about this. However, if your model contains a
1033 1036
 manual primary key value that you set and if that value already exists in the
1034  
-database, a call to ``create()`` will fail with an ``IntegrityError`` since
1035  
-primary keys must be unique. So remember to be prepared to handle the
1036  
-exception if you are using manual primary keys.
  1037
+database, a call to ``create()`` will fail with an :exc:`IntegrityError` since
  1038
+primary keys must be unique. So remember to be prepared to handle the exception
  1039
+if you are using manual primary keys.
1037 1040
 
1038  
-``get_or_create(**kwargs)``
1039  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1041
+get_or_create
  1042
+~~~~~~~~~~~~~
1040 1043
 
1041 1044
 .. method:: get_or_create(**kwargs)
1042 1045
 
@@ -1105,8 +1108,8 @@ has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec.
1105 1108
 
1106 1109
 .. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
1107 1110
 
1108  
-``count()``
1109  
-~~~~~~~~~~~
  1111
+count
  1112
+~~~~~
1110 1113
 
1111 1114
 .. method:: count()
1112 1115
 
@@ -1131,8 +1134,8 @@ Depending on which database you're using (e.g. PostgreSQL vs. MySQL),
1131 1134
 is an underlying implementation quirk that shouldn't pose any real-world
1132 1135
 problems.
1133 1136
 
1134  
-``in_bulk(id_list)``
1135  
-~~~~~~~~~~~~~~~~~~~~
  1137
+in_bulk
  1138
+~~~~~~~
1136 1139
 
1137 1140
 .. method:: in_bulk(id_list)
1138 1141
 
@@ -1150,8 +1153,8 @@ Example::
1150 1153
 
1151 1154
 If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
1152 1155
 
1153  
-``iterator()``
1154  
-~~~~~~~~~~~~~~
  1156
+iterator
  1157
+~~~~~~~~
1155 1158
 
1156 1159
 .. method:: iterator()
1157 1160
 
@@ -1168,8 +1171,8 @@ been evaluated will force it to evaluate again, repeating the query.
1168 1171
 
1169 1172
 .. _iterator: http://www.python.org/dev/peps/pep-0234/
1170 1173
 
1171  
-``latest(field_name=None)``
1172  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1174
+latest
  1175
+~~~~~~
1173 1176
 
1174 1177
 .. method:: latest(field_name=None)
1175 1178
 
@@ -1190,8 +1193,8 @@ exist with the given parameters.
1190 1193
 
1191 1194
 Note ``latest()`` exists purely for convenience and readability.
1192 1195
 
1193  
-``aggregate(*args, **kwargs)``
1194  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1196
+aggregate
  1197
+~~~~~~~~~
1195 1198
 
1196 1199
 .. method:: aggregate(*args, **kwargs)
1197 1200
 
@@ -1224,8 +1227,8 @@ control the name of the aggregation value that is returned::
1224 1227
 For an in-depth discussion of aggregation, see :doc:`the topic guide on
1225 1228
 Aggregation </topics/db/aggregation>`.
1226 1229
 
1227  
-``exists()``
1228  
-~~~~~~~~~~~~
  1230
+exists
  1231
+~~~~~~
1229 1232
 
1230 1233
 .. method:: exists()
1231 1234
 
@@ -1240,8 +1243,8 @@ that it will be at some point, then using ``some_query_set.exists()`` will do
1240 1243
 more overall work (an additional query) than simply using
1241 1244
 ``bool(some_query_set)``.
1242 1245
 
1243  
-``update(**kwargs)``
1244  
-~~~~~~~~~~~~~~~~~~~~
  1246
+update
  1247
+~~~~~~
1245 1248
 
1246 1249
 .. method:: update(**kwargs)
1247 1250
 
@@ -1265,8 +1268,8 @@ The ``update()`` method does a bulk update and does not call any ``save()``
1265 1268
 methods on your models, nor does it emit the ``pre_save`` or ``post_save``
1266 1269
 signals (which are a consequence of calling ``save()``).
1267 1270
 
1268  
-``delete()``
1269  
-~~~~~~~~~~~~~~~~~~~~
  1271
+delete
  1272
+~~~~~~
1270 1273
 
1271 1274
 .. method:: delete()
1272 1275
 
@@ -1736,7 +1739,8 @@ SQL equivalent::
1736 1739
 
1737 1740
 Note this is only available in MySQL and requires direct manipulation of the
1738 1741
 database to add the full-text index. By default Django uses BOOLEAN MODE for
1739  
-full text searches. `Please check MySQL documentation for additional details. <http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
  1742
+full text searches. `See the MySQL documentation for additional details.
  1743
+<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_
1740 1744
 
1741 1745
 
1742 1746
 .. fieldlookup:: regex
@@ -1805,8 +1809,8 @@ Django provides the following aggregation functions in the
1805 1809
 aggregate functions, see
1806 1810
 :doc:`the topic guide on aggregation </topics/db/aggregation>`.
1807 1811
 
1808  
-``Avg``
1809  
-~~~~~~~
  1812
+Avg
  1813
+~~~
1810 1814
 
1811 1815
 .. class:: Avg(field)
1812 1816
 
@@ -1815,8 +1819,8 @@ Returns the mean value of the given field.
1815 1819
     * Default alias: ``<field>__avg``
1816 1820
     * Return type: float
1817 1821
 
1818  
-``Count``
1819  
-~~~~~~~~~
  1822
+Count
  1823
+~~~~~
1820 1824
 
1821 1825
 .. class:: Count(field, distinct=False)
1822 1826
 
@@ -1832,8 +1836,8 @@ Has one optional argument:
1832 1836
     If distinct=True, the count will only include unique instances. This has
1833 1837
     the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``.
1834 1838
 
1835  
-``Max``
1836  
-~~~~~~~
  1839
+Max
  1840
+~~~
1837 1841
 
1838 1842
 .. class:: Max(field)
1839 1843
 
@@ -1842,8 +1846,8 @@ Returns the maximum value of the given field.
1842 1846
     * Default alias: ``<field>__max``
1843 1847
     * Return type: same as input field
1844 1848
 
1845  
-``Min``
1846  
-~~~~~~~
  1849
+Min
  1850
+~~~
1847 1851
 
1848 1852
 .. class:: Min(field)
1849 1853
 
@@ -1852,8 +1856,8 @@ Returns the minimum value of the given field.
1852 1856
     * Default alias: ``<field>__min``
1853 1857
     * Return type: same as input field
1854 1858
 
1855  
-``StdDev``
1856  
-~~~~~~~~~~
  1859
+StdDev
  1860
+~~~~~~
1857 1861
 
1858 1862
 .. class:: StdDev(field, sample=False)
1859 1863
 
@@ -1875,8 +1879,8 @@ Has one optional argument:
1875 1879
     available as an extension module for SQLite. Consult the SQlite
1876 1880
     documentation for instructions on obtaining and installing this extension.
1877 1881
 
1878  
-``Sum``
1879  
-~~~~~~~
  1882
+Sum
  1883
+~~~
1880 1884
 
1881 1885
 .. class:: Sum(field)
1882 1886
 
@@ -1885,8 +1889,8 @@ Computes the sum of all values of the given field.
1885 1889
     * Default alias: ``<field>__sum``
1886 1890
     * Return type: same as input field
1887 1891
 
1888  
-``Variance``
1889  
-~~~~~~~~~~~~
  1892
+Variance
  1893
+~~~~~~~~
1890 1894
 
1891 1895
 .. class:: Variance(field, sample=False)
1892 1896
 

0 notes on commit b31a956

Please sign in to comment.
Something went wrong with that request. Please try again.