Merge c79f4f5b3b into 8e082770b0

docs/topics/release-notes.md

@@ -24,6 +24,12 @@ The timeline for deprecation of a feature present in version 1.0 would work as f
 
 * Version 1.3 would remove the deprecated bits of API entirely.
 
+Deprecations are marked using `rest_framework.compat.deprecated`, which accepts a version tuple for the version when code is first deprecated and message to pass to the `warnings` module:
+
+    from rest_framework.compat import deprecated
+    ...
+    deprecated((3, 1), "Using X for Y is deprecated. Prefer Z")
+
 Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change.
 
 ## Upgrading

rest_framework/compat.py

@@ -6,6 +6,8 @@ versions of Django/Python, and compatibility wrappers around optional packages.
 # flake8: noqa
 from __future__ import unicode_literals
 
+import warnings
+
 import django
 from django.conf import settings
 from django.db import connection, transaction
@@ -13,6 +15,34 @@ from django.template import Context, RequestContext, Template
 from django.utils import six
 from django.views.generic import View
 
+import rest_framework
+
+
+def deprecated(since, message):
+    """
+    Issue a deprecation warning `message`. `since` is a tuple of major, minor
+    indicating when the deprecation should start.
+    """
+    current_version = [int(i) for i in rest_framework.VERSION.split('.')]
+
+    major_message = (
+        "Deprecated code must be removed before major version change. "
+        "Current: {0} vs Deprecated Since: {1}".format(
+            current_version[0], since[0])
+    )
+    minor_message = "Deprecated code must be removed within two minor versions"
+
+    assert current_version[0] == since[0], major_message
+
+    minor_version_difference = current_version[1] - since[1]
+    assert minor_version_difference in [1, 2], minor_message
+
+    warning_type = DeprecationWarning
+    if minor_version_difference == 1:
+        warning_type = PendingDeprecationWarning
+    warnings.warn(message, warning_type)
+
+
 try:
     import importlib  # Available in Python 3.1+
 except ImportError: