Ticket #18974: 18974.diff

File 18974.diff, 7.4 KB (added by Tim Graham, 12 years ago)

Docs only patch

  • docs/ref/models/instances.txt

    diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
    index 1d0ac08..4d717aa 100644
    a b For example::  
    482482        return "/people/%i/" % self.id
    483483
    484484(Whilst this code is correct and simple, it may not be the most portable way to
    485 write this kind of method. The :func:`permalink() decorator <permalink>`,
    486 documented below, is usually the best approach and you should read that section
    487 before diving into code implementation.)
     485write this kind of method. The :func:`~django.core.urlresolvers.reverse`
     486function is usually the best approach.)
     487
     488For example::
     489
     490    def get_absolute_url(self):
     491        return reverse('people.views.details', args=[str(self.id)])
    488492
    489493One place Django uses ``get_absolute_url()`` is in the admin app. If an object
    490494defines this method, the object-editing page will have a "View on site" link
    in ``get_absolute_url()`` and have all your other code call that one place.  
    529533The ``permalink`` decorator
    530534~~~~~~~~~~~~~~~~~~~~~~~~~~~
    531535
    532 The way we wrote ``get_absolute_url()`` above is a slightly violation of the
    533 DRY principle: the URL for this object is defined both in the URLconf file and
    534 in the model.
     536.. warning::
     537
     538    The ``permalink`` decorator is no longer recommended. You should use
     539    :func:`~django.core.urlresolvers.reverse` in the body of your
     540    ``get_absolute_url`` method instead.
    535541
    536 You can decouple your models from the URLconf using the ``permalink`` decorator:
     542In early versions of Django, there wasn't an easy way to use URLs defined in
     543URLconf file inside :meth:`~django.db.models.Model.get_absolute_url()`. That
     544meant you would need to define the URL both in URLConf and
     545:meth:`~django.db.models.Model.get_absolute_url()`. The ``permalink`` decorator
     546was added to overcome this DRY principle violation. However, since the
     547introduction of :func:`~django.core.urlresolvers.reverse` there is no
     548reason to use ``permalink`` any more.
    537549
    538550.. function:: permalink()
    539551
    correct URL, with all parameters substituted in the correct positions.  
    544556
    545557The ``permalink`` decorator is a Python-level equivalent to the :ttag:`url`
    546558template tag and a high-level wrapper for the
    547 :func:`django.core.urlresolvers.reverse()` function.
     559:func:`~django.core.urlresolvers.reverse` function.
    548560
    549561An example should make it clear how to use ``permalink()``. Suppose your URLconf
    550562contains a line such as::
  • docs/ref/unicode.txt

    diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
    index ffab647..784ff33 100644
    a b Taking care in ``get_absolute_url()``  
    262262
    263263URLs can only contain ASCII characters. If you're constructing a URL from
    264264pieces of data that might be non-ASCII, be careful to encode the results in a
    265 way that is suitable for a URL. The ``django.db.models.permalink()`` decorator
    266 handles this for you automatically.
     265way that is suitable for a URL. The :func:`~django.core.urlresolvers.reverse`
     266function handles this for you automatically.
    267267
    268 If you're constructing a URL manually (i.e., *not* using the ``permalink()``
    269 decorator), you'll need to take care of the encoding yourself. In this case,
     268If you're constructing a URL manually (i.e., *not* using the ``reverse()``
     269function), you'll need to take care of the encoding yourself. In this case,
    270270use the ``iri_to_uri()`` and ``urlquote()`` functions that were documented
    271271above_. For example::
    272272
  • docs/ref/urlresolvers.txt

    diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt
    index 1bb33c7..528f172 100644
    a b whether a view would raise a ``Http404`` error before redirecting to it::  
    178178            return HttpResponseRedirect('/')
    179179        return response
    180180
    181 
    182 permalink()
    183 -----------
    184 
    185 The :func:`~django.db.models.permalink` decorator is useful for writing short
    186 methods that return a full URL path. For example, a model's
    187 ``get_absolute_url()`` method. See :func:`django.db.models.permalink` for more.
    188 
    189181get_script_prefix()
    190182-------------------
    191183
    192184.. function:: get_script_prefix()
    193185
    194 Normally, you should always use :func:`~django.core.urlresolvers.reverse` or
    195 :func:`~django.db.models.permalink` to define URLs within your application.
    196 However, if your application constructs part of the URL hierarchy itself, you
    197 may occasionally need to generate URLs. In that case, you need to be able to
    198 find the base URL of the Django project within its Web server
    199 (normally, :func:`~django.core.urlresolvers.reverse` takes care of this for
    200 you). In that case, you can call ``get_script_prefix()``, which will return the
    201 script prefix portion of the URL for your Django project. If your Django
    202 project is at the root of its Web server, this is always ``"/"``.
     186Normally, you should always use :func:`~django.core.urlresolvers.reverse` to
     187define URLs within your application. However, if your application constructs
     188part of the URL hierarchy itself, you may occasionally need to generate URLs.
     189In that case, you need to be able to find the base URL of the Django project
     190within its Web server (normally, :func:`~django.core.urlresolvers.reverse`
     191takes care of this for you). In that case, you can call
     192``get_script_prefix()``, which will return the script prefix portion of the URL
     193for your Django project. If your Django project is at the root of its web
     194server, this is always ``"/"``.
  • docs/topics/http/urls.txt

    diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
    index e178df2..0b856b0 100644
    a b layers where URLs are needed:  
    556556  function.
    557557
    558558* In higher level code related to handling of URLs of Django model instances:
    559   The :meth:`django.db.models.Model.get_absolute_url()` method and the
    560   :func:`django.db.models.permalink` decorator.
     559  The :meth:`~django.db.models.Model.get_absolute_url()` method.
    561560
    562561Examples
    563562--------
    view::  
    622621    )
    623622
    624623This is completely valid, but it leads to problems when you try to do reverse
    625 URL matching (through the :func:`~django.db.models.permalink` decorator or the
    626 :ttag:`url` template tag). Continuing this example, if you wanted to retrieve
    627 the URL for the ``archive`` view, Django's reverse URL matcher would get
    628 confused, because *two* URL patterns point at that view.
     624URL matching (through the :func:`~django.core.urlresolvers.reverse()` function
     625or the :ttag:`url` template tag). Continuing this example, if you wanted to
     626retrieve the URL for the ``archive`` view, Django's reverse URL matcher would
     627get confused, because *two* URL patterns point at that view.
    629628
    630629To solve this problem, Django supports **named URL patterns**. That is, you can
    631630give a name to a URL pattern in order to distinguish it from other patterns
  • tests/regressiontests/generic_views/models.py

    diff --git a/tests/regressiontests/generic_views/models.py b/tests/regressiontests/generic_views/models.py
    index f59389e..30c73d6 100644
    a b  
     1from django.core.urlresolvers import reverse
    12from django.db import models
    23from django.utils.encoding import python_2_unicode_compatible
    34
    class Artist(models.Model):  
    1415    def __str__(self):
    1516        return self.name
    1617
    17     @models.permalink
    1818    def get_absolute_url(self):
    19         return ('artist_detail', (), {'pk': self.id})
     19        return reverse('artist_detail', kwargs={'pk': self.id})
    2020
    2121@python_2_unicode_compatible
    2222class Author(models.Model):
Back to Top