From 3430419b55daa9a11375638bd40ab89cd58c708d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 15 Jun 2020 10:46:12 +0100 Subject: [PATCH 1/9] Placeholder for 3.12 release --- docs/community/3.12-announcement.md | 49 +++++++++++++++++++++++++++++ docs/community/release-notes.md | 2 +- mkdocs.yml | 1 + 3 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 docs/community/3.12-announcement.md diff --git a/docs/community/3.12-announcement.md b/docs/community/3.12-announcement.md new file mode 100644 index 0000000000..60645b1ed0 --- /dev/null +++ b/docs/community/3.12-announcement.md @@ -0,0 +1,49 @@ + + +# Django REST framework 3.12 + +... + +--- + +## Funding + +REST framework is a *collaboratively funded project*. If you use +REST framework commercially we strongly encourage you to invest in its +continued development by **[signing up for a paid plan][funding]**. + +*Every single sign-up helps us make REST framework long-term financially sustainable.* + + +
+ +*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [ESG](https://software.esg-usa.com/), [Rollbar](https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), [Lights On Software](https://lightsonsoftware.com), and [Retool](https://retool.com/?utm_source=djangorest&utm_medium=sponsorship).* + +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: funding.md diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 0e634aa1e9..28aa5e13e7 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -40,7 +40,7 @@ You can determine your currently installed version using `pip show`: **Date**: 12th December 2019 -* Drop `.set_context` API [in favour of a `requires_context` marker](../3.11-announcement#validator-default-context). +* Drop `.set_context` API [in favour of a `requires_context` marker](3.11-announcement.md#validator-default-context). * Changed default widget for TextField with choices to select box. [#6892][gh6892] * Supported nested writes on non-relational fields, such as JSONField. [#6916][gh6916] * Include request/response media types in OpenAPI schemas, based on configured parsers/renderers. [#6865][gh6865] diff --git a/mkdocs.yml b/mkdocs.yml index 484971a715..573898bca0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ nav: - 'Contributing to REST framework': 'community/contributing.md' - 'Project management': 'community/project-management.md' - 'Release Notes': 'community/release-notes.md' + - '3.12 Announcement': 'community/3.12-announcement.md' - '3.11 Announcement': 'community/3.11-announcement.md' - '3.10 Announcement': 'community/3.10-announcement.md' - '3.9 Announcement': 'community/3.9-announcement.md' From a157541d127f72eae0dd495fa97419ca93946cac Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 3 Sep 2020 13:05:28 +0100 Subject: [PATCH 2/9] Updating release notes --- docs/community/release-notes.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 28aa5e13e7..b93903eb69 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -36,6 +36,33 @@ You can determine your currently installed version using `pip show`: ## 3.11.x series +### 3.12.0 + +* Add `--file` option to `generateschema` command. [#7130] +* Support `tags` for OpenAPI schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags). [#7184] +* Support customizing the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] +* Support OpenAPI components for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#components). [#7124] +* Add `__repr__` for Request instances. [#7239] +* UTF-8 decoding with Latin-1 fallback for basic auth credentials. [#7193] +* CharField treats surrogate characters as a validation failure. [#7026] +* Don't include callables as default values in schemas. [#7105] +* Improve `ListField` schema output to include all available child information. [#7137] +* Allow `default=False` to be included for `BooleanField` schema outputs. [#7165] +* Include `"type"` information in `ChoiceField` schema outputs. [#7161] +* Include `"type": "object"` on schema objects. [#7169] +* Fix schema generation for `ObtainAuthToken` view. [#7211] +* Default status code of 201 on schema output for POST requests. [#7206] +* Use camelCase for operation IDs in schema output. [#7208] +* Warn if duplicate operation IDs exist in schema output. [#7207] +* Disable YAML aliases for OpenAPI schema outputs. [#7131] +* HTTP `HEAD` requests now set `self.action` correctly on a ViewSet instance. [#7223] +* Return a valid OpenAPI schema for the case where no API schema paths exist. [#7125] +* Include tests in package distribution. [#7145] + +--- + +## 3.11.x series + ### 3.11.0 **Date**: 12th December 2019 From 82041b9880af2e55677d03286d552134a6aba38a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 3 Sep 2020 13:41:37 +0100 Subject: [PATCH 3/9] Updating release notes --- docs/community/release-notes.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index b93903eb69..f574cdc0b9 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -42,6 +42,9 @@ You can determine your currently installed version using `pip show`: * Support `tags` for OpenAPI schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags). [#7184] * Support customizing the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] * Support OpenAPI components for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#components). [#7124] +* The following methods on `AutoSchema` become public API: `get_path_parameters`, `get_pagination_parameters`, `get_filter_parameters`, `get_request_body`, `get_responses`, `get_serializer`, `get_paginator`, `map_serializer`, `map_field`, `map_choice_field`, `map_field_validators`, `allows_filters`. +* `SearchFilter` now supports nested search on `JSONField` and `HStoreField` model fields. [#7121] +* `SearchFilter` now supports searching on `annotate()` fields. [#6240] * Add `__repr__` for Request instances. [#7239] * UTF-8 decoding with Latin-1 fallback for basic auth credentials. [#7193] * CharField treats surrogate characters as a validation failure. [#7026] @@ -50,11 +53,20 @@ You can determine your currently installed version using `pip show`: * Allow `default=False` to be included for `BooleanField` schema outputs. [#7165] * Include `"type"` information in `ChoiceField` schema outputs. [#7161] * Include `"type": "object"` on schema objects. [#7169] +* Don't include component in schema output for DELETE requests. [#7229] +* Fix schema types for `DecimalField`. [#7254] * Fix schema generation for `ObtainAuthToken` view. [#7211] +* Support passing `context=...` to view `.get_serializer()` methods. [#7298] +* Pass custom code to `PermissionDenied` if permission class has one set. [#7306] +* Include "example" in schema pagination output. [#7275] * Default status code of 201 on schema output for POST requests. [#7206] * Use camelCase for operation IDs in schema output. [#7208] * Warn if duplicate operation IDs exist in schema output. [#7207] +* Improve handling of decimal type when mapping `ChoiceField` to a schema output. [#7264] * Disable YAML aliases for OpenAPI schema outputs. [#7131] +* Fix action URL names for APIs included under a namespaced URL. [#7287] +* Update jQuery version from 3.4 to 3.5. [#7313] +* Fix `UniqueTogether` handling when serializer fields use `source=...`. [#7143] * HTTP `HEAD` requests now set `self.action` correctly on a ViewSet instance. [#7223] * Return a valid OpenAPI schema for the case where no API schema paths exist. [#7125] * Include tests in package distribution. [#7145] From 633df138018a687549efaa6719c083448cd3d2a6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 3 Sep 2020 14:04:52 +0100 Subject: [PATCH 4/9] Updating release notes --- docs/community/release-notes.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index f574cdc0b9..08bd03ee2d 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -42,7 +42,8 @@ You can determine your currently installed version using `pip show`: * Support `tags` for OpenAPI schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags). [#7184] * Support customizing the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] * Support OpenAPI components for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#components). [#7124] -* The following methods on `AutoSchema` become public API: `get_path_parameters`, `get_pagination_parameters`, `get_filter_parameters`, `get_request_body`, `get_responses`, `get_serializer`, `get_paginator`, `map_serializer`, `map_field`, `map_choice_field`, `map_field_validators`, `allows_filters`. +* The following methods on `AutoSchema` become public API: `get_path_parameters`, `get_pagination_parameters`, `get_filter_parameters`, `get_request_body`, `get_responses`, `get_serializer`, `get_paginator`, `map_serializer`, `map_field`, `map_choice_field`, `map_field_validators`, `allows_filters`. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema) +* Add support for Django 3.1's database-agnositic `JSONField`. [#7467] * `SearchFilter` now supports nested search on `JSONField` and `HStoreField` model fields. [#7121] * `SearchFilter` now supports searching on `annotate()` fields. [#6240] * Add `__repr__` for Request instances. [#7239] @@ -70,6 +71,12 @@ You can determine your currently installed version using `pip show`: * HTTP `HEAD` requests now set `self.action` correctly on a ViewSet instance. [#7223] * Return a valid OpenAPI schema for the case where no API schema paths exist. [#7125] * Include tests in package distribution. [#7145] +* Allow type checkers to support annotations like `ModelSerializer[Author]`. [#7385] +* Don't include invalid `charset=None` portion in the request `Content-Type` header when using APIClient. [#7400] +* Fix `\Z`/`\z` tokens in OpenAPI regexs. [#7389] +* Fix `PrimaryKeyRelatedField` and `HyperlinkedRelatedField` when source field is actually a property. [#7142] +* `Token.generate_key` is now a class method. [#7502] +* `@action` warns if method is wrapped in a decorator that does not preserve information using `@functools.wraps`. [#7098] --- From ddad74da2c09cdfa19f756c34b6dc93124b06c5f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 3 Sep 2020 16:29:43 +0100 Subject: [PATCH 5/9] Update release notes --- docs/community/release-notes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 08bd03ee2d..47c6839eae 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -46,6 +46,7 @@ You can determine your currently installed version using `pip show`: * Add support for Django 3.1's database-agnositic `JSONField`. [#7467] * `SearchFilter` now supports nested search on `JSONField` and `HStoreField` model fields. [#7121] * `SearchFilter` now supports searching on `annotate()` fields. [#6240] +* The authtoken model no longer exposes the `pk` in the admin URL. [#7341] * Add `__repr__` for Request instances. [#7239] * UTF-8 decoding with Latin-1 fallback for basic auth credentials. [#7193] * CharField treats surrogate characters as a validation failure. [#7026] From 407fb9129431bd575a902d7461ee42f3dff2eb31 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 8 Sep 2020 15:29:39 +0100 Subject: [PATCH 6/9] Fix typo --- docs/community/release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 47c6839eae..1d1b4353f1 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -40,7 +40,7 @@ You can determine your currently installed version using `pip show`: * Add `--file` option to `generateschema` command. [#7130] * Support `tags` for OpenAPI schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags). [#7184] -* Support customizing the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] +* Support customising the operation ID for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#operationid). [#7190] * Support OpenAPI components for schema generation. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#components). [#7124] * The following methods on `AutoSchema` become public API: `get_path_parameters`, `get_pagination_parameters`, `get_filter_parameters`, `get_request_body`, `get_responses`, `get_serializer`, `get_paginator`, `map_serializer`, `map_field`, `map_choice_field`, `map_field_validators`, `allows_filters`. See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema) * Add support for Django 3.1's database-agnositic `JSONField`. [#7467] From f8394b6227ffac9a87685c9af114a83107aed972 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 8 Sep 2020 15:29:54 +0100 Subject: [PATCH 7/9] Basic structure for release announcement --- docs/community/3.12-announcement.md | 51 ++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/community/3.12-announcement.md b/docs/community/3.12-announcement.md index 60645b1ed0..7677eb8fc4 100644 --- a/docs/community/3.12-announcement.md +++ b/docs/community/3.12-announcement.md @@ -19,7 +19,56 @@ # Django REST framework 3.12 -... +## Schema generation improvements + +#### Grouping operations with tags. + +https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags + +#### Customizing the operation ID. + +https://www.django-rest-framework.org/api-guide/schemas/#operationid + +#### Support OpenAPI components. + +https://www.django-rest-framework.org/api-guide/schemas/#components + +#### More Public API + +* `get_path_parameters` +* `get_pagination_parameters` +* `get_filter_parameters` +* `get_request_body` +* `get_responses` +* `get_serializer` +* `get_paginator` +* `map_serializer` +* `map_field` +* `map_choice_field` +* `map_field_validators` +* `allows_filters`. + +See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema). + +## Support for JSONField. + +Django 3.1 deprecated the existing `django.contrib.postgres.fields.JSONField` +in favour of a new database-agnositic `JSONField`. + +REST framework 3.12 now supports this new model field, and `ModelSerializer` +classes will correctly map the model field. + +## SearchFilter improvements + +There are a couple of significant improvements to the `SearchFilter` class. + +#### Support for nested search within `JSONField` and `HStoreField` + +**TODO** Example to give better context. + +#### Support for searching against fields created using `annotate` + +**TODO** Example to give better context. --- From b32a900a6003f52da41ac2a9731d27cd6433a108 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Sep 2020 10:26:34 +0100 Subject: [PATCH 8/9] 3.12 release notes --- docs/community/3.12-announcement.md | 103 +++++++++++++++++++++++----- 1 file changed, 87 insertions(+), 16 deletions(-) diff --git a/docs/community/3.12-announcement.md b/docs/community/3.12-announcement.md index 7677eb8fc4..9d2220933c 100644 --- a/docs/community/3.12-announcement.md +++ b/docs/community/3.12-announcement.md @@ -19,21 +19,63 @@ # Django REST framework 3.12 -## Schema generation improvements +REST framework 3.12 brings a handful of refinements to the OpenAPI schema +generation, plus support for Django's new database-agnostic `JSONField`, +and some improvements to the `SearchFilter` class. -#### Grouping operations with tags. +## Grouping operations with tags. -https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags +Open API schemas will now automatically include tags, based on the first element +in the URL path. -#### Customizing the operation ID. +For example... -https://www.django-rest-framework.org/api-guide/schemas/#operationid +Method | Path | Tags +--------------------------------|-----------------|------------- +`GET`, `PUT`, `PATCH`, `DELETE` | `/users/{id}/` | `['users']` +`GET`, `POST` | `/users/` | `['users']` +`GET`, `PUT`, `PATCH`, `DELETE` | `/orders/{id}/` | `['orders']` +`GET`, `POST` | `/orders/` | `['orders']` -#### Support OpenAPI components. +The tags used for a particular view may also be overridden... -https://www.django-rest-framework.org/api-guide/schemas/#components +```python +class MyOrders(APIView): + schema = AutoSchema(tags=['users', 'orders']) + ... +``` -#### More Public API +See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#grouping-operations-with-tags) for more information. + +## Customizing the operation ID. + +REST framework automatically determines operation IDs to use in OpenAPI +schemas. The latest version provides more control for overriding the behaviour +used to generate the operation IDs. + +See [the schema documentation](https://www.django-rest-framework.org/api-guide/schemas/#operationid) for more information. + +## Support for OpenAPI components. + +In order to output more graceful OpenAPI schemes, REST framework 3.12 now +defines components in the schema, and then references them inside request +and response objects. This is in contrast with the previous approach, which +fully expanded the request and response bodies for each operation. + +The names used for a component default to using the serializer class name, [but +may be overridden if needed](https://www.django-rest-framework.org/api-guide/schemas/#components +)... + +```python +class MyOrders(APIView): + schema = AutoSchema(component_name="OrderDetails") +``` + +## More Public API + +Many methods on the `AutoSchema` class have now been promoted to public API, +allowing you to more fully customize the schema generation. The following methods +are now available for overriding... * `get_path_parameters` * `get_pagination_parameters` @@ -48,7 +90,8 @@ https://www.django-rest-framework.org/api-guide/schemas/#components * `map_field_validators` * `allows_filters`. -See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#autoschema). +See [the schema docs](https://www.django-rest-framework.org/api-guide/schemas/#per-view-customization) +for details on using custom `AutoSchema` subclasses. ## Support for JSONField. @@ -62,13 +105,41 @@ classes will correctly map the model field. There are a couple of significant improvements to the `SearchFilter` class. -#### Support for nested search within `JSONField` and `HStoreField` - -**TODO** Example to give better context. - -#### Support for searching against fields created using `annotate` - -**TODO** Example to give better context. +### Nested searches against JSONField and HStoreField + +The class now supports nested search within `JSONField` and `HStoreField`, using +the double underscore notation for traversing which element of the field the +search should apply to. + +```python +class SitesSearchView(generics.ListAPIView): + """ + An API view to return a list of archaeological sites, optionally filtered + by a search against the site name or location. (Location searches are + matched against the region and country names.) + """ + queryset = Sites.objects.all() + serializer_class = SitesSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['site_name', 'location__region', 'location__country'] +``` + +### Searches against annotate fields + +Django allows querysets to create additional virtual fields, using the `.annotate` +method. We now support searching against annotate fields. + +```python +class PublisherSearchView(generics.ListAPIView): + """ + Search for publishers, optionally filtering the search against the average + rating of all their books. + """ + queryset = Publisher.objects.annotate(avg_rating=Avg('book__rating')) + serializer_class = PublisherSerializer + filter_backends = [filters.SearchFilter] + search_fields = ['avg_rating'] +``` --- From 4f1663d6ffa4d94a9a4a4a27884ec88545621ce9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 28 Sep 2020 10:27:11 +0100 Subject: [PATCH 9/9] Version 3.12.0 --- rest_framework/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest_framework/__init__.py b/rest_framework/__init__.py index 8f2bc4466f..afb2d34292 100644 --- a/rest_framework/__init__.py +++ b/rest_framework/__init__.py @@ -8,7 +8,7 @@ """ __title__ = 'Django REST framework' -__version__ = '3.11.0' +__version__ = '3.12.0' __author__ = 'Tom Christie' __license__ = 'BSD 3-Clause' __copyright__ = 'Copyright 2011-2019 Encode OSS Ltd'