Clarify deprecation warning of pagination classes

Author: Oliver Sauder

CHANGELOG.md

@@ -16,7 +16,6 @@ any parts of the framework not mentioned in the documentation should generally b
 * Add `HyperlinkedRelatedField` and `SerializerMethodHyperlinkedRelatedField`. See [usage docs](docs/usage.md#related-fields)
 * Add related urls support. See [usage docs](docs/usage.md#related-urls)
 * Add optional [jsonapi-style](http://jsonapi.org/format/) filter backends. See [usage docs](docs/usage.md#filter-backends)
-* Performance improvement when rendering relationships with `ModelSerializer`
 
 ### Changed
 
@@ -25,6 +24,8 @@ any parts of the framework not mentioned in the documentation should generally b
 ### Fixed
 
 * Performance improvement when rendering relationships with `ModelSerializer`
+* Do not show deprecation warning when user has implemented custom pagination class overwriting default values.
+
 
 ## [2.5.0] - 2018-07-11
 
@@ -41,6 +42,16 @@ any parts of the framework not mentioned in the documentation should generally b
 ### Deprecated
 
 * Deprecate `PageNumberPagination` and `LimitOffsetPagination`. Use `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination` instead.
+  * To retain deprecated values for `PageNumberPagination` and `LimitOffsetPagination` create new custom class like the following in your code base:
+  ```python
+  class CustomPageNumberPagination(PageNumberPagination):
+    page_query_param = "page"
+    page_size_query_param = "page_size"
+
+  class CustomLimitOffsetPagination(LimitOffsetPagination):
+    max_limit = None
+  ```
+  and adjust `REST_FRAMEWORK['DEFAULT_PAGINATION_CLASS']` setting accordingly.
 * Deprecate `JSON_API_FORMAT_KEYS`, use `JSON_API_FORMAT_FIELD_NAMES`.
 
 ### Fixed

docs/usage.md

@@ -60,8 +60,7 @@ by setting `REST_FRAMEWORK['DEFAULT_PAGINATION_CLASS']` and by setting `REST_FRA
 You can configure fixed values for the page size or limit -- or allow the client to choose the size or limit
 via query parameters.
 
-Two pagination classes are available *but their names will change in release 3.0 in order to implement a more
-consistent class naming style*:
+Two pagination classes are available:
 - `JsonApiPageNumberPagination` breaks a response up into pages that start at a given page number with a given size 
   (number of items per page). It can be configured with the following attributes:
   - `page_query_param` (default `page[number]`)
@@ -82,22 +81,6 @@ consistent class naming style*:
   - `max_limit` (default `100`) enforces an upper bound on the limit.
      Set it to `None` if you don't want to enforce an upper bound.
 
-##### Preparing for future renaming of paginators with default attributes
-
-In release 3.0, the `JsonApi` prefix will be removed from the paginator names. If you currently use those (deprecated)
-names (`PageNumberPagination` or `LimitOffsetPagination`) or would like to prepare now for this change, you will want to
-explicitly override several of the class attributes.
-
-To retain deprecated values for `PageNumberPagination` set `page_query_param = "page"` and
-`page_size_query_param = "page_size"`.
-
-To prepare for the renaming of `JsonApiPageNumberPagination` use `PageNumberPagination` now with
-`page_query_param = "page[number]"` and `page_size_query_param = "page[size]"`.
-
-To retain deprecated vales for `LimitOffsetPagination` set `max_limit = None`.
-
-To prepare for the renaming of `JsonApiLimitOffsetPagination` to `LimitOffsetPagination` set `max_limit = 100`.
-
 ##### Examples
 These examples show how to configure the parameters to use non-standard names and different limits:
 

example/tests/unit/test_pagination.py

@@ -82,19 +82,10 @@ def test_valid_offset_limit(self):
     @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
                        reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
     def test_limit_offset_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
+        with pytest.warns(DeprecationWarning) as record:
             pagination.LimitOffsetPagination()
         assert len(record) == 1
-        assert 'LimitOffsetPagination will change in release 3.0' in str(record[0].message)
-
-    @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
-                       reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
-    def test_jsonapi_limit_offset_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
-            pagination.JsonApiLimitOffsetPagination()
-        assert len(record) == 1
-        assert 'JsonApiLimitOffsetPagination will be renamed to LimitOffsetPagination'\
-               in str(record[0].message)
+        assert 'LimitOffsetPagination is deprecated' in str(record[0].message)
 
     class MyInheritedLimitOffsetPagination(pagination.LimitOffsetPagination):
         """
@@ -109,10 +100,10 @@ class MyOverridenLimitOffsetPagination(pagination.LimitOffsetPagination):
         max_limit = None
 
     def test_my_limit_offset_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
+        with pytest.warns(DeprecationWarning) as record:
             self.MyInheritedLimitOffsetPagination()
         assert len(record) == 1
-        assert 'LimitOffsetPagination will change in release 3.0' in str(record[0].message)
+        assert 'LimitOffsetPagination is deprecated' in str(record[0].message)
 
         with pytest.warns(None) as record:
             self.MyOverridenLimitOffsetPagination()
@@ -127,19 +118,10 @@ class TestPageNumber:
     @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
                        reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
     def test_page_number_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
+        with pytest.warns(DeprecationWarning) as record:
             pagination.PageNumberPagination()
         assert len(record) == 1
-        assert 'PageNumberPagination will change in release 3.0' in str(record[0].message)
-
-    @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
-                       reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
-    def test_jsonapi_page_number_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
-            pagination.JsonApiPageNumberPagination()
-        assert len(record) == 1
-        assert 'JsonApiPageNumberPagination will be renamed to PageNumberPagination' \
-               in str(record[0].message)
+        assert 'PageNumberPagination is deprecated' in str(record[0].message)
 
     class MyInheritedPageNumberPagination(pagination.PageNumberPagination):
         """
@@ -157,20 +139,11 @@ class MyOverridenPageNumberPagination(pagination.PageNumberPagination):
     @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
                        reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
     def test_my_page_number_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
+        with pytest.warns(DeprecationWarning) as record:
             self.MyInheritedPageNumberPagination()
         assert len(record) == 1
-        assert 'PageNumberPagination will change in release 3.0' in str(record[0].message)
+        assert 'PageNumberPagination is deprecated' in str(record[0].message)
 
         with pytest.warns(None) as record:
             self.MyOverridenPageNumberPagination()
         assert len(record) == 0
-
-    @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
-                       reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
-    def test_my_jsonapi_page_number_deprecation(self):
-        with pytest.warns(PendingDeprecationWarning) as record:
-            pagination.JsonApiPageNumberPagination()
-        assert len(record) == 1
-        assert 'JsonApiPageNumberPagination will be renamed to PageNumberPagination' \
-               in str(record[0].message)

rest_framework_json_api/pagination.py

@@ -9,7 +9,7 @@
 from rest_framework.views import Response
 
 
-class _JsonApiPageNumberPagination(PageNumberPagination):
+class JsonApiPageNumberPagination(PageNumberPagination):
     """
     A json-api compatible pagination format.
     Use a private name for the implementation because the public name is pending deprecation.
@@ -51,21 +51,7 @@ def get_paginated_response(self, data):
         })
 
 
-class JsonApiPageNumberPagination(_JsonApiPageNumberPagination):
-    """
-    current public name to be deprecated soon.
-    """
-    def __init__(self):
-        if type(self) == JsonApiPageNumberPagination:
-            warnings.warn(
-                'JsonApiPageNumberPagination will be renamed to PageNumberPagination in'
-                ' release 3.0. See '
-                'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',  # noqa: E501
-                PendingDeprecationWarning)
-        super(_JsonApiPageNumberPagination, self).__init__()
-
-
-class _JsonApiLimitOffsetPagination(LimitOffsetPagination):
+class JsonApiLimitOffsetPagination(LimitOffsetPagination):
     """
     A limit/offset based style. For example:
     http://api.example.org/accounts/?page[limit]=100
@@ -117,22 +103,7 @@ def get_paginated_response(self, data):
         })
 
 
-class JsonApiLimitOffsetPagination(_JsonApiLimitOffsetPagination):
-    """
-    current public name to be deprecated soon.
-    """
-
-    def __init__(self):
-        warnings.warn(
-            'JsonApiLimitOffsetPagination will be renamed to LimitOffsetPagination in release 3.0'
-            ' See '
-            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
-            PendingDeprecationWarning)
-        super(JsonApiLimitOffsetPagination, self).__init__()
-
-
-
-class PageNumberPagination(_JsonApiPageNumberPagination):
+class PageNumberPagination(JsonApiPageNumberPagination):
     """
     A soon-to-be-changed paginator that uses non-JSON:API query parameters (default:
     'page' and 'page_size' instead of 'page[number]' and 'page[size]').
@@ -148,18 +119,17 @@ def __init__(self):
                     'page_size_query_param' not in type(self).__dict__)
         if warn:
             warnings.warn(
-                'PageNumberPagination will change in release 3.0 to change default values to: '
-                '`page_query_param = "page[number]"` and `page_size_query_param = "page[size]"`. '
-                'If you want to retain the current defaults you will need to explicitly set '
-                '`page_query_param = "page"` and `page_size_query_param = "page_size"`. '
-                'See '
-                'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',  # noqa: E501
-                PendingDeprecationWarning)
+                'PageNumberPagination is deprecated use JsonApiPageNumberPagination instead. '
+                'If you want to retain current defaults you will need to implement custom '
+                'pagination class explicitly setting `page_query_param = "page"` and '
+                '`page_size_query_param = "page_size"`. '
+                'See changelog for more details.',
+                DeprecationWarning)
 
         super(PageNumberPagination, self).__init__()
 
 
-class LimitOffsetPagination(_JsonApiLimitOffsetPagination):
+class LimitOffsetPagination(JsonApiLimitOffsetPagination):
     """
     Deprecated paginator that uses a different max_limit
     """
@@ -172,10 +142,9 @@ def __init__(self):
             warn = 'max_limit' not in type(self).__dict__
         if warn:
             warnings.warn(
-                'LimitOffsetPagination will change in release 3.0 to default to `max_limit=100`. '
-                'If you want to retain the current default you will need to explicitly set '
-                '`max_limit = None`.'
-                'See '
-                'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',  # noqa: E501
-                PendingDeprecationWarning)
+                'LimitOffsetPagination is deprecated use JsonApiLimitOffsetPagination instead. '
+                'If you want to retain current defaults you will need to implement custom '
+                'pagination class explicitly setting `max_limit = None`. '
+                'See changelog for more details.',
+                DeprecationWarning)
         super(LimitOffsetPagination, self).__init__()