revert JSONAPI prefix from paginators

n2ygk · n2ygk · commit 00dcf526a4ad · 2018-08-30T19:35:48.000-04:00
- see django-json-api#467 (comment) - JSONAPIPageNumberPagination goes back to PageNumberPagination - JSONAPILimitOffsetPagination goas back to LimitOffsetPagination - requires new setting: `JSON_API_STANDARD_PAGINATION=True` to get `page[number]` and `page[size]` instead of `page` and `page_size`. This is a breaking change no matter which is the default value.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,9 @@
 * 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/) filter backends. See [usage docs](docs/usage.md#filter-backends)
+* **breaking change**: Reverted v2.5.0's `JsonApiPagenumberPagination` back to `PageNumberPagination` and `JsonApiLimitOffsetPagination` back to `LimitOffsetPagination`
+  You have to set `JSON_API_STANDARD_PAGINATION = True` (default is False) to get the "new" JSON:API-style query parameters. This retains the deprecated
+  behavior for now. See [usage docs](docs/usage.md#pagination).
 
 v2.5.0 - Released July 11, 2018
 
diff --git a/README.rst b/README.rst
@@ -118,10 +118,15 @@ Running the example app
 
 ::
 
-    $ git clone https://github.com/django-json-api/django-rest-framework-json-api.git
-    $ cd django-rest-framework-json-api
-    $ pip install -e .
-    $ django-admin.py runserver --settings=example.settings
+	$ git clone https://github.com/django-json-api/django-rest-framework-json-api.git
+	$ cd django-rest-framework-json-api
+	$ python3 -m venv env
+	$ source env/bin/activate
+	$ pip install -r example/requirements.txt
+	$ pip install -e .
+	$ django-admin migrate --settings=example.settings
+	$ django-admin loaddata drf_example --settings=example.settings
+	$ django-admin runserver --settings=example.settings
 
 Browse to http://localhost:8000
 
@@ -136,7 +141,7 @@ installed and activated:
 
     $ pip install -e .
     $ pip install -r requirements-development.txt
-    $ py.test
+    $ DJANGO_SETTINGS_MODULE=example.settings.test py.test
 
 
 -----
@@ -161,7 +166,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.PageNumberPagination',
         'DEFAULT_PARSER_CLASSES': (
             'rest_framework_json_api.parsers.JSONParser',
             'rest_framework.parsers.FormParser',
@@ -173,12 +178,15 @@ override ``settings.REST_FRAMEWORK``
         ),
         'DEFAULT_METADATA_CLASS': 'rest_framework_json_api.metadata.JSONAPIMetadata',
         'DEFAULT_FILTER_BACKENDS': (
-            'rest_framework_json_api.backends.JSONAPIOrderingFilter',
+            'rest_framework_json_api.filters.JSONAPIOrderingFilter',
+            'rest_framework_json_api.filters.DjangoFilterBackend',
         ),
         'TEST_REQUEST_RENDERER_CLASSES': (
             'rest_framework_json_api.renderers.JSONRenderer',
         ),
         'TEST_REQUEST_DEFAULT_FORMAT': 'vnd.api+json'
     }
 
+    JSON_API_STANDARD_PAGINATION = True
+
 This package provides much more including automatic inflection of JSON keys, extra top level data (using nested serializers), relationships, links, and handy shortcuts like MultipleIDMixin. Read more at http://django-rest-framework-json-api.readthedocs.org/
diff --git a/docs/usage.md b/docs/usage.md
@@ -4,7 +4,7 @@
 The DJA package implements a custom renderer, parser, exception handler, query filter backends, and
 pagination. To get started enable the pieces in `settings.py` that you want to use.
 
-Many features of the [JSON:API](http://jsonapi.org/format) format standard have been implemented using 
+Many features of the [JSON:API](http://jsonapi.org/format) format standard have been implemented using
 Mixin classes in `serializers.py`.
 The easiest way to make use of those features is to import ModelSerializer variants
 from `rest_framework_json_api` instead of the usual `rest_framework`
@@ -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.PageNumberPagination',
     'DEFAULT_PARSER_CLASSES': (
         'rest_framework_json_api.parsers.JSONParser',
         'rest_framework.parsers.FormParser',
@@ -41,6 +41,8 @@ REST_FRAMEWORK = {
     ),
     'TEST_REQUEST_DEFAULT_FORMAT': 'vnd.api+json'
 }
+
+JSON_API_STANDARD_PAGINATION = True
 ```
 
 ### Pagination
@@ -50,6 +52,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 +62,46 @@ 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.
 
+You should also set `JSON_API_STANDARD_PAGINATION=True` in order to get up to date JSON:API-style default
+query parameters and pagination size limits. The default value (False) sets deprecated values that will
+be eliminated in the future. See below.
+
 Two pagination classes are available:
-- `JsonApiPageNumberPagination` breaks a response up into pages that start at a given page number with a given size 
+- `PageNumberPagination` 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`.
+  - `page_size` (default `REST_FRAMEWORK['PAGE_SIZE']`) number of items per page.
+  - `max_page_size` (default `100`) enforces an upper bound on the page size.
      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 
+  - `page_query_param` (if `JSON_API_STANDARD_PAGINATION is True`: `page[number]` otherwise `page`) is the query
+     parameter for the page number.
+  - `page_size_query_param` (if `JSON_API_STANDARD_PAGINATION is True`: `page[size]` otherwise `page_size`) is the
+     query parameter for the page size. No more than `max_page_size` items will be returned.
+     Set this to `None` if you don't want to allow the client to specify the size.
+- `LimitOffsetPagination` 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]`).
-  - `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.
-
+  - `default_limit` (default `REST_FRAMEWORK['PAGE_SIZE']`) is the number of items per page.
+  - `offset_query_param` (default `page[offset]`) is the query parameter that sets the offset (item number) to return.
+  - `limit_query_param` (default `page[limit]`) is the query parameter that sets the limit (number of items per page).
+     No more than `max_limit` items will be returned.
+  - `max_limit` (if `JSON_API_STANDARD_PAGINATION is True`: `100` otherwise `None`) enforces an upper bound on the
+     limit. Set it to `None` if you don't want to enforce an upper bound.
 
 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 PageNumberPagination, LimitOffsetPagination
 
-class MyPagePagination(JsonApiPageNumberPagination):
+class MyPagePagination(PageNumberPagination):
     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(LimitOffsetPagination):
     offset_query_param = 'offset'
     limit_query_param = 'limit'
+    default_limit = 3
     max_limit = None
 ```
 
@@ -146,7 +160,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
@@ -445,7 +459,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
@@ -583,7 +597,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.
 
diff --git a/example/tests/unit/test_pagination.py b/example/tests/unit/test_pagination.py
@@ -13,11 +13,11 @@
 
 class TestLimitOffset:
     """
-    Unit tests for `pagination.JsonApiLimitOffsetPagination`.
+    Unit tests for `pagination.LimitOffsetPagination`.
     """
 
     def setup(self):
-        class ExamplePagination(pagination.JsonApiLimitOffsetPagination):
+        class ExamplePagination(pagination.LimitOffsetPagination):
             default_limit = 10
             max_limit = 15
 
@@ -81,21 +81,98 @@ def test_valid_offset_limit(self):
 
     def test_limit_offset_deprecation(self):
         with pytest.warns(DeprecationWarning) as record:
-            pagination.LimitOffsetPagination()
+            pagination.JsonApiLimitOffsetPagination()
         assert len(record) == 1
-        assert 'LimitOffsetPagination' in str(record[0].message)
+        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`.
-    TODO: add unit tests for changing query parameter names, limits, etc.
+    Unit tests for `pagination.PageNumberPagination`.
+    TODO: add unit tests for changing query parameter names, max limits, etc.
     """
+
+    def setup(self):
+        class ExamplePagination(pagination.PageNumberPagination):
+            default_page_size = 10
+            max_page_size = 15
+
+        self.pagination = ExamplePagination()
+        self.queryset = range(1, 401)
+        self.base_url = 'http://testserver/'
+
+    def paginate_queryset(self, request):
+        return list(self.pagination.paginate_queryset(self.queryset, request))
+
+    def get_paginated_content(self, queryset):
+        response = self.pagination.get_paginated_response(queryset)
+        return response.data
+
+    def get_test_request(self, arguments):
+        return Request(factory.get('/', arguments))
+
+    def test_valid_page_size(self):
+        """
+        Basic test, assumes page and size are given.
+        """
+        page = 10
+        size = 5
+        count = len(self.queryset)
+        last_page = (count // size)
+        next_page = 11
+        prev_page = 9
+
+        request = self.get_test_request({
+            self.pagination.page_size_query_param: size,
+            self.pagination.page_query_param: page
+        })
+        base_url = replace_query_param(self.base_url, self.pagination.page_size_query_param, size)
+        first_url = replace_query_param(base_url, self.pagination.page_query_param, 1)
+        last_url = replace_query_param(base_url, self.pagination.page_query_param, last_page)
+        next_url = replace_query_param(base_url, self.pagination.page_query_param, next_page)
+        prev_url = replace_query_param(base_url, self.pagination.page_query_param, prev_page)
+        queryset = self.paginate_queryset(request)
+        content = self.get_paginated_content(queryset)
+
+        expected_content = {
+            'results': list(range((page - 1) * size + 1, (next_page - 1) * size + 1)),
+            'links': OrderedDict([
+                ('first', first_url),
+                ('last', last_url),
+                ('next', next_url),
+                ('prev', prev_url),
+            ]),
+            'meta': {
+                'pagination': OrderedDict([
+                    ('page', page),
+                    ('pages', count // size),
+                    ('count', count),
+                ])
+            }
+        }
+
+        assert queryset == list(range((page - 1) * size + 1, (next_page - 1) * size + 1))
+        assert content == expected_content
+
+    def test_page_size_too_big(self):
+        """
+        ask for a page size that's more than the max
+        """
+        page = 3
+        size = 20
+        request = self.get_test_request({
+            self.pagination.page_size_query_param: size,
+            self.pagination.page_query_param: page
+        })
+        queryset = self.paginate_queryset(request)
+        assert len(queryset) == self.pagination.max_page_size
+        assert len(queryset) < size
+
     def test_page_number_deprecation(self):
         with pytest.warns(DeprecationWarning) as record:
-            pagination.PageNumberPagination()
+            pagination.JsonApiPageNumberPagination()
         assert len(record) == 1
-        assert 'PageNumberPagination' in str(record[0].message)
+        assert 'JsonApiPageNumberPagination' in str(record[0].message)
diff --git a/rest_framework_json_api/pagination.py b/rest_framework_json_api/pagination.py
@@ -8,13 +8,24 @@
 from rest_framework.utils.urls import remove_query_param, replace_query_param
 from rest_framework.views import Response
 
+from rest_framework_json_api.settings import json_api_settings
 
-class JsonApiPageNumberPagination(PageNumberPagination):
+
+class PageNumberPagination(PageNumberPagination):
     """
     A json-api compatible pagination format
+
+    An older version of this used `page` and `page_size` so
+    use a setting to enable the "standard" query param names.
     """
-    page_query_param = 'page[number]'
-    page_size_query_param = 'page[size]'
+    if json_api_settings.STANDARD_PAGINATION:
+        page_query_param = 'page[number]'
+        page_size_query_param = 'page[size]'
+    else:
+        page_query_param = 'page'
+        page_size_query_param = 'page_size'
+        warnings.warn("'page' and 'page_size' parameters are deprecated. "
+                      "Set JSON_API_STANDARD_PAGINATION=True", DeprecationWarning)
     max_page_size = 100
 
     def build_link(self, index):
@@ -50,15 +61,19 @@ def get_paginated_response(self, data):
         })
 
 
-class JsonApiLimitOffsetPagination(LimitOffsetPagination):
+class LimitOffsetPagination(LimitOffsetPagination):
     """
     A limit/offset based style. For example:
     http://api.example.org/accounts/?page[limit]=100
     http://api.example.org/accounts/?page[offset]=400&page[limit]=100
     """
     limit_query_param = 'page[limit]'
     offset_query_param = 'page[offset]'
-    max_limit = 100
+    if json_api_settings.STANDARD_PAGINATION:
+        max_limit = 100
+    else:
+        warnings.warn("'max_limit = None' is deprecated. "
+                      "Set JSON_API_STANDARD_PAGINATION=True", DeprecationWarning)
 
     def get_last_link(self):
         if self.count == 0:
@@ -100,31 +115,28 @@ def get_paginated_response(self, data):
         })
 
 
-class PageNumberPagination(JsonApiPageNumberPagination):
+class JsonApiPageNumberPagination(PageNumberPagination):
     """
-    Deprecated paginator that uses different query parameters
+    Changed our minds about the naming scheme. Removed JsonApi prefx.
     """
-    page_query_param = 'page'
-    page_size_query_param = 'page_size'
 
     def __init__(self):
         warnings.warn(
-            'PageNumberPagination is deprecated. Use JsonApiPageNumberPagination '
+            'JsonApiPageNumberPagination is deprecated. Use PageNumberPagination '
             '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(LimitOffsetPagination):
     """
-    Deprecated paginator that uses a different max_limit
+    Changed our minds about the naming scheme. Removed JsonApi prefx.
     """
-    max_limit = None
 
     def __init__(self):
         warnings.warn(
-            'LimitOffsetPagination is deprecated. Use JsonApiLimitOffsetPagination '
+            'JsonApiLimitOffsetPagination is deprecated. Use LimitOffsetPagination '
             'or create custom pagination. See '
             'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
             DeprecationWarning)
diff --git a/rest_framework_json_api/settings.py b/rest_framework_json_api/settings.py
