Refs #18974 -- Deprecated @models.permalink() decorator.

4 files changed, 55 insertions, 14 deletions

diff --git a/django/db/models/__init__.py b/django/db/models/__init__.py
index 2ce935d3f8..3ea2891675 100644
--- a/django/db/models/__init__.py
+++ b/django/db/models/__init__.py
@@ -1,5 +1,3 @@
-from functools import wraps
-
 from django.core.exceptions import ObjectDoesNotExist  # NOQA
 from django.db.models import signals  # NOQA
 from django.db.models.aggregates import *  # NOQA
@@ -37,7 +35,17 @@ def permalink(func):
         (viewname, viewargs)
         (viewname, viewargs, viewkwargs)
     """
+    import warnings
+    from functools import wraps
+
     from django.urls import reverse
+    from django.utils.deprecation import RemovedInDjango21Warning
+
+    warnings.warn(
+        'permalink() is deprecated in favor of calling django.urls.reverse() '
+        'in the decorated method.',
+        RemovedInDjango21Warning
+    )
 
     @wraps(func)
     def inner(*args, **kwargs):
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index a1c55646d0..a7ef1b8be5 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -41,6 +41,8 @@ details on these changes.
 * The ``authenticate()`` method of authentication backends will require a
   ``request`` argument.
 
+* The ``django.db.models.permalink()`` decorator will be removed.
+
 .. _deprecation-removed-in-2.0:
 
 2.0
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 96fb2e4ae9..142eb4e9ba 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -554,6 +554,31 @@ Miscellaneous
 Features deprecated in 1.11
 ===========================
 
+``models.permalink()`` decorator
+--------------------------------
+
+Use :func:`django.urls.reverse` instead. For example::
+
+    from django.db import models
+
+    class MyModel(models.Model):
+        ...
+
+        @models.permalink
+        def url(self):
+            return ('guitarist_detail', [self.slug])
+
+becomes::
+
+    from django.db import models
+    from django.urls import reverse
+
+    class MyModel(models.Model):
+        ...
+
+        def url(self):
+            return reverse('guitarist_detail', args=[self.slug])
+
 Miscellaneous
 -------------
 
diff --git a/tests/model_permalink/models.py b/tests/model_permalink/models.py
index dacf2a3fb3..9074837a8b 100644
--- a/tests/model_permalink/models.py
+++ b/tests/model_permalink/models.py
@@ -1,4 +1,7 @@
+import warnings
+
 from django.db import models
+from django.utils.deprecation import RemovedInDjango21Warning
 
 
 def set_attr(name, value):
@@ -8,17 +11,20 @@ def set_attr(name, value):
     return wrapper
 
 
-class Guitarist(models.Model):
-    name = models.CharField(max_length=50)
-    slug = models.CharField(max_length=50)
+with warnings.catch_warnings():
+    warnings.simplefilter('ignore', category=RemovedInDjango21Warning)
+
+    class Guitarist(models.Model):
+        name = models.CharField(max_length=50)
+        slug = models.CharField(max_length=50)
 
-    @models.permalink
-    def url(self):
-        "Returns the URL for this guitarist."
-        return ('guitarist_detail', [self.slug])
+        @models.permalink
+        def url(self):
+            "Returns the URL for this guitarist."
+            return ('guitarist_detail', [self.slug])
 
-    @models.permalink
-    @set_attr('attribute', 'value')
-    def url_with_attribute(self):
-        "Returns the URL for this guitarist and holds an attribute"
-        return ('guitarist_detail', [self.slug])
+        @models.permalink
+        @set_attr('attribute', 'value')
+        def url_with_attribute(self):
+            "Returns the URL for this guitarist and holds an attribute"
+            return ('guitarist_detail', [self.slug])