Merge pull request #3531 from tomchristie/version-3.3

Version 3.3

Author: tomchristie

docs/api-guide/filtering.md

@@ -83,6 +83,10 @@ We can override `.get_queryset()` to deal with URLs such as `http://example.com/
 
 As well as being able to override the default queryset, REST framework also includes support for generic filtering backends that allow you to easily construct complex searches and filters.
 
+Generic filters can also present themselves as HTML controls in the browsable API and admin API.
+
+![Filter Example](../img/filter-controls.png)
+
 ## Setting filter backends
 
 The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKENDS` setting.  For example.

docs/img/filter-controls.png

@@ -12,9 +12,7 @@
 
 ---
 
-**Note**: This is the documentation for the **version 3.2** of REST framework. Documentation for [version 2.4](http://tomchristie.github.io/rest-framework-2-docs/) is also available.
-
-For more details see the 3.2 [announcement][3.2-announcement] and [release notes][release-notes].
+**Note**: This is the documentation for the **version 3** of REST framework. Documentation for [version 2](http://tomchristie.github.io/rest-framework-2-docs/) is also available.
 
 ---
 
@@ -31,7 +29,7 @@ For more details see the 3.2 [announcement][3.2-announcement] and [release notes
 <img alt="Django REST Framework" title="Logo by Jake 'Sid' Smith" src="img/logo.png" width="600px" style="display: block; margin: 0 auto 0 auto">
 </p>
 
-Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs.
+Django REST framework is a powerful and flexible toolkit for building Web APIs.
 
 Some reasons you might want to use REST framework:
 
@@ -52,13 +50,14 @@ Some reasons you might want to use REST framework:
 
 REST framework requires the following:
 
-* Python (2.6.5+, 2.7, 3.2, 3.3, 3.4, 3.5)
+* Python (2.7, 3.2, 3.3, 3.4, 3.5)
 * Django (1.7+, 1.8, 1.9)
 
 The following packages are optional:
 
 * [Markdown][markdown] (2.1.0+) - Markdown support for the browsable API.
 * [django-filter][django-filter] (0.9.2+) - Filtering support.
+* [django-crispy-forms][django-crispy-forms] - Improved HTML display for filtering.
 * [django-guardian][django-guardian] (1.1.1+) - Object level permissions support.
 
 ## Installation
@@ -203,6 +202,7 @@ General guides to using REST framework.
 * [3.0 Announcement][3.0-announcement]
 * [3.1 Announcement][3.1-announcement]
 * [3.2 Announcement][3.2-announcement]
+* [3.3 Announcement][3.3-announcement]
 * [Kickstarter Announcement][kickstarter-announcement]
 * [Release Notes][release-notes]
 
@@ -317,6 +317,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [3.0-announcement]: topics/3.0-announcement.md
 [3.1-announcement]: topics/3.1-announcement.md
 [3.2-announcement]: topics/3.2-announcement.md
+[3.3-announcement]: topics/3.3-announcement.md
 [kickstarter-announcement]: topics/kickstarter-announcement.md
 [release-notes]: topics/release-notes.md
 

docs/index.md

@@ -0,0 +1,58 @@
+# Django REST framework 3.3
+
+The 3.3 release marks the final work in the Kickstarter funded series. We'd like to offer a final resounding **thank you** to all our wonderful sponsors and supporters.
+
+The amount of work that has been achieved as a direct result of the funding is immense. We've added a huge amounts of new functionality, resolved nearly 2,000 tickets, and redesigned & refined large parts of the project.
+
+In order to continue driving REST framework forward, we're introducing [monthly paid plans](https://fund.django-rest-framework.org/topics/funding). These plans include various sponsorship rewards, and will ensure that the project remains sustainable and well supported.
+
+We strongly believe that collaboratively funded software development yields outstanding results for a relatively low investment-per-head. If you or your company use REST framework commercially, then we would strongly urge you to participate in this latest funding drive, and help us continue to build an increasingly polished & professional product.
+
+---
+
+## Release notes
+
+Significant new functionality in the 3.3 release includes:
+
+* Filters presented as HTML controls in the browsable API.
+* A [forms API][forms-api], allowing serializers to be rendered as HTML forms.
+* Django 1.9 support.
+* A [`JSONField` serializer field][jsonfield], corresponding to Django 1.9's Postgres `JSONField` model field.
+* Browsable API support [via AJAX][ajax-form], rather than server side request overloading.
+
+![Filter Controls](../img/filter-controls.png)
+
+*Example of the new filter controls*
+
+---
+
+## Supported versions
+
+This release drops support for Django 1.5 and 1.6. Django 1.7, 1.8 or 1.9 are now required.
+
+This brings our supported versions into line with Django's [currently supported versions][django-supported-versions]
+
+## Deprecations
+
+The AJAX based support for the browsable API means that there are a number of internal cleanups in the `request` class. For the vast majority of developers this should largely remain transparent:
+
+* To support form based `PUT` and `DELETE`, or to support form content types such as JSON, you should now use the [AJAX forms][ajax-forms] javascript library. This replaces the previous 'method and content type overloading' that required significant internal complexity to the request class.
+* The `accept` query parameter is no longer supported by the default content negotiation class. If you require it then you'll need to [use a custom content negotiation class](browser-enhancements.md#url-based-accept-headers).
+*  The custom `HTTP_X_HTTP_METHOD_OVERRIDE` header is no longer supported by default. If you require it then you'll need to [use custom middleware](browser-enhancements.md#http-header-based-method-overriding).
+
+The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly deprecated, and has now been removed entirely, in line with the deprecation policy.
+
+* `view.paginate_by` - Use `paginator.page_size` instead.
+* `view.page_query_param` - Use `paginator.page_query_param` instead.
+* `view.paginate_by_param` - Use `paginator.page_size_query_param` instead.
+* `view.max_paginate_by` - Use `paginator.max_page_size` instead.
+* `settings.PAGINATE_BY` - Use `paginator.page_size` instead.
+* `settings.PAGINATE_BY_PARAM` - Use `paginator.page_size_query_param` instead.
+* `settings.MAX_PAGINATE_BY` - Use `paginator.max_page_size` instead.
+
+The `ModelSerializer` and `HyperlinkedModelSerializer` classes should now include either a `fields` or `exclude` option, although the `fields = '__all__'` shortcut may be used. Failing to include either of these two options is currently pending deprecation, and will be removed entirely in the 3.5 release. This behavior brings `ModelSerializer` more closely in line with Django's `ModelForm` behavior.
+
+[forms-api]: html-and-forms.md
+[ajax-form]: https://github.com/tomchristie/ajax-form
+[jsonfield]: ../../api-guide/fields#jsonfield
+[django-supported-versions]: https://www.djangoproject.com/download/#supported-versions

docs/topics/3.3-announcement.md

@@ -42,9 +42,19 @@ You can determine your currently installed version using `pip freeze`:
 
 ### 3.3.0
 
-**Date**: NOT YET RELEASED
-
-* Removed support for Django Versions 1.5 & 1.6 ([#3421][gh3421], [#3429][gh3429])
+**Date**: [27th October 2015][3.3.0-milestone]
+
+* HTML controls for filters. ([#3315][gh3315])
+* Forms API. ([#3475][gh3475])
+* AJAX browsable API. ([#3410][gh3410])
+* Added JSONField. ([#3454][gh3454])
+* Correctly map `to_field` when creating `ModelSerializer` relational fields. ([#3526][gh3526])
+* Include keyword arguments when mapping `FilePathField` to a serializer field. ([#3536][gh3536])
+* Map appropriate model `error_messages` on `ModelSerializer` uniqueness constraints. ([#3435][gh3435])
+* Include `max_length` constraint for `ModelSerializer` fields mapped from TextField. ([#3509][gh3509])
+* Added support for Django 1.9. ([#3450][gh3450], [#3525][gh3525])
+* Removed support for Django 1.5 & 1.6. ([#3421][gh3421], [#3429][gh3429])
+* Removed 'south' migrations. ([#3495][gh3495])
 
 ## 3.2.x series
 
@@ -543,5 +553,17 @@ For older release notes, [please see the version 2.x documentation][old-release-
 [gh3415]: https://github.com/tomchristie/django-rest-framework/issues/3415
 
 <!-- 3.3.0 -->
-[gh3421]: https://github.com/tomchristie/django-rest-framework/pulls/3421
-[gh3429]: https://github.com/tomchristie/django-rest-framework/pull/3429
+[gh3315]: https://github.com/tomchristie/django-rest-framework/issues/3315
+[gh3410]: https://github.com/tomchristie/django-rest-framework/issues/3410
+[gh3435]: https://github.com/tomchristie/django-rest-framework/issues/3435
+[gh3450]: https://github.com/tomchristie/django-rest-framework/issues/3450
+[gh3454]: https://github.com/tomchristie/django-rest-framework/issues/3454
+[gh3475]: https://github.com/tomchristie/django-rest-framework/issues/3475
+[gh3495]: https://github.com/tomchristie/django-rest-framework/issues/3495
+[gh3509]: https://github.com/tomchristie/django-rest-framework/issues/3509
+[gh3421]: https://github.com/tomchristie/django-rest-framework/issues/3421
+[gh3525]: https://github.com/tomchristie/django-rest-framework/issues/3525
+[gh3526]: https://github.com/tomchristie/django-rest-framework/issues/3526
+[gh3429]: https://github.com/tomchristie/django-rest-framework/issues/3429
+[gh3536]: https://github.com/tomchristie/django-rest-framework/issues/3536
+

docs/topics/release-notes.md

@@ -57,5 +57,6 @@ pages:
      - '3.0 Announcement': 'topics/3.0-announcement.md'
      - '3.1 Announcement': 'topics/3.1-announcement.md'
      - '3.2 Announcement': 'topics/3.2-announcement.md'
+     - '3.3 Announcement': 'topics/3.3-announcement.md'
      - 'Kickstarter Announcement': 'topics/kickstarter-announcement.md'
      - 'Release Notes': 'topics/release-notes.md'

mkdocs.yml

@@ -5,7 +5,6 @@
 """
 from __future__ import unicode_literals
 
-import warnings
 from base64 import b64decode, b64encode
 from collections import OrderedDict, namedtuple
 
@@ -186,63 +185,11 @@ class PageNumberPagination(BasePagination):
 
     invalid_page_message = _('Invalid page "{page_number}": {message}.')
 
-    def _handle_backwards_compat(self, view):
-        """
-        Prior to version 3.1, pagination was handled in the view, and the
-        attributes were set there. The attributes should now be set on
-        the pagination class. The old style continues to work but is deprecated
-        and will be fully removed in version 3.3.
-        """
-        assert not (
-            getattr(view, 'pagination_serializer_class', None) or
-            getattr(api_settings, 'DEFAULT_PAGINATION_SERIALIZER_CLASS', None)
-        ), (
-            "The pagination_serializer_class attribute and "
-            "DEFAULT_PAGINATION_SERIALIZER_CLASS setting have been removed as "
-            "part of the 3.1 pagination API improvement. See the pagination "
-            "documentation for details on the new API."
-        )
-
-        for (settings_key, attr_name) in (
-            ('PAGINATE_BY', 'page_size'),
-            ('PAGINATE_BY_PARAM', 'page_size_query_param'),
-            ('MAX_PAGINATE_BY', 'max_page_size')
-        ):
-            value = getattr(api_settings, settings_key, None)
-            if value is not None:
-                setattr(self, attr_name, value)
-                warnings.warn(
-                    "The `%s` settings key is deprecated. "
-                    "Use the `%s` attribute on the pagination class instead." % (
-                        settings_key, attr_name
-                    ),
-                    DeprecationWarning,
-                )
-
-        for (view_attr, attr_name) in (
-            ('paginate_by', 'page_size'),
-            ('page_query_param', 'page_query_param'),
-            ('paginate_by_param', 'page_size_query_param'),
-            ('max_paginate_by', 'max_page_size')
-        ):
-            value = getattr(view, view_attr, None)
-            if value is not None:
-                setattr(self, attr_name, value)
-                warnings.warn(
-                    "The `%s` view attribute is deprecated. "
-                    "Use the `%s` attribute on the pagination class instead." % (
-                        view_attr, attr_name
-                    ),
-                    DeprecationWarning,
-                )
-
     def paginate_queryset(self, queryset, request, view=None):
         """
         Paginate a queryset if required, either returning a
         page object, or `None` if pagination is not configured for this view.
         """
-        self._handle_backwards_compat(view)
-
         page_size = self.get_page_size(request)
         if not page_size:
             return None

rest_framework/pagination.py

@@ -111,11 +111,6 @@
     'COMPACT_JSON': True,
     'COERCE_DECIMAL_TO_STRING': True,
     'UPLOADED_FILES_USE_URL': True,
-
-    # Pending deprecation:
-    'PAGINATE_BY': None,
-    'PAGINATE_BY_PARAM': None,
-    'MAX_PAGINATE_BY': None
 }
 
 

rest_framework/settings.py

@@ -147,41 +147,6 @@ def test_unpaginated_list(self):
         assert response.data == list(range(1, 101))
 
 
-class TestDeprecatedStylePagination:
-    """
-    Integration tests for deprecated style of setting pagination
-    attributes on the view.
-    """
-
-    def setup(self):
-        class PassThroughSerializer(serializers.BaseSerializer):
-            def to_representation(self, item):
-                return item
-
-        class ExampleView(generics.ListAPIView):
-            serializer_class = PassThroughSerializer
-            queryset = range(1, 101)
-            pagination_class = pagination.PageNumberPagination
-            paginate_by = 20
-            page_query_param = 'page_number'
-
-        self.view = ExampleView.as_view()
-
-    def test_paginate_by_attribute_on_view(self):
-        request = factory.get('/?page_number=2')
-        response = self.view(request)
-        assert response.status_code == status.HTTP_200_OK
-        assert response.data == {
-            'results': [
-                21, 22, 23, 24, 25, 26, 27, 28, 29, 30,
-                31, 32, 33, 34, 35, 36, 37, 38, 39, 40
-            ],
-            'previous': 'http://testserver/',
-            'next': 'http://testserver/?page_number=3',
-            'count': 100
-        }
-
-
 class TestPageNumberPagination:
     """
     Unit tests for `pagination.PageNumberPagination`.