Ticket #4303: db-api.diff

File db-api.diff, 5.2 KB (added by Gary Wilson <gary.wilson@…>, 17 years ago)

a couple other small fixes and ending whitespace removed

  • docs/db-api.txt

    === modified file 'docs/db-api.txt'
     
    143143follows this algorithm:
    144144
    145145    * If the object's primary key attribute is set to a value that evaluates to
    146       ``True`` (i.e., a value other than ``None`` or the empty string), Django 
    147       executes a ``SELECT`` query to determine whether a record with the given 
     146      ``True`` (i.e., a value other than ``None`` or the empty string), Django
     147      executes a ``SELECT`` query to determine whether a record with the given
    148148      primary key already exists.
    149149    * If the record with the given primary key does already exist, Django
    150150      executes an ``UPDATE`` query.
     
    525525    [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
    526526    >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
    527527    [datetime.datetime(2005, 3, 20)]
    528    
     528
    529529``none()``
    530530~~~~~~~~~~
    531531
    532532**New in Django development version**
    533533
    534 Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to 
     534Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to
    535535an empty list. This can be used in cases where you know that you should
    536536return an empty result set and your caller is expecting a ``QuerySet``
    537537object (instead of returning an empty list, for example.)
    538538
    539539Examples::
    540    
     540
    541541    >>> Entry.objects.none()
    542542    []
    543543
     
    610610    c = p.hometown       # Requires a database call.
    611611
    612612The ``depth`` argument is new in the Django development version.
    613    
     613
    614614``extra(select=None, where=None, params=None, tables=None)``
    615615~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    616616
     
    11361136isnull
    11371137~~~~~~
    11381138
    1139 Takes either ``True`` or ``False``, which correspond to SQL queries of 
     1139Takes either ``True`` or ``False``, which correspond to SQL queries of
    11401140``IS NULL`` and ``IS NOT NULL``, respectively.
    11411141
    11421142Example::
     
    11491149
    11501150.. admonition:: ``__isnull=True`` vs ``__exact=None``
    11511151
    1152     There is an important difference between ``__isnull=True`` and 
     1152    There is an important difference between ``__isnull=True`` and
    11531153    ``__exact=None``. ``__exact=None`` will *always* return an empty result
    1154     set, because SQL requires that no value is equal to ``NULL``. 
    1155     ``__isnull`` determines if the field is currently holding the value 
     1154    set, because SQL requires that no value is equal to ``NULL``.
     1155    ``__isnull`` determines if the field is currently holding the value
    11561156    of ``NULL`` without performing a comparison.
    11571157
    11581158search
     
    11811181----------------------
    11821182
    11831183For convenience, Django provides a ``pk`` lookup type, which stands for
    1184 "primary_key". 
     1184"primary_key".
    11851185
    11861186In the example ``Blog`` model, the primary key is the ``id`` field, so these
    11871187three statements are equivalent::
     
    11901190    Blog.objects.get(id=14) # __exact is implied
    11911191    Blog.objects.get(pk=14) # pk implies id__exact
    11921192
    1193 The use of ``pk`` isn't limited to ``__exact`` queries -- any query term 
     1193The use of ``pk`` isn't limited to ``__exact`` queries -- any query term
    11941194can be combined with ``pk`` to perform a query on the primary key of a model::
    11951195
    11961196    # Get blogs entries  with id 1, 4 and 7
    11971197    Blog.objects.filter(pk__in=[1,4,7])
    11981198    # Get all blog entries with id > 14
    1199     Blog.objects.filter(pk__gt=14) 
    1200    
     1199    Blog.objects.filter(pk__gt=14)
     1200
    12011201``pk`` lookups also work across joins. For example, these three statements are
    12021202equivalent::
    12031203
     
    17541754-------------------
    17551755
    17561756One common idiom to use ``get()`` and raise ``Http404`` if the
    1757 object doesn't exist. This idiom is captured by ``get_object_or_404()``. 
    1758 This function takes a Django model as its first argument and an 
    1759 arbitrary number of keyword arguments, which it passes to the manager's 
     1757object doesn't exist. This idiom is captured by ``get_object_or_404()``.
     1758This function takes a Django model as its first argument and an
     1759arbitrary number of keyword arguments, which it passes to the manager's
    17601760``get()`` function. It raises ``Http404`` if the object doesn't
    1761 exist. For example:: 
    1762    
     1761exist. For example::
     1762
    17631763    # Get the Entry with a primary key of 3
    17641764    e = get_object_or_404(Entry, pk=3)
    17651765
    1766 When you provide a model to this shortcut function, the default manager 
    1767 is used to execute the underlying ``get()`` query. If you don't want to 
    1768 use the default manager, or you want to search a list of related objects,
    1769 you can provide ``get_object_or_404()`` with a manager object, instead.
     1766When you provide a model to this shortcut function, the default manager
     1767is used to execute the underlying ``get()`` query. If you don't want to
     1768use the default manager, or if you want to search a list of related objects,
     1769you can provide ``get_object_or_404()`` with a manager object instead.
    17701770For example::
    17711771
    17721772    # Get the author of blog instance `e` with a name of 'Fred'
     
    17791779get_list_or_404()
    17801780-----------------
    17811781
    1782 ``get_list_or_404`` behaves the same was as ``get_object_or_404()``
    1783 -- except the it uses using ``filter()`` instead of ``get()``. It raises
     1782``get_list_or_404`` behaves the same way as ``get_object_or_404()``
     1783-- except that it uses ``filter()`` instead of ``get()``. It raises
    17841784``Http404`` if the list is empty.
    17851785
    17861786Falling back to raw SQL
Back to Top