Skip to content

Commit 2c9c0f1

Browse files
tomchristietomchristie
authored
Version 3.9 (#6247)
* Release notes to 5174a26 * Update version for v3.9.0 * Removed exclude_from_schema per deprecation policy. * Updated list_route() and detail_route() deprecations. * Weakened to PendingDeprecationWarning for `base_name` cc @rpkilby. * Add (beginning of) 3.9 release announcement. @tomchristie: Input on OpenAPI and What’s Next very welcome! :) * Add announcement section for Extra Actions in Browsable API * Update release notes and add deprecation note for Django Guardian backend. * Add release note for #6073 * Add release notes to dd19a44 * Adding release notes * Update 3.9 announcement * Add Oct 18 release date
1 parent 28040b3 commit 2c9c0f1

File tree

10 files changed

+313
-72
lines changed

10 files changed

+313
-72
lines changed

‎docs/community/3.9-announcement.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
<style>
2+
.promo li a {
3+
float: left;
4+
width: 130px;
5+
height: 20px;
6+
text-align: center;
7+
margin: 10px 30px;
8+
padding: 150px 0 0 0;
9+
background-position: 0 50%;
10+
background-size: 130px auto;
11+
background-repeat: no-repeat;
12+
font-size: 120%;
13+
color: black;
14+
}
15+
.promo li {
16+
list-style: none;
17+
}
18+
</style>
19+
20+
# Django REST framework 3.9
21+
22+
The 3.9 release gives access to _extra actions_ in the Browsable API, introduces composable permissions and built-in [OpenAPI][openapi] schema support. (Formerly known as Swagger)
23+
24+
---
25+
26+
## Funding
27+
28+
If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by
29+
**[signing up for a paid&nbsp;plan][funding]**.
30+
31+
32+
<ul class="premium-promo promo">
33+
<li><a href="http://jobs.rover.com/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rover_130x130.png)">Rover.com</a></li>
34+
<li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
35+
<li><a href="https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
36+
<li><a href="https://auklet.io" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/auklet-new.png)">Auklet</a></li>
37+
<li><a href="https://rollbar.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/rollbar2.png)">Rollbar</a></li>
38+
<li><a href="https://cadre.com" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/cadre.png)">Cadre</a></li>
39+
<li><a href="https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/load-impact.png)">Load Impact</a></li>
40+
<li><a href="https://hubs.ly/H0f30Lf0" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/kloudless.png)">Kloudless</a></li>
41+
</ul>
42+
<div style="clear: both; padding-bottom: 20px;"></div>
43+
44+
*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Auklet](https://auklet.io/), [Rollbar](https://rollbar.com), [Cadre](https://cadre.com), [Load Impact](https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf), and [Kloudless](https://hubs.ly/H0f30Lf0).*
45+
46+
---
47+
48+
## Built-in OpenAPI schema support
49+
50+
REST framework now has a first-pass at directly including OpenAPI schema support. (Formerly known as Swagger)
51+
52+
Specifically:
53+
54+
* There are now `OpenAPIRenderer`, and `JSONOpenAPIRenderer` classes that deal with encoding `coreapi.Document` instances into OpenAPI YAML or OpenAPI JSON.
55+
* The `get_schema_view(...)` method now defaults to OpenAPI YAML, with CoreJSON as a secondary
56+
option if it is selected via HTTP content negotiation.
57+
* There is a new management command `generateschema`, which you can use to dump
58+
the schema into your repository.
59+
60+
Here's an example of adding an OpenAPI schema to the URL conf:
61+
62+
```python
63+
from rest_framework.schemas import get_schema_view
64+
from rest_framework.renderers import JSONOpenAPIRenderer
65+
66+
schema_view = get_schema_view(
67+
title='Server Monitoring API',
68+
url='https://www.example.org/api/',
69+
renderer_classes=[JSONOpenAPIRenderer]
70+
)
71+
72+
urlpatterns = [
73+
url('^schema.json$', schema_view),
74+
...
75+
]
76+
```
77+
78+
And here's how you can use the `generateschema` management command:
79+
80+
```shell
81+
$ python manage.py generateschema --format openapi > schema.yml
82+
```
83+
84+
There's lots of different tooling that you can use for working with OpenAPI
85+
schemas. One option that we're working on is the [API Star](https://docs.apistar.com/)
86+
command line tool.
87+
88+
You can use `apistar` to validate your API schema:
89+
90+
```shell
91+
$ apistar validate --path schema.json --format openapi
92+
✓ Valid OpenAPI schema.
93+
```
94+
95+
Or to build API documentation:
96+
97+
```shell
98+
$ apistar docs --path schema.json --format openapi
99+
✓ Documentation built at "build/index.html".
100+
```
101+
102+
API Star also includes a [dynamic client library](https://docs.apistar.com/client-library/)
103+
that uses an API schema to automatically provide a client library interface for making requests.
104+
105+
## Composable permission classes
106+
107+
You can now compose permission classes using the and/or operators, `&` and `|`.
108+
109+
For example...
110+
111+
```python
112+
permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)]
113+
```
114+
115+
If you're using custom permission classes then make sure that you are subclassing
116+
from `BasePermission` in order to enable this support.
117+
118+
## ViewSet _Extra Actions_ available in the Browsable API
119+
120+
Following the introduction of the `action` decorator in v3.8, _extra actions_ defined on a ViewSet are now available
121+
from the Browsable API.
122+
123+
![Extra Actions displayed in the Browsable API](https://user-images.githubusercontent.com/2370209/32976956-1ca9ab7e-cbf1-11e7-981a-a20cb1e83d63.png)
124+
125+
When defined, a dropdown of "Extra Actions", appropriately filtered to detail/non-detail actions, is displayed.
126+
127+
---
128+
129+
## Supported Versions
130+
131+
REST framework 3.9 supports Django versions 1.11, 2.0, and 2.1.
132+
133+
---
134+
135+
## Deprecations
136+
137+
### `DjangoObjectPermissionsFilter` moved to third-party package.
138+
139+
The `DjangoObjectPermissionsFilter` class is pending deprecation, will be deprecated in 3.10 and removed entirely in 3.11.
140+
141+
It has been moved to the third-party [`djangorestframework-guardian`](https://github.com/rpkilby/django-rest-framework-guardian)
142+
package. Please use this instead.
143+
144+
### Router argument/method renamed to use `basename` for consistency.
145+
146+
* The `Router.register` `base_name` argument has been renamed in favor of `basename`.
147+
* The `Router.get_default_base_name` method has been renamed in favor of `Router.get_default_basename`. [#5990][gh5990]
148+
149+
See [#5990][gh5990].
150+
151+
[gh5990]: https://github.com/encode/django-rest-framework/pull/5990
152+
153+
`base_name` and `get_default_base_name()` are pending deprecation. They will be deprecated in 3.10 and removed entirely in 3.11.
154+
155+
### `action` decorator replaces `list_route` and `detail_route`
156+
157+
Both `list_route` and `detail_route` are now deprecated in favour of the single `action` decorator.
158+
They will be removed entirely in 3.10.
159+
160+
The `action` decorator takes a boolean `detail` argument.
161+
162+
* Replace `detail_route` uses with `@action(detail=True)`.
163+
* Replace `list_route` uses with `@action(detail=False)`.
164+
165+
### `exclude_from_schema`
166+
167+
Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` have now been removed.
168+
169+
For `APIView` you should instead set a `schema = None` attribute on the view class.
170+
171+
For function based views the `@schema` decorator can be used to exclude the view from the schema, by using `@schema(None)`.
172+
173+
---
174+
175+
## Minor fixes and improvements
176+
177+
There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page for a complete listing.
178+
179+
180+
## What's next
181+
182+
We're planning to iteratively working towards OpenAPI becoming the standard schema
183+
representation. This will mean that the `coreapi` dependency will gradually become
184+
removed, and we'll instead generate the schema directly, rather than building
185+
a CoreAPI `Document` object.
186+
187+
OpenAPI has clearly become the standard for specifying Web APIs, so there's not
188+
much value any more in our schema-agnostic document model. Making this change
189+
will mean that we'll more easily be able to take advantage of the full set of
190+
OpenAPI functionality.
191+
192+
This will also make a wider range of tooling available.
193+
194+
We'll focus on continuing to develop the [API Star](https://docs.apistar.com/)
195+
library and client tool into a recommended option for generating API docs,
196+
validating API schemas, and providing a dynamic client library.
197+
198+
There's also a huge amount of ongoing work on maturing the ASGI landscape,
199+
with the possibility that some of this work will eventually [feed back into
200+
Django](https://www.aeracode.org/2018/06/04/django-async-roadmap/).
201+
202+
There will be further work on the [Uvicorn](https://www.uvicorn.org/)
203+
webserver, as well as lots of functionality planned for the [Starlette](https://www.starlette.io/)
204+
web framework, which is building a foundational set of tooling for working with
205+
ASGI.
206+
207+
208+
[funding]: funding.md
209+
[gh5886]: https://github.com/encode/django-rest-framework/issues/5886
210+
[gh5705]: https://github.com/encode/django-rest-framework/issues/5705
211+
[openapi]: https://www.openapis.org/
212+
[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors

‎docs/community/release-notes.md

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,52 @@ You can determine your currently installed version using `pip show`:
4242

4343
### 3.9.0
4444

45-
**Date**: Unreleased
45+
**Date**: [18st October 2018][3.9.0-milestone]
4646

47+
* Improvements to ViewSet extra actions [#5605][gh5605]
48+
* Fix `action` support for ViewSet suffixes [#6081][gh6081]
49+
* Allow `action` docs sections [#6060][gh6060]
4750
* Deprecate the `Router.register` `base_name` argument in favor of `basename`. [#5990][gh5990]
4851
* Deprecate the `Router.get_default_base_name` method in favor of `Router.get_default_basename`. [#5990][gh5990]
52+
* Change `CharField` to disallow null bytes. [#6073][gh6073]
53+
To revert to the old behavior, subclass `CharField` and remove `ProhibitNullCharactersValidator` from the validators.
54+
```python
55+
class NullableCharField(serializers.CharField):
56+
def __init__(self, *args, **kwargs):
57+
super().__init__(*args, **kwargs)
58+
self.validators = [v for v in self.validators if not isinstance(v, ProhibitNullCharactersValidator)]
59+
```
60+
* Add `OpenAPIRenderer` and `generate_schema` management command. [#6229][gh6229]
61+
* Add OpenAPIRenderer by default, and add schema docs. [#6233][gh6233]
62+
* Allow permissions to be composed [#5753][gh5753]
63+
* Allow nullable BooleanField in Django 2.1 [#6183][gh6183]
64+
* Add testing of Python 3.7 support [#6141][gh6141]
65+
* Test using Django 2.1 final release. [#6109][gh6109]
66+
* Added djangorestframework-datatables to third-party packages [#5931][gh5931]
67+
* Change ISO 8601 date format to exclude year/month [#5936][gh5936]
68+
* Update all pypi.python.org URLs to pypi.org [#5942][gh5942]
69+
* Ensure that html forms (multipart form data) respect optional fields [#5927][gh5927]
70+
* Allow hashing of ErrorDetail. [#5932][gh5932]
71+
* Correct schema parsing for JSONField [#5878][gh5878]
72+
* Render descriptions (from help_text) using safe [#5869][gh5869]
73+
* Removed input value from deault_error_message [#5881][gh5881]
74+
* Added min_value/max_value support in DurationField [#5643][gh5643]
75+
* Fixed instance being overwritten in pk-only optimization try/except block [#5747][gh5747]
76+
* Fixed AttributeError from items filter when value is None [#5981][gh5981]
77+
* Fixed Javascript `e.indexOf` is not a function error [#5982][gh5982]
78+
* Fix schemas for extra actions [#5992][gh5992]
79+
* Improved get_error_detail to use error_dict/error_list [#5785][gh5785]
80+
* Imprvied URLs in Admin renderer [#5988][gh5988]
81+
* Add "Community" section to docs, minor cleanup [#5993][gh5993]
82+
* Moved guardian imports out of compat [#6054][gh6054]
4983
* Deprecate the `DjangoObjectPermissionsFilter` class, moved to the `djangorestframework-guardian` package. [#6075][gh6075]
84+
* Drop Django 1.10 support [#5657][gh5657]
85+
* Only catch TypeError/ValueError for object lookups [#6028][gh6028]
86+
* Handle models without .objects manager in ModelSerializer. [#6111][gh6111]
87+
* Improve ModelSerializer.create() error message. [#6112][gh6112]
88+
* Fix CSRF cookie check failure when using session auth with django 1.11.6+ [#6113][gh6113]
89+
* Updated JWT docs. [#6138][gh6138]
90+
* Fix autoescape not getting passed to urlize_quoted_links filter [#6191][gh6191]
5091

5192

5293
## 3.8.x series
@@ -1093,6 +1134,7 @@ For older release notes, [please see the version 2.x documentation][old-release-
10931134
[3.8.0-milestone]: https://github.com/encode/django-rest-framework/milestone/61?closed=1
10941135
[3.8.1-milestone]: https://github.com/encode/django-rest-framework/milestone/67?closed=1
10951136
[3.8.2-milestone]: https://github.com/encode/django-rest-framework/milestone/68?closed=1
1137+
[3.9.0-milestone]: https://github.com/encode/django-rest-framework/milestone/66?closed=1
10961138

10971139
<!-- 3.0.1 -->
10981140
[gh2013]: https://github.com/encode/django-rest-framework/issues/2013
@@ -1974,5 +2016,39 @@ For older release notes, [please see the version 2.x documentation][old-release-
19742016
[gh5920]: https://github.com/encode/django-rest-framework/issues/5920
19752017

19762018
<!-- 3.9.0 -->
2019+
[gh6109]: https://github.com/encode/django-rest-framework/issues/6109
2020+
[gh6141]: https://github.com/encode/django-rest-framework/issues/6141
2021+
[gh6113]: https://github.com/encode/django-rest-framework/issues/6113
2022+
[gh6112]: https://github.com/encode/django-rest-framework/issues/6112
2023+
[gh6111]: https://github.com/encode/django-rest-framework/issues/6111
2024+
[gh6028]: https://github.com/encode/django-rest-framework/issues/6028
2025+
[gh5657]: https://github.com/encode/django-rest-framework/issues/5657
2026+
[gh6054]: https://github.com/encode/django-rest-framework/issues/6054
2027+
[gh5993]: https://github.com/encode/django-rest-framework/issues/5993
19772028
[gh5990]: https://github.com/encode/django-rest-framework/issues/5990
2029+
[gh5988]: https://github.com/encode/django-rest-framework/issues/5988
2030+
[gh5785]: https://github.com/encode/django-rest-framework/issues/5785
2031+
[gh5992]: https://github.com/encode/django-rest-framework/issues/5992
2032+
[gh5605]: https://github.com/encode/django-rest-framework/issues/5605
2033+
[gh5982]: https://github.com/encode/django-rest-framework/issues/5982
2034+
[gh5981]: https://github.com/encode/django-rest-framework/issues/5981
2035+
[gh5747]: https://github.com/encode/django-rest-framework/issues/5747
2036+
[gh5643]: https://github.com/encode/django-rest-framework/issues/5643
2037+
[gh5881]: https://github.com/encode/django-rest-framework/issues/5881
2038+
[gh5869]: https://github.com/encode/django-rest-framework/issues/5869
2039+
[gh5878]: https://github.com/encode/django-rest-framework/issues/5878
2040+
[gh5932]: https://github.com/encode/django-rest-framework/issues/5932
2041+
[gh5927]: https://github.com/encode/django-rest-framework/issues/5927
2042+
[gh5942]: https://github.com/encode/django-rest-framework/issues/5942
2043+
[gh5936]: https://github.com/encode/django-rest-framework/issues/5936
2044+
[gh5931]: https://github.com/encode/django-rest-framework/issues/5931
2045+
[gh6183]: https://github.com/encode/django-rest-framework/issues/6183
19782046
[gh6075]: https://github.com/encode/django-rest-framework/issues/6075
2047+
[gh6138]: https://github.com/encode/django-rest-framework/issues/6138
2048+
[gh6081]: https://github.com/encode/django-rest-framework/issues/6081
2049+
[gh6073]: https://github.com/encode/django-rest-framework/issues/6073
2050+
[gh6191]: https://github.com/encode/django-rest-framework/issues/6191
2051+
[gh6060]: https://github.com/encode/django-rest-framework/issues/6060
2052+
[gh6233]: https://github.com/encode/django-rest-framework/issues/6233
2053+
[gh5753]: https://github.com/encode/django-rest-framework/issues/5753
2054+
[gh6229]: https://github.com/encode/django-rest-framework/issues/6229

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ pages:
6565
- 'Contributing to REST framework': 'community/contributing.md'
6666
- 'Project management': 'community/project-management.md'
6767
- 'Release Notes': 'community/release-notes.md'
68+
- '3.9 Announcement': 'community/3.9-announcement.md'
6869
- '3.8 Announcement': 'community/3.8-announcement.md'
6970
- '3.7 Announcement': 'community/3.7-announcement.md'
7071
- '3.6 Announcement': 'community/3.6-announcement.md'

‎rest_framework/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"""
99

1010
__title__ = 'Django REST framework'
11-
__version__ = '3.8.2'
11+
__version__ = '3.9.0'
1212
__author__ = 'Tom Christie'
1313
__license__ = 'BSD 2-Clause'
1414
__copyright__ = 'Copyright 2011-2018 Tom Christie'

‎rest_framework/decorators.py

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
from rest_framework.views import APIView
1818

1919

20-
def api_view(http_method_names=None, exclude_from_schema=False):
20+
def api_view(http_method_names=None):
2121
"""
2222
Decorator that converts a function-based view into an APIView subclass.
2323
Takes a list of allowed methods for the view as an argument.
@@ -77,15 +77,8 @@ def handler(self, *args, **kwargs):
7777
WrappedAPIView.schema = getattr(func, 'schema',
7878
APIView.schema)
7979

80-
if exclude_from_schema:
81-
warnings.warn(
82-
"The `exclude_from_schema` argument to `api_view` is deprecated. "
83-
"Use the `schema` decorator instead, passing `None`.",
84-
DeprecationWarning
85-
)
86-
WrappedAPIView.exclude_from_schema = exclude_from_schema
87-
8880
return WrappedAPIView.as_view()
81+
8982
return decorator
9083

9184

@@ -230,9 +223,9 @@ def detail_route(methods=None, **kwargs):
230223
Used to mark a method on a ViewSet that should be routed for detail requests.
231224
"""
232225
warnings.warn(
233-
"`detail_route` is pending deprecation and will be removed in 3.10 in favor of "
226+
"`detail_route` is deprecated and will be removed in 3.10 in favor of "
234227
"`action`, which accepts a `detail` bool. Use `@action(detail=True)` instead.",
235-
PendingDeprecationWarning, stacklevel=2
228+
DeprecationWarning, stacklevel=2
236229
)
237230

238231
def decorator(func):
@@ -248,9 +241,9 @@ def list_route(methods=None, **kwargs):
248241
Used to mark a method on a ViewSet that should be routed for list requests.
249242
"""
250243
warnings.warn(
251-
"`list_route` is pending deprecation and will be removed in 3.10 in favor of "
244+
"`list_route` is deprecated and will be removed in 3.10 in favor of "
252245
"`action`, which accepts a `detail` bool. Use `@action(detail=False)` instead.",
253-
PendingDeprecationWarning, stacklevel=2
246+
DeprecationWarning, stacklevel=2
254247
)
255248

256249
def decorator(func):

0 commit comments

Comments
 (0)