Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit a781c13

Browse files
author
Oliver Sauder
committed
Clarify deprecation warning of pagination classes
1 parent 929251f commit a781c13

File tree

4 files changed

+23
-84
lines changed

4 files changed

+23
-84
lines changed

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ any parts of the framework not mentioned in the documentation should generally b
2525
### Fixed
2626

2727
* Performance improvement when rendering relationships with `ModelSerializer`
28+
* Do not show deprecation warning when user has implemented custom pagination class overwriting default values.
29+
2830

2931
## [2.5.0] - 2018年07月11日
3032

@@ -41,6 +43,16 @@ any parts of the framework not mentioned in the documentation should generally b
4143
### Deprecated
4244

4345
* Deprecate `PageNumberPagination` and `LimitOffsetPagination`. Use `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination` instead.
46+
* To retain deprecated values for `PageNumberPagination` and `LimitOffsetPagination` create new custom class like the following in your code base:
47+
```python
48+
class CustomPageNumberPagination(PageNumberPagination):
49+
page_query_param = "page"
50+
page_size_query_param = "page_size"
51+
52+
class CustomLimitOffsetPagination(LimitOffsetPagination):
53+
max_limit = None
54+
```
55+
and adjust `REST_FRAMEWORK['DEFAULT_PAGINATION_CLASS']` setting accordingly.
4456
* Deprecate `JSON_API_FORMAT_KEYS`, use `JSON_API_FORMAT_FIELD_NAMES`.
4557

4658
### Fixed

