Merge master

Author: tomchristie

.gitignore

@@ -14,3 +14,4 @@ MANIFEST
 
 !.gitignore
 !.travis.yml
+!.isort.cfg

.isort.cfg

@@ -0,0 +1,6 @@
+[settings]
+skip=.tox
+atomic=true
+multi_line_output=5
+known_third_party=pytest,django
+known_first_party=rest_framework

.travis.yml

@@ -3,7 +3,7 @@ language: python
 sudo: false
 
 env:
-    - TOX_ENV=py27-flake8
+    - TOX_ENV=py27-lint
     - TOX_ENV=py27-docs
     - TOX_ENV=py34-django18
     - TOX_ENV=py33-django18

CONTRIBUTING.md

@@ -38,7 +38,7 @@ Some tips on good issue reporting:
 
 ## Triaging issues
 
-Getting involved in triaging incoming issues is a good way to start contributing.  Every single ticket that comes into the ticket tracker needs to be reviewed in order to determine what the next steps should be.  Anyone can help out with this, you just need to be willing to
+Getting involved in triaging incoming issues is a good way to start contributing.  Every single ticket that comes into the ticket tracker needs to be reviewed in order to determine what the next steps should be.  Anyone can help out with this, you just need to be willing to:
 
 * Read through the ticket - does it make sense, is it missing any context that would help explain it better?
 * Is the ticket reported in the correct place, would it be better suited as a discussion on the discussion group?

README.md

