Merge remote-tracking branch 'origin/master' into markdown-compat

Conflicts:
	requirements/requirements-optionals.txt

Author: xordoquy

.isort.cfg

@@ -2,5 +2,6 @@
 skip=.tox
 atomic=true
 multi_line_output=5
+known_standard_library=types
 known_third_party=pytest,django
 known_first_party=rest_framework

.tx/config

@@ -1,5 +1,6 @@
 [main]
 host = https://www.transifex.com
+lang_map = sr@latin:sr_Latn, zh-Hans:zh_Hans, zh-Hant:zh_Hant
 
 [django-rest-framework.djangopo]
 file_filter = rest_framework/locale/<lang>/LC_MESSAGES/django.po

LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright (c) 2011-2015, Tom Christie
+Copyright (c) 2011-2016, Tom Christie
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/api-guide/authentication.md

@@ -165,6 +165,8 @@ The `curl` command line tool may be useful for testing token authenticated APIs.
 
 #### Generating Tokens
 
+##### By using signals
+
 If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal.
 
     from django.conf import settings
@@ -187,6 +189,8 @@ If you've already created some users, you can generate tokens for all existing u
     for user in User.objects.all():
         Token.objects.get_or_create(user=user)
 
+##### By exposing an api endpoint
+
 When using `TokenAuthentication`, you may want to provide a mechanism for clients to obtain a token given the username and password.  REST framework provides a built-in view to provide this behavior.  To use it, add the `obtain_auth_token` view to your URLconf:
 
     from rest_framework.authtoken import views
@@ -202,6 +206,17 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a
 
 Note that the default `obtain_auth_token` view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings.  If you need a customized version of the `obtain_auth_token` view, you can do so by overriding the `ObtainAuthToken` view class, and using that in your url conf instead.
 
+##### With Django admin
+
+It is also possible to create Tokens manually through admin interface. In case you are using a large user base, we recommend that you monkey patch the `TokenAdmin` class to customize it to your needs, more specifically by declaring the `user` field as `raw_field`.
+
+`your_app/admin.py`:
+
+    from rest_framework.authtoken.admin import TokenAdmin
+
+    TokenAdmin.raw_id_fields = ('user',)
+
+
 #### Schema migrations
 
 The `rest_framework.authtoken` app includes both Django native migrations (for Django versions >1.7) and South migrations (for Django versions <1.7) that will create the authtoken table.

docs/api-guide/filtering.md

@@ -145,11 +145,11 @@ To use REST framework's `DjangoFilterBackend`, first install `django-filter`.
 
     pip install django-filter
 
-If you are using the browsable API or admin API you may also want to install `crispy-forms`, which will enhance the presentation of the filter forms in HTML views, by allowing them to render Bootstrap 3 HTML.
+If you are using the browsable API or admin API you may also want to install `django-crispy-forms`, which will enhance the presentation of the filter forms in HTML views, by allowing them to render Bootstrap 3 HTML.
 
     pip install django-crispy-forms
 
-With crispy forms installed, the browsable API will present a filtering control for `DjangoFilterBackend`, like so:
+With crispy forms installed and added to Django's `INSTALLED_APPS`, the browsable API will present a filtering control for `DjangoFilterBackend`, like so:
 
 ![Django Filter](../img/django-filter.png)
 
@@ -177,7 +177,7 @@ For more advanced filtering requirements you can specify a `FilterSet` class tha
     from rest_framework import filters
     from rest_framework import generics
 
-    class ProductFilter(django_filters.FilterSet):
+    class ProductFilter(filters.FilterSet):
         min_price = django_filters.NumberFilter(name="price", lookup_type='gte')
         max_price = django_filters.NumberFilter(name="price", lookup_type='lte')
         class Meta:
@@ -199,12 +199,12 @@ You can also span relationships using `django-filter`, let's assume that each
 product has foreign key to `Manufacturer` model, so we create filter that
 filters using `Manufacturer` name. For example:
 
-    import django_filters
     from myapp.models import Product
     from myapp.serializers import ProductSerializer
+    from rest_framework import filters
     from rest_framework import generics
 
-    class ProductFilter(django_filters.FilterSet):
+    class ProductFilter(filters.FilterSet):
         class Meta:
             model = Product
             fields = ['category', 'in_stock', 'manufacturer__name']
@@ -218,9 +218,10 @@ This is nice, but it exposes the Django's double underscore convention as part o
     import django_filters
     from myapp.models import Product
     from myapp.serializers import ProductSerializer
+    from rest_framework import filters
     from rest_framework import generics
 
-    class ProductFilter(django_filters.FilterSet):
+    class ProductFilter(filters.FilterSet):
         manufacturer = django_filters.CharFilter(name="manufacturer__name")
 
         class Meta:

docs/api-guide/generic-views.md

@@ -35,14 +35,6 @@ For more complex cases you might also want to override various methods on the vi
         serializer_class = UserSerializer
         permission_classes = (IsAdminUser,)
 
-        def get_paginate_by(self):
-            """
-            Use smaller pagination for HTML representations.
-            """
-            if self.request.accepted_renderer.format == 'html':
-                return 20
-            return 100
-
         def list(self, request):
             # Note the use of `get_queryset()` instead of `self.queryset`
             queryset = self.get_queryset()
@@ -125,22 +117,22 @@ 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.
 
 #### `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)`
@@ -156,19 +148,6 @@ For example:
             return FullAccountSerializer
         return BasicAccountSerializer
 
-#### `get_paginate_by(self)`
-
-Returns the page size to use with pagination.  By default this uses the `paginate_by` attribute, and may be overridden by the client if the `paginate_by_param` attribute is set.
-
-You may want to override this method to provide more complex behavior, such as modifying page sizes based on the media type of the response.
-
-For example:
-
-    def get_paginate_by(self):
-        if self.request.accepted_renderer.format == 'html':
-            return 20
-        return 100
-
 **Save and deletion hooks**:
 
 The following methods are provided by the mixin classes, and provide easy overriding of the object save or deletion behavior.
@@ -416,5 +395,3 @@ The [django-rest-framework-bulk package][django-rest-framework-bulk] implements
 [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/pagination.md

@@ -17,6 +17,8 @@ The built-in styles currently all use links included as part of the content of t
 
 Pagination is only performed automatically if you're using the generic views or viewsets. If you're using a regular `APIView`, you'll need to call into the pagination API yourself to ensure you return a paginated response. See the source code for the `mixins.ListModelMixin` and `generics.GenericAPIView` classes for an example.
 
+Pagination can be turned off by setting the pagination class to `None`.
+
 ## Setting the pagination style
 
 The default pagination style may be set globally, using the `DEFAULT_PAGINATION_CLASS` settings key. For example, to use the built-in limit/offset pagination, you would do:
@@ -95,6 +97,7 @@ The `PageNumberPagination` class includes a number of attributes that may be ove
 
 To set these attributes you should override the `PageNumberPagination` class, and then enable your custom pagination class as above.
 
+* `django_paginator_class` - The Django Paginator class to use. Default is `django.core.paginator.Paginator`, which should be fine for most use cases.
 * `page_size` - A numeric value indicating the page size. If set, this overrides the `PAGE_SIZE` setting. Defaults to the same value as the `PAGE_SIZE` settings key.
 * `page_query_param` - A string value indicating the name of the query parameter to use for the pagination control.
 * `page_size_query_param` - If set, this is a string value indicating the name of a query parameter that allows the client to set the page size on a per-request basis. Defaults to `None`, indicating that the client may not control the requested page size.
@@ -175,7 +178,7 @@ Proper usage of cursor pagination should have an ordering field that satisfies t
 * Should be a non-nullable value that can be coerced to a string.
 * The field should have a database index.
 
-Using an ordering field that does not satisfy these constraints will generally still work, but you'll be loosing some of the benefits of cursor pagination.
+Using an ordering field that does not satisfy these constraints will generally still work, but you'll be losing some of the benefits of cursor pagination.
 
 For more technical details on the implementation we use for cursor pagination, the ["Building cursors for the Disqus API"][disqus-cursor-api] blog post gives a good overview of the basic approach.
 

docs/api-guide/parsers.md

@@ -51,6 +51,9 @@ using the `APIView` class based views.
             return Response({'received data': request.data})
 
 Or, if you're using the `@api_view` decorator with function based views.
+    
+    from rest_framework.decorators import api_view
+    from rest_framework.decorators import parser_classes
 
     @api_view(['POST'])
     @parser_classes((JSONParser,))

docs/api-guide/permissions.md

@@ -100,6 +100,8 @@ Or, if you're using the `@api_view` decorator with function based views.
         }
         return Response(content)
 
+__Note:__ when you set new permission classes through class attribute or decorators you're telling the view to ignore the default list set over the __settings.py__ file.
+
 ---
 
 # API Reference

docs/api-guide/relations.md

@@ -459,7 +459,7 @@ In cases where the cutoff is being enforced you may want to instead use a plain
 
     assigned_to = serializers.SlugRelatedField(
        queryset=User.objects.all(),
-       slug field='username',
+       slug_field='username',
        style={'base_template': 'input.html'}
     )
 

docs/api-guide/renderers.md

@@ -187,6 +187,15 @@ This renderer is suitable for CRUD-style web APIs that should also present a use
 
 Note that views that have nested or list serializers for their input won't work well with the `AdminRenderer`, as the HTML forms are unable to properly support them.
 
+**Note**: The `AdminRenderer` is only able to include links to detail pages when a properly configured `URL_FIELD_NAME` (`url` by default) attribute is present in the data. For `HyperlinkedModelSerializer` this will be the case, but for `ModelSerializer` or plain `Serializer` classes you'll need to make sure to include the field explicitly. For example here we use models `get_absolute_url` method:
+
+    class AccountSerializer(serializers.ModelSerializer):
+        url = serializers.CharField(source='get_absolute_url', read_only=True)
+
+        class Meta:
+            model = Account
+
+
 **.media_type**: `text/html`
 
 **.format**: `'.admin'`

docs/api-guide/serializers.md

@@ -774,6 +774,8 @@ To support multiple updates you'll need to do so explicitly. When writing your m
 * How should insertions be handled? Are they invalid, or do they create new objects?
 * How should removals be handled? Do they imply object deletion, or removing a relationship? Should they be silently ignored, or are they invalid?
 * How should ordering be handled? Does changing the position of two items imply any state change or is it ignored?
+ 
+You will need to add an explicit `id` field to the instance serializer. The default implicitly-generated `id` field is marked as `read_only`. This causes it to be removed on updates. Once you declare it explicitly, it will be available in the list serializer's `update` method.
 
 Here's an example of how you might choose to implement multiple updates:
 
@@ -800,7 +802,13 @@ Here's an example of how you might choose to implement multiple updates:
             return ret
 
     class BookSerializer(serializers.Serializer):
+        # We need to identify elements in the list using their primary key,
+        # so use a writable field here, rather than the default which would be read-only.
+        id = serializers.IntegerField()
+
         ...
+        id = serializers.IntegerField(required=False)
+    
         class Meta:
             list_serializer_class = BookListSerializer
 

docs/api-guide/status-codes.md

@@ -89,6 +89,7 @@ The 4xx class of status code is intended for cases in which the client seems to
     HTTP_428_PRECONDITION_REQUIRED
     HTTP_429_TOO_MANY_REQUESTS
     HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE
+    HTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS
 
 ## Server Error - 5xx
 

docs/api-guide/versioning.md

@@ -130,12 +130,12 @@ Your URL conf must include a pattern that matches the version with a `'version'`
 
     urlpatterns = [
         url(
-            r'^(?P<version>[v1|v2]+)/bookings/$',
+            r'^(?P<version>(v1|v2))/bookings/$',
             bookings_list,
             name='bookings-list'
         ),
         url(
-            r'^(?P<version>[v1|v2]+)/bookings/(?P<pk>[0-9]+)/$',
+            r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
             bookings_detail,
             name='bookings-detail'
         )

docs/img/drfdocs.png

@@ -86,7 +86,7 @@ If you're intending to use the browsable API you'll probably also want to add RE
         url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
     ]
 
-Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace.
+Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. You may leave out the namespace in Django 1.9+, and REST framework will set it for you.
 
 ## Example
 
@@ -231,7 +231,7 @@ Send a description of the issue via email to [rest-framework-security@googlegrou
 
 ## License
 
-Copyright (c) 2011-2015, Tom Christie
+Copyright (c) 2011-2016, Tom Christie
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -258,6 +258,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [eventbrite]: https://www.eventbrite.co.uk/about/
 [markdown]: http://pypi.python.org/pypi/Markdown/
 [django-filter]: http://pypi.python.org/pypi/django-filter
+[django-crispy-forms]: https://github.com/maraujop/django-crispy-forms
 [django-guardian]: https://github.com/lukaszb/django-guardian
 [0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X
 [image]: img/quickstart.png

docs/img/rest-framework-docs.png

@@ -17,7 +17,7 @@ By default, the API will return the format specified by the headers, which in th
 
 ## Customizing
 
-The browsable API is built with [Twitter's Bootstrap][bootstrap] (v 2.1.1), making it easy to customize the look-and-feel.
+The browsable API is built with [Twitter's Bootstrap][bootstrap] (v 3.3.5), making it easy to customize the look-and-feel.
 
 To customize the default style, create a template called `rest_framework/api.html` that extends from `rest_framework/base.html`.  For example:
 

docs/index.md

@@ -12,23 +12,29 @@ The most common way to document Web APIs today is to produce documentation that
 
 ---
 
-#### Django REST Swagger
+#### DRF Docs
 
-Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool.  The package produces well presented API documentation, and includes interactive tools for testing API endpoints.
+[DRF Docs][drfdocs-repo] allows you to document Web APIs made with Django REST Framework and it is authored by Emmanouil Konstantinidis. It's made to work out of the box and its setup should not take more than a couple of minutes. Complete documentation can be found on the [website][drfdocs-website] while there is also a [demo][drfdocs-demo] available for people to see what it looks like.
 
-The package is fully documented, well supported, and comes highly recommended.
+Features include customizing the template with your branding, settings for hiding the docs depending on the environment and more.
 
-Django REST Swagger supports REST framework versions 2.3 and above.
+Both this package and Django REST Swagger are fully documented, well supported, and come highly recommended.
 
-![Screenshot - Django REST Swagger][image-django-rest-swagger]
+![Screenshot - DRF docs][image-drf-docs]
 
 ---
 
-#### REST Framework Docs
+#### Django REST Swagger
 
-The [REST Framework Docs][rest-framework-docs] package is an earlier project, also by Marc Gibbons, that offers clean, simple autogenerated documentation for your API.
+Marc Gibbons' [Django REST Swagger][django-rest-swagger] integrates REST framework with the [Swagger][swagger] API documentation tool.  The package produces well presented API documentation, and includes interactive tools for testing API endpoints.
 
-![Screenshot - REST Framework Docs][image-rest-framework-docs]
+Django REST Swagger supports REST framework versions 2.3 and above.
+
+Mark is also the author of the [REST Framework Docs][rest-framework-docs] package which offers clean, simple autogenerated documentation for your API but is deprecated and has moved to Django REST Swagger.
+
+Both this package and DRF docs are fully documented, well supported, and come highly recommended.
+
+![Screenshot - Django REST Swagger][image-django-rest-swagger]
 
 ---
 
@@ -100,13 +106,16 @@ In this approach, rather than documenting the available API endpoints up front,
 To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type.  The [REST, Hypermedia & HATEOAS][hypermedia-docs] section of the documentation includes pointers to background reading, as well as links to various hypermedia formats.
 
 [cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
+[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs
+[drfdocs-website]: http://www.drfdocs.com/
+[drfdocs-demo]: http://demo.drfdocs.com/
 [django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger
 [swagger]: https://developers.helloreverb.com/swagger/
 [rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs
 [apiary]: http://apiary.io/
 [markdown]: http://daringfireball.net/projects/markdown/
 [hypermedia-docs]: rest-hypermedia-hateoas.md
+[image-drf-docs]: ../img/drfdocs.png
 [image-django-rest-swagger]: ../img/django-rest-swagger.png
-[image-rest-framework-docs]: ../img/rest-framework-docs.png
 [image-apiary]: ../img/apiary.png
 [image-self-describing-api]: ../img/self-describing.png