Code

Ticket #18974: 18974.diff

File 18974.diff, 7.4 KB (added by timo, 17 months ago)

Docs only patch

Line 
1diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
2index 1d0ac08..4d717aa 100644
3--- a/docs/ref/models/instances.txt
4+++ b/docs/ref/models/instances.txt
5@@ -482,9 +482,13 @@ For example::
6         return "/people/%i/" % self.id
7 
8 (Whilst this code is correct and simple, it may not be the most portable way to
9-write this kind of method. The :func:`permalink() decorator <permalink>`,
10-documented below, is usually the best approach and you should read that section
11-before diving into code implementation.)
12+write this kind of method. The :func:`~django.core.urlresolvers.reverse`
13+function is usually the best approach.)
14+
15+For example::
16+
17+    def get_absolute_url(self):
18+        return reverse('people.views.details', args=[str(self.id)])
19 
20 One place Django uses ``get_absolute_url()`` is in the admin app. If an object
21 defines this method, the object-editing page will have a "View on site" link
22@@ -529,11 +533,19 @@ in ``get_absolute_url()`` and have all your other code call that one place.
23 The ``permalink`` decorator
24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
25 
26-The way we wrote ``get_absolute_url()`` above is a slightly violation of the
27-DRY principle: the URL for this object is defined both in the URLconf file and
28-in the model.
29+.. warning::
30+
31+    The ``permalink`` decorator is no longer recommended. You should use
32+    :func:`~django.core.urlresolvers.reverse` in the body of your
33+    ``get_absolute_url`` method instead.
34 
35-You can decouple your models from the URLconf using the ``permalink`` decorator:
36+In early versions of Django, there wasn't an easy way to use URLs defined in
37+URLconf file inside :meth:`~django.db.models.Model.get_absolute_url()`. That
38+meant you would need to define the URL both in URLConf and
39+:meth:`~django.db.models.Model.get_absolute_url()`. The ``permalink`` decorator
40+was added to overcome this DRY principle violation. However, since the
41+introduction of :func:`~django.core.urlresolvers.reverse` there is no
42+reason to use ``permalink`` any more.
43 
44 .. function:: permalink()
45 
46@@ -544,7 +556,7 @@ correct URL, with all parameters substituted in the correct positions.
47 
48 The ``permalink`` decorator is a Python-level equivalent to the :ttag:`url`
49 template tag and a high-level wrapper for the
50-:func:`django.core.urlresolvers.reverse()` function.
51+:func:`~django.core.urlresolvers.reverse` function.
52 
53 An example should make it clear how to use ``permalink()``. Suppose your URLconf
54 contains a line such as::
55diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
56index ffab647..784ff33 100644
57--- a/docs/ref/unicode.txt
58+++ b/docs/ref/unicode.txt
59@@ -262,11 +262,11 @@ Taking care in ``get_absolute_url()``
60 
61 URLs can only contain ASCII characters. If you're constructing a URL from
62 pieces of data that might be non-ASCII, be careful to encode the results in a
63-way that is suitable for a URL. The ``django.db.models.permalink()`` decorator
64-handles this for you automatically.
65+way that is suitable for a URL. The :func:`~django.core.urlresolvers.reverse`
66+function handles this for you automatically.
67 
68-If you're constructing a URL manually (i.e., *not* using the ``permalink()``
69-decorator), you'll need to take care of the encoding yourself. In this case,
70+If you're constructing a URL manually (i.e., *not* using the ``reverse()``
71+function), you'll need to take care of the encoding yourself. In this case,
72 use the ``iri_to_uri()`` and ``urlquote()`` functions that were documented
73 above_. For example::
74 
75diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt
76index 1bb33c7..528f172 100644
77--- a/docs/ref/urlresolvers.txt
78+++ b/docs/ref/urlresolvers.txt
79@@ -178,25 +178,17 @@ whether a view would raise a ``Http404`` error before redirecting to it::
80             return HttpResponseRedirect('/')
81         return response
82 
83-
84-permalink()
85------------
86-
87-The :func:`~django.db.models.permalink` decorator is useful for writing short
88-methods that return a full URL path. For example, a model's
89-``get_absolute_url()`` method. See :func:`django.db.models.permalink` for more.
90-
91 get_script_prefix()
92 -------------------
93 
94 .. function:: get_script_prefix()
95 
96-Normally, you should always use :func:`~django.core.urlresolvers.reverse` or
97-:func:`~django.db.models.permalink` to define URLs within your application.
98-However, if your application constructs part of the URL hierarchy itself, you
99-may occasionally need to generate URLs. In that case, you need to be able to
100-find the base URL of the Django project within its Web server
101-(normally, :func:`~django.core.urlresolvers.reverse` takes care of this for
102-you). In that case, you can call ``get_script_prefix()``, which will return the
103-script prefix portion of the URL for your Django project. If your Django
104-project is at the root of its Web server, this is always ``"/"``.
105+Normally, you should always use :func:`~django.core.urlresolvers.reverse` to
106+define URLs within your application. However, if your application constructs
107+part of the URL hierarchy itself, you may occasionally need to generate URLs.
108+In that case, you need to be able to find the base URL of the Django project
109+within its Web server (normally, :func:`~django.core.urlresolvers.reverse`
110+takes care of this for you). In that case, you can call
111+``get_script_prefix()``, which will return the script prefix portion of the URL
112+for your Django project. If your Django project is at the root of its web
113+server, this is always ``"/"``.
114diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
115index e178df2..0b856b0 100644
116--- a/docs/topics/http/urls.txt
117+++ b/docs/topics/http/urls.txt
118@@ -556,8 +556,7 @@ layers where URLs are needed:
119   function.
120 
121 * In higher level code related to handling of URLs of Django model instances:
122-  The :meth:`django.db.models.Model.get_absolute_url()` method and the
123-  :func:`django.db.models.permalink` decorator.
124+  The :meth:`~django.db.models.Model.get_absolute_url()` method.
125 
126 Examples
127 --------
128@@ -622,10 +621,10 @@ view::
129     )
130 
131 This is completely valid, but it leads to problems when you try to do reverse
132-URL matching (through the :func:`~django.db.models.permalink` decorator or the
133-:ttag:`url` template tag). Continuing this example, if you wanted to retrieve
134-the URL for the ``archive`` view, Django's reverse URL matcher would get
135-confused, because *two* URL patterns point at that view.
136+URL matching (through the :func:`~django.core.urlresolvers.reverse()` function
137+or the :ttag:`url` template tag). Continuing this example, if you wanted to
138+retrieve the URL for the ``archive`` view, Django's reverse URL matcher would
139+get confused, because *two* URL patterns point at that view.
140 
141 To solve this problem, Django supports **named URL patterns**. That is, you can
142 give a name to a URL pattern in order to distinguish it from other patterns
143diff --git a/tests/regressiontests/generic_views/models.py b/tests/regressiontests/generic_views/models.py
144index f59389e..30c73d6 100644
145--- a/tests/regressiontests/generic_views/models.py
146+++ b/tests/regressiontests/generic_views/models.py
147@@ -1,3 +1,4 @@
148+from django.core.urlresolvers import reverse
149 from django.db import models
150 from django.utils.encoding import python_2_unicode_compatible
151 
152@@ -14,9 +15,8 @@ class Artist(models.Model):
153     def __str__(self):
154         return self.name
155 
156-    @models.permalink
157     def get_absolute_url(self):
158-        return ('artist_detail', (), {'pk': self.id})
159+        return reverse('artist_detail', kwargs={'pk': self.id})
160 
161 @python_2_unicode_compatible
162 class Author(models.Model):