diff --git a/docs/db-api.txt b/docs/db-api.txt index 9d2f09daf3..de612e0e3d 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -143,8 +143,8 @@ or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django follows this algorithm: * If the object's primary key attribute is set to a value that evaluates to - ``True`` (i.e., a value other than ``None`` or the empty string), Django - executes a ``SELECT`` query to determine whether a record with the given + ``True`` (i.e., a value other than ``None`` or the empty string), Django + executes a ``SELECT`` query to determine whether a record with the given primary key already exists. * If the record with the given primary key does already exist, Django executes an ``UPDATE`` query. @@ -525,19 +525,19 @@ Examples:: [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') [datetime.datetime(2005, 3, 20)] - + ``none()`` ~~~~~~~~~~ **New in Django development version** -Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to +Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to an empty list. This can be used in cases where you know that you should return an empty result set and your caller is expecting a ``QuerySet`` object (instead of returning an empty list, for example.) Examples:: - + >>> Entry.objects.none() [] @@ -610,7 +610,7 @@ follow:: c = p.hometown # Requires a database call. The ``depth`` argument is new in the Django development version. - + ``extra(select=None, where=None, params=None, tables=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1136,7 +1136,7 @@ such as January 3, July 3, etc. isnull ~~~~~~ -Takes either ``True`` or ``False``, which correspond to SQL queries of +Takes either ``True`` or ``False``, which correspond to SQL queries of ``IS NULL`` and ``IS NOT NULL``, respectively. Example:: @@ -1149,10 +1149,10 @@ SQL equivalent:: .. admonition:: ``__isnull=True`` vs ``__exact=None`` - There is an important difference between ``__isnull=True`` and + There is an important difference between ``__isnull=True`` and ``__exact=None``. ``__exact=None`` will *always* return an empty result - set, because SQL requires that no value is equal to ``NULL``. - ``__isnull`` determines if the field is currently holding the value + set, because SQL requires that no value is equal to ``NULL``. + ``__isnull`` determines if the field is currently holding the value of ``NULL`` without performing a comparison. search @@ -1181,7 +1181,7 @@ The pk lookup shortcut ---------------------- For convenience, Django provides a ``pk`` lookup type, which stands for -"primary_key". +"primary_key". In the example ``Blog`` model, the primary key is the ``id`` field, so these three statements are equivalent:: @@ -1190,14 +1190,14 @@ three statements are equivalent:: Blog.objects.get(id=14) # __exact is implied Blog.objects.get(pk=14) # pk implies id__exact -The use of ``pk`` isn't limited to ``__exact`` queries -- any query term +The use of ``pk`` isn't limited to ``__exact`` queries -- any query term can be combined with ``pk`` to perform a query on the primary key of a model:: # Get blogs entries with id 1, 4 and 7 Blog.objects.filter(pk__in=[1,4,7]) # Get all blog entries with id > 14 - Blog.objects.filter(pk__gt=14) - + Blog.objects.filter(pk__gt=14) + ``pk`` lookups also work across joins. For example, these three statements are equivalent:: @@ -1754,19 +1754,19 @@ get_object_or_404() ------------------- One common idiom to use ``get()`` and raise ``Http404`` if the -object doesn't exist. This idiom is captured by ``get_object_or_404()``. -This function takes a Django model as its first argument and an -arbitrary number of keyword arguments, which it passes to the manager's +object doesn't exist. This idiom is captured by ``get_object_or_404()``. +This function takes a Django model as its first argument and an +arbitrary number of keyword arguments, which it passes to the manager's ``get()`` function. It raises ``Http404`` if the object doesn't -exist. For example:: - +exist. For example:: + # Get the Entry with a primary key of 3 e = get_object_or_404(Entry, pk=3) -When you provide a model to this shortcut function, the default manager -is used to execute the underlying ``get()`` query. If you don't want to -use the default manager, or you want to search a list of related objects, -you can provide ``get_object_or_404()`` with a manager object, instead. +When you provide a model to this shortcut function, the default manager +is used to execute the underlying ``get()`` query. If you don't want to +use the default manager, or if you want to search a list of related objects, +you can provide ``get_object_or_404()`` with a manager object instead. For example:: # Get the author of blog instance `e` with a name of 'Fred' @@ -1779,8 +1779,8 @@ For example:: get_list_or_404() ----------------- -``get_list_or_404`` behaves the same was as ``get_object_or_404()`` --- except the it uses using ``filter()`` instead of ``get()``. It raises +``get_list_or_404`` behaves the same way as ``get_object_or_404()`` +-- except that it uses ``filter()`` instead of ``get()``. It raises ``Http404`` if the list is empty. Falling back to raw SQL diff --git a/docs/model-api.txt b/docs/model-api.txt index 961269aebd..e7afbfd13a 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -1759,6 +1759,15 @@ But this template code is good:: {{ object.name }} +.. note:: + The string you return from ``get_absolute_url()`` must be use only ASCII + characters (required by the URI spec, `RFC 2396`_) that has been + URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` + should be able to use the result directly without needing to do any + further processing. + +.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt + The ``permalink`` decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index d9d4f53b88..2a03e6d5a6 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -146,7 +146,10 @@ put into those elements. exist, it tries calling a method ``item_link()`` in the ``Feed`` class, passing it a single parameter, ``item``, which is the object itself. Both ``get_absolute_url()`` and ``item_link()`` should return the item's - URL as a normal Python string. + URL as a normal Python string. As with ``get_absolute_url()``, the + result of ``item_link()`` will be included directly in the URL, so you + are responsible for doing all necessary URL quoting and conversion to + ASCII inside the method itself. * For the LatestEntries example above, we could have very simple feed templates: