Ticket #15558: 15558_queryset.diff

File 15558_queryset.diff, 6.2 KB (added by Gabriel Hurley, 14 years ago)
  • docs/ref/models/querysets.txt

     
    22QuerySet API reference
    33======================
    44
    5 .. currentmodule:: django.db.models.QuerySet
     5.. currentmodule:: django.db.models.query
    66
    77This document describes the details of the ``QuerySet`` API. It builds on the
    88material presented in the :doc:`model </topics/db/models>` and :doc:`database
     
    120120============
    121121
    122122Though you usually won't create one manually -- you'll go through a
    123 :class:`Manager` -- here's the formal declaration of a ``QuerySet``:
     123:class:`~django.db.models.Manager` -- here's the formal declaration of a
     124``QuerySet``:
    124125
    125 .. class:: QuerySet([model=None])
     126.. class:: QuerySet([model=None, query=None, using=None])
    126127
    127 Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining
    128 filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets.
     128    Usually when you'll interact with a ``QuerySet`` you'll use it by
     129    :ref:`chaining filters <chaining-filters>`. To make this work, most
     130    ``QuerySet`` methods return new querysets. These methods are covered in
     131    detail later in this section.
    129132
     133    The ``QuerySet`` class has two public attributes you can use for
     134    introspection:
     135
     136    .. attribute:: ordered
     137
     138        ``True`` if the ``QuerySet`` is ordered -- i.e. has an order_by()
     139        clause or a default ordering on the model. ``False`` otherwise.
     140
     141    .. attribute:: db
     142   
     143        The database that will be used if this query is executed now.
     144
     145.. currentmodule:: django.db.models.query.QuerySet
     146
    130147Methods that return new QuerySets
    131148---------------------------------
    132149
     
    285302ordering, call ``order_by()`` with no parameters.
    286303
    287304You can tell if a query is ordered or not by checking the
    288 :attr:`QuerySet.ordered` attribute, which will be ``True`` if the
     305:attr:`.QuerySet.ordered` attribute, which will be ``True`` if the
    289306``QuerySet`` has been ordered in any way.
    290307
    291308reverse
     
    9991016elsewhere, but all it means is that a new object will always be created.
    10001017Normally you won't need to worry about this. However, if your model contains a
    10011018manual primary key value that you set and if that value already exists in the
    1002 database, a call to ``create()`` will fail with an :exc:`IntegrityError` since
    1003 primary keys must be unique. So remember to be prepared to handle the exception
    1004 if you are using manual primary keys.
     1019database, a call to ``create()`` will fail with an
     1020:exc:`~django.db.IntegrityError` since primary keys must be unique. So remember
     1021to be prepared to handle the exception if you are using manual primary keys.
    10051022
    10061023get_or_create
    10071024~~~~~~~~~~~~~
     
    11971214
    11981215.. versionadded:: 1.2
    11991216
    1200 Returns ``True`` if the :class:`QuerySet` contains any results, and ``False``
     1217Returns ``True`` if the :class:`.QuerySet` contains any results, and ``False``
    12011218if not. This tries to perform the query in the simplest and fastest way
    12021219possible, but it *does* execute nearly the same query. This means that calling
    1203 :meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by
     1220:meth:`.QuerySet.exists` is faster than ``bool(some_query_set)``, but not by
    12041221a large degree.  If ``some_query_set`` has not yet been evaluated, but you know
    12051222that it will be at some point, then using ``some_query_set.exists()`` will do
    12061223more overall work (an additional query) than simply using
     
    12131230
    12141231Performs an SQL update query for the specified fields, and returns
    12151232the number of rows affected. The ``update()`` method is applied instantly and
    1216 the only restriction on the :class:`QuerySet` that is updated is that it can
     1233the only restriction on the :class:`.QuerySet` that is updated is that it can
    12171234only update columns in the model's main table. Filtering based on related
    12181235fields is still possible. You cannot call ``update()`` on a
    1219 :class:`QuerySet` that has had a slice taken or can otherwise no longer be
     1236:class:`.QuerySet` that has had a slice taken or can otherwise no longer be
    12201237filtered.
    12211238
    12221239For example, if you wanted to update all the entries in a particular blog
     
    12361253
    12371254.. method:: delete()
    12381255
    1239 Performs an SQL delete query on all rows in the :class:`QuerySet`. The
     1256Performs an SQL delete query on all rows in the :class:`.QuerySet`. The
    12401257``delete()`` is applied instantly. You cannot call ``delete()`` on a
    1241 :class:`QuerySet` that has had a slice taken or can otherwise no longer be
     1258:class:`.QuerySet` that has had a slice taken or can otherwise no longer be
    12421259filtered.
    12431260
    12441261For example, to delete all the entries in a particular blog::
  • docs/topics/http/shortcuts.txt

     
    2424
    2525   :func:`render()` is the same as a call to
    2626   :func:`render_to_response()` with a `context_instance` argument that
    27    that forces the use of a :class:`RequestContext`.
     27   that forces the use of a :class:`~django.template.RequestContext`.
    2828
    2929Required arguments
    3030------------------
     
    220220
    221221.. function:: get_object_or_404(klass, *args, **kwargs)
    222222
    223    Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,
     223   Calls :meth:`~django.db.models.query.QuerySet.get()` on a given model manager,
    224224   but it raises :class:`~django.http.Http404` instead of the model's
    225225   :class:`~django.core.exceptions.DoesNotExist` exception.
    226226
     
    229229
    230230``klass``
    231231    A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or
    232     :class:`~django.db.models.QuerySet` instance from which to get the object.
     232    :class:`~django.db.models.query.QuerySet` instance from which to get the
     233    object.
    233234
    234235``**kwargs``
    235236    Lookup parameters, which should be in the format accepted by ``get()`` and
     
    265266
    266267.. function:: get_list_or_404(klass, *args, **kwargs)
    267268
    268    Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a
     269   Returns the result of :meth:`~django.db.models.query.QuerySet.filter()` on a
    269270   given model manager, raising :class:`~django.http.Http404` if the resulting
    270271   list is empty.
    271272
Back to Top