@@ -159,7 +159,7 @@ Send a description of the issue via email to [rest-framework-security@googlegrou
 
 [build-status-image]: https://secure.travis-ci.org/tomchristie/django-rest-framework.svg?branch=master
 [travis]: http://travis-ci.org/tomchristie/django-rest-framework?branch=master
-[pypi-version]: https://pypip.in/version/djangorestframework/badge.svg
+[pypi-version]: https://img.shields.io/pypi/v/djangorestframework.svg
 [pypi]: https://pypi.python.org/pypi/djangorestframework
 [twitter]: https://twitter.com/_tomchristie
 [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework

docs/api-guide/authentication.md

@@ -247,6 +247,10 @@ Unauthenticated responses that are denied permission will result in an `HTTP 403
 
 If you're using an AJAX style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as `PUT`, `PATCH`, `POST` or `DELETE` requests.  See the [Django CSRF documentation][csrf-ajax] for more details.
 
+**Warning**: Always use Django's standard login view when creating login pages. This will ensure your login views are properly protected.
+
+CSRF validation in REST framework works slightly differently to standard Django due to the need to support both session and non-session based authentication to the same views. This means that only authenticated requests require CSRF tokens, and anonymous requests may be sent without CSRF tokens. This behaviour is not suitable for login views, which should always have CSRF validation applied.
+
 # Custom authentication
 
 To implement a custom authentication scheme, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method.  The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise.

docs/api-guide/fields.md

@@ -20,6 +20,8 @@ Each serializer field class constructor takes at least these arguments.  Some Fi
 
 ### `read_only`
 
+Read-only fields are included in the API output, but should not be included in the input during create or update operations. Any 'read_only' fields that are incorrectly included in the serializer input will be ignored. 
+
 Set this to `True` to ensure that the field is used when serializing a representation, but is not used when creating or updating an instance during deserialization.
 
 Defaults to `False`
@@ -183,6 +185,26 @@ A field that ensures the input is a valid UUID string. The `to_internal_value` m
 
     "de305d54-75b4-431b-adb2-eb6b9e546013"
 
+**Signature:** `UUIDField(format='hex_verbose')`
+
+- `format`: Determines the representation format of the uuid value
+    - `'hex_verbose'` - The cannoncical hex representation, including hyphens: `"5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
+    - `'hex'` - The compact hex representation of the UUID, not including hyphens: `"5ce0e9a55ffa654bcee01238041fb31a"`
+    - `'int'` - A 128 bit integer representation of the UUID: `"123456789012312313134124512351145145114"`
+    - `'urn'` - RFC 4122 URN representation of the UUID: `"urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a"`
+  Changing the `format` parameters only affects representation values. All formats are accepted by `to_internal_value`
+
+## IPAddressField
+
+A field that ensures the input is a valid IPv4 or IPv6 string.
+
+Corresponds to `django.forms.fields.IPAddressField` and `django.forms.fields.GenericIPAddressField`.
+
+**Signature**: `IPAddressField(protocol='both', unpack_ipv4=False, **options)`
+
+- `protocol` Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.
+- `unpack_ipv4` Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.
+
 ---
 
 # Numeric fields
@@ -302,6 +324,18 @@ Corresponds to `django.db.models.fields.TimeField`
 
 Format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`)
 
+## DurationField
+
+A Duration representation.
+Corresponds to `django.db.models.fields.DurationField`
+
+The `validated_data` for these fields will contain a `datetime.timedelta` instance.
+The representation is a string following this format `'[DD] [HH:[MM:]]ss[.uuuuuu]'`.
+
+**Note:** This field is only available with Django versions >= 1.8.
+
+**Signature:** `DurationField()`
+
 ---
 
 # Choice selection fields

docs/api-guide/filtering.md

@@ -149,6 +149,7 @@ If all you need is simple equality-based filtering, you can set a `filter_fields
     class ProductList(generics.ListAPIView):
         queryset = Product.objects.all()
         serializer_class = ProductSerializer
+        filter_backends = (filters.DjangoFilterBackend,)
         filter_fields = ('category', 'in_stock')
 
 This will automatically create a `FilterSet` class for the given fields, and will allow you to make requests such as:
@@ -174,6 +175,7 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
     class ProductList(generics.ListAPIView):
         queryset = Product.objects.all()
         serializer_class = ProductSerializer
+        filter_backends = (filters.DjangoFilterBackend,)
         filter_class = ProductFilter
 
 

docs/api-guide/generic-views.md

@@ -124,21 +124,24 @@ For example:
 
 Note that if your API doesn't include any object level permissions, you may optionally exclude the `self.check_object_permissions`, and simply return the object from the `get_object_or_404` lookup.
 
-#### `get_filter_backends(self)`
-
-Returns the classes that should be used to filter the queryset. Defaults to returning the `filter_backends` attribute.
-
-May be overridden to provide more complex behavior with filters, such as using different (or even exclusive) lists of filter_backends depending on different criteria.
-
-For example:
-
-    def get_filter_backends(self):
-        if "geo_route" in self.request.query_params:
-            return (GeoRouteFilter, CategoryFilter)
-        elif "geo_point" in self.request.query_params:
-            return (GeoPointFilter, CategoryFilter)
-
-        return (CategoryFilter,)
+#### `filter_queryset(self, queryset)`       
+       
+Given a queryset, filter it with whichever filter backends are in use, returning a new queryset.   
+        
+For example:       
+       
+    def filter_queryset(self, queryset):
+        filter_backends = (CategoryFilter,)
+        
+        if 'geo_route' in self.request.query_params:
+            filter_backends = (GeoRouteFilter, CategoryFilter)
+        elif 'geo_point' in self.request.query_params:
+            filter_backends = (GeoPointFilter, CategoryFilter)
+        
+        for backend in list(filter_backends):
+            queryset = backend().filter_queryset(self.request, queryset, view=self)
+        
+        return queryset
 
 #### `get_serializer_class(self)`
 
@@ -192,7 +195,7 @@ These override points are also particularly useful for adding behavior that occu
 You won't typically need to override the following methods, although you might need to call into them if you're writing custom views using `GenericAPIView`.
 
 * `get_serializer_context(self)` - Returns a dictionary containing any extra context that should be supplied to the serializer.  Defaults to including `'request'`, `'view'` and `'format'` keys.
-* `get_serializer(self, instance=None, data=None, files=None, many=False, partial=False, allow_add_remove=False)` - Returns a serializer instance.
+* `get_serializer(self, instance=None, data=None, many=False, partial=False)` - Returns a serializer instance.
 * `get_paginated_response(self, data)` - Returns a paginated style `Response` object.
 * `paginate_queryset(self, queryset)` - Paginate a queryset if required, either returning a page object, or `None` if pagination is not configured for this view.
 * `filter_queryset(self, queryset)` - Given a queryset, filter it with whichever filter backends are in use, returning a new queryset.
@@ -391,6 +394,10 @@ The following third party packages provide additional generic view implementatio
 
 The [django-rest-framework-bulk package][django-rest-framework-bulk] implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests.
 
+## Django Rest Multiple Models
+
+[Django Rest Multiple Models][django-rest-multiple-models] provides a generic view (and mixin) for sending multiple serialized models and/or querysets via a single API request.
+
 
 [cite]: https://docs.djangoproject.com/en/dev/ref/class-based-views/#base-vs-generic-views
 [GenericAPIView]: #genericapiview
@@ -400,3 +407,6 @@ The [django-rest-framework-bulk package][django-rest-framework-bulk] implements
 [UpdateModelMixin]: #updatemodelmixin
 [DestroyModelMixin]: #destroymodelmixin
 [django-rest-framework-bulk]: https://github.com/miki725/django-rest-framework-bulk
+[django-rest-multiple-models]: https://github.com/Axiologue/DjangoRestMultipleModels
+
+

docs/api-guide/metadata.md

@@ -98,6 +98,12 @@ The following class could be used to limit the information that is returned to `
                 'description': view.get_view_description()
             }
 
+Then configure your settings to use this custom class:
+
+    REST_FRAMEWORK = {
+        'DEFAULT_METADATA_CLASS': 'myproject.apps.core.MinimalMetadata'
+    }
+
 [cite]: http://tools.ietf.org/html/rfc7231#section-4.3.7
 [no-options]: https://www.mnot.net/blog/2012/10/29/NO_OPTIONS
 [json-schema]: http://json-schema.org/

docs/api-guide/pagination.md

@@ -246,11 +246,11 @@ Let's modify the built-in `PageNumberPagination` style, so that instead of inclu
             previous_url = self.get_previous_link()
 
             if next_url is not None and previous_url is not None:
-                link = '<{next_url}; rel="next">, <{previous_url}; rel="prev">'
+                link = '<{next_url}>; rel="next", <{previous_url}>; rel="prev"'
             elif next_url is not None:
-                link = '<{next_url}; rel="next">'
+                link = '<{next_url}>; rel="next"'
             elif previous_url is not None:
-                link = '<{previous_url}; rel="prev">'
+                link = '<{previous_url}>; rel="prev"'
             else:
                 link = ''
 

docs/api-guide/parsers.md

@@ -144,17 +144,16 @@ By default this will include the following keys: `view`, `request`, `args`, `kwa
 The following is an example plaintext parser that will populate the `request.data` property with a string representing the body of the request.
 
     class PlainTextParser(BaseParser):
-    """
-    Plain text parser.
-    """
-
-    media_type = 'text/plain'
-
-    def parse(self, stream, media_type=None, parser_context=None):
         """
-        Simply return a string representing the body of the request.
+        Plain text parser.
         """
-        return stream.read()
+        media_type = 'text/plain'
+
+        def parse(self, stream, media_type=None, parser_context=None):
+            """
+            Simply return a string representing the body of the request.
+            """
+            return stream.read()
 
 ---
 

docs/api-guide/permissions.md

@@ -150,7 +150,7 @@ Similar to `DjangoModelPermissions`, but also allows unauthenticated users to ha
 
 This permission class ties into Django's standard [object permissions framework][objectpermissions] that allows per-object permissions on models.  In order to use this permission class, you'll also need to add a permission backend that supports object-level permissions, such as [django-guardian][guardian].
 
-As with `DjangoModelPermissions`, this permission must only be applied to views that have a `.queryset` property. Authorization will only be granted if the user *is authenticated* and has the *relevant per-object permissions* and *relevant model permissions* assigned.
+As with `DjangoModelPermissions`, this permission must only be applied to views that have a `.queryset` property or `.get_queryset()` method. Authorization will only be granted if the user *is authenticated* and has the *relevant per-object permissions* and *relevant model permissions* assigned.
 
 * `POST` requests require the user to have the `add` permission on the model instance.
 * `PUT` and `PATCH` requests require the user to have the `change` permission on the model instance.
@@ -190,6 +190,16 @@ If you need to test if a request is a read operation or a write operation, you s
 
 ---
 
+Custom permissions will raise a `PermissionDenied` exception if the test fails. To change the error message associated with the exception, implement a `message` attribute directly on your custom permission. Otherwise the `default_detail` attribute from `PermissionDenied` will be used.
+    
+    from rest_framework import permissions
+
+    class CustomerAccessPermission(permissions.BasePermission):
+        message = 'Adding customers not allowed.'
+        
+        def has_permission(self, request, view):
+             ...
+        
 ## Examples
 
 The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted.
@@ -233,10 +243,6 @@ Also note that the generic views will only check the object-level permissions fo
 
 The following third party packages are also available.
 
-## DRF Any Permissions
-
-The [DRF Any Permissions][drf-any-permissions] packages provides a different permission behavior in contrast to REST framework.  Instead of all specified permissions being required, only one of the given permissions has to be true in order to get access to the view.
-
 ## Composed Permissions
 
 The [Composed Permissions][composed-permissions] package provides a simple way to define complex and multi-depth (with logic operators) permission objects, using small and reusable components.

docs/api-guide/relations.md

@@ -116,6 +116,8 @@ By default this field is read-write, although you can change this behavior using
 * `queryset` - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set `read_only=True`.
 * `many` - If applied to a to-many relationship, you should set this argument to `True`.
 * `allow_null` - If set to `True`, the field will accept values of `None` or the empty string for nullable relationships. Defaults to `False`.
+* `pk_field` - Set to a field to control serialization/deserialization of the primary key's value. For example, `pk_field=UUIDField(format='hex')` would serialize a UUID primary key into its compact hex representation.
+
 
 ## HyperlinkedRelatedField
 
@@ -254,17 +256,64 @@ For example, the following serializer:
 
 Would serialize to a nested representation like this:
 
+    >>> album = Album.objects.create(album_name="The Grey Album", artist='Danger Mouse')
+    >>> Track.objects.create(album=album, order=1, title='Public Service Announcement', duration=245)
+    <Track: Track object>
+    >>> Track.objects.create(album=album, order=2, title='What More Can I Say', duration=264)
+    <Track: Track object>
+    >>> Track.objects.create(album=album, order=3, title='Encore', duration=159)
+    <Track: Track object>
+    >>> serializer = AlbumSerializer(instance=album)
+    >>> serializer.data
     {
         'album_name': 'The Grey Album',
         'artist': 'Danger Mouse',
         'tracks': [
-            {'order': 1, 'title': 'Public Service Announcement'},
-            {'order': 2, 'title': 'What More Can I Say'},
-            {'order': 3, 'title': 'Encore'},
+            {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},
+            {'order': 2, 'title': 'What More Can I Say', 'duration': 264},
+            {'order': 3, 'title': 'Encore', 'duration': 159},
             ...
         ],
     }
 
+# Writable nested serializers
+
+Be default nested serializers are read-only. If you want to to support write-operations to a nested serializer field you'll need to create either or both of the `create()` and/or `update()` methods, in order to explicitly specify how the child relationships should be saved.
+
+    class TrackSerializer(serializers.ModelSerializer):
+        class Meta:
+            model = Track
+            fields = ('order', 'title')
+
+    class AlbumSerializer(serializers.ModelSerializer):
+        tracks = TrackSerializer(many=True)
+
+        class Meta:
+            model = Album
+            fields = ('album_name', 'artist', 'tracks')
+
+        def create(self, validated_data):
+            tracks_data = validated_data.pop('tracks')
+            album = Album.objects.create(**validated_data)
+            for track_data in tracks_data:
+                Track.objects.create(album=album, **track_data)
+            return album
+
+    >>> data = {
+        'album_name': 'The Grey Album',
+        'artist': 'Danger Mouse',
+        'tracks': [
+            {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},
+            {'order': 2, 'title': 'What More Can I Say', 'duration': 264},
+            {'order': 3, 'title': 'Encore', 'duration': 159},
+        ],
+    }
+    >>> serializer = AlbumSerializer(data=data)
+    >>> serializer.is_valid()
+    True
+    >>> serializer.save()
+    <Album: Album object>
+
 # Custom relational fields
 
 To implement a custom relational field, you should override `RelatedField`, and implement the `.to_representation(self, value)` method. This method takes the target of the field as the `value` argument, and should return the representation that should be used to serialize the target. The `value` argument will typically be a model instance.