‎docs/usage.md‎

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,7 @@ by setting `REST_FRAMEWORK['DEFAULT_PAGINATION_CLASS']` and by setting `REST_FRA
6060
You can configure fixed values for the page size or limit -- or allow the client to choose the size or limit
6161
via query parameters.
6262

63-
Two pagination classes are available *but their names will change in release 3.0 in order to implement a more
64-
consistent class naming style*:
63+
Two pagination classes are available:
6564
- `JsonApiPageNumberPagination` breaks a response up into pages that start at a given page number with a given size
6665
(number of items per page). It can be configured with the following attributes:
6766
- `page_query_param` (default `page[number]`)
@@ -82,22 +81,6 @@ consistent class naming style*:
8281
- `max_limit` (default `100`) enforces an upper bound on the limit.
8382
Set it to `None` if you don't want to enforce an upper bound.
8483

85-
##### Preparing for future renaming of paginators with default attributes
86-
87-
In release 3.0, the `JsonApi` prefix will be removed from the paginator names. If you currently use those (deprecated)
88-
names (`PageNumberPagination` or `LimitOffsetPagination`) or would like to prepare now for this change, you will want to
89-
explicitly override several of the class attributes.
90-
91-
To retain deprecated values for `PageNumberPagination` set `page_query_param = "page"` and
92-
`page_size_query_param = "page_size"`.
93-
94-
To prepare for the renaming of `JsonApiPageNumberPagination` use `PageNumberPagination` now with
95-
`page_query_param = "page[number]"` and `page_size_query_param = "page[size]"`.
96-
97-
To retain deprecated vales for `LimitOffsetPagination` set `max_limit = None`.
98-
99-
To prepare for the renaming of `JsonApiLimitOffsetPagination` to `LimitOffsetPagination` set `max_limit = 100`.
100-
10184
##### Examples
10285
These examples show how to configure the parameters to use non-standard names and different limits:
10386

‎example/tests/unit/test_pagination.py‎

Lines changed: 4 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -82,20 +82,11 @@ def test_valid_offset_limit(self):
8282
@pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
8383
reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
8484
def test_limit_offset_deprecation(self):
85-
with pytest.warns(PendingDeprecationWarning) as record:
85+
with pytest.warns(DeprecationWarning) as record:
8686
pagination.LimitOffsetPagination()
8787
assert len(record) == 1
8888
assert 'LimitOffsetPagination will change in release 3.0' in str(record[0].message)
8989

90-
@pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
91-
reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
92-
def test_jsonapi_limit_offset_deprecation(self):
93-
with pytest.warns(PendingDeprecationWarning) as record:
94-
pagination.JsonApiLimitOffsetPagination()
95-
assert len(record) == 1
96-
assert 'JsonApiLimitOffsetPagination will be renamed to LimitOffsetPagination'\
97-
in str(record[0].message)
98-
9990
class MyInheritedLimitOffsetPagination(pagination.LimitOffsetPagination):
10091
"""
10192
Inherit the default values
@@ -109,7 +100,7 @@ class MyOverridenLimitOffsetPagination(pagination.LimitOffsetPagination):
109100
max_limit = None
110101

111102
def test_my_limit_offset_deprecation(self):
112-
with pytest.warns(PendingDeprecationWarning) as record:
103+
with pytest.warns(DeprecationWarning) as record:
113104
self.MyInheritedLimitOffsetPagination()
114105
assert len(record) == 1
115106
assert 'LimitOffsetPagination will change in release 3.0' in str(record[0].message)
@@ -127,20 +118,11 @@ class TestPageNumber:
127118
@pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
128119
reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
129120
def test_page_number_deprecation(self):
130-
with pytest.warns(PendingDeprecationWarning) as record:
121+
with pytest.warns(DeprecationWarning) as record:
131122
pagination.PageNumberPagination()
132123
assert len(record) == 1
133124
assert 'PageNumberPagination will change in release 3.0' in str(record[0].message)
134125

135-
@pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
136-
reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
137-
def test_jsonapi_page_number_deprecation(self):
138-
with pytest.warns(PendingDeprecationWarning) as record:
139-
pagination.JsonApiPageNumberPagination()
140-
assert len(record) == 1
141-
assert 'JsonApiPageNumberPagination will be renamed to PageNumberPagination' \
142-
in str(record[0].message)
143-
144126
class MyInheritedPageNumberPagination(pagination.PageNumberPagination):
145127
"""
146128
Inherit the default values
@@ -157,20 +139,11 @@ class MyOverridenPageNumberPagination(pagination.PageNumberPagination):
157139
@pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
158140
reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
159141
def test_my_page_number_deprecation(self):
160-
with pytest.warns(PendingDeprecationWarning) as record:
142+
with pytest.warns(DeprecationWarning) as record:
161143
self.MyInheritedPageNumberPagination()
162144
assert len(record) == 1
163145
assert 'PageNumberPagination will change in release 3.0' in str(record[0].message)
164146

165147
with pytest.warns(None) as record:
166148
self.MyOverridenPageNumberPagination()
167149
assert len(record) == 0
168-
169-
@pytest.mark.xfail((sys.version_info.major, sys.version_info.minor) == (2, 7),
170-
reason="python2.7 fails to generate DeprecationWarrning for unknown reason")
171-
def test_my_jsonapi_page_number_deprecation(self):
172-
with pytest.warns(PendingDeprecationWarning) as record:
173-
pagination.JsonApiPageNumberPagination()
174-
assert len(record) == 1
175-
assert 'JsonApiPageNumberPagination will be renamed to PageNumberPagination' \
176-
in str(record[0].message)

‎rest_framework_json_api/pagination.py‎

Lines changed: 6 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
from rest_framework.views import Response
1010

1111

12-
class _JsonApiPageNumberPagination(PageNumberPagination):
12+
class JsonApiPageNumberPagination(PageNumberPagination):
1313
"""
1414
A json-api compatible pagination format.
1515
Use a private name for the implementation because the public name is pending deprecation.
@@ -51,21 +51,7 @@ def get_paginated_response(self, data):
5151
})
5252

5353

54-
class JsonApiPageNumberPagination(_JsonApiPageNumberPagination):
55-
"""
56-
current public name to be deprecated soon.
57-
"""
58-
def __init__(self):
59-
if type(self) == JsonApiPageNumberPagination:
60-
warnings.warn(
61-
'JsonApiPageNumberPagination will be renamed to PageNumberPagination in'
62-
' release 3.0. See '
63-
'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination', # noqa: E501
64-
PendingDeprecationWarning)
65-
super(_JsonApiPageNumberPagination, self).__init__()
66-
67-
68-
class _JsonApiLimitOffsetPagination(LimitOffsetPagination):
54+
class JsonApiLimitOffsetPagination(LimitOffsetPagination):
6955
"""
7056
A limit/offset based style. For example:
7157
http://api.example.org/accounts/?page[limit]=100
@@ -117,22 +103,7 @@ def get_paginated_response(self, data):
117103
})
118104

119105

120-
class JsonApiLimitOffsetPagination(_JsonApiLimitOffsetPagination):
121-
"""
122-
current public name to be deprecated soon.
123-
"""
124-
125-
def __init__(self):
126-
warnings.warn(
127-
'JsonApiLimitOffsetPagination will be renamed to LimitOffsetPagination in release 3.0'
128-
' See '
129-
'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination',
130-
PendingDeprecationWarning)
131-
super(JsonApiLimitOffsetPagination, self).__init__()
132-
133-
134-
135-
class PageNumberPagination(_JsonApiPageNumberPagination):
106+
class PageNumberPagination(JsonApiPageNumberPagination):
136107
"""
137108
A soon-to-be-changed paginator that uses non-JSON:API query parameters (default:
138109
'page' and 'page_size' instead of 'page[number]' and 'page[size]').
@@ -154,12 +125,12 @@ def __init__(self):
154125
'`page_query_param = "page"` and `page_size_query_param = "page_size"`. '
155126
'See '
156127
'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination', # noqa: E501
157-
PendingDeprecationWarning)
128+
DeprecationWarning)
158129

159130
super(PageNumberPagination, self).__init__()
160131

161132

162-
class LimitOffsetPagination(_JsonApiLimitOffsetPagination):
133+
class LimitOffsetPagination(JsonApiLimitOffsetPagination):
163134
"""
164135
Deprecated paginator that uses a different max_limit
165136
"""
@@ -177,5 +148,5 @@ def __init__(self):
177148
'`max_limit = None`.'
178149
'See '
179150
'https://django-rest-framework-json-api.readthedocs.io/en/stable/usage.html#pagination', # noqa: E501
180-
PendingDeprecationWarning)
151+
DeprecationWarning)
181152
super(LimitOffsetPagination, self).__init__()

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /