JSONAPI prefix for paginators

CHANGELOG.md

@@ -5,6 +5,8 @@
 * Add related urls support. See [usage docs](docs/usage.md#related-urls)
 * Replaced binary `drf_example` sqlite3 db with a [fixture](example/fixtures/drf_example.yaml). See [usage docs](docs/usage.md#running-the-example-app).
 * Add optional [jsonapi-style](http://jsonapi.org/format/) sort filter backend. See [usage docs](docs/usage.md#filter-backends)
+* For naming consistency, renamed new `JsonApi`-prefix pagination classes to `JSONAPI`-prefix.
+  * Deprecates `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination`
 
 v2.5.0 - Released July 11, 2018
 

README.rst

@@ -161,7 +161,7 @@ override ``settings.REST_FRAMEWORK``
         'PAGE_SIZE': 10,
         'EXCEPTION_HANDLER': 'rest_framework_json_api.exceptions.exception_handler',
         'DEFAULT_PAGINATION_CLASS':
-            'rest_framework_json_api.pagination.JsonApiPageNumberPagination',
+            'rest_framework_json_api.pagination.JSONAPIPageNumberPagination',
         'DEFAULT_PARSER_CLASSES': (
             'rest_framework_json_api.parsers.JSONParser',
             'rest_framework.parsers.FormParser',

docs/usage.md

@@ -16,7 +16,7 @@ REST_FRAMEWORK = {
     'PAGE_SIZE': 10,
     'EXCEPTION_HANDLER': 'rest_framework_json_api.exceptions.exception_handler',
     'DEFAULT_PAGINATION_CLASS':
-        'rest_framework_json_api.pagination.JsonApiPageNumberPagination',
+        'rest_framework_json_api.pagination.JSONAPIPageNumberPagination',
     'DEFAULT_PARSER_CLASSES': (
         'rest_framework_json_api.parsers.JSONParser',
         'rest_framework.parsers.FormParser',
@@ -58,15 +58,15 @@ You can configure fixed values for the page size or limit -- or allow the client
 via query parameters.
 
 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:
+- `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]`)
   - `page_size_query_param` (default `page[size]`) Set this to `None` if you don't want to allow the client 
      to specify the size.
   - `max_page_size` (default `100`) enforces an upper bound on the `page_size_query_param`.
      Set it to `None` if you don't want to enforce an upper bound.
-- `JsonApiLimitOffsetPagination` breaks a response up into pages that start from an item's offset in the viewset for 
-  a given number of items (the limit).
+- `JSONAPILimitOffsetPagination` breaks a response up into pages that start from an item's offset
+  in the viewset for a given number of items (the limit).
   It can be configured with the following attributes:
   - `offset_query_param` (default `page[offset]`).
   - `limit_query_param` (default `page[limit]`).
@@ -77,14 +77,14 @@ Two pagination classes are available:
 These examples show how to configure the parameters to use non-standard names and different limits:
 
 ```python
-from rest_framework_json_api.pagination import JsonApiPageNumberPagination, JsonApiLimitOffsetPagination
+from rest_framework_json_api.pagination import JSONAPIPageNumberPagination, JSONAPILimitOffsetPagination
 
-class MyPagePagination(JsonApiPageNumberPagination):
+class MyPagePagination(JSONAPIPageNumberPagination):
     page_query_param = 'page_number'
     page_size_query_param = 'page_size'
     max_page_size = 1000
 
-class MyLimitPagination(JsonApiLimitOffsetPagination):
+class MyLimitPagination(JSONAPILimitOffsetPagination):
     offset_query_param = 'offset'
     limit_query_param = 'limit'
     max_limit = None

example/tests/unit/test_pagination.py

@@ -13,11 +13,11 @@
 
 class TestLimitOffset:
     """
-    Unit tests for `pagination.JsonApiLimitOffsetPagination`.
+    Unit tests for `pagination.JSONAPILimitOffsetPagination`.
     """
 
     def setup(self):
-        class ExamplePagination(pagination.JsonApiLimitOffsetPagination):
+        class ExamplePagination(pagination.JSONAPILimitOffsetPagination):
             default_limit = 10
             max_limit = 15
 
@@ -85,17 +85,27 @@ def test_limit_offset_deprecation(self):
         assert len(record) == 1
         assert 'LimitOffsetPagination' in str(record[0].message)
 
+        with pytest.warns(DeprecationWarning) as record:
+            pagination.JsonApiLimitOffsetPagination()
+        assert len(record) == 1
+        assert 'JsonApiLimitOffsetPagination' in str(record[0].message)
+
 
 # TODO: This test fails under py27 but it's not clear why so just leave it out for now.
 @pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
                    reason="python2.7 fails for unknown reason")
 class TestPageNumber:
     """
-    Unit tests for `pagination.JsonApiPageNumberPagination`.
+    Unit tests for `pagination.JSONAPIPageNumberPagination`.
     TODO: add unit tests for changing query parameter names, limits, etc.
     """
     def test_page_number_deprecation(self):
         with pytest.warns(DeprecationWarning) as record:
             pagination.PageNumberPagination()
         assert len(record) == 1
         assert 'PageNumberPagination' in str(record[0].message)
+
+        with pytest.warns(DeprecationWarning) as record:
+            pagination.JsonApiPageNumberPagination()
+        assert len(record) == 1
+        assert 'JsonApiPageNumberPagination' in str(record[0].message)

example/views.py

@@ -34,7 +34,7 @@ def get_object(self):
         return super(BlogViewSet, self).get_object()
 
 
-class JsonApiViewSet(ModelViewSet):
+class JSONAPIViewSet(ModelViewSet):
     """
     This is an example on how to configure DRF-jsonapi from
     within a class. It allows using DRF-jsonapi alongside
@@ -58,12 +58,12 @@ def handle_exception(self, exc):
             exc.status_code = HTTP_422_UNPROCESSABLE_ENTITY
         # exception handler can't be set on class so you have to
         # override the error response in this method
-        response = super(JsonApiViewSet, self).handle_exception(exc)
+        response = super(JSONAPIViewSet, self).handle_exception(exc)
         context = self.get_exception_handler_context()
         return format_drf_errors(response, context, exc)
 
 
-class BlogCustomViewSet(JsonApiViewSet):
+class BlogCustomViewSet(JSONAPIViewSet):
     queryset = Blog.objects.all()
     serializer_class = BlogSerializer
 

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
     """
@@ -50,7 +50,7 @@ def get_paginated_response(self, data):
         })
 
 
-class JsonApiLimitOffsetPagination(LimitOffsetPagination):
+class JSONAPILimitOffsetPagination(LimitOffsetPagination):
     """
     A limit/offset based style. For example:
     http://api.example.org/accounts/?page[limit]=100
@@ -100,7 +100,23 @@ def get_paginated_response(self, data):
         })
 
 
-class PageNumberPagination(JsonApiPageNumberPagination):
+class JsonApiPageNumberPagination(JSONAPIPageNumberPagination):
+    """
+    Deprecated due to desire to use `JSONAPI` prefix for all classes.
+    """
+    page_query_param = 'page'
+    page_size_query_param = 'page_size'
+
+    def __init__(self):
+        warnings.warn(
+            'JsonApiPageNumberPagination is deprecated. Use JSONAPIPageNumberPagination '
+            'or create custom pagination. See '
+            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
+            DeprecationWarning)
+        super(JsonApiPageNumberPagination, self).__init__()
+
+
+class PageNumberPagination(JSONAPIPageNumberPagination):
     """
     Deprecated paginator that uses different query parameters
     """
@@ -109,22 +125,37 @@ class PageNumberPagination(JsonApiPageNumberPagination):
 
     def __init__(self):
         warnings.warn(
-            'PageNumberPagination is deprecated. Use JsonApiPageNumberPagination '
+            'PageNumberPagination is deprecated. Use JSONAPIPageNumberPagination '
             'or create custom pagination. See '
             'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
             DeprecationWarning)
         super(PageNumberPagination, self).__init__()
 
 
-class LimitOffsetPagination(JsonApiLimitOffsetPagination):
+class JsonApiLimitOffsetPagination(JSONAPILimitOffsetPagination):
+    """
+    Deprecated due to desire to use `JSONAPI` prefix for all classes.
+    """
+    max_limit = None
+
+    def __init__(self):
+        warnings.warn(
+            'JsonApiLimitOffsetPagination is deprecated. Use JSONAPILimitOffsetPagination '
+            'or create custom pagination. See '
+            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
+            DeprecationWarning)
+        super(JsonApiLimitOffsetPagination, self).__init__()
+
+
+class LimitOffsetPagination(JSONAPILimitOffsetPagination):
     """
     Deprecated paginator that uses a different max_limit
     """
     max_limit = None
 
     def __init__(self):
         warnings.warn(
-            'LimitOffsetPagination is deprecated. Use JsonApiLimitOffsetPagination '
+            'LimitOffsetPagination is deprecated. Use JSONAPILimitOffsetPagination '
             'or create custom pagination. See '
             'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
             DeprecationWarning)