revert JSONAPI prefix to JsonApi for paginators.

CHANGELOG.md

@@ -3,11 +3,9 @@
 * Add testing configuration to `REST_FRAMEWORK` configuration as described in [DRF](https://www.django-rest-framework.org/api-guide/testing/#configuration)
 * Add `HyperlinkedRelatedField` and `SerializerMethodHyperlinkedRelatedField`. See [usage docs](docs/usage.md#related-fields)
 * 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 [getting started](docs/getting-started.md#running-the-example-app).
-* For naming consistency, renamed new `JsonApi`-prefix pagination classes to `JSONAPI`-prefix.
-  * Deprecates `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination`
-* Performance improvement when rendering relationships with `ModelSerializer`
+* 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/) filter backends. See [usage docs](docs/usage.md#filter-backends)
+* Performance improvement when rendering relationships with `ModelSerializer`
 
 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',
@@ -50,6 +50,8 @@ DJA pagination is based on [DRF pagination](https://www.django-rest-framework.or
 When pagination is enabled, the renderer will return a `meta` object with
 record count and a `links` object with the next, previous, first, and last links.
 
+Optional query parameters can also be provided to customize the page size or offset limit.
+
 #### Configuring the Pagination Style
 
 Pagination style can be set on a particular viewset with the `pagination_class` attribute or by default for all viewsets
@@ -58,36 +60,45 @@ 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:
-- `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:
+Two pagination classes are available **but their names will change in release 3.0**:
+- `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.
+  - `page_size` (default `REST_FRAMEWORK['PAGE_SIZE']`) default number of items per page unless overridden by
+     `page_size_query_param`.
   - `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).
+
+  In release 3.0, `JsonApiPageNumberPagination` will be renamed `PageNumberPagination`.
+- `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]`).
+  - `default_limit` (default `REST_FRAMEWORK['PAGE_SIZE']`) is the default number of items per page unless
+     overridden by `limit_query_param`.
   - `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.
 
+  In release 3.0, `JsonApiLimitOffsetPagination` will be renamed `LimitOffsetPagination`.
 
 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'
+    page_size_query_param = 'page_length'
+    page_size = 3
     max_page_size = 1000
 
-class MyLimitPagination(JSONAPILimitOffsetPagination):
+class MyLimitPagination(JsonApiLimitOffsetPagination):
     offset_query_param = 'offset'
     limit_query_param = 'limit'
+    default_limit = 3
     max_limit = None
 ```
 
@@ -146,7 +157,7 @@ If you are also using [`rest_framework.filters.SearchFilter`](https://django-res
 (which performs single parameter searchs across multiple fields) you'll want to customize the name of the query
 parameter for searching to make sure it doesn't conflict with a field name defined in the filterset.
 The recommended value is: `search_param="filter[search]"` but just make sure it's
-`filter[_something_]` to comply with the jsonapi spec requirement to use the filter
+`filter[_something_]` to comply with the JSON:API spec requirement to use the filter
 keyword. The default is "search" unless overriden.
 
 The filter returns a `400 Bad Request` error for invalid filter query parameters as in this example
@@ -446,7 +457,7 @@ class OrderSerializer(serializers.ModelSerializer):
 
 ```
 
-In the [JSON API spec](http://jsonapi.org/format/#document-resource-objects),
+In the [JSON:API spec](http://jsonapi.org/format/#document-resource-objects),
 relationship objects contain links to related objects. To make this work
 on a serializer we need to tell the `ResourceRelatedField` about the
 corresponding view. Use the `HyperlinkedModelSerializer` and instantiate
@@ -584,7 +595,7 @@ class OrderSerializer(serializers.HyperlinkedModelSerializer):
 ### RelationshipView
 `rest_framework_json_api.views.RelationshipView` is used to build
 relationship views (see the
-[JSON API spec](http://jsonapi.org/format/#fetching-relationships)).
+[JSON:API spec](http://jsonapi.org/format/#fetching-relationships)).
 The `self` link on a relationship object should point to the corresponding
 relationship view.
 

example/settings/dev.py

@@ -68,6 +68,7 @@
 
 JSON_API_FORMAT_FIELD_NAMES = 'camelize'
 JSON_API_FORMAT_TYPES = 'camelize'
+JSON_API_STANDARD_PAGINATION = True
 REST_FRAMEWORK = {
     'PAGE_SIZE': 5,
     'EXCEPTION_HANDLER': 'rest_framework_json_api.exceptions.exception_handler',

example/settings/test.py

@@ -12,6 +12,9 @@
 JSON_API_FIELD_NAMES = 'camelize'
 JSON_API_FORMAT_TYPES = 'camelize'
 JSON_API_PLURALIZE_TYPES = True
+# TODO: 13 tests fail when this is True because they use `page` and `page_size`. Fix them.
+JSON_API_STANDARD_PAGINATION = False
+
 REST_FRAMEWORK.update({
     'PAGE_SIZE': 1,
 })

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
 
@@ -79,33 +79,30 @@ def test_valid_offset_limit(self):
         assert queryset == list(range(offset + 1, next_offset + 1))
         assert content == expected_content
 
+    @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(DeprecationWarning) as record:
             pagination.LimitOffsetPagination()
-        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)
+        assert len(record) == 2
+        assert 'LimitOffsetPagination will change in release 3.0' in str(record[0].message)
+        assert 'JsonApiLimitOffsetPagination will be replaced by LimitOffsetPagination' \
+               in str(record[1].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.
     """
+
+    @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(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)
+        assert len(record) == 2
+        assert 'PageNumberPagination will change in release 3.0' in str(record[0].message)
+        assert 'JsonApiPageNumberPagination will be replaced by PageNumberPagination' \
+               in str(record[1].message)

example/views.py

@@ -35,7 +35,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
@@ -59,12 +59,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,14 +9,22 @@
 from rest_framework.views import Response
 
 
-class JSONAPIPageNumberPagination(PageNumberPagination):
+class JsonApiPageNumberPagination(PageNumberPagination):
     """
     A json-api compatible pagination format
     """
     page_query_param = 'page[number]'
     page_size_query_param = 'page[size]'
     max_page_size = 100
 
+    def __init__(self):
+        warnings.warn(
+            'JsonApiPageNumberPagination will be replaced by PageNumberPagination in release 3.0'
+            ' See '
+            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
+            DeprecationWarning)
+        super(JsonApiPageNumberPagination, self).__init__()
+
     def build_link(self, index):
         if not index:
             return None
@@ -50,7 +58,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
@@ -60,6 +68,14 @@ class JSONAPILimitOffsetPagination(LimitOffsetPagination):
     offset_query_param = 'page[offset]'
     max_limit = 100
 
+    def __init__(self):
+        warnings.warn(
+            'JsonApiLimitOffsetPagination will be replaced by LimitOffsetPagination in release 3.0'
+            ' See '
+            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
+            DeprecationWarning)
+        super(JsonApiLimitOffsetPagination, self).__init__()
+
     def get_last_link(self):
         if self.count == 0:
             return None
@@ -100,63 +116,34 @@ def get_paginated_response(self, data):
         })
 
 
-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):
+class PageNumberPagination(JsonApiPageNumberPagination):
     """
     Deprecated paginator that uses different query parameters
     """
     page_query_param = 'page'
     page_size_query_param = 'page_size'
 
     def __init__(self):
-        warnings.warn(
-            'PageNumberPagination is deprecated. Use JSONAPIPageNumberPagination '
-            'or create custom pagination. See '
-            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
-            DeprecationWarning)
+        if self.page_query_param == 'page' or self.page_size_query_param == 'page_size':
+            warnings.warn(
+                'PageNumberPagination will change in release 3.0 to default to use page[number] and'
+                ' page[size] query parameters. See '
+                'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',  # noqa: E501
+                DeprecationWarning)
         super(PageNumberPagination, self).__init__()
 
 
-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):
+class LimitOffsetPagination(JsonApiLimitOffsetPagination):
     """
     Deprecated paginator that uses a different max_limit
     """
     max_limit = None
 
     def __init__(self):
-        warnings.warn(
-            'LimitOffsetPagination is deprecated. Use JSONAPILimitOffsetPagination '
-            'or create custom pagination. See '
-            'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
-            DeprecationWarning)
+        if self.max_limit is None:
+            warnings.warn(
+                'LimitOffsetPagination will change in release 3.0 to default to max_limit=100. '
+                'See '
+                'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',  # noqa: E501
+                DeprecationWarning)
         super(LimitOffsetPagination, self).__init__()