diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 000000000..d7c23d635 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +custom: https://fund.django-rest-framework.org/topics/funding/ diff --git a/.travis.yml b/.travis.yml index 04a5ff99e..a4a4ed8b5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,9 +5,6 @@ matrix: fast_finish: true include: - - { python: "3.4", env: DJANGO=1.11 } - - { python: "3.4", env: DJANGO=2.0 } - - { python: "3.5", env: DJANGO=1.11 } - { python: "3.5", env: DJANGO=2.0 } - { python: "3.5", env: DJANGO=2.1 } diff --git a/README.md b/README.md index 7d0bdd2ad..13ad47aef 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,10 @@ The initial aim is to provide a single full-time position on REST framework. [![][rollbar-img]][rollbar-url] [![][cadre-img]][cadre-url] [![][kloudless-img]][kloudless-url] -[![][release-history-img]][release-history-url] +[![][esg-img]][esg-url] [![][lightson-img]][lightson-url] -Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Rollbar][rollbar-url], [Cadre][cadre-url], [Kloudless][kloudless-url], [Release History][release-history-url], and [Lights On Software][lightson-url]. +Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Sentry][sentry-url], [Stream][stream-url], [Rollbar][rollbar-url], [Cadre][cadre-url], [Kloudless][kloudless-url], [ESG][esg-url], and [Lights On Software][lightson-url]. --- @@ -53,7 +53,7 @@ There is a live example API for testing purposes, [available here][sandbox]. # Requirements -* Python (3.4, 3.5, 3.6, 3.7) +* Python (3.5, 3.6, 3.7) * Django (1.11, 2.0, 2.1, 2.2) We **highly recommend** and only officially support the latest patch release of @@ -67,10 +67,10 @@ Install using `pip`... Add `'rest_framework'` to your `INSTALLED_APPS` setting. - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) + ] # Example @@ -96,7 +96,7 @@ from rest_framework import serializers, viewsets, routers class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User - fields = ('url', 'username', 'email', 'is_staff') + fields = ['url', 'username', 'email', 'is_staff'] # ViewSets define the view behavior. @@ -123,10 +123,10 @@ We'd also like to configure a couple of settings for our API. Add the following to your `settings.py` module: ```python -INSTALLED_APPS = ( +INSTALLED_APPS = [ ... # Make sure to include the default installed apps here. 'rest_framework', -) +] REST_FRAMEWORK = { # Use Django's standard `django.contrib.auth` permissions, @@ -175,9 +175,7 @@ You may also want to [follow the author on Twitter][twitter]. # Security -If you believe you've found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**. - -Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail]. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. +Please see the [security policy][security-policy]. [build-status-image]: https://secure.travis-ci.org/encode/django-rest-framework.svg?branch=master [travis]: https://travis-ci.org/encode/django-rest-framework?branch=master @@ -199,17 +197,15 @@ Send a description of the issue via email to [rest-framework-security@googlegrou [cadre-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/cadre-readme.png [load-impact-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/load-impact-readme.png [kloudless-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/kloudless-readme.png -[release-history-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/release-history.png +[esg-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/esg-readme.png [lightson-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/lightson-readme.png -[rover-url]: http://jobs.rover.com/ [sentry-url]: https://getsentry.com/welcome/ [stream-url]: https://getstream.io/try-the-api/?utm_source=drf&utm_medium=banner&utm_campaign=drf -[rollbar-url]: https://rollbar.com/ +[rollbar-url]: https://rollbar.com/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial [cadre-url]: https://cadre.com/ -[load-impact-url]: https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf [kloudless-url]: https://hubs.ly/H0f30Lf0 -[release-history-url]: https://releasehistory.io +[esg-url]: https://software.esg-usa.com/ [lightson-url]: https://lightsonsoftware.com [oauth1-section]: https://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth @@ -225,4 +221,4 @@ Send a description of the issue via email to [rest-framework-security@googlegrou [image]: https://www.django-rest-framework.org/img/quickstart.png [docs]: https://www.django-rest-framework.org/ -[security-mail]: mailto:rest-framework-security@googlegroups.com +[security-policy]: https://github.com/encode/django-rest-framework/security/policy diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..d3faefa3c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,9 @@ +# Security Policy + +## Reporting a Vulnerability + +If you believe you've found something in Django REST framework which has security implications, please **do not raise the issue in a public forum**. + +Send a description of the issue via email to [rest-framework-security@googlegroups.com][security-mail]. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure. + +[security-mail]: mailto:rest-framework-security@googlegroups.com diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 52650299f..c4dbe8856 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -1,4 +1,7 @@ -source: authentication.py +--- +source: + - authentication.py +--- # Authentication @@ -37,10 +40,10 @@ The value of `request.user` and `request.auth` for unauthenticated requests can The default authentication schemes may be set globally, using the `DEFAULT_AUTHENTICATION_CLASSES` setting. For example. REST_FRAMEWORK = { - 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'DEFAULT_AUTHENTICATION_CLASSES': [ 'rest_framework.authentication.BasicAuthentication', 'rest_framework.authentication.SessionAuthentication', - ) + ] } You can also set the authentication scheme on a per-view or per-viewset basis, @@ -52,8 +55,8 @@ using the `APIView` class-based views. from rest_framework.views import APIView class ExampleView(APIView): - authentication_classes = (SessionAuthentication, BasicAuthentication) - permission_classes = (IsAuthenticated,) + authentication_classes = [SessionAuthentication, BasicAuthentication] + permission_classes = [IsAuthenticated] def get(self, request, format=None): content = { @@ -65,8 +68,8 @@ using the `APIView` class-based views. Or, if you're using the `@api_view` decorator with function based views. @api_view(['GET']) - @authentication_classes((SessionAuthentication, BasicAuthentication)) - @permission_classes((IsAuthenticated,)) + @authentication_classes([SessionAuthentication, BasicAuthentication]) + @permission_classes([IsAuthenticated]) def example_view(request, format=None): content = { 'user': unicode(request.user), # `django.contrib.auth.User` instance. @@ -121,10 +124,10 @@ This authentication scheme uses a simple token-based HTTP Authentication scheme. To use the `TokenAuthentication` scheme you'll need to [configure the authentication classes](#setting-the-authentication-scheme) to include `TokenAuthentication`, and additionally include `rest_framework.authtoken` in your `INSTALLED_APPS` setting: - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework.authtoken' - ) + ] --- @@ -247,7 +250,7 @@ It is also possible to create Tokens manually through admin interface. In case y from rest_framework.authtoken.admin import TokenAdmin - TokenAdmin.raw_id_fields = ('user',) + TokenAdmin.raw_id_fields = ['user'] #### Using Django manage.py command @@ -321,13 +324,13 @@ If the `.authenticate_header()` method is not overridden, the authentication sch --- -**Note:** When your custom authenticator is invoked by the request object's `.user` or `.auth` properties, you may see an `AttributeError` re-raised as a `WrappedAttributeError`. This is necessary to prevent the original exception from being suppressed by the outer property access. Python will not recognize that the `AttributeError` orginates from your custom authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. These errors should be fixed or otherwise handled by your authenticator. +**Note:** When your custom authenticator is invoked by the request object's `.user` or `.auth` properties, you may see an `AttributeError` re-raised as a `WrappedAttributeError`. This is necessary to prevent the original exception from being suppressed by the outer property access. Python will not recognize that the `AttributeError` originates from your custom authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. These errors should be fixed or otherwise handled by your authenticator. --- ## Example -The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X_USERNAME'. +The following example will authenticate any incoming request as the user given by the username in a custom request header named 'X-USERNAME'. from django.contrib.auth.models import User from rest_framework import authentication @@ -335,7 +338,7 @@ The following example will authenticate any incoming request as the user given b class ExampleAuthentication(authentication.BaseAuthentication): def authenticate(self, request): - username = request.META.get('X_USERNAME') + username = request.META.get('HTTP_X_USERNAME') if not username: return None @@ -364,15 +367,15 @@ Install using `pip`. Add the package to your `INSTALLED_APPS` and modify your REST framework settings. - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'oauth2_provider', - ) + ] REST_FRAMEWORK = { - 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'DEFAULT_AUTHENTICATION_CLASSES': [ 'oauth2_provider.contrib.rest_framework.OAuth2Authentication', - ) + ] } For more details see the [Django REST framework - Getting started][django-oauth-toolkit-getting-started] documentation. diff --git a/docs/api-guide/caching.md b/docs/api-guide/caching.md index 5342345e4..502a0a9a9 100644 --- a/docs/api-guide/caching.md +++ b/docs/api-guide/caching.md @@ -1,6 +1,6 @@ # Caching -> A certain woman had a very sharp conciousness but almost no +> A certain woman had a very sharp consciousness but almost no > memory ... She remembered enough to work, and she worked hard. > - Lydia Davis diff --git a/docs/api-guide/content-negotiation.md b/docs/api-guide/content-negotiation.md index 8112a2e80..3a4b0357f 100644 --- a/docs/api-guide/content-negotiation.md +++ b/docs/api-guide/content-negotiation.md @@ -1,4 +1,7 @@ -source: negotiation.py +--- +source: + - negotiation.py +--- # Content negotiation diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index 820e6d3b8..d7d73a2f2 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -1,4 +1,7 @@ -source: exceptions.py +--- +source: + - exceptions.py +--- # Exceptions diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index d371bb8fd..19abb0424 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -1,4 +1,7 @@ -source: fields.py +--- +source: + - fields.py +--- # Serializer fields @@ -209,7 +212,7 @@ A field that ensures the input is a valid UUID string. The `to_internal_value` m **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_verbose'` - The canonical 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"` @@ -448,9 +451,10 @@ Requires either the `Pillow` package or `PIL` package. The `Pillow` package is A field class that validates a list of objects. -**Signature**: `ListField(child=, min_length=None, max_length=None)` +**Signature**: `ListField(child=, allow_empty=True, min_length=None, max_length=None)` - `child` - A field instance that should be used for validating the objects in the list. If this argument is not provided then objects in the list will not be validated. +- `allow_empty` - Designates if empty lists are allowed. - `min_length` - Validates that the list contains no fewer than this number of elements. - `max_length` - Validates that the list contains no more than this number of elements. @@ -471,9 +475,10 @@ We can now reuse our custom `StringListField` class throughout our application, A field class that validates a dictionary of objects. The keys in `DictField` are always assumed to be string values. -**Signature**: `DictField(child=)` +**Signature**: `DictField(child=, allow_empty=True)` - `child` - A field instance that should be used for validating the values in the dictionary. If this argument is not provided then values in the mapping will not be validated. +- `allow_empty` - Designates if empty dictionaries are allowed. For example, to create a field that validates a mapping of strings to strings, you would write something like this: @@ -488,9 +493,10 @@ You can also use the declarative style, as with `ListField`. For example: A preconfigured `DictField` that is compatible with Django's postgres `HStoreField`. -**Signature**: `HStoreField(child=)` +**Signature**: `HStoreField(child=, allow_empty=True)` - `child` - A field instance that is used for validating the values in the dictionary. The default child field accepts both empty strings and null values. +- `allow_empty` - Designates if empty dictionaries are allowed. Note that the child field **must** be an instance of `CharField`, as the hstore extension stores values as strings. @@ -498,9 +504,10 @@ Note that the child field **must** be an instance of `CharField`, as the hstore A field class that validates that the incoming data structure consists of valid JSON primitives. In its alternate binary mode, it will represent and validate JSON-encoded binary strings. -**Signature**: `JSONField(binary)` +**Signature**: `JSONField(binary, encoder)` - `binary` - If set to `True` then the field will output and validate a JSON encoded string, rather than a primitive data structure. Defaults to `False`. +- `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`. --- @@ -519,7 +526,7 @@ For example, if `has_expired` was a property on the `Account` model, then the fo class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'has_expired') + fields = ['id', 'account_name', 'has_expired'] ## HiddenField @@ -718,7 +725,7 @@ to the desired output. >>> instance = DataPoint(label='Example', x_coordinate=1, y_coordinate=2) >>> out_serializer = DataPointSerializer(instance) >>> out_serializer.data - ReturnDict([('label', 'testing'), ('coordinates', {'x': 1, 'y': 2})]) + ReturnDict([('label', 'Example'), ('coordinates', {'x': 1, 'y': 2})]) * Unless our field is to be read-only, `to_internal_value` must map back to a dict suitable for updating our target object. With `source='*'`, the return from diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 8a500f386..1bdb6c52b 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -1,4 +1,7 @@ -source: filters.py +--- +source: + - filters.py +--- # Filtering @@ -92,7 +95,7 @@ Generic filters can also present themselves as HTML controls in the browsable AP The default filter backends may be set globally, using the `DEFAULT_FILTER_BACKENDS` setting. For example. REST_FRAMEWORK = { - 'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',) + 'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'] } You can also set the filter backends on a per-view, or per-viewset basis, @@ -106,7 +109,7 @@ using the `GenericAPIView` class-based views. class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (django_filters.rest_framework.DjangoFilterBackend,) + filter_backends = [django_filters.rest_framework.DjangoFilterBackend] ## Filtering and object lookups @@ -139,7 +142,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering ## DjangoFilterBackend -The `django-filter` library includes a `DjangoFilterBackend` class which +The [`django-filter`][django-filter-docs] library includes a `DjangoFilterBackend` class which supports highly customizable field filtering for REST framework. To use `DjangoFilterBackend`, first install `django-filter`. Then add `django_filters` to Django's `INSTALLED_APPS` @@ -149,7 +152,7 @@ To use `DjangoFilterBackend`, first install `django-filter`. Then add `django_fi You should now either add the filter backend to your settings: REST_FRAMEWORK = { - 'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',) + 'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend'] } Or add the filter backend to an individual View or ViewSet. @@ -158,15 +161,15 @@ Or add the filter backend to an individual View or ViewSet. class UserListView(generics.ListAPIView): ... - filter_backends = (DjangoFilterBackend,) + filter_backends = [DjangoFilterBackend] If all you need is simple equality-based filtering, you can set a `filterset_fields` attribute on the view, or viewset, listing the set of fields you wish to filter against. class ProductList(generics.ListAPIView): queryset = Product.objects.all() serializer_class = ProductSerializer - filter_backends = (DjangoFilterBackend,) - filterset_fields = ('category', 'in_stock') + filter_backends = [DjangoFilterBackend] + filterset_fields = ['category', 'in_stock'] This will automatically create a `FilterSet` class for the given fields, and will allow you to make requests such as: @@ -192,8 +195,8 @@ The `SearchFilter` class will only be applied if the view has a `search_fields` class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (filters.SearchFilter,) - search_fields = ('username', 'email') + filter_backends = [filters.SearchFilter] + search_fields = ['username', 'email'] This will allow the client to filter the items in the list by making queries such as: @@ -201,7 +204,7 @@ This will allow the client to filter the items in the list by making queries suc You can also perform a related lookup on a ForeignKey or ManyToManyField with the lookup API double-underscore notation: - search_fields = ('username', 'email', 'profile__profession') + search_fields = ['username', 'email', 'profile__profession'] By default, searches will use case-insensitive partial matches. The search parameter may contain multiple search terms, which should be whitespace and/or comma separated. If multiple search terms are used then objects will be returned in the list only if all the provided terms are matched. @@ -214,18 +217,18 @@ The search behavior may be restricted by prepending various characters to the `s For example: - search_fields = ('=username', '=email') + search_fields = ['=username', '=email'] -By default, the search parameter is named `'search`', but this may be overridden with the `SEARCH_PARAM` setting. +By default, the search parameter is named `'search'`, but this may be overridden with the `SEARCH_PARAM` setting. To dynamically change search fields based on request content, it's possible to subclass the `SearchFilter` and override the `get_search_fields()` function. For example, the following subclass will only search on `title` if the query parameter `title_only` is in the request: from rest_framework import filters - + class CustomSearchFilter(filters.SearchFilter): def get_search_fields(self, view, request): if request.query_params.get('title_only'): - return ('title',) + return ['title'] return super(CustomSearchFilter, self).get_search_fields(view, request) For more details, see the [Django documentation][search-django-admin]. @@ -259,8 +262,8 @@ It's recommended that you explicitly specify which fields the API should allowin class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (filters.OrderingFilter,) - ordering_fields = ('username', 'email') + filter_backends = [filters.OrderingFilter] + ordering_fields = ['username', 'email'] This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data. @@ -271,7 +274,7 @@ If you are confident that the queryset being used by the view doesn't contain an class BookingsListView(generics.ListAPIView): queryset = Booking.objects.all() serializer_class = BookingSerializer - filter_backends = (filters.OrderingFilter,) + filter_backends = [filters.OrderingFilter] ordering_fields = '__all__' ### Specifying a default ordering @@ -283,61 +286,14 @@ Typically you'd instead control this by setting `order_by` on the initial querys class UserListView(generics.ListAPIView): queryset = User.objects.all() serializer_class = UserSerializer - filter_backends = (filters.OrderingFilter,) - ordering_fields = ('username', 'email') - ordering = ('username',) + filter_backends = [filters.OrderingFilter] + ordering_fields = ['username', 'email'] + ordering = ['username'] The `ordering` attribute may be either a string or a list/tuple of strings. --- -## DjangoObjectPermissionsFilter - -The `DjangoObjectPermissionsFilter` is intended to be used together with the [`django-guardian`][guardian] package, with custom `'view'` permissions added. The filter will ensure that querysets only returns objects for which the user has the appropriate view permission. - ---- - -**Note:** This filter has been deprecated as of version 3.9 and moved to the 3rd-party [`djangorestframework-guardian` package][django-rest-framework-guardian]. - ---- - -If you're using `DjangoObjectPermissionsFilter`, you'll probably also want to add an appropriate object permissions class, to ensure that users can only operate on instances if they have the appropriate object permissions. The easiest way to do this is to subclass `DjangoObjectPermissions` and add `'view'` permissions to the `perms_map` attribute. - -A complete example using both `DjangoObjectPermissionsFilter` and `DjangoObjectPermissions` might look something like this. - -**permissions.py**: - - class CustomObjectPermissions(permissions.DjangoObjectPermissions): - """ - Similar to `DjangoObjectPermissions`, but adding 'view' permissions. - """ - perms_map = { - 'GET': ['%(app_label)s.view_%(model_name)s'], - 'OPTIONS': ['%(app_label)s.view_%(model_name)s'], - 'HEAD': ['%(app_label)s.view_%(model_name)s'], - 'POST': ['%(app_label)s.add_%(model_name)s'], - 'PUT': ['%(app_label)s.change_%(model_name)s'], - 'PATCH': ['%(app_label)s.change_%(model_name)s'], - 'DELETE': ['%(app_label)s.delete_%(model_name)s'], - } - -**views.py**: - - class EventViewSet(viewsets.ModelViewSet): - """ - Viewset that only lists events if user has 'view' permissions, and only - allows operations on individual events if user has appropriate 'view', 'add', - 'change' or 'delete' permissions. - """ - queryset = Event.objects.all() - serializer_class = EventSerializer - filter_backends = (filters.DjangoObjectPermissionsFilter,) - permission_classes = (myapp.permissions.CustomObjectPermissions,) - -For more information on adding `'view'` permissions for models, see the [relevant section][view-permissions] of the `django-guardian` documentation, and [this blogpost][view-permissions-blogpost]. - ---- - # Custom generic filtering You can also provide your own generic filtering backend, or write an installable app for other developers to use. @@ -399,12 +355,8 @@ The [djangorestframework-word-filter][django-rest-framework-word-search-filter] [cite]: https://docs.djangoproject.com/en/stable/topics/db/queries/#retrieving-specific-objects-with-filters [django-filter-docs]: https://django-filter.readthedocs.io/en/latest/index.html [django-filter-drf-docs]: https://django-filter.readthedocs.io/en/latest/guide/rest_framework.html -[guardian]: https://django-guardian.readthedocs.io/ -[view-permissions]: https://django-guardian.readthedocs.io/en/latest/userguide/assign.html -[view-permissions-blogpost]: https://blog.nyaruka.com/adding-a-view-permission-to-django-models [search-django-admin]: https://docs.djangoproject.com/en/stable/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields [django-rest-framework-filters]: https://github.com/philipn/django-rest-framework-filters -[django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian [django-rest-framework-word-search-filter]: https://github.com/trollknurr/django-rest-framework-word-search-filter [django-url-filter]: https://github.com/miki725/django-url-filter [drf-url-filter]: https://github.com/manjitkumar/drf-url-filters diff --git a/docs/api-guide/format-suffixes.md b/docs/api-guide/format-suffixes.md index 629f003f3..04467b3d3 100644 --- a/docs/api-guide/format-suffixes.md +++ b/docs/api-guide/format-suffixes.md @@ -1,4 +1,7 @@ -source: urlpatterns.py +--- +source: + - urlpatterns.py +--- # Format suffixes @@ -38,7 +41,7 @@ Example: When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views. For example: - @api_view(('GET', 'POST')) + @api_view(['GET', 'POST']) def comment_list(request, format=None): # do stuff... diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index a0ed7bdea..8d9ead107 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -1,5 +1,8 @@ -source: mixins.py - generics.py +--- +source: + - mixins.py + - generics.py +--- # Generic views @@ -25,14 +28,14 @@ Typically when using the generic views, you'll override the view, and set severa class UserList(generics.ListCreateAPIView): queryset = User.objects.all() serializer_class = UserSerializer - permission_classes = (IsAdminUser,) + permission_classes = [IsAdminUser] For more complex cases you might also want to override various methods on the view class. For example. class UserList(generics.ListCreateAPIView): queryset = User.objects.all() serializer_class = UserSerializer - permission_classes = (IsAdminUser,) + permission_classes = [IsAdminUser] def list(self, request): # Note the use of `get_queryset()` instead of `self.queryset` @@ -120,12 +123,12 @@ Given a queryset, filter it with whichever filter backends are in use, returning For example: def filter_queryset(self, queryset): - filter_backends = (CategoryFilter,) + filter_backends = [CategoryFilter] if 'geo_route' in self.request.query_params: - filter_backends = (GeoRouteFilter, CategoryFilter) + filter_backends = [GeoRouteFilter, CategoryFilter] elif 'geo_point' in self.request.query_params: - filter_backends = (GeoPointFilter, CategoryFilter) + filter_backends = [GeoPointFilter, CategoryFilter] for backend in list(filter_backends): queryset = backend().filter_queryset(self.request, queryset, view=self) @@ -339,7 +342,7 @@ You can then simply apply this mixin to a view or viewset anytime you need to ap class RetrieveUserView(MultipleFieldLookupMixin, generics.RetrieveAPIView): queryset = User.objects.all() serializer_class = UserSerializer - lookup_fields = ('account', 'username') + lookup_fields = ['account', 'username'] Using custom mixins is a good option if you have custom behavior that needs to be used. diff --git a/docs/api-guide/metadata.md b/docs/api-guide/metadata.md index a3ba9ac20..fdb778626 100644 --- a/docs/api-guide/metadata.md +++ b/docs/api-guide/metadata.md @@ -1,4 +1,7 @@ -source: metadata.py +--- +source: + - metadata.py +--- # Metadata diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 99612ef46..8d9eb2288 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -1,4 +1,7 @@ -source: pagination.py +--- +source: + - pagination.py +--- # Pagination @@ -257,6 +260,10 @@ To have your custom pagination class be used by default, use the `DEFAULT_PAGINA API responses for list endpoints will now include a `Link` header, instead of including the pagination links as part of the body of the response, for example: +![Link Header][link-header] + +*A custom pagination style, using the 'Link' header'* + ## Pagination & schemas You can also make the pagination controls available to the schema autogeneration @@ -268,12 +275,6 @@ The method should return a list of `coreapi.Field` instances. --- -![Link Header][link-header] - -*A custom pagination style, using the 'Link' header'* - ---- - # HTML pagination controls By default using the pagination classes will cause HTML pagination controls to be displayed in the browsable API. There are two built-in display styles. The `PageNumberPagination` and `LimitOffsetPagination` classes display a list of page numbers with previous and next controls. The `CursorPagination` class displays a simpler style that only displays a previous and next control. diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index be48ae7e5..a3bc74a2b 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -1,4 +1,7 @@ -source: parsers.py +--- +source: + - parsers.py +--- # Parsers @@ -29,9 +32,9 @@ As an example, if you are sending `json` encoded data using jQuery with the [.aj The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow only requests with `JSON` content, instead of the default of JSON or form data. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework.parsers.JSONParser', - ) + ] } You can also set the parsers used for an individual view, or viewset, @@ -45,7 +48,7 @@ using the `APIView` class-based views. """ A view that can accept POST requests with JSON content. """ - parser_classes = (JSONParser,) + parser_classes = [JSONParser] def post(self, request, format=None): return Response({'received data': request.data}) @@ -57,7 +60,7 @@ Or, if you're using the `@api_view` decorator with function based views. from rest_framework.parsers import JSONParser @api_view(['POST']) - @parser_classes((JSONParser,)) + @parser_classes([JSONParser]) def example_view(request, format=None): """ A view that can accept POST requests with JSON content. @@ -110,7 +113,7 @@ If it is called without a `filename` URL keyword argument, then the client must # views.py class FileUploadView(views.APIView): - parser_classes = (FileUploadParser,) + parser_classes = [FileUploadParser] def put(self, request, filename, format=None): file_obj = request.data['file'] @@ -186,12 +189,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_yaml.parsers.YAMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_yaml.renderers.YAMLRenderer', - ), + ], } ## XML @@ -207,12 +210,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_xml.parsers.XMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_xml.renderers.XMLRenderer', - ), + ], } ## MessagePack diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 901f810c5..25baa4813 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -1,4 +1,7 @@ -source: permissions.py +--- +source: + - permissions.py +--- # Permissions @@ -72,16 +75,16 @@ Often when you're using object level permissions you'll also want to [filter the The default permission policy may be set globally, using the `DEFAULT_PERMISSION_CLASSES` setting. For example. REST_FRAMEWORK = { - 'DEFAULT_PERMISSION_CLASSES': ( + 'DEFAULT_PERMISSION_CLASSES': [ 'rest_framework.permissions.IsAuthenticated', - ) + ] } If not specified, this setting defaults to allowing unrestricted access: - 'DEFAULT_PERMISSION_CLASSES': ( + 'DEFAULT_PERMISSION_CLASSES': [ 'rest_framework.permissions.AllowAny', - ) + ] You can also set the authentication policy on a per-view, or per-viewset basis, using the `APIView` class-based views. @@ -91,7 +94,7 @@ using the `APIView` class-based views. from rest_framework.views import APIView class ExampleView(APIView): - permission_classes = (IsAuthenticated,) + permission_classes = [IsAuthenticated] def get(self, request, format=None): content = { @@ -106,7 +109,7 @@ Or, if you're using the `@api_view` decorator with function based views. from rest_framework.response import Response @api_view(['GET']) - @permission_classes((IsAuthenticated, )) + @permission_classes([IsAuthenticated]) def example_view(request, format=None): content = { 'status': 'request was permitted' @@ -126,7 +129,7 @@ Provided they inherit from `rest_framework.permissions.BasePermission`, permissi return request.method in SAFE_METHODS class ExampleView(APIView): - permission_classes = (IsAuthenticated|ReadOnly,) + permission_classes = [IsAuthenticated|ReadOnly] def get(self, request, format=None): content = { @@ -281,6 +284,10 @@ Also note that the generic views will only check the object-level permissions fo The following third party packages are also available. +## DRF - Access Policy + +The [Django REST - Access Policy][drf-access-policy] package provides a way to define complex access rules in declarative policy classes that are attached to view sets or function-based views. The policies are defined in JSON in a format similar to AWS' Identity & Access Management policies. + ## 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. @@ -299,7 +306,7 @@ The [Django Rest Framework Roles][django-rest-framework-roles] package makes it ## Django REST Framework API Key -The [Django REST Framework API Key][djangorestframework-api-key] package provides the ability to authorize clients based on customizable API key headers. This package is targeted at situations in which regular user-based authentication (e.g. `TokenAuthentication`) is not suitable, e.g. allowing non-human clients to safely use your API. API keys are generated and validated through cryptographic methods and can be created and revoked from the Django admin interface at anytime. +The [Django REST Framework API Key][djangorestframework-api-key] package provides permissions classes, models and helpers to add API key authorization to your API. It can be used to authorize internal or third-party backends and services (i.e. _machines_) which do not have a user account. API keys are stored securely using Django's password hashing infrastructure, and they can be viewed, edited and revoked at anytime in the Django admin. ## Django Rest Framework Role Filters @@ -317,6 +324,7 @@ The [Django Rest Framework Role Filters][django-rest-framework-role-filters] pac [rest-condition]: https://github.com/caxap/rest_condition [dry-rest-permissions]: https://github.com/Helioscene/dry-rest-permissions [django-rest-framework-roles]: https://github.com/computer-lab/django-rest-framework-roles -[djangorestframework-api-key]: https://github.com/florimondmanca/djangorestframework-api-key +[djangorestframework-api-key]: https://florimondmanca.github.io/djangorestframework-api-key/ [django-rest-framework-role-filters]: https://github.com/allisson/django-rest-framework-role-filters [django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian +[drf-access-policy]: https://github.com/rsinger86/drf-access-policy diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 8665e80f6..14f197b21 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -1,4 +1,7 @@ -source: relations.py +--- +source: + - relations.py +--- # Serializer relations @@ -43,7 +46,7 @@ In order to explain the various types of relational fields, we'll use a couple o duration = models.IntegerField() class Meta: - unique_together = ('album', 'order') + unique_together = ['album', 'order'] ordering = ['order'] def __str__(self): @@ -60,7 +63,7 @@ For example, the following serializer. class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to the following representation. @@ -92,7 +95,7 @@ For example, the following serializer: class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a representation like this: @@ -132,7 +135,7 @@ For example, the following serializer: class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a representation like this: @@ -184,7 +187,7 @@ For example, the following serializer: class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a representation like this: @@ -219,7 +222,7 @@ This field can be applied as an identity relationship, such as the `'url'` field class Meta: model = Album - fields = ('album_name', 'artist', 'track_listing') + fields = ['album_name', 'artist', 'track_listing'] Would serialize to a representation like this: @@ -253,14 +256,14 @@ For example, the following serializer: class TrackSerializer(serializers.ModelSerializer): class Meta: model = Track - fields = ('order', 'title', 'duration') + fields = ['order', 'title', 'duration'] class AlbumSerializer(serializers.ModelSerializer): tracks = TrackSerializer(many=True, read_only=True) class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to a nested representation like this: @@ -291,14 +294,14 @@ By default nested serializers are read-only. If you want to support write-operat class TrackSerializer(serializers.ModelSerializer): class Meta: model = Track - fields = ('order', 'title', 'duration') + fields = ['order', 'title', 'duration'] class AlbumSerializer(serializers.ModelSerializer): tracks = TrackSerializer(many=True) class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] def create(self, validated_data): tracks_data = validated_data.pop('tracks') @@ -352,7 +355,7 @@ For example, we could define a relational field to serialize a track to a custom class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] This custom field would then serialize to the following representation. @@ -477,7 +480,7 @@ Note that reverse relationships are not automatically included by the `ModelSeri class AlbumSerializer(serializers.ModelSerializer): class Meta: - fields = ('tracks', ...) + fields = ['tracks', ...] You'll normally want to ensure that you've set an appropriate `related_name` argument on the relationship, that you can use as the field name. For example: @@ -489,7 +492,7 @@ If you have not set a related name for the reverse relationship, you'll need to class AlbumSerializer(serializers.ModelSerializer): class Meta: - fields = ('track_set', ...) + fields = ['track_set', ...] See the Django documentation on [reverse relationships][reverse-relationships] for more details. @@ -576,6 +579,8 @@ If you explicitly specify a relational field pointing to a ``ManyToManyField`` with a through model, be sure to set ``read_only`` to ``True``. +If you wish to represent [extra fields on a through model][django-intermediary-manytomany] then you may serialize the through model as [a nested object][dealing-with-nested-objects]. + --- # Third Party Packages @@ -596,3 +601,5 @@ The [rest-framework-generic-relations][drf-nested-relations] library provides re [generic-relations]: https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/#id1 [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers [drf-nested-relations]: https://github.com/Ian-Foote/rest-framework-generic-relations +[django-intermediary-manytomany]: https://docs.djangoproject.com/en/2.2/topics/db/models/#intermediary-manytomany +[dealing-with-nested-objects]: https://www.django-rest-framework.org/api-guide/serializers/#dealing-with-nested-objects diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 4ec409681..a3321e860 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -1,4 +1,7 @@ -source: renderers.py +--- +source: + - renderers.py +--- # Renderers @@ -21,10 +24,10 @@ For more information see the documentation on [content negotiation][conneg]. The default set of renderers may be set globally, using the `DEFAULT_RENDERER_CLASSES` setting. For example, the following settings would use `JSON` as the main media type and also include the self describing API. REST_FRAMEWORK = { - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', - ) + ] } You can also set the renderers used for an individual view, or viewset, @@ -39,7 +42,7 @@ using the `APIView` class-based views. """ A view that returns the count of active users in JSON. """ - renderer_classes = (JSONRenderer, ) + renderer_classes = [JSONRenderer] def get(self, request, format=None): user_count = User.objects.filter(active=True).count() @@ -49,7 +52,7 @@ using the `APIView` class-based views. Or, if you're using the `@api_view` decorator with function based views. @api_view(['GET']) - @renderer_classes((JSONRenderer,)) + @renderer_classes([JSONRenderer]) def user_count_view(request, format=None): """ A view that returns the count of active users in JSON. @@ -113,7 +116,7 @@ An example of a view that uses `TemplateHTMLRenderer`: A view that returns a templated HTML representation of a given user. """ queryset = User.objects.all() - renderer_classes = (TemplateHTMLRenderer,) + renderer_classes = [TemplateHTMLRenderer] def get(self, request, *args, **kwargs): self.object = self.get_object() @@ -139,8 +142,8 @@ A simple renderer that simply returns pre-rendered HTML. Unlike other renderers An example of a view that uses `StaticHTMLRenderer`: - @api_view(('GET',)) - @renderer_classes((StaticHTMLRenderer,)) + @api_view(['GET']) + @renderer_classes([StaticHTMLRenderer]) def simple_html_view(request): data = '

Hello, world

' return Response(data) @@ -325,8 +328,8 @@ In some cases you might want your view to use different serialization styles dep For example: - @api_view(('GET',)) - @renderer_classes((TemplateHTMLRenderer, JSONRenderer)) + @api_view(['GET']) + @renderer_classes([TemplateHTMLRenderer, JSONRenderer]) def list_users(request): """ A view that can return JSON or HTML representations @@ -398,12 +401,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_yaml.parsers.YAMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_yaml.renderers.YAMLRenderer', - ), + ], } ## XML @@ -419,12 +422,12 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_PARSER_CLASSES': ( + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_xml.parsers.XMLParser', - ), - 'DEFAULT_RENDERER_CLASSES': ( + ], + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_xml.renderers.XMLRenderer', - ), + ], } ## JSONP @@ -448,9 +451,9 @@ Install using pip. Modify your REST framework settings. REST_FRAMEWORK = { - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_jsonp.renderers.JSONPRenderer', - ), + ], } ## MessagePack @@ -472,11 +475,11 @@ Modify your REST framework settings. REST_FRAMEWORK = { ... - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', 'drf_renderer_xlsx.renderers.XLSXRenderer', - ), + ], } To avoid having a file streamed without a filename (which the browser will often default to the filename "download", with no extension), we need to use a mixin to override the `Content-Disposition` header. If no filename is provided, it will default to `export.xlsx`. For example: @@ -491,7 +494,7 @@ To avoid having a file streamed without a filename (which the browser will often class MyExampleViewSet(XLSXFileMixin, ReadOnlyModelViewSet): queryset = MyExampleModel.objects.all() serializer_class = MyExampleSerializer - renderer_classes = (XLSXRenderer,) + renderer_classes = [XLSXRenderer] filename = 'my_export.xlsx' ## CSV @@ -534,7 +537,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily [messagepack]: https://msgpack.org/ [juanriaza]: https://github.com/juanriaza [mjumbewu]: https://github.com/mjumbewu -[flipperpa]: https://githuc.com/flipperpa +[flipperpa]: https://github.com/flipperpa [wharton]: https://github.com/wharton [drf-renderer-xlsx]: https://github.com/wharton/drf-renderer-xlsx [vbabiy]: https://github.com/vbabiy diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 28450f082..3bc083893 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -1,4 +1,7 @@ -source: request.py +--- +source: + - request.py +--- # Requests @@ -90,7 +93,7 @@ You won't typically need to access this property. --- -**Note:** You may see a `WrappedAttributeError` raised when calling the `.user` or `.auth` properties. These errors originate from an authenticator as a standard `AttributeError`, however it's necessary that they be re-raised as a different exception type in order to prevent them from being suppressed by the outer property access. Python will not recognize that the `AttributeError` orginates from the authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. The authenticator will need to be fixed. +**Note:** You may see a `WrappedAttributeError` raised when calling the `.user` or `.auth` properties. These errors originate from an authenticator as a standard `AttributeError`, however it's necessary that they be re-raised as a different exception type in order to prevent them from being suppressed by the outer property access. Python will not recognize that the `AttributeError` originates from the authenticator and will instead assume that the request object does not have a `.user` or `.auth` property. The authenticator will need to be fixed. --- diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index e9c2d41f1..1a56b0101 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -1,4 +1,7 @@ -source: response.py +--- +source: + - response.py +--- # Responses diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md index 00abcf571..70df42b8f 100644 --- a/docs/api-guide/reverse.md +++ b/docs/api-guide/reverse.md @@ -1,4 +1,7 @@ -source: reverse.py +--- +source: + - reverse.py +--- # Returning URLs diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index 09c6c39cb..5f6802222 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -1,4 +1,7 @@ -source: routers.py +--- +source: + - routers.py +--- # Routers diff --git a/docs/api-guide/schemas.md b/docs/api-guide/schemas.md index b09b1606e..e1ac16a22 100644 --- a/docs/api-guide/schemas.md +++ b/docs/api-guide/schemas.md @@ -1,6 +1,9 @@ -source: schemas.py +--- +source: + - schemas.py +--- -# Schemas +# Schema > A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. > @@ -10,24 +13,24 @@ API schemas are a useful tool that allow for a range of use cases, including generating reference documentation, or driving dynamic client libraries that can interact with your API. -## Install Core API & PyYAML +Django REST Framework provides support for automatic generation of +[OpenAPI][openapi] schemas. -You'll need to install the `coreapi` package in order to add schema support -for REST framework. You probably also want to install `pyyaml`, so that you -can render the schema into the commonly used YAML-based OpenAPI format. +## Generating an OpenAPI Schema - pip install coreapi pyyaml +### Install `pyyaml` -## Quickstart +You'll need to install `pyyaml`, so that you can render your generated schema +into the commonly used YAML-based OpenAPI format. -There are two different ways you can serve a schema description for your API. + pip install pyyaml -### Generating a schema with the `generateschema` management command +### Generating a static schema with the `generateschema` management command -To generate a static API schema, use the `generateschema` management command. +If your schema is static, you can use the `generateschema` management command: -```shell -$ python manage.py generateschema > schema.yml +```bash +./manage.py generateschema > openapi-schema.yml ``` Once you've generated a schema in this way you can annotate it with any @@ -37,154 +40,136 @@ generator. You might want to check your API schema into version control and update it with each new release, or serve the API schema from your site's static media. -### Adding a view with `get_schema_view` +### Generating a dynamic schema with `SchemaView` -To add a dynamically generated schema view to your API, use `get_schema_view`. +If you require a dynamic schema, because foreign key choices depend on database +values, for example, you can route a `SchemaView` that will generate and serve +your schema on demand. + +To route a `SchemaView`, use the `get_schema_view()` helper. + +In `urls.py`: ```python from rest_framework.schemas import get_schema_view -schema_view = get_schema_view(title="Example API") - urlpatterns = [ - url('^schema$', schema_view), - ... + # ... + # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs. + # * `title` and `description` parameters are passed to `SchemaGenerator`. + # * Provide view name for use with `reverse()`. + path('openapi', get_schema_view( + title="Your Project", + description="API for all things …", + version="1.0.0" + ), name='openapi-schema'), + # ... ] ``` -See below [for more details](#the-get_schema_view-shortcut) on customizing a -dynamically generated schema view. +#### `get_schema_view()` -## Internal schema representation +The `get_schema_view()` helper takes the following keyword arguments: -REST framework uses [Core API][coreapi] in order to model schema information in -a format-independent representation. This information can then be rendered -into various different schema formats, or used to generate API documentation. +* `title`: May be used to provide a descriptive title for the schema definition. +* `description`: Longer descriptive text. +* `version`: The version of the API. Defaults to `0.1.0`. +* `url`: May be used to pass a canonical base URL for the schema. -When using Core API, a schema is represented as a `Document` which is the -top-level container object for information about the API. Available API -interactions are represented using `Link` objects. Each link includes a URL, -HTTP method, and may include a list of `Field` instances, which describe any -parameters that may be accepted by the API endpoint. The `Link` and `Field` -instances may also include descriptions, that allow an API schema to be -rendered into user documentation. + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/' + ) -Here's an example of an API description that includes a single `search` -endpoint: +* `urlconf`: A string representing the import path to the URL conf that you want + to generate an API schema for. This defaults to the value of Django's + `ROOT_URLCONF` setting. - coreapi.Document( - title='Flight Search API', - url='https://api.example.org/', - content={ - 'search': coreapi.Link( - url='/search/', - action='get', - fields=[ - coreapi.Field( - name='from', - required=True, - location='query', - description='City name or airport code.' - ), - coreapi.Field( - name='to', - required=True, - location='query', - description='City name or airport code.' - ), - coreapi.Field( - name='date', - required=True, - location='query', - description='Flight date in "YYYY-MM-DD" format.' - ) - ], - description='Return flight availability and prices.' - ) - } - ) + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + urlconf='myproject.urls' + ) +* `patterns`: List of url patterns to limit the schema introspection to. If you + only want the `myproject.api` urls to be exposed in the schema: -## Schema output formats + schema_url_patterns = [ + url(r'^api/', include('myproject.api.urls')), + ] -In order to be presented in an HTTP response, the internal representation -has to be rendered into the actual bytes that are used in the response. + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + patterns=schema_url_patterns, + ) -REST framework includes a few different renderers that you can use for -encoding the API schema. - -* `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format. -* `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api]. -* `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for -use with the `coreapi` client library. +* `generator_class`: May be used to specify a `SchemaGenerator` subclass to be + passed to the `SchemaView`. +* `authentication_classes`: May be used to specify the list of authentication + classes that will apply to the schema endpoint. Defaults to + `settings.DEFAULT_AUTHENTICATION_CLASSES` +* `permission_classes`: May be used to specify the list of permission classes + that will apply to the schema endpoint. Defaults to + `settings.DEFAULT_PERMISSION_CLASSES`. +* `renderer_classes`: May be used to pass the set of renderer classes that can + be used to render the API root endpoint. -[Core JSON][corejson] is designed as a canonical format for use with Core API. -REST framework includes a renderer class for handling this media type, which -is available as `renderers.CoreJSONRenderer`. +## Customizing Schema Generation +You may customize schema generation at the level of the schema as a whole, or +on a per-view basis. -## Schemas vs Hypermedia +### Schema Level Customization -It's worth pointing out here that Core API can also be used to model hypermedia -responses, which present an alternative interaction style to API schemas. +In order to customize the top-level schema sublass +`rest_framework.schemas.openapi.SchemaGenerator` and provide it as an argument +to the `generateschema` command or `get_schema_view()` helper function. -With an API schema, the entire available interface is presented up-front -as a single endpoint. Responses to individual API endpoints are then typically -presented as plain data, without any further interactions contained in each -response. +#### SchemaGenerator -With Hypermedia, the client is instead presented with a document containing -both data and available interactions. Each interaction results in a new -document, detailing both the current state and the available interactions. +A class that walks a list of routed URL patterns, requests the schema for each +view and collates the resulting OpenAPI schema. -Further information and support on building Hypermedia APIs with REST framework -is planned for a future version. +Typically you'll instantiate `SchemaGenerator` with a `title` argument, like so: + generator = SchemaGenerator(title='Stock Prices API') ---- +Arguments: -# Creating a schema +* `title` **required**: The name of the API. +* `description`: Longer descriptive text. +* `version`: The version of the API. Defaults to `0.1.0`. +* `url`: The root URL of the API schema. This option is not required unless the schema is included under path prefix. +* `patterns`: A list of URLs to inspect when generating the schema. Defaults to the project's URL conf. +* `urlconf`: A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`. -REST framework includes functionality for auto-generating a schema, -or allows you to specify one explicitly. +##### get_schema(self, request) -## Manual Schema Specification +Returns a dictionary that represents the OpenAPI schema: -To manually specify a schema you create a Core API `Document`, similar to the -example above. - - schema = coreapi.Document( - title='Flight Search API', - content={ - ... - } - ) - - -## Automatic Schema Generation - -Automatic schema generation is provided by the `SchemaGenerator` class. - -`SchemaGenerator` processes a list of routed URL patterns and compiles the -appropriately structured Core API Document. - -Basic usage is just to provide the title for your schema and call -`get_schema()`: - - generator = schemas.SchemaGenerator(title='Flight Search API') + generator = SchemaGenerator(title='Stock Prices API') schema = generator.get_schema() -## Per-View Schema Customisation +The `request` argument is optional, and may be used if you want to apply +per-user permissions to the resulting schema generation. + +This is a good point to override if you want to customise the generated +dictionary, for example to add custom +[specification extensions][openapi-specification-extensions]. + +### Per-View Customization By default, view introspection is performed by an `AutoSchema` instance accessible via the `schema` attribute on `APIView`. This provides the -appropriate Core API `Link` object for the view, request method and path: +appropriate [Open API operation object][openapi-operation] for the view, +request method and path: auto_schema = view.schema - coreapi_link = auto_schema.get_link(...) + operation = auto_schema.get_operation(...) -(In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for -each view, allowed method and path.) +In compiling the schema, `SchemaGenerator` calls `view.schema.get_operation()` +for each view, allowed method, and path. --- @@ -198,641 +183,39 @@ provide richer path field descriptions. (The key hooks here are the relevant --- -To customise the `Link` generation you may: +In order to customise the operation generation, you should provide an `AutoSchema` subclass, overriding `get_operation()` as you need: -* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg: from rest_framework.views import APIView - from rest_framework.schemas import AutoSchema - - class CustomView(APIView): - ... - schema = AutoSchema( - manual_fields=[ - coreapi.Field("extra_field", ...), - ] - ) - - This allows extension for the most common case without subclassing. - -* Provide an `AutoSchema` subclass with more complex customisation: - - from rest_framework.views import APIView - from rest_framework.schemas import AutoSchema + from rest_framework.schemas.openapi import AutoSchema class CustomSchema(AutoSchema): def get_link(...): # Implement custom introspection here (or in other sub-methods) class CustomView(APIView): - ... + """APIView subclass with custom schema introspection.""" schema = CustomSchema() - This provides complete control over view introspection. - -* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for - the view explicitly: - - from rest_framework.views import APIView - from rest_framework.schemas import ManualSchema - - class CustomView(APIView): - ... - schema = ManualSchema(fields=[ - coreapi.Field( - "first_field", - required=True, - location="path", - schema=coreschema.String() - ), - coreapi.Field( - "second_field", - required=True, - location="path", - schema=coreschema.String() - ), - ]) - - This allows manually specifying the schema for some views whilst maintaining - automatic generation elsewhere. +This provides complete control over view introspection. You may disable schema generation for a view by setting `schema` to `None`: - class CustomView(APIView): - ... - schema = None # Will not appear in schema + class CustomView(APIView): + ... + schema = None # Will not appear in schema This also applies to extra actions for `ViewSet`s: - class CustomViewSet(viewsets.ModelViewSet): + class CustomViewSet(viewsets.ModelViewSet): - @action(detail=True, schema=None) - def extra_action(self, request, pk=None): - ... - ---- - -**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and -`ManualSchema` descriptors see the [API Reference below](#api-reference). - ---- - -# Adding a schema view - -There are a few different ways to add a schema view to your API, depending on -exactly what you need. - -## The get_schema_view shortcut - -The simplest way to include a schema in your project is to use the -`get_schema_view()` function. - - from rest_framework.schemas import get_schema_view - - schema_view = get_schema_view(title="Server Monitoring API") - - urlpatterns = [ - url('^$', schema_view), - ... - ] - -Once the view has been added, you'll be able to make API requests to retrieve -the auto-generated schema definition. - - $ http http://127.0.0.1:8000/ Accept:application/coreapi+json - HTTP/1.0 200 OK - Allow: GET, HEAD, OPTIONS - Content-Type: application/vnd.coreapi+json - - { - "_meta": { - "title": "Server Monitoring API" - }, - "_type": "document", - ... - } - -The arguments to `get_schema_view()` are: - -#### `title` - -May be used to provide a descriptive title for the schema definition. - -#### `url` - -May be used to pass a canonical URL for the schema. - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/' - ) - -#### `urlconf` - -A string representing the import path to the URL conf that you want -to generate an API schema for. This defaults to the value of Django's -ROOT_URLCONF setting. - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/', - urlconf='myproject.urls' - ) - -#### `renderer_classes` - -May be used to pass the set of renderer classes that can be used to render the API root endpoint. - - from rest_framework.schemas import get_schema_view - from rest_framework.renderers import JSONOpenAPIRenderer - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/', - renderer_classes=[JSONOpenAPIRenderer] - ) - -#### `patterns` - -List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls -to be exposed in the schema: - - schema_url_patterns = [ - url(r'^api/', include('myproject.api.urls')), - ] - - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/', - patterns=schema_url_patterns, - ) - -#### `generator_class` - -May be used to specify a `SchemaGenerator` subclass to be passed to the -`SchemaView`. - -#### `authentication_classes` - -May be used to specify the list of authentication classes that will apply to the schema endpoint. -Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES` - -#### `permission_classes` - -May be used to specify the list of permission classes that will apply to the schema endpoint. -Defaults to `settings.DEFAULT_PERMISSION_CLASSES` - -## Using an explicit schema view - -If you need a little more control than the `get_schema_view()` shortcut gives you, -then you can use the `SchemaGenerator` class directly to auto-generate the -`Document` instance, and to return that from a view. - -This option gives you the flexibility of setting up the schema endpoint -with whatever behaviour you want. For example, you can apply different -permission, throttling, or authentication policies to the schema endpoint. - -Here's an example of using `SchemaGenerator` together with a view to -return the schema. - -**views.py:** - - from rest_framework.decorators import api_view, renderer_classes - from rest_framework import renderers, response, schemas - - generator = schemas.SchemaGenerator(title='Bookings API') - - @api_view() - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - schema = generator.get_schema(request) - return response.Response(schema) - -**urls.py:** - - urlpatterns = [ - url('/', schema_view), - ... - ] - -You can also serve different schemas to different users, depending on the -permissions they have available. This approach can be used to ensure that -unauthenticated requests are presented with a different schema to -authenticated requests, or to ensure that different parts of the API are -made visible to different users depending on their role. - -In order to present a schema with endpoints filtered by user permissions, -you need to pass the `request` argument to the `get_schema()` method, like so: - - @api_view() - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - generator = schemas.SchemaGenerator(title='Bookings API') - return response.Response(generator.get_schema(request=request)) - -## Explicit schema definition - -An alternative to the auto-generated approach is to specify the API schema -explicitly, by declaring a `Document` object in your codebase. Doing so is a -little more work, but ensures that you have full control over the schema -representation. - - import coreapi - from rest_framework.decorators import api_view, renderer_classes - from rest_framework import renderers, response - - schema = coreapi.Document( - title='Bookings API', - content={ + @action(detail=True, schema=None) + def extra_action(self, request, pk=None): ... - } - ) - @api_view() - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - return response.Response(schema) +If you wish to provide a base `AutoSchema` subclass to be used throughout your +project you may adjust `settings.DEFAULT_SCHEMA_CLASS` appropriately. ---- - -# Schemas as documentation - -One common usage of API schemas is to use them to build documentation pages. - -The schema generation in REST framework uses docstrings to automatically -populate descriptions in the schema document. - -These descriptions will be based on: - -* The corresponding method docstring if one exists. -* A named section within the class docstring, which can be either single line or multi-line. -* The class docstring. - -## Examples - -An `APIView`, with an explicit method docstring. - - class ListUsernames(APIView): - def get(self, request): - """ - Return a list of all user names in the system. - """ - usernames = [user.username for user in User.objects.all()] - return Response(usernames) - -A `ViewSet`, with an explict action docstring. - - class ListUsernames(ViewSet): - def list(self, request): - """ - Return a list of all user names in the system. - """ - usernames = [user.username for user in User.objects.all()] - return Response(usernames) - -A generic view with sections in the class docstring, using single-line style. - - class UserList(generics.ListCreateAPIView): - """ - get: List all the users. - post: Create a new user. - """ - queryset = User.objects.all() - serializer_class = UserSerializer - permission_classes = (IsAdminUser,) - -A generic viewset with sections in the class docstring, using multi-line style. - - class UserViewSet(viewsets.ModelViewSet): - """ - API endpoint that allows users to be viewed or edited. - - retrieve: - Return a user instance. - - list: - Return all users, ordered by most recently joined. - """ - queryset = User.objects.all().order_by('-date_joined') - serializer_class = UserSerializer - ---- - -# API Reference - -## SchemaGenerator - -A class that walks a list of routed URL patterns, requests the schema for each view, -and collates the resulting CoreAPI Document. - -Typically you'll instantiate `SchemaGenerator` with a single argument, like so: - - generator = SchemaGenerator(title='Stock Prices API') - -Arguments: - -* `title` **required** - The name of the API. -* `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix. -* `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf. -* `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`. - -### get_schema(self, request) - -Returns a `coreapi.Document` instance that represents the API schema. - - @api_view - @renderer_classes([renderers.OpenAPIRenderer]) - def schema_view(request): - generator = schemas.SchemaGenerator(title='Bookings API') - return Response(generator.get_schema()) - -The `request` argument is optional, and may be used if you want to apply per-user -permissions to the resulting schema generation. - -### get_links(self, request) - -Return a nested dictionary containing all the links that should be included in the API schema. - -This is a good point to override if you want to modify the resulting structure of the generated schema, -as you can build a new dictionary with a different layout. - - -## AutoSchema - -A class that deals with introspection of individual views for schema generation. - -`AutoSchema` is attached to `APIView` via the `schema` attribute. - -The `AutoSchema` constructor takes a single keyword argument `manual_fields`. - -**`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to -the generated fields. Generated fields with a matching `name` will be overwritten. - - class CustomView(APIView): - schema = AutoSchema(manual_fields=[ - coreapi.Field( - "my_extra_field", - required=True, - location="path", - schema=coreschema.String() - ), - ]) - -For more advanced customisation subclass `AutoSchema` to customise schema generation. - - class CustomViewSchema(AutoSchema): - """ - Overrides `get_link()` to provide Custom Behavior X - """ - - def get_link(self, path, method, base_url): - link = super().get_link(path, method, base_url) - # Do something to customize link here... - return link - - class MyView(APIView): - schema = CustomViewSchema() - -The following methods are available to override. - -### get_link(self, path, method, base_url) - -Returns a `coreapi.Link` instance corresponding to the given view. - -This is the main entry point. -You can override this if you need to provide custom behaviors for particular views. - -### get_description(self, path, method) - -Returns a string to use as the link description. By default this is based on the -view docstring as described in the "Schemas as Documentation" section above. - -### get_encoding(self, path, method) - -Returns a string to indicate the encoding for any request body, when interacting -with the given view. Eg. `'application/json'`. May return a blank string for views -that do not expect a request body. - -### get_path_fields(self, path, method): - -Return a list of `coreapi.Field()` instances. One for each path parameter in the URL. - -### get_serializer_fields(self, path, method) - -Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view. - -### get_pagination_fields(self, path, method) - -Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view. - -### get_filter_fields(self, path, method) - -Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view. - -### get_manual_fields(self, path, method) - -Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor. - -May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this: - -```python -def get_manual_fields(self, path, method): - """Example adding per-method fields.""" - - extra_fields = [] - if method=='GET': - extra_fields = # ... list of extra fields for GET ... - if method=='POST': - extra_fields = # ... list of extra fields for POST ... - - manual_fields = super().get_manual_fields(path, method) - return manual_fields + extra_fields -``` - -### update_fields(fields, update_with) - -Utility `staticmethod`. Encapsulates logic to add or replace fields from a list -by `Field.name`. May be overridden to adjust replacement criteria. - - -## ManualSchema - -Allows manually providing a list of `coreapi.Field` instances for the schema, -plus an optional description. - - class MyView(APIView): - schema = ManualSchema(fields=[ - coreapi.Field( - "first_field", - required=True, - location="path", - schema=coreschema.String() - ), - coreapi.Field( - "second_field", - required=True, - location="path", - schema=coreschema.String() - ), - ] - ) - -The `ManualSchema` constructor takes two arguments: - -**`fields`**: A list of `coreapi.Field` instances. Required. - -**`description`**: A string description. Optional. - -**`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional. - ---- - -## Core API - -This documentation gives a brief overview of the components within the `coreapi` -package that are used to represent an API schema. - -Note that these classes are imported from the `coreapi` package, rather than -from the `rest_framework` package. - -### Document - -Represents a container for the API schema. - -#### `title` - -A name for the API. - -#### `url` - -A canonical URL for the API. - -#### `content` - -A dictionary, containing the `Link` objects that the schema contains. - -In order to provide more structure to the schema, the `content` dictionary -may be nested, typically to a second level. For example: - - content={ - "bookings": { - "list": Link(...), - "create": Link(...), - ... - }, - "venues": { - "list": Link(...), - ... - }, - ... - } - -### Link - -Represents an individual API endpoint. - -#### `url` - -The URL of the endpoint. May be a URI template, such as `/users/{username}/`. - -#### `action` - -The HTTP method associated with the endpoint. Note that URLs that support -more than one HTTP method, should correspond to a single `Link` for each. - -#### `fields` - -A list of `Field` instances, describing the available parameters on the input. - -#### `description` - -A short description of the meaning and intended usage of the endpoint. - -### Field - -Represents a single input parameter on a given API endpoint. - -#### `name` - -A descriptive name for the input. - -#### `required` - -A boolean, indicated if the client is required to included a value, or if -the parameter can be omitted. - -#### `location` - -Determines how the information is encoded into the request. Should be one of -the following strings: - -**"path"** - -Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`. - -These fields will normally correspond with [named arguments in the project URL conf][named-arguments]. - -**"query"** - -Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests. - -These fields will normally correspond with pagination and filtering controls on a view. - -**"form"** - -Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link. - -These fields will normally correspond with serializer fields on a view. - -**"body"** - -Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields. - -These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views. - -#### `encoding` - -**"application/json"** - -JSON encoded request content. Corresponds to views using `JSONParser`. -Valid only if either one or more `location="form"` fields, or a single -`location="body"` field is included on the `Link`. - -**"multipart/form-data"** - -Multipart encoded request content. Corresponds to views using `MultiPartParser`. -Valid only if one or more `location="form"` fields is included on the `Link`. - -**"application/x-www-form-urlencoded"** - -URL encoded request content. Corresponds to views using `FormParser`. Valid -only if one or more `location="form"` fields is included on the `Link`. - -**"application/octet-stream"** - -Binary upload request content. Corresponds to views using `FileUploadParser`. -Valid only if a `location="body"` field is included on the `Link`. - -#### `description` - -A short description of the meaning and intended usage of the input field. - - ---- - -# Third party packages - -## drf-yasg - Yet Another Swagger Generator - -[drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas, -named models, response bodies, enum/pattern/min/max validators, form parameters, etc. - -[cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api -[coreapi]: https://www.coreapi.org/ -[corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding -[drf-yasg]: https://github.com/axnsan12/drf-yasg/ -[open-api]: https://openapis.org/ -[json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html -[api-blueprint]: https://apiblueprint.org/ -[static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/ -[named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups +[openapi]: https://github.com/OAI/OpenAPI-Specification +[openapi-specification-extensions]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specification-extensions +[openapi-operation]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject \ No newline at end of file diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index feb5651f7..ef70adbe1 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -1,4 +1,7 @@ -source: serializers.py +--- +source: + - serializers.py +--- # Serializers @@ -308,7 +311,7 @@ The following example demonstrates how you might handle creating a user with a n class Meta: model = User - fields = ('username', 'email', 'profile') + fields = ['username', 'email', 'profile'] def create(self, validated_data): profile_data = validated_data.pop('profile') @@ -438,7 +441,7 @@ Declaring a `ModelSerializer` looks like this: class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') + fields = ['id', 'account_name', 'users', 'created'] By default, all the model fields on the class will be mapped to a corresponding serializer fields. @@ -467,7 +470,7 @@ For example: class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') + fields = ['id', 'account_name', 'users', 'created'] You can also set the `fields` attribute to the special value `'__all__'` to indicate that all fields in the model should be used. @@ -485,7 +488,7 @@ For example: class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - exclude = ('users',) + exclude = ['users'] In the example above, if the `Account` model had 3 fields `account_name`, `users`, and `created`, this will result in the fields `account_name` and `created` to be serialized. @@ -502,7 +505,7 @@ The default `ModelSerializer` uses primary keys for relationships, but you can a class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') + fields = ['id', 'account_name', 'users', 'created'] depth = 1 The `depth` option should be set to an integer value that indicates the depth of relationships that should be traversed before reverting to a flat representation. @@ -531,8 +534,8 @@ This option should be a list or tuple of field names, and is declared as follows class AccountSerializer(serializers.ModelSerializer): class Meta: model = Account - fields = ('id', 'account_name', 'users', 'created') - read_only_fields = ('account_name',) + fields = ['id', 'account_name', 'users', 'created'] + read_only_fields = ['account_name'] Model fields which have `editable=False` set, and `AutoField` fields will be set to read-only by default, and do not need to be added to the `read_only_fields` option. @@ -560,7 +563,7 @@ This option is a dictionary, mapping field names to a dictionary of keyword argu class CreateUserSerializer(serializers.ModelSerializer): class Meta: model = User - fields = ('email', 'username', 'password') + fields = ['email', 'username', 'password'] extra_kwargs = {'password': {'write_only': True}} def create(self, validated_data): @@ -670,7 +673,7 @@ You can explicitly include the primary key by adding it to the `fields` option, class AccountSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Account - fields = ('url', 'id', 'account_name', 'users', 'created') + fields = ['url', 'id', 'account_name', 'users', 'created'] ## Absolute and relative URLs @@ -702,7 +705,7 @@ You can override a URL field view name and lookup field by using either, or both class AccountSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Account - fields = ('account_url', 'account_name', 'users', 'created') + fields = ['account_url', 'account_name', 'users', 'created'] extra_kwargs = { 'url': {'view_name': 'accounts', 'lookup_field': 'account_name'}, 'users': {'lookup_field': 'username'} @@ -724,7 +727,7 @@ Alternatively you can set the fields on the serializer explicitly. For example: class Meta: model = Account - fields = ('url', 'account_name', 'users', 'created') + fields = ['url', 'account_name', 'users', 'created'] --- @@ -963,6 +966,7 @@ The following class is an example of a generic serializer that can handle coerci into primitive representations. """ def to_representation(self, obj): + output = {} for attribute_name in dir(obj): attribute = getattr(obj, attribute_name) if attribute_name.startswith('_'): @@ -988,6 +992,7 @@ The following class is an example of a generic serializer that can handle coerci else: # Force anything else to its string representation. output[attribute_name] = str(attribute) + return output --- @@ -1094,7 +1099,7 @@ This would then allow you to do the following: >>> class UserSerializer(DynamicFieldsModelSerializer): >>> class Meta: >>> model = User - >>> fields = ('id', 'username', 'email') + >>> fields = ['id', 'username', 'email'] >>> >>> print(UserSerializer(user)) {'id': 2, 'username': 'jonwatts', 'email': 'jon@example.com'} diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 85e38185e..768e343a7 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -1,4 +1,7 @@ -source: settings.py +--- +source: + - settings.py +--- # Settings @@ -11,12 +14,12 @@ Configuration for REST framework is all namespaced inside a single Django settin For example your project's `settings.py` file might include something like this: REST_FRAMEWORK = { - 'DEFAULT_RENDERER_CLASSES': ( + 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', - ), - 'DEFAULT_PARSER_CLASSES': ( + ], + 'DEFAULT_PARSER_CLASSES': [ 'rest_framework.parsers.JSONParser', - ) + ] } ## Accessing settings @@ -44,10 +47,10 @@ A list or tuple of renderer classes, that determines the default set of renderer Default: - ( + [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', - ) + ] #### DEFAULT_PARSER_CLASSES @@ -55,11 +58,11 @@ A list or tuple of parser classes, that determines the default set of parsers us Default: - ( + [ 'rest_framework.parsers.JSONParser', 'rest_framework.parsers.FormParser', 'rest_framework.parsers.MultiPartParser' - ) + ] #### DEFAULT_AUTHENTICATION_CLASSES @@ -67,10 +70,10 @@ A list or tuple of authentication classes, that determines the default set of au Default: - ( + [ 'rest_framework.authentication.SessionAuthentication', 'rest_framework.authentication.BasicAuthentication' - ) + ] #### DEFAULT_PERMISSION_CLASSES @@ -78,15 +81,15 @@ A list or tuple of permission classes, that determines the default set of permis Default: - ( + [ 'rest_framework.permissions.AllowAny', - ) + ] #### DEFAULT_THROTTLE_CLASSES A list or tuple of throttle classes, that determines the default set of throttles checked at the start of a view. -Default: `()` +Default: `[]` #### DEFAULT_CONTENT_NEGOTIATION_CLASS @@ -106,32 +109,19 @@ Default: `'rest_framework.schemas.AutoSchema'` *The following settings control the behavior of the generic class-based views.* -#### DEFAULT_PAGINATION_SERIALIZER_CLASS - ---- - -**This setting has been removed.** - -The pagination API does not use serializers to determine the output format, and -you'll need to instead override the `get_paginated_response method on a -pagination class in order to specify how the output format is controlled. - ---- - #### DEFAULT_FILTER_BACKENDS A list of filter backend classes that should be used for generic filtering. If set to `None` then generic filtering is disabled. -#### PAGINATE_BY +#### DEFAULT_PAGINATION_CLASS ---- +The default class to use for queryset pagination. If set to `None`, pagination +is disabled by default. See the pagination documentation for further guidance on +[setting](pagination.md#setting-the-pagination-style) and +[modifying](pagination.md#modifying-the-pagination-style) the pagination style. -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). - ---- +Default: `None` #### PAGE_SIZE @@ -139,26 +129,6 @@ The default page size to use for pagination. If set to `None`, pagination is di Default: `None` -#### PAGINATE_BY_PARAM - ---- - -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). - ---- - -#### MAX_PAGINATE_BY - ---- - -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). - ---- - ### SEARCH_PARAM The name of a query parameter, which can be used to specify the search term used by `SearchFilter`. @@ -235,10 +205,10 @@ The format of any of these renderer classes may be used when constructing a test Default: - ( + [ 'rest_framework.renderers.MultiPartRenderer', 'rest_framework.renderers.JSONRenderer' - ) + ] --- @@ -404,7 +374,7 @@ This should be a function with the following signature: If the view instance inherits `ViewSet`, it may have been initialized with several optional arguments: -* `name`: A name expliticly provided to a view in the viewset. Typically, this value should be used as-is when provided. +* `name`: A name explicitly provided to a view in the viewset. Typically, this value should be used as-is when provided. * `suffix`: Text used when differentiating individual views in a viewset. This argument is mutually exclusive to `name`. * `detail`: Boolean that differentiates an individual view in a viewset as either being a 'list' or 'detail' view. diff --git a/docs/api-guide/status-codes.md b/docs/api-guide/status-codes.md index 1016f3374..a37ba15d4 100644 --- a/docs/api-guide/status-codes.md +++ b/docs/api-guide/status-codes.md @@ -1,4 +1,7 @@ -source: status.py +--- +source: + - status.py +--- # Status Codes @@ -20,13 +23,13 @@ The full set of HTTP status codes included in the `status` module is listed belo The module also includes a set of helper functions for testing if a status code is in a given range. from rest_framework import status - from rest_framework.test import APITestCase + from rest_framework.test import APITestCase - class ExampleTestCase(APITestCase): - def test_url_root(self): - url = reverse('index') - response = self.client.get(url) - self.assertTrue(status.is_success(response.status_code)) + class ExampleTestCase(APITestCase): + def test_url_root(self): + url = reverse('index') + response = self.client.get(url) + self.assertTrue(status.is_success(response.status_code)) For more information on proper usage of HTTP status codes see [RFC 2616][rfc2616] @@ -51,6 +54,8 @@ This class of status code indicates that the client's request was successfully r HTTP_205_RESET_CONTENT HTTP_206_PARTIAL_CONTENT HTTP_207_MULTI_STATUS + HTTP_208_ALREADY_REPORTED + HTTP_226_IM_USED ## Redirection - 3xx @@ -64,6 +69,7 @@ This class of status code indicates that further action needs to be taken by the HTTP_305_USE_PROXY HTTP_306_RESERVED HTTP_307_TEMPORARY_REDIRECT + HTTP_308_PERMANENT_REDIRECT ## Client Error - 4xx @@ -90,6 +96,7 @@ The 4xx class of status code is intended for cases in which the client seems to HTTP_422_UNPROCESSABLE_ENTITY HTTP_423_LOCKED HTTP_424_FAILED_DEPENDENCY + HTTP_426_UPGRADE_REQUIRED HTTP_428_PRECONDITION_REQUIRED HTTP_429_TOO_MANY_REQUESTS HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE @@ -105,7 +112,11 @@ Response status codes beginning with the digit "5" indicate cases in which the s HTTP_503_SERVICE_UNAVAILABLE HTTP_504_GATEWAY_TIMEOUT HTTP_505_HTTP_VERSION_NOT_SUPPORTED + HTTP_506_VARIANT_ALSO_NEGOTIATES HTTP_507_INSUFFICIENT_STORAGE + HTTP_508_LOOP_DETECTED + HTTP_509_BANDWIDTH_LIMIT_EXCEEDED + HTTP_510_NOT_EXTENDED HTTP_511_NETWORK_AUTHENTICATION_REQUIRED ## Helper functions diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md index 5ca01b4e7..dab0e264d 100644 --- a/docs/api-guide/testing.md +++ b/docs/api-guide/testing.md @@ -1,4 +1,7 @@ -source: test.py +--- +source: + - test.py +--- # Testing @@ -399,11 +402,11 @@ For example, to add support for using `format='html'` in test requests, you migh REST_FRAMEWORK = { ... - 'TEST_REQUEST_RENDERER_CLASSES': ( + 'TEST_REQUEST_RENDERER_CLASSES': [ 'rest_framework.renderers.MultiPartRenderer', 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.TemplateHTMLRenderer' - ) + ] } [cite]: https://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index dade47460..215c735bf 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -1,4 +1,7 @@ -source: throttling.py +--- +source: + - throttling.py +--- # Throttling @@ -28,10 +31,10 @@ If any throttle check fails an `exceptions.Throttled` exception will be raised, The default throttling policy may be set globally, using the `DEFAULT_THROTTLE_CLASSES` and `DEFAULT_THROTTLE_RATES` settings. For example. REST_FRAMEWORK = { - 'DEFAULT_THROTTLE_CLASSES': ( + 'DEFAULT_THROTTLE_CLASSES': [ 'rest_framework.throttling.AnonRateThrottle', 'rest_framework.throttling.UserRateThrottle' - ), + ], 'DEFAULT_THROTTLE_RATES': { 'anon': '100/day', 'user': '1000/day' @@ -48,7 +51,7 @@ using the `APIView` class-based views. from rest_framework.views import APIView class ExampleView(APIView): - throttle_classes = (UserRateThrottle,) + throttle_classes = [UserRateThrottle] def get(self, request, format=None): content = { @@ -74,7 +77,7 @@ If you need to strictly identify unique client IP addresses, you'll need to firs It is important to understand that if you configure the `NUM_PROXIES` setting, then all clients behind a unique [NAT'd](https://en.wikipedia.org/wiki/Network_address_translation) gateway will be treated as a single client. -Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifing-clients]. +Further context on how the `X-Forwarded-For` header works, and identifying a remote client IP can be [found here][identifying-clients]. ## Setting up the cache @@ -126,10 +129,10 @@ For example, multiple user throttle rates could be implemented by using the foll ...and the following settings. REST_FRAMEWORK = { - 'DEFAULT_THROTTLE_CLASSES': ( + 'DEFAULT_THROTTLE_CLASSES': [ 'example.throttles.BurstRateThrottle', 'example.throttles.SustainedRateThrottle' - ), + ], 'DEFAULT_THROTTLE_RATES': { 'burst': '60/min', 'sustained': '1000/day' @@ -161,9 +164,9 @@ For example, given the following views... ...and the following settings. REST_FRAMEWORK = { - 'DEFAULT_THROTTLE_CLASSES': ( + 'DEFAULT_THROTTLE_CLASSES': [ 'rest_framework.throttling.ScopedRateThrottle', - ), + ], 'DEFAULT_THROTTLE_RATES': { 'contacts': '1000/day', 'uploads': '20/day' @@ -194,6 +197,6 @@ The following is an example of a rate throttle, that will randomly throttle 1 in [cite]: https://developer.twitter.com/en/docs/basics/rate-limiting [permissions]: permissions.md -[identifing-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster +[identifying-clients]: http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#Multiple_Proxies_in_front_of_the_cluster [cache-setting]: https://docs.djangoproject.com/en/stable/ref/settings/#caches [cache-docs]: https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache diff --git a/docs/api-guide/validators.md b/docs/api-guide/validators.md index 9b2fc82ed..87417b7f1 100644 --- a/docs/api-guide/validators.md +++ b/docs/api-guide/validators.md @@ -1,4 +1,7 @@ -source: validators.py +--- +source: + - validators.py +--- # Validators @@ -94,7 +97,7 @@ The validator should be applied to *serializer classes*, like so: validators = [ UniqueTogetherValidator( queryset=ToDoItem.objects.all(), - fields=('list', 'position') + fields=['list', 'position'] ) ] @@ -149,8 +152,6 @@ If you want the date field to be visible, but not editable by the user, then set published = serializers.DateTimeField(read_only=True, default=timezone.now) -The field will not be writable to the user, but the default value will still be passed through to the `validated_data`. - #### Using with a hidden date field. If you want the date field to be entirely hidden from the user, then use `HiddenField`. This field type does not accept user input, but instead always returns its default value to the `validated_data` in the serializer. @@ -221,7 +222,7 @@ For example: # Apply custom validation either here, or in the view. class Meta: - fields = ('client', 'date', 'amount') + fields = ['client', 'date', 'amount'] extra_kwargs = {'client': {'required': False}} validators = [] # Remove a default "unique together" constraint. diff --git a/docs/api-guide/versioning.md b/docs/api-guide/versioning.md index c106e536d..ad76ced3d 100644 --- a/docs/api-guide/versioning.md +++ b/docs/api-guide/versioning.md @@ -1,4 +1,7 @@ -source: versioning.py +--- +source: + - versioning.py +--- # Versioning diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index 7b2c4eff7..45226d57b 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -1,5 +1,8 @@ -source: decorators.py - views.py +--- +source: + - decorators.py + - views.py +--- # Class-based Views @@ -32,8 +35,8 @@ For example: * Requires token authentication. * Only admin users are able to access this view. """ - authentication_classes = (authentication.TokenAuthentication,) - permission_classes = (permissions.IsAdminUser,) + authentication_classes = [authentication.TokenAuthentication] + permission_classes = [permissions.IsAdminUser] def get(self, request, format=None): """ diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index e7cf4d48f..cd765d3e6 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -1,4 +1,7 @@ -source: viewsets.py +--- +source: + - viewsets.py +--- # ViewSets diff --git a/docs/community/3.0-announcement.md b/docs/community/3.0-announcement.md index 7a29b5554..b9461defe 100644 --- a/docs/community/3.0-announcement.md +++ b/docs/community/3.0-announcement.md @@ -258,13 +258,13 @@ If you try to use a writable nested serializer without writing a custom `create( >>> class ProfileSerializer(serializers.ModelSerializer): >>> class Meta: >>> model = Profile - >>> fields = ('address', 'phone') + >>> fields = ['address', 'phone'] >>> >>> class UserSerializer(serializers.ModelSerializer): >>> profile = ProfileSerializer() >>> class Meta: >>> model = User - >>> fields = ('username', 'email', 'profile') + >>> fields = ['username', 'email', 'profile'] >>> >>> data = { >>> 'username': 'lizzy', @@ -283,7 +283,7 @@ To use writable nested serialization you'll want to declare a nested field on th class Meta: model = User - fields = ('username', 'email', 'profile') + fields = ['username', 'email', 'profile'] def create(self, validated_data): profile_data = validated_data.pop('profile') @@ -327,7 +327,7 @@ The `write_only_fields` option on `ModelSerializer` has been moved to `PendingDe class MySerializer(serializer.ModelSerializer): class Meta: model = MyModel - fields = ('id', 'email', 'notes', 'is_admin') + fields = ['id', 'email', 'notes', 'is_admin'] extra_kwargs = { 'is_admin': {'write_only': True} } @@ -339,7 +339,7 @@ Alternatively, specify the field explicitly on the serializer class: class Meta: model = MyModel - fields = ('id', 'email', 'notes', 'is_admin') + fields = ['id', 'email', 'notes', 'is_admin'] The `read_only_fields` option remains as a convenient shortcut for the more common case. @@ -350,7 +350,7 @@ The `view_name` and `lookup_field` options have been moved to `PendingDeprecatio class MySerializer(serializer.HyperlinkedModelSerializer): class Meta: model = MyModel - fields = ('url', 'email', 'notes', 'is_admin') + fields = ['url', 'email', 'notes', 'is_admin'] extra_kwargs = { 'url': {'lookup_field': 'uuid'} } @@ -365,7 +365,7 @@ Alternatively, specify the field explicitly on the serializer class: class Meta: model = MyModel - fields = ('url', 'email', 'notes', 'is_admin') + fields = ['url', 'email', 'notes', 'is_admin'] #### Fields for model methods and properties. @@ -384,7 +384,7 @@ You can include `expiry_date` as a field option on a `ModelSerializer` class. class InvitationSerializer(serializers.ModelSerializer): class Meta: model = Invitation - fields = ('to_email', 'message', 'expiry_date') + fields = ['to_email', 'message', 'expiry_date'] These fields will be mapped to `serializers.ReadOnlyField()` instances. @@ -738,7 +738,7 @@ The `UniqueTogetherValidator` should be applied to a serializer, and takes a `qu class Meta: validators = [UniqueTogetherValidator( queryset=RaceResult.objects.all(), - fields=('category', 'position') + fields=['category', 'position'] )] #### The `UniqueForDateValidator` classes. diff --git a/docs/community/3.1-announcement.md b/docs/community/3.1-announcement.md index 2213c379d..641f313d0 100644 --- a/docs/community/3.1-announcement.md +++ b/docs/community/3.1-announcement.md @@ -61,7 +61,7 @@ For example, when using `NamespaceVersioning`, and the following hyperlinked ser class AccountsSerializer(serializer.HyperlinkedModelSerializer): class Meta: model = Accounts - fields = ('account_name', 'users') + fields = ['account_name', 'users'] The output representation would match the version used on the incoming request. Like so: diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md new file mode 100644 index 000000000..065dd3480 --- /dev/null +++ b/docs/community/3.10-announcement.md @@ -0,0 +1,147 @@ + + +# Django REST framework 3.10 + +The 3.10 release drops support for Python 2. + +* Our supported Python versions are now: 3.5, 3.6, and 3.7. +* Our supported Django versions are now: 1.11, 2.0, 2.1, and 2.2. + +## OpenAPI Schema Generation + +Since we first introduced schema support in Django REST Framework 3.5, OpenAPI has emerged as the widely adopted standard for modeling Web APIs. + +This release begins the deprecation process for the CoreAPI based schema generation, and introduces OpenAPI schema generation in its place. + +--- + +## Continuing to use CoreAPI + +If you're currently using the CoreAPI schemas, you'll need to make sure to +update your REST framework settings to include `DEFAULT_SCHEMA_CLASS` explicitly. + +**settings.py**: + +```python +REST_FRAMEWORK = { + ... + 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema' +} +``` + +You'll still be able to keep using CoreAPI schemas, API docs, and client for the +foreseeable future. We'll aim to ensure that the CoreAPI schema generator remains +available as a third party package, even once it has eventually been removed +from REST framework, scheduled for version 3.12. + +We have removed the old documentation for the CoreAPI based schema generation. +You may view the [Legacy CoreAPI documentation here][legacy-core-api-docs]. + +---- + +## OpenAPI Quickstart + +You can generate a static OpenAPI schema, using the `generateschema` management +command. + +Alternately, to have the project serve an API schema, use the `get_schema_view()` +shortcut. + +In your `urls.py`: + +```python +from rest_framework.schemas import get_schema_view + +urlpatterns = [ + # ... + # Use the `get_schema_view()` helper to add a `SchemaView` to project URLs. + # * `title` and `description` parameters are passed to `SchemaGenerator`. + # * Provide view name for use with `reverse()`. + path('openapi', get_schema_view( + title="Your Project", + description="API for all things …" + ), name='openapi-schema'), + # ... +] +``` + +### Customization + +For customizations that you want to apply across the the entire API, you can subclass `rest_framework.schemas.openapi.SchemaGenerator` and provide it as an argument +to the `generateschema` command or `get_schema_view()` helper function. + +For specific per-view customizations, you can subclass `AutoSchema`, +making sure to set `schema = ` on the view. + +For more details, see the [API Schema documentation](../api-guide/schemas.md). + +### API Documentation + +There are some great third party options for documenting your API, based on the +OpenAPI schema. + +See the [Documenting you API](../topics/documenting-your-api.md) section for more details. + +--- + +## Feature Roadmap + +Given that our OpenAPI schema generation is a new feature, it's likely that there +will still be some iterative improvements for us to make. There will be two +main cases here: + +* Expanding the supported range of OpenAPI schemas that are generated by default. +* Improving the ability for developers to customize the output. + +We'll aim to bring the first type of change quickly in point releases. For the +second kind we'd like to adopt a slower approach, to make sure we keep the API +simple, and as widely applicable as possible, before we bring in API changes. + +It's also possible that we'll end up implementing API documentation and API client +tooling that are driven by the OpenAPI schema. The `apistar` project has a +significant amount of work towards this. However, if we do so, we'll plan +on keeping any tooling outside of the core framework. + +--- + +## 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), and [Lights On Software](https://lightsonsoftware.com).* + +[legacy-core-api-docs]:https://github.com/encode/django-rest-framework/blob/master/docs/coreapi/index.md +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: community/funding.md diff --git a/docs/community/3.6-announcement.md b/docs/community/3.6-announcement.md index c6e8dfa06..c41ad8ecb 100644 --- a/docs/community/3.6-announcement.md +++ b/docs/community/3.6-announcement.md @@ -60,7 +60,7 @@ REST framework's new API documentation supports a number of features: * Support for various authentication schemes. * Code snippets for the Python, JavaScript, and Command Line clients. -The `coreapi` library is required as a dependancy for the API docs. Make sure +The `coreapi` library is required as a dependency for the API docs. Make sure to install the latest version (2.3.0 or above). The `pygments` and `markdown` libraries are optional but recommended. diff --git a/docs/community/jobs.md b/docs/community/jobs.md index e74b78c7f..5f3d60b55 100644 --- a/docs/community/jobs.md +++ b/docs/community/jobs.md @@ -9,6 +9,7 @@ Looking for a new Django REST Framework related role? On this site we provide a * [https://www.python.org/jobs/][python-org-jobs] * [https://djangogigs.com][django-gigs-com] * [https://djangojobs.net/jobs/][django-jobs-net] +* [https://findwork.dev/django-rest-framework-jobs][findwork-dev] * [https://www.indeed.com/q-Django-jobs.html][indeed-com] * [https://stackoverflow.com/jobs/developer-jobs-using-django][stackoverflow-com] * [https://www.upwork.com/o/jobs/browse/skill/django-framework/][upwork-com] @@ -26,6 +27,7 @@ Wonder how else you can help? One of the best ways you can help Django REST Fram [python-org-jobs]: https://www.python.org/jobs/ [django-gigs-com]: https://djangogigs.com [django-jobs-net]: https://djangojobs.net/jobs/ +[findwork-dev]: https://findwork.dev/django-rest-framework-jobs [indeed-com]: https://www.indeed.com/q-Django-jobs.html [stackoverflow-com]: https://stackoverflow.com/jobs/developer-jobs-using-django [upwork-com]: https://www.upwork.com/o/jobs/browse/skill/django-framework/ diff --git a/docs/community/release-notes.md b/docs/community/release-notes.md index 6fcb5bb6b..cdaa35044 100644 --- a/docs/community/release-notes.md +++ b/docs/community/release-notes.md @@ -38,11 +38,66 @@ You can determine your currently installed version using `pip show`: --- +## 3.10.x series + +### 3.10.3 + +* Include API version in OpenAPI schema generation, defaulting to empty string. +* Add pagination properties to OpenAPI response schemas. +* Add missing "description" property to OpenAPI response schemas. +* Only include "required" for non-empty cases in OpenAPI schemas. +* Fix response schemas for "DELETE" case in OpenAPI schemas. +* Use an array type for list view response schemas. +* Use consistent `lowerInitialCamelCase` style in OpenAPI operation IDs. +* Fix `minLength`/`maxLength`/`minItems`/`maxItems` properties in OpenAPI schemas. +* Only call `FileField.url` once in serialization, for improved performance. +* Fix an edge case where throttling calcualtions could error after a configuration change. + +* TODO + +### 3.10.2 + +**Date**: 29th July 2019 + +* Various `OpenAPI` schema fixes. +* Ability to specify urlconf in include_docs_urls. + +### 3.10.1 + +**Date**: 17th July 2019 + +* Don't include autocomplete fields on TokenAuth admin, since it forces constraints on custom user models & admin. +* Require `uritemplate` for OpenAPI schema generation, but not `coreapi`. + +### 3.10.0 + +**Date**: [15th July 2019][3.10.0-milestone] + +* Switch to OpenAPI schema generation. +* Drop Python 2 support. +* Add `generateschema --generator_class` CLI option +* Updated PyYaml dependency for OpenAPI schema generation to `pyyaml>=5.1` [#6680][gh6680] +* Resolve DeprecationWarning with markdown. [#6317][gh6317] +* Use `user.get_username` in templates, in preference to `user.username`. +* Fix for cursor pagination issue that could occur after object deletions. +* Fix for nullable fields with `source="*"` +* Always apply all throttle classes during throttling checks. +* Updates to jQuery and Markdown dependencies. +* Don't strict disallow redundant `SerializerMethodField` field name arguments. +* Don't render extra actions in browable API if not authenticated. +* Strip null characters from search parameters. + ## 3.9.x series +### 3.9.4 + +**Date**: 10th May 2019 + +This is a maintenance release that fixes an error handling bug under Python 2. + ### 3.9.3 -**Date**: [29th April 2019] +**Date**: 29th April 2019 This is the last Django REST Framework release that will support Python 2. Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10. @@ -52,7 +107,7 @@ Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10. ### 3.9.2 -**Date**: [3rd March 2019][3.9.1-milestone] +**Date**: [3rd March 2019][3.9.2-milestone] * Routers: invalidate `_urls` cache on `register()` [#6407][gh6407] * Deferred schema renderer creation to avoid requiring pyyaml. [#6416][gh6416] @@ -304,7 +359,7 @@ Be sure to upgrade to Python 3 before upgrading to Django REST Framework 3.10. Note: `AutoSchema.__init__` now ensures `manual_fields` is a list. Previously may have been stored internally as `None`. -* Remove ulrparse compatability shim; use six instead [#5579][gh5579] +* Remove ulrparse compatibility shim; use six instead [#5579][gh5579] * Drop compat wrapper for `TimeDelta.total_seconds()` [#5577][gh5577] * Clean up all whitespace throughout project [#5578][gh5578] * Compat cleanup [#5581][gh5581] @@ -1175,7 +1230,8 @@ For older release notes, [please see the version 2.x documentation][old-release- [3.8.2-milestone]: https://github.com/encode/django-rest-framework/milestone/68?closed=1 [3.9.0-milestone]: https://github.com/encode/django-rest-framework/milestone/66?closed=1 [3.9.1-milestone]: https://github.com/encode/django-rest-framework/milestone/70?closed=1 -[3.9.1-milestone]: https://github.com/encode/django-rest-framework/milestone/71?closed=1 +[3.9.2-milestone]: https://github.com/encode/django-rest-framework/milestone/71?closed=1 +[3.10.0-milestone]: https://github.com/encode/django-rest-framework/milestone/69?closed=1 [gh2013]: https://github.com/encode/django-rest-framework/issues/2013 @@ -2119,3 +2175,7 @@ For older release notes, [please see the version 2.x documentation][old-release- [gh6613]: https://github.com/encode/django-rest-framework/issues/6613 + + +[gh6680]: https://github.com/encode/django-rest-framework/issues/6680 +[gh6317]: https://github.com/encode/django-rest-framework/issues/6317 diff --git a/docs/community/third-party-packages.md b/docs/community/third-party-packages.md index ace54f6f7..0f8bdc4a4 100644 --- a/docs/community/third-party-packages.md +++ b/docs/community/third-party-packages.md @@ -20,7 +20,7 @@ If you have an idea for a new feature please consider how it may be packaged as You can use [this cookiecutter template][cookiecutter] for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution. -Note: Let us know if you have an alternate cookiecuter package so we can also link to it. +Note: Let us know if you have an alternate cookiecutter package so we can also link to it. #### Running the initial cookiecutter command @@ -55,7 +55,7 @@ We recommend using [Travis CI][travis-ci], a hosted continuous integration servi To get started with Travis CI, [sign in][travis-ci] with your GitHub account. Once you're signed in, go to your [profile page][travis-profile] and enable the service hook for the repository you want. -If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests. By default, builds are triggered everytime you push to your repository or create Pull Request. +If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests. By default, builds are triggered every time you push to your repository or create Pull Request. #### Uploading to PyPI @@ -197,6 +197,7 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [djangorestframework-composed-permissions][djangorestframework-composed-permissions] - Provides a simple way to define complex permissions. * [rest_condition][rest-condition] - Another extension for building complex permissions in a simple and convenient way. * [dry-rest-permissions][dry-rest-permissions] - Provides a simple way to define permissions for individual api actions. +* [drf-access-policy][drf-access-policy] - Declarative and flexible permissions inspired by AWS' IAM policies. ### Serializers @@ -208,6 +209,8 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [django-rest-framework-serializer-extensions][drf-serializer-extensions] - Enables black/whitelisting fields, and conditionally expanding child serializers on a per-view/request basis. * [djangorestframework-queryfields][djangorestframework-queryfields] - Serializer mixin allowing clients to control which fields will be sent in the API response. +* [drf-flex-fields][drf-flex-fields] - Serializer providing dynamic field expansion and sparse field sets via URL parameters. +* [drf-action-serializer][drf-action-serializer] - Serializer providing per-action fields config for use with ViewSets to prevent having to write multiple serializers. ### Serializer fields @@ -244,6 +247,7 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [djangorestframework-chain][djangorestframework-chain] - Allows arbitrary chaining of both relations and lookup filters. * [django-url-filter][django-url-filter] - Allows a safe way to filter data via human-friendly URLs. It is a generic library which is not tied to DRF but it provides easy integration with DRF. * [drf-url-filter][drf-url-filter] is a simple Django app to apply filters on drf `ModelViewSet`'s `Queryset` in a clean, simple and configurable way. It also supports validations on incoming query params and their values. +* [django-rest-framework-guardian][django-rest-framework-guardian] - Provides integration with django-guardian, including the `DjangoObjectPermissionsFilter` previously found in DRF. ### Misc @@ -264,6 +268,8 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque * [djangorest-alchemy][djangorest-alchemy] - SQLAlchemy support for REST framework. * [djangorestframework-datatables][djangorestframework-datatables] - Seamless integration between Django REST framework and [Datatables](https://datatables.net). * [django-rest-framework-condition][django-rest-framework-condition] - Decorators for managing HTTP cache headers for Django REST framework (ETag and Last-modified). +* [django-rest-witchcraft][django-rest-witchcraft] - Provides DRF integration with SQLAlchemy with SQLAlchemy model serializers/viewsets and a bunch of other goodies +* [djangorestframework-mvt][djangorestframework-mvt] - An extension for creating views that serve Postgres data as Map Box Vector Tiles. [cite]: http://www.software-ecosystems.com/Software_Ecosystems/Ecosystems.html [cookiecutter]: https://github.com/jpadilla/cookiecutter-django-rest-framework @@ -338,3 +344,9 @@ To submit new content, [open an issue][drf-create-issue] or [create a pull reque [djangorest-alchemy]: https://github.com/dealertrack/djangorest-alchemy [djangorestframework-datatables]: https://github.com/izimobil/django-rest-framework-datatables [django-rest-framework-condition]: https://github.com/jozo/django-rest-framework-condition +[django-rest-witchcraft]: https://github.com/shosca/django-rest-witchcraft +[drf-access-policy]: https://github.com/rsinger86/drf-access-policy +[drf-flex-fields]: https://github.com/rsinger86/drf-flex-fields +[drf-action-serializer]: https://github.com/gregschmit/drf-action-serializer +[djangorestframework-mvt]: https://github.com/corteva/djangorestframework-mvt +[django-rest-framework-guardian]: https://github.com/rpkilby/django-rest-framework-guardian diff --git a/docs/community/tutorials-and-resources.md b/docs/community/tutorials-and-resources.md index a03d63a3c..7993f54fb 100644 --- a/docs/community/tutorials-and-resources.md +++ b/docs/community/tutorials-and-resources.md @@ -85,11 +85,11 @@ Want your Django REST Framework talk/tutorial/article to be added to our website [beginners-guide-to-the-django-rest-framework]: https://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786 -[getting-started-with-django-rest-framework-and-angularjs]: https://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html +[getting-started-with-django-rest-framework-and-angularjs]: https://blog.kevinastone.com/django-rest-framework-and-angular-js [end-to-end-web-app-with-django-rest-framework-angularjs]: https://mourafiq.com/2013/07/01/end-to-end-web-app-with-django-angular-1.html -[start-your-api-django-rest-framework-part-1]: https://godjango.com/41-start-your-api-django-rest-framework-part-1/ -[permissions-authentication-django-rest-framework-part-2]: https://godjango.com/43-permissions-authentication-django-rest-framework-part-2/ -[viewsets-and-routers-django-rest-framework-part-3]: https://godjango.com/45-viewsets-and-routers-django-rest-framework-part-3/ +[start-your-api-django-rest-framework-part-1]: https://www.youtube.com/watch?v=hqo2kk91WpE +[permissions-authentication-django-rest-framework-part-2]: https://www.youtube.com/watch?v=R3xvUDUZxGU +[viewsets-and-routers-django-rest-framework-part-3]: https://www.youtube.com/watch?v=2d6w4DGQ4OU [django-rest-framework-user-endpoint]: https://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/ [check-credentials-using-django-rest-framework]: https://richardtier.com/2014/03/06/110/ [ember-and-django-part 1-video]: http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1 diff --git a/docs/tutorial/7-schemas-and-client-libraries.md b/docs/coreapi/7-schemas-and-client-libraries.md similarity index 100% rename from docs/tutorial/7-schemas-and-client-libraries.md rename to docs/coreapi/7-schemas-and-client-libraries.md diff --git a/docs/coreapi/from-documenting-your-api.md b/docs/coreapi/from-documenting-your-api.md new file mode 100644 index 000000000..9ac3be686 --- /dev/null +++ b/docs/coreapi/from-documenting-your-api.md @@ -0,0 +1,171 @@ + +## Built-in API documentation + +The built-in API documentation includes: + +* Documentation of API endpoints. +* Automatically generated code samples for each of the available API client libraries. +* Support for API interaction. + +### Installation + +The `coreapi` library is required as a dependency for the API docs. Make sure +to install the latest version. The `Pygments` and `Markdown` libraries +are optional but recommended. + +To install the API documentation, you'll need to include it in your project's URLconf: + + from rest_framework.documentation import include_docs_urls + + urlpatterns = [ + ... + url(r'^docs/', include_docs_urls(title='My API title')) + ] + +This will include two different views: + + * `/docs/` - The documentation page itself. + * `/docs/schema.js` - A JavaScript resource that exposes the API schema. + +--- + +**Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas. +This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`. + +To be compatible with this behaviour, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case. + +You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`: + + from rest_framework.documentation import include_docs_urls + + urlpatterns = [ + ... + # Generate schema with valid `request` instance: + url(r'^docs/', include_docs_urls(title='My API title', public=False)) + ] + + +--- + + +### Documenting your views + +You can document your views by including docstrings that describe each of the available actions. +For example: + + class UserList(generics.ListAPIView): + """ + Return a list of all the existing users. + """ + +If a view supports multiple methods, you should split your documentation using `method:` style delimiters. + + class UserList(generics.ListCreateAPIView): + """ + get: + Return a list of all the existing users. + + post: + Create a new user instance. + """ + +When using viewsets, you should use the relevant action names as delimiters. + + class UserViewSet(viewsets.ModelViewSet): + """ + retrieve: + Return the given user. + + list: + Return a list of all the existing users. + + create: + Create a new user instance. + """ + +Custom actions on viewsets can also be documented in a similar way using the method names +as delimiters or by attaching the documentation to action mapping methods. + + class UserViewSet(viewsets.ModelViewset): + ... + + @action(detail=False, methods=['get', 'post']) + def some_action(self, request, *args, **kwargs): + """ + get: + A description of the get method on the custom action. + + post: + A description of the post method on the custom action. + """ + + @some_action.mapping.put + def put_some_action(): + """ + A description of the put method on the custom action. + """ + + +### `documentation` API Reference + +The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`. + + `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.) + +#### `include_docs_urls` + +* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. +* `description`: Default `None`. May be used to provide a description for the schema definition. +* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. +* `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views. +* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. +* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. +* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. +* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. +* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. + +#### `get_docs_view` + +* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. +* `description`: Default `None`. May be used to provide a description for the schema definition. +* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. +* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. +* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. +* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. +* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. +* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`. +* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats. + +#### `get_schemajs_view` + +* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. +* `description`: Default `None`. May be used to provide a description for the schema definition. +* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. +* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. +* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. +* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. +* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. +* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. + + +### Customising code samples + +The built-in API documentation includes automatically generated code samples for +each of the available API client libraries. + +You may customise these samples by subclassing `DocumentationRenderer`, setting +`languages` to the list of languages you wish to support: + + from rest_framework.renderers import DocumentationRenderer + + + class CustomRenderer(DocumentationRenderer): + languages = ['ruby', 'go'] + +For each language you need to provide an `intro` template, detailing installation instructions and such, +plus a generic template for making API requests, that can be filled with individual request details. +See the [templates for the bundled languages][client-library-templates] for examples. + +--- + +[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs \ No newline at end of file diff --git a/docs/coreapi/index.md b/docs/coreapi/index.md new file mode 100644 index 000000000..9195eb33e --- /dev/null +++ b/docs/coreapi/index.md @@ -0,0 +1,29 @@ +# Legacy CoreAPI Schemas Docs + +Use of CoreAPI-based schemas were deprecated with the introduction of native OpenAPI-based schema generation in Django REST Framework v3.10. + +See the [Version 3.10 Release Announcement](/community/3.10-announcement.md) for more details. + +---- + +You can continue to use CoreAPI schemas by setting the appropriate default schema class: + +```python +# In settings.py +REST_FRAMEWORK = { + 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema', +} +``` + +Under-the-hood, any subclass of `coreapi.AutoSchema` here will trigger use of the old CoreAPI schemas. +**Otherwise** you will automatically be opted-in to the new OpenAPI schemas. + +All CoreAPI related code will be removed in Django REST Framework v3.12. Switch to OpenAPI schemas by then. + +---- + +For reference this folder contains the old CoreAPI related documentation: + +* [Tutorial 7: Schemas & client libraries](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//7-schemas-and-client-libraries.md). +* [Excerpts from _Documenting your API_ topic page](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//from-documenting-your-api.md). +* [`rest_framework.schemas` API Reference](https://github.com/encode/django-rest-framework/blob/master/docs/coreapi//schemas.md). diff --git a/docs/coreapi/schemas.md b/docs/coreapi/schemas.md new file mode 100644 index 000000000..6ee620343 --- /dev/null +++ b/docs/coreapi/schemas.md @@ -0,0 +1,838 @@ +source: schemas.py + +# Schemas + +> A machine-readable [schema] describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. +> +> — Heroku, [JSON Schema for the Heroku Platform API][cite] + +API schemas are a useful tool that allow for a range of use cases, including +generating reference documentation, or driving dynamic client libraries that +can interact with your API. + +## Install Core API & PyYAML + +You'll need to install the `coreapi` package in order to add schema support +for REST framework. You probably also want to install `pyyaml`, so that you +can render the schema into the commonly used YAML-based OpenAPI format. + + pip install coreapi pyyaml + +## Quickstart + +There are two different ways you can serve a schema description for your API. + +### Generating a schema with the `generateschema` management command + +To generate a static API schema, use the `generateschema` management command. + +```shell +$ python manage.py generateschema > schema.yml +``` + +Once you've generated a schema in this way you can annotate it with any +additional information that cannot be automatically inferred by the schema +generator. + +You might want to check your API schema into version control and update it +with each new release, or serve the API schema from your site's static media. + +### Adding a view with `get_schema_view` + +To add a dynamically generated schema view to your API, use `get_schema_view`. + +```python +from rest_framework.schemas import get_schema_view + +schema_view = get_schema_view(title="Example API") + +urlpatterns = [ + url('^schema$', schema_view), + ... +] +``` + +See below [for more details](#the-get_schema_view-shortcut) on customizing a +dynamically generated schema view. + +## Internal schema representation + +REST framework uses [Core API][coreapi] in order to model schema information in +a format-independent representation. This information can then be rendered +into various different schema formats, or used to generate API documentation. + +When using Core API, a schema is represented as a `Document` which is the +top-level container object for information about the API. Available API +interactions are represented using `Link` objects. Each link includes a URL, +HTTP method, and may include a list of `Field` instances, which describe any +parameters that may be accepted by the API endpoint. The `Link` and `Field` +instances may also include descriptions, that allow an API schema to be +rendered into user documentation. + +Here's an example of an API description that includes a single `search` +endpoint: + + coreapi.Document( + title='Flight Search API', + url='https://api.example.org/', + content={ + 'search': coreapi.Link( + url='/search/', + action='get', + fields=[ + coreapi.Field( + name='from', + required=True, + location='query', + description='City name or airport code.' + ), + coreapi.Field( + name='to', + required=True, + location='query', + description='City name or airport code.' + ), + coreapi.Field( + name='date', + required=True, + location='query', + description='Flight date in "YYYY-MM-DD" format.' + ) + ], + description='Return flight availability and prices.' + ) + } + ) + +## Schema output formats + +In order to be presented in an HTTP response, the internal representation +has to be rendered into the actual bytes that are used in the response. + +REST framework includes a few different renderers that you can use for +encoding the API schema. + +* `renderers.OpenAPIRenderer` - Renders into YAML-based [OpenAPI][open-api], the most widely used API schema format. +* `renderers.JSONOpenAPIRenderer` - Renders into JSON-based [OpenAPI][open-api]. +* `renderers.CoreJSONRenderer` - Renders into [Core JSON][corejson], a format designed for +use with the `coreapi` client library. + + +[Core JSON][corejson] is designed as a canonical format for use with Core API. +REST framework includes a renderer class for handling this media type, which +is available as `renderers.CoreJSONRenderer`. + + +## Schemas vs Hypermedia + +It's worth pointing out here that Core API can also be used to model hypermedia +responses, which present an alternative interaction style to API schemas. + +With an API schema, the entire available interface is presented up-front +as a single endpoint. Responses to individual API endpoints are then typically +presented as plain data, without any further interactions contained in each +response. + +With Hypermedia, the client is instead presented with a document containing +both data and available interactions. Each interaction results in a new +document, detailing both the current state and the available interactions. + +Further information and support on building Hypermedia APIs with REST framework +is planned for a future version. + + +--- + +# Creating a schema + +REST framework includes functionality for auto-generating a schema, +or allows you to specify one explicitly. + +## Manual Schema Specification + +To manually specify a schema you create a Core API `Document`, similar to the +example above. + + schema = coreapi.Document( + title='Flight Search API', + content={ + ... + } + ) + + +## Automatic Schema Generation + +Automatic schema generation is provided by the `SchemaGenerator` class. + +`SchemaGenerator` processes a list of routed URL patterns and compiles the +appropriately structured Core API Document. + +Basic usage is just to provide the title for your schema and call +`get_schema()`: + + generator = schemas.SchemaGenerator(title='Flight Search API') + schema = generator.get_schema() + +## Per-View Schema Customisation + +By default, view introspection is performed by an `AutoSchema` instance +accessible via the `schema` attribute on `APIView`. This provides the +appropriate Core API `Link` object for the view, request method and path: + + auto_schema = view.schema + coreapi_link = auto_schema.get_link(...) + +(In compiling the schema, `SchemaGenerator` calls `view.schema.get_link()` for +each view, allowed method and path.) + +--- + +**Note**: For basic `APIView` subclasses, default introspection is essentially +limited to the URL kwarg path parameters. For `GenericAPIView` +subclasses, which includes all the provided class based views, `AutoSchema` will +attempt to introspect serialiser, pagination and filter fields, as well as +provide richer path field descriptions. (The key hooks here are the relevant +`GenericAPIView` attributes and methods: `get_serializer`, `pagination_class`, +`filter_backends` and so on.) + +--- + +To customise the `Link` generation you may: + +* Instantiate `AutoSchema` on your view with the `manual_fields` kwarg: + + from rest_framework.views import APIView + from rest_framework.schemas import AutoSchema + + class CustomView(APIView): + ... + schema = AutoSchema( + manual_fields=[ + coreapi.Field("extra_field", ...), + ] + ) + + This allows extension for the most common case without subclassing. + +* Provide an `AutoSchema` subclass with more complex customisation: + + from rest_framework.views import APIView + from rest_framework.schemas import AutoSchema + + class CustomSchema(AutoSchema): + def get_link(...): + # Implement custom introspection here (or in other sub-methods) + + class CustomView(APIView): + ... + schema = CustomSchema() + + This provides complete control over view introspection. + +* Instantiate `ManualSchema` on your view, providing the Core API `Fields` for + the view explicitly: + + from rest_framework.views import APIView + from rest_framework.schemas import ManualSchema + + class CustomView(APIView): + ... + schema = ManualSchema(fields=[ + coreapi.Field( + "first_field", + required=True, + location="path", + schema=coreschema.String() + ), + coreapi.Field( + "second_field", + required=True, + location="path", + schema=coreschema.String() + ), + ]) + + This allows manually specifying the schema for some views whilst maintaining + automatic generation elsewhere. + +You may disable schema generation for a view by setting `schema` to `None`: + + class CustomView(APIView): + ... + schema = None # Will not appear in schema + +This also applies to extra actions for `ViewSet`s: + + class CustomViewSet(viewsets.ModelViewSet): + + @action(detail=True, schema=None) + def extra_action(self, request, pk=None): + ... + +--- + +**Note**: For full details on `SchemaGenerator` plus the `AutoSchema` and +`ManualSchema` descriptors see the [API Reference below](#api-reference). + +--- + +# Adding a schema view + +There are a few different ways to add a schema view to your API, depending on +exactly what you need. + +## The get_schema_view shortcut + +The simplest way to include a schema in your project is to use the +`get_schema_view()` function. + + from rest_framework.schemas import get_schema_view + + schema_view = get_schema_view(title="Server Monitoring API") + + urlpatterns = [ + url('^$', schema_view), + ... + ] + +Once the view has been added, you'll be able to make API requests to retrieve +the auto-generated schema definition. + + $ http http://127.0.0.1:8000/ Accept:application/coreapi+json + HTTP/1.0 200 OK + Allow: GET, HEAD, OPTIONS + Content-Type: application/vnd.coreapi+json + + { + "_meta": { + "title": "Server Monitoring API" + }, + "_type": "document", + ... + } + +The arguments to `get_schema_view()` are: + +#### `title` + +May be used to provide a descriptive title for the schema definition. + +#### `url` + +May be used to pass a canonical URL for the schema. + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/' + ) + +#### `urlconf` + +A string representing the import path to the URL conf that you want +to generate an API schema for. This defaults to the value of Django's +ROOT_URLCONF setting. + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + urlconf='myproject.urls' + ) + +#### `renderer_classes` + +May be used to pass the set of renderer classes that can be used to render the API root endpoint. + + from rest_framework.schemas import get_schema_view + from rest_framework.renderers import JSONOpenAPIRenderer + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + renderer_classes=[JSONOpenAPIRenderer] + ) + +#### `patterns` + +List of url patterns to limit the schema introspection to. If you only want the `myproject.api` urls +to be exposed in the schema: + + schema_url_patterns = [ + url(r'^api/', include('myproject.api.urls')), + ] + + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + patterns=schema_url_patterns, + ) + +#### `generator_class` + +May be used to specify a `SchemaGenerator` subclass to be passed to the +`SchemaView`. + +#### `authentication_classes` + +May be used to specify the list of authentication classes that will apply to the schema endpoint. +Defaults to `settings.DEFAULT_AUTHENTICATION_CLASSES` + +#### `permission_classes` + +May be used to specify the list of permission classes that will apply to the schema endpoint. +Defaults to `settings.DEFAULT_PERMISSION_CLASSES` + +## Using an explicit schema view + +If you need a little more control than the `get_schema_view()` shortcut gives you, +then you can use the `SchemaGenerator` class directly to auto-generate the +`Document` instance, and to return that from a view. + +This option gives you the flexibility of setting up the schema endpoint +with whatever behaviour you want. For example, you can apply different +permission, throttling, or authentication policies to the schema endpoint. + +Here's an example of using `SchemaGenerator` together with a view to +return the schema. + +**views.py:** + + from rest_framework.decorators import api_view, renderer_classes + from rest_framework import renderers, response, schemas + + generator = schemas.SchemaGenerator(title='Bookings API') + + @api_view() + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + schema = generator.get_schema(request) + return response.Response(schema) + +**urls.py:** + + urlpatterns = [ + url('/', schema_view), + ... + ] + +You can also serve different schemas to different users, depending on the +permissions they have available. This approach can be used to ensure that +unauthenticated requests are presented with a different schema to +authenticated requests, or to ensure that different parts of the API are +made visible to different users depending on their role. + +In order to present a schema with endpoints filtered by user permissions, +you need to pass the `request` argument to the `get_schema()` method, like so: + + @api_view() + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + generator = schemas.SchemaGenerator(title='Bookings API') + return response.Response(generator.get_schema(request=request)) + +## Explicit schema definition + +An alternative to the auto-generated approach is to specify the API schema +explicitly, by declaring a `Document` object in your codebase. Doing so is a +little more work, but ensures that you have full control over the schema +representation. + + import coreapi + from rest_framework.decorators import api_view, renderer_classes + from rest_framework import renderers, response + + schema = coreapi.Document( + title='Bookings API', + content={ + ... + } + ) + + @api_view() + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + return response.Response(schema) + +--- + +# Schemas as documentation + +One common usage of API schemas is to use them to build documentation pages. + +The schema generation in REST framework uses docstrings to automatically +populate descriptions in the schema document. + +These descriptions will be based on: + +* The corresponding method docstring if one exists. +* A named section within the class docstring, which can be either single line or multi-line. +* The class docstring. + +## Examples + +An `APIView`, with an explicit method docstring. + + class ListUsernames(APIView): + def get(self, request): + """ + Return a list of all user names in the system. + """ + usernames = [user.username for user in User.objects.all()] + return Response(usernames) + +A `ViewSet`, with an explicit action docstring. + + class ListUsernames(ViewSet): + def list(self, request): + """ + Return a list of all user names in the system. + """ + usernames = [user.username for user in User.objects.all()] + return Response(usernames) + +A generic view with sections in the class docstring, using single-line style. + + class UserList(generics.ListCreateAPIView): + """ + get: List all the users. + post: Create a new user. + """ + queryset = User.objects.all() + serializer_class = UserSerializer + permission_classes = [IsAdminUser] + +A generic viewset with sections in the class docstring, using multi-line style. + + class UserViewSet(viewsets.ModelViewSet): + """ + API endpoint that allows users to be viewed or edited. + + retrieve: + Return a user instance. + + list: + Return all users, ordered by most recently joined. + """ + queryset = User.objects.all().order_by('-date_joined') + serializer_class = UserSerializer + +--- + +# API Reference + +## SchemaGenerator + +A class that walks a list of routed URL patterns, requests the schema for each view, +and collates the resulting CoreAPI Document. + +Typically you'll instantiate `SchemaGenerator` with a single argument, like so: + + generator = SchemaGenerator(title='Stock Prices API') + +Arguments: + +* `title` **required** - The name of the API. +* `url` - The root URL of the API schema. This option is not required unless the schema is included under path prefix. +* `patterns` - A list of URLs to inspect when generating the schema. Defaults to the project's URL conf. +* `urlconf` - A URL conf module name to use when generating the schema. Defaults to `settings.ROOT_URLCONF`. + +### get_schema(self, request) + +Returns a `coreapi.Document` instance that represents the API schema. + + @api_view + @renderer_classes([renderers.OpenAPIRenderer]) + def schema_view(request): + generator = schemas.SchemaGenerator(title='Bookings API') + return Response(generator.get_schema()) + +The `request` argument is optional, and may be used if you want to apply per-user +permissions to the resulting schema generation. + +### get_links(self, request) + +Return a nested dictionary containing all the links that should be included in the API schema. + +This is a good point to override if you want to modify the resulting structure of the generated schema, +as you can build a new dictionary with a different layout. + + +## AutoSchema + +A class that deals with introspection of individual views for schema generation. + +`AutoSchema` is attached to `APIView` via the `schema` attribute. + +The `AutoSchema` constructor takes a single keyword argument `manual_fields`. + +**`manual_fields`**: a `list` of `coreapi.Field` instances that will be added to +the generated fields. Generated fields with a matching `name` will be overwritten. + + class CustomView(APIView): + schema = AutoSchema(manual_fields=[ + coreapi.Field( + "my_extra_field", + required=True, + location="path", + schema=coreschema.String() + ), + ]) + +For more advanced customisation subclass `AutoSchema` to customise schema generation. + + class CustomViewSchema(AutoSchema): + """ + Overrides `get_link()` to provide Custom Behavior X + """ + + def get_link(self, path, method, base_url): + link = super().get_link(path, method, base_url) + # Do something to customize link here... + return link + + class MyView(APIView): + schema = CustomViewSchema() + +The following methods are available to override. + +### get_link(self, path, method, base_url) + +Returns a `coreapi.Link` instance corresponding to the given view. + +This is the main entry point. +You can override this if you need to provide custom behaviors for particular views. + +### get_description(self, path, method) + +Returns a string to use as the link description. By default this is based on the +view docstring as described in the "Schemas as Documentation" section above. + +### get_encoding(self, path, method) + +Returns a string to indicate the encoding for any request body, when interacting +with the given view. Eg. `'application/json'`. May return a blank string for views +that do not expect a request body. + +### get_path_fields(self, path, method): + +Return a list of `coreapi.Field()` instances. One for each path parameter in the URL. + +### get_serializer_fields(self, path, method) + +Return a list of `coreapi.Field()` instances. One for each field in the serializer class used by the view. + +### get_pagination_fields(self, path, method) + +Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view. + +### get_filter_fields(self, path, method) + +Return a list of `coreapi.Field()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view. + +### get_manual_fields(self, path, method) + +Return a list of `coreapi.Field()` instances to be added to or replace generated fields. Defaults to (optional) `manual_fields` passed to `AutoSchema` constructor. + +May be overridden to customise manual fields by `path` or `method`. For example, a per-method adjustment may look like this: + +```python +def get_manual_fields(self, path, method): + """Example adding per-method fields.""" + + extra_fields = [] + if method=='GET': + extra_fields = # ... list of extra fields for GET ... + if method=='POST': + extra_fields = # ... list of extra fields for POST ... + + manual_fields = super().get_manual_fields(path, method) + return manual_fields + extra_fields +``` + +### update_fields(fields, update_with) + +Utility `staticmethod`. Encapsulates logic to add or replace fields from a list +by `Field.name`. May be overridden to adjust replacement criteria. + + +## ManualSchema + +Allows manually providing a list of `coreapi.Field` instances for the schema, +plus an optional description. + + class MyView(APIView): + schema = ManualSchema(fields=[ + coreapi.Field( + "first_field", + required=True, + location="path", + schema=coreschema.String() + ), + coreapi.Field( + "second_field", + required=True, + location="path", + schema=coreschema.String() + ), + ] + ) + +The `ManualSchema` constructor takes two arguments: + +**`fields`**: A list of `coreapi.Field` instances. Required. + +**`description`**: A string description. Optional. + +**`encoding`**: Default `None`. A string encoding, e.g `application/json`. Optional. + +--- + +## Core API + +This documentation gives a brief overview of the components within the `coreapi` +package that are used to represent an API schema. + +Note that these classes are imported from the `coreapi` package, rather than +from the `rest_framework` package. + +### Document + +Represents a container for the API schema. + +#### `title` + +A name for the API. + +#### `url` + +A canonical URL for the API. + +#### `content` + +A dictionary, containing the `Link` objects that the schema contains. + +In order to provide more structure to the schema, the `content` dictionary +may be nested, typically to a second level. For example: + + content={ + "bookings": { + "list": Link(...), + "create": Link(...), + ... + }, + "venues": { + "list": Link(...), + ... + }, + ... + } + +### Link + +Represents an individual API endpoint. + +#### `url` + +The URL of the endpoint. May be a URI template, such as `/users/{username}/`. + +#### `action` + +The HTTP method associated with the endpoint. Note that URLs that support +more than one HTTP method, should correspond to a single `Link` for each. + +#### `fields` + +A list of `Field` instances, describing the available parameters on the input. + +#### `description` + +A short description of the meaning and intended usage of the endpoint. + +### Field + +Represents a single input parameter on a given API endpoint. + +#### `name` + +A descriptive name for the input. + +#### `required` + +A boolean, indicated if the client is required to included a value, or if +the parameter can be omitted. + +#### `location` + +Determines how the information is encoded into the request. Should be one of +the following strings: + +**"path"** + +Included in a templated URI. For example a `url` value of `/products/{product_code}/` could be used together with a `"path"` field, to handle API inputs in a URL path such as `/products/slim-fit-jeans/`. + +These fields will normally correspond with [named arguments in the project URL conf][named-arguments]. + +**"query"** + +Included as a URL query parameter. For example `?search=sale`. Typically for `GET` requests. + +These fields will normally correspond with pagination and filtering controls on a view. + +**"form"** + +Included in the request body, as a single item of a JSON object or HTML form. For example `{"colour": "blue", ...}`. Typically for `POST`, `PUT` and `PATCH` requests. Multiple `"form"` fields may be included on a single link. + +These fields will normally correspond with serializer fields on a view. + +**"body"** + +Included as the complete request body. Typically for `POST`, `PUT` and `PATCH` requests. No more than one `"body"` field may exist on a link. May not be used together with `"form"` fields. + +These fields will normally correspond with views that use `ListSerializer` to validate the request input, or with file upload views. + +#### `encoding` + +**"application/json"** + +JSON encoded request content. Corresponds to views using `JSONParser`. +Valid only if either one or more `location="form"` fields, or a single +`location="body"` field is included on the `Link`. + +**"multipart/form-data"** + +Multipart encoded request content. Corresponds to views using `MultiPartParser`. +Valid only if one or more `location="form"` fields is included on the `Link`. + +**"application/x-www-form-urlencoded"** + +URL encoded request content. Corresponds to views using `FormParser`. Valid +only if one or more `location="form"` fields is included on the `Link`. + +**"application/octet-stream"** + +Binary upload request content. Corresponds to views using `FileUploadParser`. +Valid only if a `location="body"` field is included on the `Link`. + +#### `description` + +A short description of the meaning and intended usage of the input field. + + +--- + +# Third party packages + +## drf-yasg - Yet Another Swagger Generator + +[drf-yasg][drf-yasg] generates [OpenAPI][open-api] documents suitable for code generation - nested schemas, +named models, response bodies, enum/pattern/min/max validators, form parameters, etc. + +[cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api +[coreapi]: https://www.coreapi.org/ +[corejson]: https://www.coreapi.org/specification/encoding/#core-json-encoding +[drf-yasg]: https://github.com/axnsan12/drf-yasg/ +[open-api]: https://openapis.org/ +[json-hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html +[api-blueprint]: https://apiblueprint.org/ +[static-files]: https://docs.djangoproject.com/en/stable/howto/static-files/ +[named-arguments]: https://docs.djangoproject.com/en/stable/topics/http/urls/#named-groups diff --git a/docs/img/drfdocs.png b/docs/img/drfdocs.png deleted file mode 100644 index 0cccb41f7..000000000 Binary files a/docs/img/drfdocs.png and /dev/null differ diff --git a/docs/img/premium/cadre-readme.png b/docs/img/premium/cadre-readme.png index b61539469..08290b727 100644 Binary files a/docs/img/premium/cadre-readme.png and b/docs/img/premium/cadre-readme.png differ diff --git a/docs/img/premium/esg-readme.png b/docs/img/premium/esg-readme.png new file mode 100644 index 000000000..5aeb93fd2 Binary files /dev/null and b/docs/img/premium/esg-readme.png differ diff --git a/docs/img/premium/kloudless-readme.png b/docs/img/premium/kloudless-readme.png index 5d32b31b6..e2f05831d 100644 Binary files a/docs/img/premium/kloudless-readme.png and b/docs/img/premium/kloudless-readme.png differ diff --git a/docs/img/premium/lightson-readme.png b/docs/img/premium/lightson-readme.png index 3c8c6c62a..82cd61364 100644 Binary files a/docs/img/premium/lightson-readme.png and b/docs/img/premium/lightson-readme.png differ diff --git a/docs/img/premium/load-impact-readme.png b/docs/img/premium/load-impact-readme.png deleted file mode 100644 index c46d36ada..000000000 Binary files a/docs/img/premium/load-impact-readme.png and /dev/null differ diff --git a/docs/img/premium/machinalis-readme.png b/docs/img/premium/machinalis-readme.png deleted file mode 100644 index cd98c23c7..000000000 Binary files a/docs/img/premium/machinalis-readme.png and /dev/null differ diff --git a/docs/img/premium/micropyramid-readme.png b/docs/img/premium/micropyramid-readme.png deleted file mode 100644 index 9fa9500e1..000000000 Binary files a/docs/img/premium/micropyramid-readme.png and /dev/null differ diff --git a/docs/img/premium/rollbar-readme.png b/docs/img/premium/rollbar-readme.png index b0655f783..630cddb32 100644 Binary files a/docs/img/premium/rollbar-readme.png and b/docs/img/premium/rollbar-readme.png differ diff --git a/docs/img/premium/rover-readme.png b/docs/img/premium/rover-readme.png deleted file mode 100644 index b8055d62e..000000000 Binary files a/docs/img/premium/rover-readme.png and /dev/null differ diff --git a/docs/img/premium/sentry-readme.png b/docs/img/premium/sentry-readme.png index 5536ce52f..b322e3735 100644 Binary files a/docs/img/premium/sentry-readme.png and b/docs/img/premium/sentry-readme.png differ diff --git a/docs/img/premium/stream-readme.png b/docs/img/premium/stream-readme.png index fc3733c70..967ee7fc8 100644 Binary files a/docs/img/premium/stream-readme.png and b/docs/img/premium/stream-readme.png differ diff --git a/docs/index.md b/docs/index.md index 7adc52dfb..6e55c10bf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,7 +68,7 @@ continued development by **[signing up for a paid plan][funding]**.
-*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), [Release History](https://releasehistory.io), [Rollbar](https://rollbar.com), [Cadre](https://cadre.com), [Kloudless](https://hubs.ly/H0f30Lf0), and [Lights On Software](https://lightsonsoftware.com).* +*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), and [Lights On Software](https://lightsonsoftware.com).* --- @@ -84,7 +84,7 @@ continued development by **[signing up for a paid plan][funding]**. REST framework requires the following: -* Python (3.4, 3.5, 3.6, 3.7) +* Python (3.5, 3.6, 3.7) * Django (1.11, 2.0, 2.1, 2.2) We **highly recommend** and only officially support the latest patch release of @@ -93,9 +93,9 @@ each Python and Django series. The following packages are optional: * [coreapi][coreapi] (1.32.0+) - Schema generation support. -* [Markdown][markdown] (2.1.0+) - Markdown support for the browsable API. +* [Markdown][markdown] (3.0.0+) - Markdown support for the browsable API. +* [Pygments][pygments] (2.4.0+) - Add syntax highlighting to Markdown processing. * [django-filter][django-filter] (1.0.1+) - 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 @@ -112,10 +112,10 @@ Install using `pip`, including any optional packages you want... Add `'rest_framework'` to your `INSTALLED_APPS` setting. - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) + ] If you're intending to use the browsable API you'll probably also want to add REST framework's login and logout views. Add the following to your root `urls.py` file. @@ -155,7 +155,7 @@ Here's our project's root `urls.py` module: class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User - fields = ('url', 'username', 'email', 'is_staff') + fields = ['url', 'username', 'email', 'is_staff'] # ViewSets define the view behavior. class UserViewSet(viewsets.ModelViewSet): @@ -238,8 +238,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [eventbrite]: https://www.eventbrite.co.uk/about/ [coreapi]: https://pypi.org/project/coreapi/ [markdown]: https://pypi.org/project/Markdown/ +[pygments]: https://pypi.org/project/Pygments/ [django-filter]: https://pypi.org/project/django-filter/ -[django-crispy-forms]: https://github.com/maraujop/django-crispy-forms [django-guardian]: https://github.com/django-guardian/django-guardian [index]: . [oauth1-section]: api-guide/authentication/#django-rest-framework-oauth diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index fa07b6064..67c1c1898 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -51,13 +51,15 @@ For example: METHOD_OVERRIDE_HEADER = 'HTTP_X_HTTP_METHOD_OVERRIDE' - class MethodOverrideMiddleware(object): - def process_view(self, request, callback, callback_args, callback_kwargs): - if request.method != 'POST': - return - if METHOD_OVERRIDE_HEADER not in request.META: - return - request.method = request.META[METHOD_OVERRIDE_HEADER] + class MethodOverrideMiddleware: + + def __init__(self, get_response): + self.get_response = get_response + + def __call__(self, request): + if request.method == 'POST' and METHOD_OVERRIDE_HEADER in request.META: + request.method = request.META[METHOD_OVERRIDE_HEADER] + return self.get_response(request) ## URL based accept headers diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index 701b5824b..5cdf631a6 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -4,176 +4,121 @@ > > — Roy Fielding, [REST APIs must be hypertext driven][cite] -REST framework provides built-in support for API documentation. There are also a number of great third-party documentation tools available. +REST framework provides built-in support for generating OpenAPI schemas, which +can be used with tools that allow you to build API documentation. -## Built-in API documentation +There are also a number of great third-party documentation packages available. -The built-in API documentation includes: +## Generating documentation from OpenAPI schemas -* Documentation of API endpoints. -* Automatically generated code samples for each of the available API client libraries. -* Support for API interaction. +There are a number of packages available that allow you to generate HTML +documentation pages from OpenAPI schemas. -### Installation +Two popular options are [Swagger UI][swagger-ui] and [ReDoc][redoc]. -The `coreapi` library is required as a dependency for the API docs. Make sure -to install the latest version. The `Pygments` and `Markdown` libraries -are optional but recommended. +Both require little more than the location of your static schema file or +dynamic `SchemaView` endpoint. -To install the API documentation, you'll need to include it in your project's URLconf: +### A minimal example with Swagger UI - from rest_framework.documentation import include_docs_urls +Assuming you've followed the example from the schemas documentation for routing +a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be +this: - urlpatterns = [ - ... - url(r'^docs/', include_docs_urls(title='My API title')) - ] +```html + + + + Swagger + + + + + +
+ + + + +``` -This will include two different views: +Save this in your templates folder as `swagger-ui.html`. Then route a +`TemplateView` in your project's URL conf: - * `/docs/` - The documentation page itself. - * `/docs/schema.js` - A JavaScript resource that exposes the API schema. +```python +from django.views.generic import TemplateView ---- +urlpatterns = [ + # ... + # Route TemplateView to serve Swagger UI template. + # * Provide `extra_context` with view name of `SchemaView`. + path('swagger-ui/', TemplateView.as_view( + template_name='swagger-ui.html', + extra_context={'schema_url':'openapi-schema'} + ), name='swagger-ui'), +] +``` -**Note**: By default `include_docs_urls` configures the underlying `SchemaView` to generate _public_ schemas. -This means that views will not be instantiated with a `request` instance. i.e. Inside the view `self.request` will be `None`. +See the [Swagger UI documentation][swagger-ui] for advanced usage. -To be compatible with this behaviour, methods (such as `get_serializer` or `get_serializer_class` etc.) which inspect `self.request` or, particularly, `self.request.user` may need to be adjusted to handle this case. +### A minimal example with ReDoc. -You may ensure views are given a `request` instance by calling `include_docs_urls` with `public=False`: +Assuming you've followed the example from the schemas documentation for routing +a dynamic `SchemaView`, a minimal Django template for using Swagger UI might be +this: - from rest_framework.documentation import include_docs_urls +```html + + + + ReDoc + + + + + + + + + + + + +``` - urlpatterns = [ - ... - # Generate schema with valid `request` instance: - url(r'^docs/', include_docs_urls(title='My API title', public=False)) - ] +Save this in your templates folder as `redoc.html`. Then route a `TemplateView` +in your project's URL conf: +```python +from django.views.generic import TemplateView ---- +urlpatterns = [ + # ... + # Route TemplateView to serve the ReDoc template. + # * Provide `extra_context` with view name of `SchemaView`. + path('redoc/', TemplateView.as_view( + template_name='redoc.html', + extra_context={'schema_url':'openapi-schema'} + ), name='redoc'), +] +``` - -### Documenting your views - -You can document your views by including docstrings that describe each of the available actions. -For example: - - class UserList(generics.ListAPIView): - """ - Return a list of all the existing users. - """ - -If a view supports multiple methods, you should split your documentation using `method:` style delimiters. - - class UserList(generics.ListCreateAPIView): - """ - get: - Return a list of all the existing users. - - post: - Create a new user instance. - """ - -When using viewsets, you should use the relevant action names as delimiters. - - class UserViewSet(viewsets.ModelViewSet): - """ - retrieve: - Return the given user. - - list: - Return a list of all the existing users. - - create: - Create a new user instance. - """ - -Custom actions on viewsets can also be documented in a similar way using the method names -as delimiters or by attaching the documentation to action mapping methods. - - class UserViewSet(viewsets.ModelViewset): - ... - - @action(detail=False, methods=['get', 'post']) - def some_action(self, request, *args, **kwargs): - """ - get: - A description of the get method on the custom action. - - post: - A description of the post method on the custom action. - """ - - @some_action.mapping.put - def put_some_action(): - """ - A description of the put method on the custom action. - """ - - -### `documentation` API Reference - -The `rest_framework.documentation` module provides three helper functions to help configure the interactive API documentation, `include_docs_urls` (usage shown above), `get_docs_view` and `get_schemajs_view`. - - `include_docs_urls` employs `get_docs_view` and `get_schemajs_view` to generate the url patterns for the documentation page and JavaScript resource that exposes the API schema respectively. They expose the following options for customisation. (`get_docs_view` and `get_schemajs_view` ultimately call `rest_frameworks.schemas.get_schema_view()`, see the Schemas docs for more options there.) - -#### `include_docs_urls` - -* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. -* `description`: Default `None`. May be used to provide a description for the schema definition. -* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. -* `public`: Default `True`. Should the schema be considered _public_? If `True` schema is generated without a `request` instance being passed to views. -* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. -* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. -* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. -* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. -* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. - -#### `get_docs_view` - -* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. -* `description`: Default `None`. May be used to provide a description for the schema definition. -* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. -* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. -* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. -* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. -* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. -* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES`. May be used to pass custom permission classes to the `SchemaView`. -* `renderer_classes`: Default `None`. May be used to pass custom renderer classes to the `SchemaView`. If `None` the `SchemaView` will be configured with `DocumentationRenderer` and `CoreJSONRenderer` renderers, corresponding to the (default) `html` and `corejson` formats. - -#### `get_schemajs_view` - -* `title`: Default `None`. May be used to provide a descriptive title for the schema definition. -* `description`: Default `None`. May be used to provide a description for the schema definition. -* `schema_url`: Default `None`. May be used to pass a canonical base URL for the schema. -* `public`: Default `True`. If `True` schema is generated without a `request` instance being passed to views. -* `patterns`: Default `None`. A list of URLs to inspect when generating the schema. If `None` project's URL conf will be used. -* `generator_class`: Default `rest_framework.schemas.SchemaGenerator`. May be used to specify a `SchemaGenerator` subclass to be passed to the `SchemaView`. -* `authentication_classes`: Default `api_settings.DEFAULT_AUTHENTICATION_CLASSES`. May be used to pass custom authentication classes to the `SchemaView`. -* `permission_classes`: Default `api_settings.DEFAULT_PERMISSION_CLASSES` May be used to pass custom permission classes to the `SchemaView`. - - -### Customising code samples - -The built-in API documentation includes automatically generated code samples for -each of the available API client libraries. - -You may customise these samples by subclassing `DocumentationRenderer`, setting -`languages` to the list of languages you wish to support: - - from rest_framework.renderers import DocumentationRenderer - - - class CustomRenderer(DocumentationRenderer): - languages = ['ruby', 'go'] - -For each language you need to provide an `intro` template, detailing installation instructions and such, -plus a generic template for making API requests, that can be filled with individual request details. -See the [templates for the bundled languages][client-library-templates] for examples. - ---- +See the [ReDoc documentation][redoc] for advanced usage. ## Third party packages @@ -195,18 +140,6 @@ This also translates into a very useful interactive documentation viewer in the --- -#### DRF Docs - -[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. **Live API Endpoints** allow you to utilize the endpoints from within the documentation in a neat way. - -Features include customizing the template with your branding, settings for hiding the docs depending on the environment and more. - -Both this package and Django REST Swagger are fully documented, well supported, and come highly recommended. - -![Screenshot - DRF docs][image-drf-docs] - ---- - #### Django REST Swagger 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. @@ -215,7 +148,7 @@ 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. +This package is fully documented, well supported, and comes highly recommended. ![Screenshot - Django REST Swagger][image-django-rest-swagger] @@ -322,9 +255,6 @@ To implement a hypermedia API you'll need to decide on an appropriate media type [cite]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven [drf-yasg]: https://github.com/axnsan12/drf-yasg/ [image-drf-yasg]: ../img/drf-yasg.png -[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs -[drfdocs-website]: https://www.drfdocs.com/ -[drfdocs-demo]: http://demo.drfdocs.com/ [drfautodocs-repo]: https://github.com/iMakedonsky/drf-autodocs [django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger [swagger]: https://swagger.io/ @@ -333,10 +263,12 @@ To implement a hypermedia API you'll need to decide on an appropriate media type [apiary]: https://apiary.io/ [markdown]: https://daringfireball.net/projects/markdown/syntax [hypermedia-docs]: rest-hypermedia-hateoas.md -[image-drf-docs]: ../img/drfdocs.png [image-django-rest-swagger]: ../img/django-rest-swagger.png [image-apiary]: ../img/apiary.png [image-self-describing-api]: ../img/self-describing.png -[schemas-examples]: ../api-guide/schemas/#examples [metadata-docs]: ../api-guide/metadata/ -[client-library-templates]: https://github.com/encode/django-rest-framework/tree/master/rest_framework/templates/rest_framework/docs/langs + +[schemas-examples]: ../api-guide/schemas/#examples +[swagger-ui]: https://swagger.io/tools/swagger-ui/ +[redoc]: https://github.com/Rebilly/ReDoc + diff --git a/docs/topics/writable-nested-serializers.md b/docs/topics/writable-nested-serializers.md index 9ba719f4e..3bac84ffa 100644 --- a/docs/topics/writable-nested-serializers.md +++ b/docs/topics/writable-nested-serializers.md @@ -15,14 +15,14 @@ Nested data structures are easy enough to work with if they're read-only - simpl class ToDoItemSerializer(serializers.ModelSerializer): class Meta: model = ToDoItem - fields = ('text', 'is_completed') + fields = ['text', 'is_completed'] class ToDoListSerializer(serializers.ModelSerializer): items = ToDoItemSerializer(many=True, read_only=True) class Meta: model = ToDoList - fields = ('title', 'items') + fields = ['title', 'items'] Some example output from our serializer. diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 22fe49e39..85d8676b1 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -42,11 +42,11 @@ Once that's done we can create an app that we'll use to create a simple Web API. We'll need to add our new `snippets` app and the `rest_framework` app to `INSTALLED_APPS`. Let's edit the `tutorial/settings.py` file: - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', 'snippets.apps.SnippetsConfig', - ) + ] Okay, we're ready to roll. @@ -60,7 +60,7 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni LEXERS = [item for item in get_all_lexers() if item[1]] LANGUAGE_CHOICES = sorted([(item[1][0], item[0]) for item in LEXERS]) - STYLE_CHOICES = sorted((item, item) for item in get_all_styles()) + STYLE_CHOICES = sorted([(item, item) for item in get_all_styles()]) class Snippet(models.Model): @@ -72,7 +72,7 @@ For the purposes of this tutorial we're going to start by creating a simple `Sni style = models.CharField(choices=STYLE_CHOICES, default='friendly', max_length=100) class Meta: - ordering = ('created',) + ordering = ['created'] We'll also need to create an initial migration for our snippet model, and sync the database for the first time. @@ -189,7 +189,7 @@ Open the file `snippets/serializers.py` again, and replace the `SnippetSerialize class SnippetSerializer(serializers.ModelSerializer): class Meta: model = Snippet - fields = ('id', 'title', 'code', 'linenos', 'language', 'style') + fields = ['id', 'title', 'code', 'linenos', 'language', 'style'] One nice property that serializers have is that you can inspect all the fields in a serializer instance, by printing its representation. Open the Django shell with `python manage.py shell`, then try the following: diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md index d616b6539..6808780fa 100644 --- a/docs/tutorial/4-authentication-and-permissions.md +++ b/docs/tutorial/4-authentication-and-permissions.md @@ -63,7 +63,7 @@ Now that we've got some users to work with, we'd better add representations of t class Meta: model = User - fields = ('id', 'username', 'snippets') + fields = ['id', 'username', 'snippets'] Because `'snippets'` is a *reverse* relationship on the User model, it will not be included by default when using the `ModelSerializer` class, so we needed to add an explicit field for it. @@ -127,7 +127,7 @@ First add the following import in the views module Then, add the following property to **both** the `SnippetList` and `SnippetDetail` view classes. - permission_classes = (permissions.IsAuthenticatedOrReadOnly,) + permission_classes = [permissions.IsAuthenticatedOrReadOnly] ## Adding login to the Browsable API @@ -178,8 +178,8 @@ In the snippets app, create a new file, `permissions.py` Now we can add that custom permission to our snippet instance endpoint, by editing the `permission_classes` property on the `SnippetDetail` view class: - permission_classes = (permissions.IsAuthenticatedOrReadOnly, - IsOwnerOrReadOnly,) + permission_classes = [permissions.IsAuthenticatedOrReadOnly, + IsOwnerOrReadOnly] Make sure to also import the `IsOwnerOrReadOnly` class. diff --git a/docs/tutorial/5-relationships-and-hyperlinked-apis.md b/docs/tutorial/5-relationships-and-hyperlinked-apis.md index 0177afce1..4cd4e9bbd 100644 --- a/docs/tutorial/5-relationships-and-hyperlinked-apis.md +++ b/docs/tutorial/5-relationships-and-hyperlinked-apis.md @@ -35,7 +35,7 @@ Instead of using a concrete generic view, we'll use the base class for represent class SnippetHighlight(generics.GenericAPIView): queryset = Snippet.objects.all() - renderer_classes = (renderers.StaticHTMLRenderer,) + renderer_classes = [renderers.StaticHTMLRenderer] def get(self, request, *args, **kwargs): snippet = self.get_object() @@ -80,8 +80,8 @@ We can easily re-write our existing serializers to use hyperlinking. In your `sn class Meta: model = Snippet - fields = ('url', 'id', 'highlight', 'owner', - 'title', 'code', 'linenos', 'language', 'style') + fields = ['url', 'id', 'highlight', 'owner', + 'title', 'code', 'linenos', 'language', 'style'] class UserSerializer(serializers.HyperlinkedModelSerializer): @@ -89,7 +89,7 @@ We can easily re-write our existing serializers to use hyperlinking. In your `sn class Meta: model = User - fields = ('url', 'id', 'username', 'snippets') + fields = ['url', 'id', 'username', 'snippets'] Notice that we've also added a new `'highlight'` field. This field is of the same type as the `url` field, except that it points to the `'snippet-highlight'` url pattern, instead of the `'snippet-detail'` url pattern. diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index 1d4058813..11e24448f 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -37,8 +37,8 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl """ queryset = Snippet.objects.all() serializer_class = SnippetSerializer - permission_classes = (permissions.IsAuthenticatedOrReadOnly, - IsOwnerOrReadOnly,) + permission_classes = [permissions.IsAuthenticatedOrReadOnly, + IsOwnerOrReadOnly] @action(detail=True, renderer_classes=[renderers.StaticHTMLRenderer]) def highlight(self, request, *args, **kwargs): @@ -128,8 +128,3 @@ The `DefaultRouter` class we're using also automatically creates the API root vi Using viewsets can be a really useful abstraction. It helps ensure that URL conventions will be consistent across your API, minimizes the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views instead of function based views. Using viewsets is less explicit than building your views individually. - -In [part 7][tut-7] of the tutorial we'll look at how we can add an API schema, -and interact with our API using a client library or command line tool. - -[tut-7]: 7-schemas-and-client-libraries.md diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 8b02b888e..ee54816dc 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -69,13 +69,13 @@ First up we're going to define some serializers. Let's create a new module named class UserSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = User - fields = ('url', 'username', 'email', 'groups') + fields = ['url', 'username', 'email', 'groups'] class GroupSerializer(serializers.HyperlinkedModelSerializer): class Meta: model = Group - fields = ('url', 'name') + fields = ['url', 'name'] Notice that we're using hyperlinked relations in this case with `HyperlinkedModelSerializer`. You can also use primary key and various other relationships, but hyperlinking is good RESTful design. @@ -144,10 +144,10 @@ Pagination allows you to control how many objects per page are returned. To enab Add `'rest_framework'` to `INSTALLED_APPS`. The settings module will be in `tutorial/settings.py` - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) + ] Okay, we're done. diff --git a/docs_theme/js/theme.js b/docs_theme/js/theme.js index ddbd9c905..0918ae85d 100644 --- a/docs_theme/js/theme.js +++ b/docs_theme/js/theme.js @@ -9,11 +9,6 @@ var getSearchTerm = function() { } }; -var initilizeSearch = function() { - require.config({ baseUrl: '/mkdocs/js' }); - require(['search']); -}; - $(function() { var searchTerm = getSearchTerm(), $searchModal = $('#mkdocs_search_modal'), @@ -30,6 +25,5 @@ $(function() { $searchModal.on('shown', function() { $searchQuery.focus(); - initilizeSearch(); }); }); diff --git a/docs_theme/main.html b/docs_theme/main.html index b60b231c2..21e9171a2 100644 --- a/docs_theme/main.html +++ b/docs_theme/main.html @@ -6,7 +6,7 @@ {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} - + @@ -138,14 +138,17 @@ + - - - + + {% for path in config.extra_javascript %} + + {% endfor %} + - + diff --git a/rest_framework/templates/rest_framework/base.html b/rest_framework/templates/rest_framework/base.html index 6d740f2b5..5d9d80b05 100644 --- a/rest_framework/templates/rest_framework/base.html +++ b/rest_framework/templates/rest_framework/base.html @@ -293,7 +293,7 @@ csrfToken: "{% if request %}{{ csrf_token }}{% endif %}" }; - + diff --git a/rest_framework/templates/rest_framework/docs/error.html b/rest_framework/templates/rest_framework/docs/error.html index ecdb67830..6afd25e7b 100644 --- a/rest_framework/templates/rest_framework/docs/error.html +++ b/rest_framework/templates/rest_framework/docs/error.html @@ -66,6 +66,6 @@ at rest_framework/docs/error.html.

- + diff --git a/rest_framework/templates/rest_framework/docs/index.html b/rest_framework/templates/rest_framework/docs/index.html index f73a2a993..6804afe10 100644 --- a/rest_framework/templates/rest_framework/docs/index.html +++ b/rest_framework/templates/rest_framework/docs/index.html @@ -38,7 +38,7 @@ {% include "rest_framework/docs/auth/basic.html" %} {% include "rest_framework/docs/auth/session.html" %} - + diff --git a/rest_framework/templatetags/rest_framework.py b/rest_framework/templatetags/rest_framework.py index 56e2994ea..79dd953ff 100644 --- a/rest_framework/templatetags/rest_framework.py +++ b/rest_framework/templatetags/rest_framework.py @@ -4,7 +4,7 @@ from collections import OrderedDict from django import template from django.template import loader from django.urls import NoReverseMatch, reverse -from django.utils.encoding import force_text, iri_to_uri +from django.utils.encoding import force_str, iri_to_uri from django.utils.html import escape, format_html, smart_urlquote from django.utils.safestring import SafeData, mark_safe @@ -233,7 +233,7 @@ def format_value(value): def items(value): """ Simple filter to return the items of the dict. Useful when the dict may - have a key 'items' which is resolved first in Django tempalte dot-notation + have a key 'items' which is resolved first in Django template dot-notation lookup. See issue #4931 Also see: https://stackoverflow.com/questions/15416662/django-template-loop-over-dictionary-items-with-items-as-key """ @@ -339,7 +339,7 @@ def urlize_quoted_links(text, trim_url_limit=None, nofollow=True, autoescape=Tru def conditional_escape(text): return escape(text) if autoescape and not safe_input else text - words = word_split_re.split(force_text(text)) + words = word_split_re.split(force_str(text)) for i, word in enumerate(words): if '.' in word or '@' in word or ':' in word: # Deal with punctuation. diff --git a/rest_framework/test.py b/rest_framework/test.py index 852d4919e..ab16c2787 100644 --- a/rest_framework/test.py +++ b/rest_framework/test.py @@ -185,7 +185,7 @@ class APIRequestFactory(DjangoRequestFactory): # Coerce text to bytes if required. if isinstance(ret, str): - ret = bytes(ret.encode(renderer.charset)) + ret = ret.encode(renderer.charset) return ret, content_type diff --git a/rest_framework/utils/encoders.py b/rest_framework/utils/encoders.py index a7875a868..27293b725 100644 --- a/rest_framework/utils/encoders.py +++ b/rest_framework/utils/encoders.py @@ -8,7 +8,7 @@ import uuid from django.db.models.query import QuerySet from django.utils import timezone -from django.utils.encoding import force_text +from django.utils.encoding import force_str from django.utils.functional import Promise from rest_framework.compat import coreapi @@ -23,7 +23,7 @@ class JSONEncoder(json.JSONEncoder): # For Date Time string spec, see ECMA 262 # https://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 if isinstance(obj, Promise): - return force_text(obj) + return force_str(obj) elif isinstance(obj, datetime.datetime): representation = obj.isoformat() if representation.endswith('+00:00'): @@ -57,8 +57,9 @@ class JSONEncoder(json.JSONEncoder): 'You should be using a schema renderer instead for this view.' ) elif hasattr(obj, '__getitem__'): + cls = (list if isinstance(obj, (list, tuple)) else dict) try: - return dict(obj) + return cls(obj) except Exception: pass elif hasattr(obj, '__iter__'): diff --git a/rest_framework/utils/field_mapping.py b/rest_framework/utils/field_mapping.py index 1281ee167..b90c3eead 100644 --- a/rest_framework/utils/field_mapping.py +++ b/rest_framework/utils/field_mapping.py @@ -109,6 +109,9 @@ def get_field_kwargs(field_name, model_field): if model_field.blank and (isinstance(model_field, (models.CharField, models.TextField))): kwargs['allow_blank'] = True + if not model_field.blank and (postgres_fields and isinstance(model_field, postgres_fields.ArrayField)): + kwargs['allow_empty'] = False + if isinstance(model_field, models.FilePathField): kwargs['path'] = model_field.path diff --git a/rest_framework/utils/formatting.py b/rest_framework/utils/formatting.py index 4e003f614..c5917fd41 100644 --- a/rest_framework/utils/formatting.py +++ b/rest_framework/utils/formatting.py @@ -3,7 +3,7 @@ Utility functions to return a formatted name and description for a given view. """ import re -from django.utils.encoding import force_text +from django.utils.encoding import force_str from django.utils.html import escape from django.utils.safestring import mark_safe @@ -29,7 +29,7 @@ def dedent(content): as it fails to dedent multiline docstrings that include unindented text on the initial line. """ - content = force_text(content) + content = force_str(content) lines = [line for line in content.splitlines()[1:] if line.lstrip()] # unindent the content if needed @@ -65,3 +65,29 @@ def markup_description(description): description = escape(description).replace('\n', '
') description = '

' + description + '

' return mark_safe(description) + + +class lazy_format: + """ + Delay formatting until it's actually needed. + + Useful when the format string or one of the arguments is lazy. + + Not using Django's lazy because it is too slow. + """ + __slots__ = ('format_string', 'args', 'kwargs', 'result') + + def __init__(self, format_string, *args, **kwargs): + self.result = None + self.format_string = format_string + self.args = args + self.kwargs = kwargs + + def __str__(self): + if self.result is None: + self.result = self.format_string.format(*self.args, **self.kwargs) + self.format_string, self.args, self.kwargs = None, None, None + return self.result + + def __mod__(self, value): + return str(self) % value diff --git a/rest_framework/utils/representation.py b/rest_framework/utils/representation.py index 3916eb686..6f2efee16 100644 --- a/rest_framework/utils/representation.py +++ b/rest_framework/utils/representation.py @@ -5,7 +5,7 @@ of serializer classes and serializer fields. import re from django.db import models -from django.utils.encoding import force_text +from django.utils.encoding import force_str from django.utils.functional import Promise @@ -28,7 +28,7 @@ def smart_repr(value): return manager_repr(value) if isinstance(value, Promise) and value._delegate_text: - value = force_text(value) + value = force_str(value) value = repr(value) diff --git a/rest_framework/utils/serializer_helpers.py b/rest_framework/utils/serializer_helpers.py index 80aea27d3..b18fbe0df 100644 --- a/rest_framework/utils/serializer_helpers.py +++ b/rest_framework/utils/serializer_helpers.py @@ -1,7 +1,7 @@ from collections import OrderedDict from collections.abc import MutableMapping -from django.utils.encoding import force_text +from django.utils.encoding import force_str from rest_framework.utils import json @@ -123,7 +123,7 @@ class NestedBoundField(BoundField): if isinstance(value, (list, dict)): values[key] = value else: - values[key] = '' if (value is None or value is False) else force_text(value) + values[key] = '' if (value is None or value is False) else force_str(value) return self.__class__(self._field, values, self.errors, self._prefix) diff --git a/rest_framework/views.py b/rest_framework/views.py index 6ef7021d4..bec10560a 100644 --- a/rest_framework/views.py +++ b/rest_framework/views.py @@ -350,9 +350,21 @@ class APIView(View): Check if request should be throttled. Raises an appropriate exception if the request is throttled. """ + throttle_durations = [] for throttle in self.get_throttles(): if not throttle.allow_request(request, self): - self.throttled(request, throttle.wait()) + throttle_durations.append(throttle.wait()) + + if throttle_durations: + # Filter out `None` values which may happen in case of config / rate + # changes, see #1438 + durations = [ + duration for duration in throttle_durations + if duration is not None + ] + + duration = max(durations, default=None) + self.throttled(request, duration) def determine_version(self, request, *args, **kwargs): """ diff --git a/rest_framework/viewsets.py b/rest_framework/viewsets.py index ad5633854..d94c81df4 100644 --- a/rest_framework/viewsets.py +++ b/rest_framework/viewsets.py @@ -53,7 +53,7 @@ class ViewSetMixin: and slightly modify the view function that is created and returned. """ # The name and description initkwargs may be explicitly overridden for - # certain route confiugurations. eg, names of extra actions. + # certain route configurations. eg, names of extra actions. cls.name = None cls.description = None diff --git a/setup.py b/setup.py index 632c7dfd3..2f8dafd21 100755 --- a/setup.py +++ b/setup.py @@ -8,7 +8,7 @@ from io import open from setuptools import find_packages, setup CURRENT_PYTHON = sys.version_info[:2] -REQUIRED_PYTHON = (3, 4) +REQUIRED_PYTHON = (3, 5) # This check and everything above must remain compatible with Python 2.7. if CURRENT_PYTHON < REQUIRED_PYTHON: @@ -56,6 +56,10 @@ if sys.argv[-1] == 'publish': print("twine not installed.\nUse `pip install twine`.\nExiting.") sys.exit() os.system("python setup.py sdist bdist_wheel") + if os.system("twine check dist/*"): + print("twine check failed. Packages might be outdated.") + print("Try using `pip install -U twine wheel`.\nExiting.") + sys.exit() os.system("twine upload dist/*") print("You probably want to also tag the version now:") print(" git tag -a %s -m 'version %s'" % (version, version)) @@ -79,7 +83,7 @@ setup( packages=find_packages(exclude=['tests*']), include_package_data=True, install_requires=[], - python_requires=">=3.4", + python_requires=">=3.5", zip_safe=False, classifiers=[ 'Development Status :: 5 - Production/Stable', @@ -94,13 +98,16 @@ setup( 'Operating System :: OS Independent', 'Programming Language :: Python', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.4', 'Programming Language :: Python :: 3.5', 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3 :: Only', 'Topic :: Internet :: WWW/HTTP', - ] + ], + project_urls={ + 'Funding': 'https://fund.django-rest-framework.org/topics/funding/', + 'Source': 'https://github.com/encode/django-rest-framework', + }, ) # (*) Please direct queries to the discussion group, rather than to me directly diff --git a/tests/authentication/test_authentication.py b/tests/authentication/test_authentication.py index 927989028..37e265e17 100644 --- a/tests/authentication/test_authentication.py +++ b/tests/authentication/test_authentication.py @@ -533,11 +533,13 @@ class BasicAuthenticationUnitTests(TestCase): is_active = False old_authenticate = authentication.authenticate authentication.authenticate = lambda **kwargs: MockUser() - auth = authentication.BasicAuthentication() - with pytest.raises(exceptions.AuthenticationFailed) as error: - auth.authenticate_credentials('foo', 'bar') - assert 'User inactive or deleted.' in str(error) - authentication.authenticate = old_authenticate + try: + auth = authentication.BasicAuthentication() + with pytest.raises(exceptions.AuthenticationFailed) as exc_info: + auth.authenticate_credentials('foo', 'bar') + assert 'User inactive or deleted.' in str(exc_info.value) + finally: + authentication.authenticate = old_authenticate @override_settings(ROOT_URLCONF=__name__, diff --git a/tests/importable/__init__.py b/tests/importable/__init__.py index b36599027..ded08258c 100644 --- a/tests/importable/__init__.py +++ b/tests/importable/__init__.py @@ -1 +1,16 @@ -from rest_framework import compat # noqa +""" +This test "app" exists to ensure that parts of Django REST Framework can be +imported/invoked before Django itself has been fully initialized. +""" + +from rest_framework import compat, serializers # noqa + + +# test initializing fields with lazy translations +class ExampleSerializer(serializers.Serializer): + charfield = serializers.CharField(min_length=1, max_length=2) + integerfield = serializers.IntegerField(min_value=1, max_value=2) + floatfield = serializers.FloatField(min_value=1, max_value=2) + decimalfield = serializers.DecimalField(max_digits=10, decimal_places=1, min_value=1, max_value=2) + durationfield = serializers.DurationField(min_value=1, max_value=2) + listfield = serializers.ListField(min_length=1, max_length=2) diff --git a/tests/importable/test_installed.py b/tests/importable/test_installed.py index 072d3b2e4..c7e53af23 100644 --- a/tests/importable/test_installed.py +++ b/tests/importable/test_installed.py @@ -4,10 +4,21 @@ from tests import importable def test_installed(): - # ensure that apps can freely import rest_framework.compat + # ensure the test app hasn't been removed from the test suite assert 'tests.importable' in settings.INSTALLED_APPS -def test_imported(): - # ensure that the __init__ hasn't been mucked with +def test_compat(): assert hasattr(importable, 'compat') + + +def test_serializer_fields_initialization(): + assert hasattr(importable, 'ExampleSerializer') + + serializer = importable.ExampleSerializer() + assert 'charfield' in serializer.fields + assert 'integerfield' in serializer.fields + assert 'floatfield' in serializer.fields + assert 'decimalfield' in serializer.fields + assert 'durationfield' in serializer.fields + assert 'listfield' in serializer.fields diff --git a/tests/schemas/__init__.py b/tests/schemas/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tests/test_schemas.py b/tests/schemas/test_coreapi.py similarity index 94% rename from tests/test_schemas.py rename to tests/schemas/test_coreapi.py index 230f8f012..66275ade9 100644 --- a/tests/test_schemas.py +++ b/tests/schemas/test_coreapi.py @@ -16,15 +16,16 @@ from rest_framework.routers import DefaultRouter, SimpleRouter from rest_framework.schemas import ( AutoSchema, ManualSchema, SchemaGenerator, get_schema_view ) +from rest_framework.schemas.coreapi import field_to_schema from rest_framework.schemas.generators import EndpointEnumerator -from rest_framework.schemas.inspectors import field_to_schema from rest_framework.schemas.utils import is_list_view from rest_framework.test import APIClient, APIRequestFactory from rest_framework.utils import formatting from rest_framework.views import APIView from rest_framework.viewsets import GenericViewSet, ModelViewSet -from .models import BasicModel, ForeignKeySource, ManyToManySource +from . import views +from ..models import BasicModel, ForeignKeySource, ManyToManySource factory = APIRequestFactory() @@ -133,11 +134,12 @@ class ExampleViewSet(ModelViewSet): pass -if coreapi: - schema_view = get_schema_view(title='Example API') -else: - def schema_view(request): - pass +with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + if coreapi: + schema_view = get_schema_view(title='Example API') + else: + def schema_view(request): + pass router = DefaultRouter() router.register('example', ExampleViewSet, basename='example') @@ -148,7 +150,7 @@ urlpatterns = [ @unittest.skipUnless(coreapi, 'coreapi is not installed') -@override_settings(ROOT_URLCONF='tests.test_schemas') +@override_settings(ROOT_URLCONF=__name__, REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestRouterGeneratedSchema(TestCase): def test_anonymous_request(self): client = APIClient() @@ -400,12 +402,13 @@ class ExampleDetailView(APIView): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGenerator(TestCase): def setUp(self): self.patterns = [ - url(r'^example/?$', ExampleListView.as_view()), - url(r'^example/(?P\d+)/?$', ExampleDetailView.as_view()), - url(r'^example/(?P\d+)/sub/?$', ExampleDetailView.as_view()), + url(r'^example/?$', views.ExampleListView.as_view()), + url(r'^example/(?P\d+)/?$', views.ExampleDetailView.as_view()), + url(r'^example/(?P\d+)/sub/?$', views.ExampleDetailView.as_view()), ] def test_schema_for_regular_views(self): @@ -453,12 +456,13 @@ class TestSchemaGenerator(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') @unittest.skipUnless(path, 'needs Django 2') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorDjango2(TestCase): def setUp(self): self.patterns = [ - path('example/', ExampleListView.as_view()), - path('example//', ExampleDetailView.as_view()), - path('example//sub/', ExampleDetailView.as_view()), + path('example/', views.ExampleListView.as_view()), + path('example//', views.ExampleDetailView.as_view()), + path('example//sub/', views.ExampleDetailView.as_view()), ] def test_schema_for_regular_views(self): @@ -505,12 +509,13 @@ class TestSchemaGeneratorDjango2(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorNotAtRoot(TestCase): def setUp(self): self.patterns = [ - url(r'^api/v1/example/?$', ExampleListView.as_view()), - url(r'^api/v1/example/(?P\d+)/?$', ExampleDetailView.as_view()), - url(r'^api/v1/example/(?P\d+)/sub/?$', ExampleDetailView.as_view()), + url(r'^api/v1/example/?$', views.ExampleListView.as_view()), + url(r'^api/v1/example/(?P\d+)/?$', views.ExampleDetailView.as_view()), + url(r'^api/v1/example/(?P\d+)/sub/?$', views.ExampleDetailView.as_view()), ] def test_schema_for_regular_views(self): @@ -558,6 +563,7 @@ class TestSchemaGeneratorNotAtRoot(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithMethodLimitedViewSets(TestCase): def setUp(self): router = DefaultRouter() @@ -622,13 +628,14 @@ class TestSchemaGeneratorWithMethodLimitedViewSets(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithRestrictedViewSets(TestCase): def setUp(self): router = DefaultRouter() router.register('example1', Http404ExampleViewSet, basename='example1') router.register('example2', PermissionDeniedExampleViewSet, basename='example2') self.patterns = [ - url('^example/?$', ExampleListView.as_view()), + url('^example/?$', views.ExampleListView.as_view()), url(r'^', include(router.urls)) ] @@ -668,6 +675,7 @@ class ForeignKeySourceView(generics.CreateAPIView): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithForeignKey(TestCase): def setUp(self): self.patterns = [ @@ -713,6 +721,7 @@ class ManyToManySourceView(generics.CreateAPIView): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestSchemaGeneratorWithManyToMany(TestCase): def setUp(self): self.patterns = [ @@ -747,6 +756,7 @@ class TestSchemaGeneratorWithManyToMany(TestCase): @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class Test4605Regression(TestCase): def test_4605_regression(self): generator = SchemaGenerator() @@ -762,6 +772,7 @@ class CustomViewInspector(AutoSchema): pass +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestAutoSchema(TestCase): def test_apiview_schema_descriptor(self): @@ -777,7 +788,7 @@ class TestAutoSchema(TestCase): assert isinstance(view.schema, CustomViewInspector) def test_set_custom_inspector_class_via_settings(self): - with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'tests.test_schemas.CustomViewInspector'}): + with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'tests.schemas.test_coreapi.CustomViewInspector'}): view = APIView() assert isinstance(view.schema, CustomViewInspector) @@ -971,6 +982,7 @@ class TestAutoSchema(TestCase): self.assertEqual(field_to_schema(case[0]), case[1]) +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) def test_docstring_is_not_stripped_by_get_description(): class ExampleDocstringAPIView(APIView): """ @@ -1007,25 +1019,25 @@ def test_docstring_is_not_stripped_by_get_description(): # Views for SchemaGenerationExclusionTests -class ExcludedAPIView(APIView): - schema = None +with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + class ExcludedAPIView(APIView): + schema = None - def get(self, request, *args, **kwargs): + def get(self, request, *args, **kwargs): + pass + + @api_view(['GET']) + @schema(None) + def excluded_fbv(request): + pass + + @api_view(['GET']) + def included_fbv(request): pass -@api_view(['GET']) -@schema(None) -def excluded_fbv(request): - pass - - -@api_view(['GET']) -def included_fbv(request): - pass - - @unittest.skipUnless(coreapi, 'coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class SchemaGenerationExclusionTests(TestCase): def setUp(self): self.patterns = [ @@ -1078,11 +1090,6 @@ class SchemaGenerationExclusionTests(TestCase): assert should_include == expected -@api_view(["GET"]) -def simple_fbv(request): - pass - - class BasicModelSerializer(serializers.ModelSerializer): class Meta: model = BasicModel @@ -1118,11 +1125,16 @@ naming_collisions_router.register(r'collision', NamingCollisionViewSet, basename @pytest.mark.skipif(not coreapi, reason='coreapi is not installed') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) class TestURLNamingCollisions(TestCase): """ Ref: https://github.com/encode/django-rest-framework/issues/4704 """ def test_manually_routing_nested_routes(self): + @api_view(["GET"]) + def simple_fbv(request): + pass + patterns = [ url(r'^test', simple_fbv), url(r'^test/list/', simple_fbv), @@ -1228,6 +1240,10 @@ class TestURLNamingCollisions(TestCase): def test_url_under_same_key_not_replaced_another(self): + @api_view(["GET"]) + def simple_fbv(request): + pass + patterns = [ url(r'^test/list/', simple_fbv), url(r'^test/(?P\d+)/list/', simple_fbv), @@ -1302,10 +1318,8 @@ def test_head_and_options_methods_are_excluded(): assert inspector.get_allowed_methods(callback) == ["GET"] -@pytest.mark.skipif(not coreapi, reason='coreapi is not installed') -class TestAutoSchemaAllowsFilters: - class MockAPIView(APIView): - filter_backends = [filters.OrderingFilter] +class MockAPIView(APIView): + filter_backends = [filters.OrderingFilter] def _test(self, method): view = self.MockAPIView() diff --git a/tests/schemas/test_get_schema_view.py b/tests/schemas/test_get_schema_view.py new file mode 100644 index 000000000..f582c6495 --- /dev/null +++ b/tests/schemas/test_get_schema_view.py @@ -0,0 +1,20 @@ +import pytest +from django.test import TestCase, override_settings + +from rest_framework import renderers +from rest_framework.schemas import coreapi, get_schema_view, openapi + + +class GetSchemaViewTests(TestCase): + """For the get_schema_view() helper.""" + def test_openapi(self): + schema_view = get_schema_view(title="With OpenAPI") + assert isinstance(schema_view.initkwargs['schema_generator'], openapi.SchemaGenerator) + assert renderers.OpenAPIRenderer in schema_view.cls().renderer_classes + + @pytest.mark.skipif(not coreapi.coreapi, reason='coreapi is not installed') + def test_coreapi(self): + with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + schema_view = get_schema_view(title="With CoreAPI") + assert isinstance(schema_view.initkwargs['schema_generator'], coreapi.SchemaGenerator) + assert renderers.CoreAPIOpenAPIRenderer in schema_view.cls().renderer_classes diff --git a/tests/test_generateschema.py b/tests/schemas/test_managementcommand.py similarity index 51% rename from tests/test_generateschema.py rename to tests/schemas/test_managementcommand.py index a6a1f2bed..6cdf7f8b1 100644 --- a/tests/test_generateschema.py +++ b/tests/schemas/test_managementcommand.py @@ -6,7 +6,8 @@ from django.core.management import call_command from django.test import TestCase from django.test.utils import override_settings -from rest_framework.compat import coreapi +from rest_framework.compat import uritemplate, yaml +from rest_framework.management.commands import generateschema from rest_framework.utils import formatting, json from rest_framework.views import APIView @@ -21,15 +22,60 @@ urlpatterns = [ ] -@override_settings(ROOT_URLCONF='tests.test_generateschema') -@pytest.mark.skipif(not coreapi, reason='coreapi is not installed') +class CustomSchemaGenerator: + SCHEMA = {"key": "value"} + + def __init__(self, *args, **kwargs): + pass + + def get_schema(self, **kwargs): + return self.SCHEMA + + +@override_settings(ROOT_URLCONF=__name__) +@pytest.mark.skipif(not uritemplate, reason='uritemplate is not installed') class GenerateSchemaTests(TestCase): """Tests for management command generateschema.""" def setUp(self): self.out = io.StringIO() + def test_command_detects_schema_generation_mode(self): + """Switching between CoreAPI & OpenAPI""" + command = generateschema.Command() + assert command.get_mode() == generateschema.OPENAPI_MODE + with override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}): + assert command.get_mode() == generateschema.COREAPI_MODE + + @pytest.mark.skipif(yaml is None, reason='PyYAML is required.') def test_renders_default_schema_with_custom_title_url_and_description(self): + call_command('generateschema', + '--title=SampleAPI', + '--url=http://api.sample.com', + '--description=Sample description', + stdout=self.out) + # Check valid YAML was output. + schema = yaml.safe_load(self.out.getvalue()) + assert schema['openapi'] == '3.0.2' + + def test_renders_openapi_json_schema(self): + call_command('generateschema', + '--format=openapi-json', + stdout=self.out) + # Check valid JSON was output. + out_json = json.loads(self.out.getvalue()) + assert out_json['openapi'] == '3.0.2' + + def test_accepts_custom_schema_generator(self): + call_command('generateschema', + '--generator_class={}.{}'.format(__name__, CustomSchemaGenerator.__name__), + stdout=self.out) + out_json = yaml.safe_load(self.out.getvalue()) + assert out_json == CustomSchemaGenerator.SCHEMA + + @pytest.mark.skipif(yaml is None, reason='PyYAML is required.') + @override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) + def test_coreapi_renders_default_schema_with_custom_title_url_and_description(self): expected_out = """info: description: Sample description title: SampleAPI @@ -50,7 +96,8 @@ class GenerateSchemaTests(TestCase): self.assertIn(formatting.dedent(expected_out), self.out.getvalue()) - def test_renders_openapi_json_schema(self): + @override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) + def test_coreapi_renders_openapi_json_schema(self): expected_out = { "openapi": "3.0.0", "info": { @@ -78,6 +125,7 @@ class GenerateSchemaTests(TestCase): self.assertDictEqual(out_json, expected_out) + @override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'}) def test_renders_corejson_schema(self): expected_out = """{"_type":"document","":{"list":{"_type":"link","url":"/","action":"get"}}}""" call_command('generateschema', diff --git a/tests/schemas/test_openapi.py b/tests/schemas/test_openapi.py new file mode 100644 index 000000000..d9375585b --- /dev/null +++ b/tests/schemas/test_openapi.py @@ -0,0 +1,572 @@ +import pytest +from django.conf.urls import url +from django.test import RequestFactory, TestCase, override_settings +from django.utils.translation import gettext_lazy as _ + +from rest_framework import filters, generics, pagination, routers, serializers +from rest_framework.compat import uritemplate +from rest_framework.request import Request +from rest_framework.schemas.openapi import AutoSchema, SchemaGenerator + +from . import views + + +def create_request(path): + factory = RequestFactory() + request = Request(factory.get(path)) + return request + + +def create_view(view_cls, method, request): + generator = SchemaGenerator() + view = generator.create_view(view_cls.as_view(), method, request) + return view + + +class TestBasics(TestCase): + def dummy_view(request): + pass + + def test_filters(self): + classes = [filters.SearchFilter, filters.OrderingFilter] + for c in classes: + f = c() + assert f.get_schema_operation_parameters(self.dummy_view) + + def test_pagination(self): + classes = [pagination.PageNumberPagination, pagination.LimitOffsetPagination, pagination.CursorPagination] + for c in classes: + f = c() + assert f.get_schema_operation_parameters(self.dummy_view) + + +class TestFieldMapping(TestCase): + def test_list_field_mapping(self): + inspector = AutoSchema() + cases = [ + (serializers.ListField(), {'items': {}, 'type': 'array'}), + (serializers.ListField(child=serializers.BooleanField()), {'items': {'type': 'boolean'}, 'type': 'array'}), + (serializers.ListField(child=serializers.FloatField()), {'items': {'type': 'number'}, 'type': 'array'}), + (serializers.ListField(child=serializers.CharField()), {'items': {'type': 'string'}, 'type': 'array'}), + ] + for field, mapping in cases: + with self.subTest(field=field): + assert inspector._map_field(field) == mapping + + def test_lazy_string_field(self): + class Serializer(serializers.Serializer): + text = serializers.CharField(help_text=_('lazy string')) + + inspector = AutoSchema() + + data = inspector._map_serializer(Serializer()) + assert isinstance(data['properties']['text']['description'], str), "description must be str" + + +@pytest.mark.skipif(uritemplate is None, reason='uritemplate not installed.') +class TestOperationIntrospection(TestCase): + + def test_path_without_parameters(self): + path = '/example/' + method = 'GET' + + view = create_view( + views.ExampleListView, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + operation = inspector.get_operation(path, method) + assert operation == { + 'operationId': 'listExamples', + 'parameters': [], + 'responses': { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'array', + 'items': {}, + }, + }, + }, + }, + }, + } + + def test_path_with_id_parameter(self): + path = '/example/{id}/' + method = 'GET' + + view = create_view( + views.ExampleDetailView, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + parameters = inspector._get_path_parameters(path, method) + assert parameters == [{ + 'description': '', + 'in': 'path', + 'name': 'id', + 'required': True, + 'schema': { + 'type': 'string', + }, + }] + + def test_request_body(self): + path = '/' + method = 'POST' + + class Serializer(serializers.Serializer): + text = serializers.CharField() + read_only = serializers.CharField(read_only=True) + + class View(generics.GenericAPIView): + serializer_class = Serializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + request_body = inspector._get_request_body(path, method) + assert request_body['content']['application/json']['schema']['required'] == ['text'] + assert list(request_body['content']['application/json']['schema']['properties'].keys()) == ['text'] + + def test_empty_required(self): + path = '/' + method = 'POST' + + class Serializer(serializers.Serializer): + read_only = serializers.CharField(read_only=True) + write_only = serializers.CharField(write_only=True, required=False) + + class View(generics.GenericAPIView): + serializer_class = Serializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + request_body = inspector._get_request_body(path, method) + # there should be no empty 'required' property, see #6834 + assert 'required' not in request_body['content']['application/json']['schema'] + + for response in inspector._get_responses(path, method).values(): + assert 'required' not in response['content']['application/json']['schema'] + + def test_response_body_generation(self): + path = '/' + method = 'POST' + + class Serializer(serializers.Serializer): + text = serializers.CharField() + write_only = serializers.CharField(write_only=True) + + class View(generics.GenericAPIView): + serializer_class = Serializer + + view = create_view( + View, + method, + create_request(path) + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + assert responses['200']['content']['application/json']['schema']['required'] == ['text'] + assert list(responses['200']['content']['application/json']['schema']['properties'].keys()) == ['text'] + assert 'description' in responses['200'] + + def test_response_body_nested_serializer(self): + path = '/' + method = 'POST' + + class NestedSerializer(serializers.Serializer): + number = serializers.IntegerField() + + class Serializer(serializers.Serializer): + text = serializers.CharField() + nested = NestedSerializer() + + class View(generics.GenericAPIView): + serializer_class = Serializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + schema = responses['200']['content']['application/json']['schema'] + assert sorted(schema['required']) == ['nested', 'text'] + assert sorted(list(schema['properties'].keys())) == ['nested', 'text'] + assert schema['properties']['nested']['type'] == 'object' + assert list(schema['properties']['nested']['properties'].keys()) == ['number'] + assert schema['properties']['nested']['required'] == ['number'] + + def test_list_response_body_generation(self): + """Test that an array schema is returned for list views.""" + path = '/' + method = 'GET' + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'array', + 'items': { + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + }, + }, + }, + }, + }, + } + + def test_paginated_list_response_body_generation(self): + """Test that pagination properties are added for a paginated list view.""" + path = '/' + method = 'GET' + + class Pagination(pagination.BasePagination): + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'item': schema, + } + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + pagination_class = Pagination + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'object', + 'item': { + 'type': 'array', + 'items': { + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + }, + }, + }, + }, + }, + }, + } + + def test_delete_response_body_generation(self): + """Test that a view's delete method generates a proper response body schema.""" + path = '/{id}/' + method = 'DELETE' + + class View(generics.DestroyAPIView): + serializer_class = views.ExampleSerializer + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + assert responses == { + '204': { + 'description': '', + }, + } + + def test_retrieve_response_body_generation(self): + """ + Test that a list of properties is returned for retrieve item views. + + Pagination properties should not be added as the view represents a single item. + """ + path = '/{id}/' + method = 'GET' + + class Pagination(pagination.BasePagination): + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'item': schema, + } + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + pagination_class = Pagination + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + }, + }, + }, + }, + } + + def test_operation_id_generation(self): + path = '/' + method = 'GET' + + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + operationId = inspector._get_operation_id(path, method) + assert operationId == 'listExamples' + + def test_repeat_operation_ids(self): + router = routers.SimpleRouter() + router.register('account', views.ExampleGenericViewSet, basename="account") + urlpatterns = router.urls + + generator = SchemaGenerator(patterns=urlpatterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + schema_str = str(schema) + print(schema_str) + assert schema_str.count("operationId") == 2 + assert schema_str.count("newExample") == 1 + assert schema_str.count("oldExample") == 1 + + def test_serializer_datefield(self): + path = '/' + method = 'GET' + view = create_view( + views.ExampleGenericAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + response_schema = responses['200']['content']['application/json']['schema'] + properties = response_schema['items']['properties'] + assert properties['date']['type'] == properties['datetime']['type'] == 'string' + assert properties['date']['format'] == 'date' + assert properties['datetime']['format'] == 'date-time' + + def test_serializer_validators(self): + path = '/' + method = 'GET' + view = create_view( + views.ExampleValidatedAPIView, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + response_schema = responses['200']['content']['application/json']['schema'] + properties = response_schema['items']['properties'] + + assert properties['integer']['type'] == 'integer' + assert properties['integer']['maximum'] == 99 + assert properties['integer']['minimum'] == -11 + + assert properties['string']['minLength'] == 2 + assert properties['string']['maxLength'] == 10 + + assert properties['lst']['minItems'] == 2 + assert properties['lst']['maxItems'] == 10 + + assert properties['regex']['pattern'] == r'[ABC]12{3}' + assert properties['regex']['description'] == 'must have an A, B, or C followed by 1222' + + assert properties['decimal1']['type'] == 'number' + assert properties['decimal1']['multipleOf'] == .01 + assert properties['decimal1']['maximum'] == 10000 + assert properties['decimal1']['minimum'] == -10000 + + assert properties['decimal2']['type'] == 'number' + assert properties['decimal2']['multipleOf'] == .0001 + + assert properties['email']['type'] == 'string' + assert properties['email']['format'] == 'email' + assert properties['email']['default'] == 'foo@bar.com' + + assert properties['url']['type'] == 'string' + assert properties['url']['nullable'] is True + assert properties['url']['default'] == 'http://www.example.com' + + assert properties['uuid']['type'] == 'string' + assert properties['uuid']['format'] == 'uuid' + + assert properties['ip4']['type'] == 'string' + assert properties['ip4']['format'] == 'ipv4' + + assert properties['ip6']['type'] == 'string' + assert properties['ip6']['format'] == 'ipv6' + + assert properties['ip']['type'] == 'string' + assert 'format' not in properties['ip'] + + +@pytest.mark.skipif(uritemplate is None, reason='uritemplate not installed.') +@override_settings(REST_FRAMEWORK={'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.openapi.AutoSchema'}) +class TestGenerator(TestCase): + + def test_override_settings(self): + assert isinstance(views.ExampleListView.schema, AutoSchema) + + def test_paths_construction(self): + """Construction of the `paths` key.""" + patterns = [ + url(r'^example/?$', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + generator._initialise_endpoints() + + paths = generator.get_paths() + + assert '/example/' in paths + example_operations = paths['/example/'] + assert len(example_operations) == 2 + assert 'get' in example_operations + assert 'post' in example_operations + + def test_prefixed_paths_construction(self): + """Construction of the `paths` key maintains a common prefix.""" + patterns = [ + url(r'^v1/example/?$', views.ExampleListView.as_view()), + url(r'^v1/example/{pk}/?$', views.ExampleDetailView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + generator._initialise_endpoints() + + paths = generator.get_paths() + + assert '/v1/example/' in paths + assert '/v1/example/{id}/' in paths + + def test_mount_url_prefixed_to_paths(self): + patterns = [ + url(r'^example/?$', views.ExampleListView.as_view()), + url(r'^example/{pk}/?$', views.ExampleDetailView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns, url='/api') + generator._initialise_endpoints() + + paths = generator.get_paths() + + assert '/api/example/' in paths + assert '/api/example/{id}/' in paths + + def test_schema_construction(self): + """Construction of the top level dictionary.""" + patterns = [ + url(r'^example/?$', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns) + + request = create_request('/') + schema = generator.get_schema(request=request) + + assert 'openapi' in schema + assert 'paths' in schema + + def test_schema_information(self): + """Construction of the top level dictionary.""" + patterns = [ + url(r'^example/?$', views.ExampleListView.as_view()), + ] + generator = SchemaGenerator(patterns=patterns, title='My title', version='1.2.3', description='My description') + + request = create_request('/') + schema = generator.get_schema(request=request) + + assert schema['info']['title'] == 'My title' + assert schema['info']['version'] == '1.2.3' + assert schema['info']['description'] == 'My description' diff --git a/tests/schemas/views.py b/tests/schemas/views.py new file mode 100644 index 000000000..d1fc75eb8 --- /dev/null +++ b/tests/schemas/views.py @@ -0,0 +1,113 @@ +import uuid + +from django.core.validators import ( + DecimalValidator, MaxLengthValidator, MaxValueValidator, + MinLengthValidator, MinValueValidator, RegexValidator +) + +from rest_framework import generics, permissions, serializers +from rest_framework.decorators import action +from rest_framework.response import Response +from rest_framework.views import APIView +from rest_framework.viewsets import GenericViewSet + + +class ExampleListView(APIView): + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, *args, **kwargs): + pass + + def post(self, request, *args, **kwargs): + pass + + +class ExampleDetailView(APIView): + permission_classes = [permissions.IsAuthenticatedOrReadOnly] + + def get(self, *args, **kwargs): + pass + + +# Generics. +class ExampleSerializer(serializers.Serializer): + date = serializers.DateField() + datetime = serializers.DateTimeField() + + +class ExampleGenericAPIView(generics.GenericAPIView): + serializer_class = ExampleSerializer + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + +class ExampleGenericViewSet(GenericViewSet): + serializer_class = ExampleSerializer + + def get(self, *args, **kwargs): + from datetime import datetime + now = datetime.now() + + serializer = self.get_serializer(data=now.date(), datetime=now) + return Response(serializer.data) + + @action(detail=False) + def new(self, *args, **kwargs): + pass + + @action(detail=False) + def old(self, *args, **kwargs): + pass + + +# Validators and/or equivalent Field attributes. +class ExampleValidatedSerializer(serializers.Serializer): + integer = serializers.IntegerField( + validators=( + MaxValueValidator(limit_value=99), + MinValueValidator(limit_value=-11), + ) + ) + string = serializers.CharField( + validators=( + MaxLengthValidator(limit_value=10), + MinLengthValidator(limit_value=2), + ) + ) + regex = serializers.CharField( + validators=( + RegexValidator(regex=r'[ABC]12{3}'), + ), + help_text='must have an A, B, or C followed by 1222' + ) + lst = serializers.ListField( + validators=( + MaxLengthValidator(limit_value=10), + MinLengthValidator(limit_value=2), + ) + ) + decimal1 = serializers.DecimalField(max_digits=6, decimal_places=2) + decimal2 = serializers.DecimalField(max_digits=5, decimal_places=0, + validators=(DecimalValidator(max_digits=17, decimal_places=4),)) + email = serializers.EmailField(default='foo@bar.com') + url = serializers.URLField(default='http://www.example.com', allow_null=True) + uuid = serializers.UUIDField() + ip4 = serializers.IPAddressField(protocol='ipv4') + ip6 = serializers.IPAddressField(protocol='ipv6') + ip = serializers.IPAddressField() + + +class ExampleValidatedAPIView(generics.GenericAPIView): + serializer_class = ExampleValidatedSerializer + + def get(self, *args, **kwargs): + serializer = self.get_serializer(integer=33, string='hello', regex='foo', decimal1=3.55, + decimal2=5.33, email='a@b.co', + url='http://localhost', uuid=uuid.uuid4(), ip4='127.0.0.1', ip6='::1', + ip='192.168.1.1') + return Response(serializer.data) diff --git a/tests/test_decorators.py b/tests/test_decorators.py index bd30449e5..e10f0e5c5 100644 --- a/tests/test_decorators.py +++ b/tests/test_decorators.py @@ -1,12 +1,11 @@ import pytest from django.test import TestCase -from rest_framework import RemovedInDRF310Warning, status +from rest_framework import status from rest_framework.authentication import BasicAuthentication from rest_framework.decorators import ( - action, api_view, authentication_classes, detail_route, list_route, - parser_classes, permission_classes, renderer_classes, schema, - throttle_classes + action, api_view, authentication_classes, parser_classes, + permission_classes, renderer_classes, schema, throttle_classes ) from rest_framework.parsers import JSONParser from rest_framework.permissions import IsAuthenticated @@ -285,39 +284,3 @@ class ActionDecoratorTestCase(TestCase): @test_action.mapping.post def test_action(): raise NotImplementedError - - def test_detail_route_deprecation(self): - with pytest.warns(RemovedInDRF310Warning) as record: - @detail_route() - def view(request): - raise NotImplementedError - - assert len(record) == 1 - assert str(record[0].message) == ( - "`detail_route` is deprecated and will be removed in " - "3.10 in favor of `action`, which accepts a `detail` bool. Use " - "`@action(detail=True)` instead." - ) - - def test_list_route_deprecation(self): - with pytest.warns(RemovedInDRF310Warning) as record: - @list_route() - def view(request): - raise NotImplementedError - - assert len(record) == 1 - assert str(record[0].message) == ( - "`list_route` is deprecated and will be removed in " - "3.10 in favor of `action`, which accepts a `detail` bool. Use " - "`@action(detail=False)` instead." - ) - - def test_route_url_name_from_path(self): - # pre-3.8 behavior was to base the `url_name` off of the `url_path` - with pytest.warns(RemovedInDRF310Warning): - @list_route(url_path='foo_bar') - def view(request): - raise NotImplementedError - - assert view.url_path == 'foo_bar' - assert view.url_name == 'foo-bar' diff --git a/tests/test_encoders.py b/tests/test_encoders.py index c66954b80..c104dd5a5 100644 --- a/tests/test_encoders.py +++ b/tests/test_encoders.py @@ -8,6 +8,7 @@ from django.utils.timezone import utc from rest_framework.compat import coreapi from rest_framework.utils.encoders import JSONEncoder +from rest_framework.utils.serializer_helpers import ReturnList class MockList: @@ -93,3 +94,10 @@ class JSONEncoderTests(TestCase): """ foo = MockList() assert self.encoder.default(foo) == [1, 2, 3] + + def test_encode_empty_returnlist(self): + """ + Tests encoding an empty ReturnList + """ + foo = ReturnList(serializer=None) + assert self.encoder.default(foo) == [] diff --git a/tests/test_fields.py b/tests/test_fields.py index e0833564b..7c495cd63 100644 --- a/tests/test_fields.py +++ b/tests/test_fields.py @@ -1,7 +1,6 @@ import datetime import os import re -import unittest import uuid from decimal import ROUND_DOWN, ROUND_UP, Decimal @@ -15,17 +14,14 @@ from django.utils.timezone import activate, deactivate, override, utc import rest_framework from rest_framework import exceptions, serializers from rest_framework.compat import ProhibitNullCharactersValidator -from rest_framework.fields import DjangoImageField, is_simple_callable - -try: - import typing -except ImportError: - typing = False - +from rest_framework.fields import ( + BuiltinSignatureError, DjangoImageField, is_simple_callable +) # Tests for helper functions. # --------------------------- + class TestIsSimpleCallable: def test_method(self): @@ -92,7 +88,18 @@ class TestIsSimpleCallable: assert is_simple_callable(ChoiceModel().get_choice_field_display) - @unittest.skipUnless(typing, 'requires python 3.5') + def test_builtin_function(self): + # Built-in function signatures are not easily inspectable, so the + # current expectation is to just raise a helpful error message. + timestamp = datetime.datetime.now() + + with pytest.raises(BuiltinSignatureError) as exc_info: + is_simple_callable(timestamp.date) + + assert str(exc_info.value) == ( + 'Built-in function signatures are not inspectable. Wrap the ' + 'function call in a simple, pure Python function.') + def test_type_annotation(self): # The annotation will otherwise raise a syntax error in python < 3.5 locals = {} @@ -213,6 +220,18 @@ class TestSource: assert 'method call failed' in str(exc_info.value) + def test_builtin_callable_source_raises(self): + class BuiltinSerializer(serializers.Serializer): + date = serializers.ReadOnlyField(source='timestamp.date') + + with pytest.raises(BuiltinSignatureError) as exc_info: + BuiltinSerializer({'timestamp': datetime.datetime.now()}).data + + assert str(exc_info.value) == ( + 'Field source for `BuiltinSerializer.date` maps to a built-in ' + 'function type and is invalid. Define a property or method on ' + 'the `dict` instance that wraps the call to the built-in function.') + class TestReadOnly: def setup(self): @@ -226,7 +245,7 @@ class TestReadOnly: Read-only fields should not be writable, even with default () """ serializer = self.Serializer() - assert len(serializer._writable_fields) == 1 + assert len(list(serializer._writable_fields)) == 1 def test_validate_read_only(self): """ @@ -1989,6 +2008,7 @@ class TestDictField(FieldValues): """ valid_inputs = [ ({'a': 1, 'b': '2', 3: 3}, {'a': '1', 'b': '2', '3': '3'}), + ({}, {}), ] invalid_inputs = [ ({'a': 1, 'b': None, 'c': None}, {'b': ['This field may not be null.'], 'c': ['This field may not be null.']}), @@ -2016,6 +2036,16 @@ class TestDictField(FieldValues): output = field.run_validation(None) assert output is None + def test_allow_empty_disallowed(self): + """ + If allow_empty is False then an empty dict is not a valid input. + """ + field = serializers.DictField(allow_empty=False) + with pytest.raises(serializers.ValidationError) as exc_info: + field.run_validation({}) + + assert exc_info.value.detail == ['This dictionary may not be empty.'] + class TestNestedDictField(FieldValues): """ @@ -2174,8 +2204,8 @@ class TestBinaryJSONField(FieldValues): field = serializers.JSONField(binary=True) -# Tests for FieldField. -# --------------------- +# Tests for FileField. +# -------------------- class MockRequest: def build_absolute_uri(self, value): @@ -2208,19 +2238,30 @@ class TestSerializerMethodField: } def test_redundant_method_name(self): + # Prior to v3.10, redundant method names were not allowed. + # This restriction has since been removed. class ExampleSerializer(serializers.Serializer): example_field = serializers.SerializerMethodField('get_example_field') - with pytest.raises(AssertionError) as exc_info: - ExampleSerializer().fields - assert str(exc_info.value) == ( - "It is redundant to specify `get_example_field` on " - "SerializerMethodField 'example_field' in serializer " - "'ExampleSerializer', because it is the same as the default " - "method name. Remove the `method_name` argument." - ) + field = ExampleSerializer().fields['example_field'] + assert field.method_name == 'get_example_field' +# Tests for ModelField. +# --------------------- + +class TestModelField: + def test_max_length_init(self): + field = serializers.ModelField(None) + assert len(field.validators) == 0 + + field = serializers.ModelField(None, max_length=10) + assert len(field.validators) == 1 + + +# Tests for validation errors +# --------------------------- + class TestValidationErrorCode: @pytest.mark.parametrize('use_list', (False, True)) def test_validationerror_code_with_msg(self, use_list): @@ -2229,14 +2270,33 @@ class TestValidationErrorCode: password = serializers.CharField() def validate_password(self, obj): - err = DjangoValidationError('exc_msg', code='exc_code') + err = DjangoValidationError( + 'exc_msg %s', code='exc_code', params=('exc_param',), + ) if use_list: err = DjangoValidationError([err]) raise err serializer = ExampleSerializer(data={'password': 123}) serializer.is_valid() - assert serializer.errors == {'password': ['exc_msg']} + assert serializer.errors == {'password': ['exc_msg exc_param']} + assert serializer.errors['password'][0].code == 'exc_code' + + @pytest.mark.parametrize('use_list', (False, True)) + def test_validationerror_code_with_msg_including_percent(self, use_list): + + class ExampleSerializer(serializers.Serializer): + password = serializers.CharField() + + def validate_password(self, obj): + err = DjangoValidationError('exc_msg with %', code='exc_code') + if use_list: + err = DjangoValidationError([err]) + raise err + + serializer = ExampleSerializer(data={'password': 123}) + serializer.is_valid() + assert serializer.errors == {'password': ['exc_msg with %']} assert serializer.errors['password'][0].code == 'exc_code' @pytest.mark.parametrize('code', (None, 'exc_code',)) diff --git a/tests/test_filters.py b/tests/test_filters.py index a52f40103..6d7969a92 100644 --- a/tests/test_filters.py +++ b/tests/test_filters.py @@ -180,6 +180,15 @@ class SearchFilterTests(TestCase): {'id': 3, 'title': 'zzz', 'text': 'cde'} ] + def test_search_field_with_null_characters(self): + view = generics.GenericAPIView() + request = factory.get('/?search=\0as%00d\x00f') + request = view.initialize_request(request) + + terms = filters.SearchFilter().get_search_terms(request) + + assert terms == ['asdf'] + class AttributeModel(models.Model): label = models.CharField(max_length=32) diff --git a/tests/test_model_serializer.py b/tests/test_model_serializer.py index 413d7885d..21ec82347 100644 --- a/tests/test_model_serializer.py +++ b/tests/test_model_serializer.py @@ -13,10 +13,13 @@ from collections import OrderedDict import django import pytest from django.core.exceptions import ImproperlyConfigured +from django.core.serializers.json import DjangoJSONEncoder from django.core.validators import ( MaxValueValidator, MinLengthValidator, MinValueValidator ) from django.db import models +from django.db.models.signals import m2m_changed +from django.dispatch import receiver from django.test import TestCase from rest_framework import serializers @@ -300,7 +303,7 @@ class TestRegularFieldMappings(TestCase): def test_invalid_field(self): """ Field names that do not map to a model field or relationship should - raise a configuration errror. + raise a configuration error. """ class TestSerializer(serializers.ModelSerializer): class Meta: @@ -437,30 +440,34 @@ class TestPosgresFieldsMapping(TestCase): def test_array_field(self): class ArrayFieldModel(models.Model): array_field = postgres_fields.ArrayField(base_field=models.CharField()) + array_field_with_blank = postgres_fields.ArrayField(blank=True, base_field=models.CharField()) class TestSerializer(serializers.ModelSerializer): class Meta: model = ArrayFieldModel - fields = ['array_field'] + fields = ['array_field', 'array_field_with_blank'] expected = dedent(""" TestSerializer(): - array_field = ListField(child=CharField(label='Array field', validators=[])) + array_field = ListField(allow_empty=False, child=CharField(label='Array field', validators=[])) + array_field_with_blank = ListField(child=CharField(label='Array field with blank', validators=[]), required=False) """) self.assertEqual(repr(TestSerializer()), expected) def test_json_field(self): class JSONFieldModel(models.Model): json_field = postgres_fields.JSONField() + json_field_with_encoder = postgres_fields.JSONField(encoder=DjangoJSONEncoder) class TestSerializer(serializers.ModelSerializer): class Meta: model = JSONFieldModel - fields = ['json_field'] + fields = ['json_field', 'json_field_with_encoder'] expected = dedent(""" TestSerializer(): - json_field = JSONField(style={'base_template': 'textarea.html'}) + json_field = JSONField(encoder=None, style={'base_template': 'textarea.html'}) + json_field_with_encoder = JSONField(encoder=, style={'base_template': 'textarea.html'}) """) self.assertEqual(repr(TestSerializer()), expected) @@ -1248,7 +1255,6 @@ class Issue6110ModelSerializer(serializers.ModelSerializer): class Issue6110Test(TestCase): - def test_model_serializer_custom_manager(self): instance = Issue6110ModelSerializer().create({'name': 'test_name'}) self.assertEqual(instance.name, 'test_name') @@ -1257,3 +1263,43 @@ class Issue6110Test(TestCase): msginitial = ('Got a `TypeError` when calling `Issue6110TestModel.all_objects.create()`.') with self.assertRaisesMessage(TypeError, msginitial): Issue6110ModelSerializer().create({'wrong_param': 'wrong_param'}) + + +class Issue6751Model(models.Model): + many_to_many = models.ManyToManyField(ManyToManyTargetModel, related_name='+') + char_field = models.CharField(max_length=100) + char_field2 = models.CharField(max_length=100) + + +@receiver(m2m_changed, sender=Issue6751Model.many_to_many.through) +def process_issue6751model_m2m_changed(action, instance, **_): + if action == 'post_add': + instance.char_field = 'value changed by signal' + instance.save() + + +class Issue6751Test(TestCase): + def test_model_serializer_save_m2m_after_instance(self): + class TestSerializer(serializers.ModelSerializer): + class Meta: + model = Issue6751Model + fields = ( + 'many_to_many', + 'char_field', + ) + + instance = Issue6751Model.objects.create(char_field='initial value') + m2m_target = ManyToManyTargetModel.objects.create(name='target') + + serializer = TestSerializer( + instance=instance, + data={ + 'many_to_many': (m2m_target.id,), + 'char_field': 'will be changed by signal', + } + ) + + serializer.is_valid() + serializer.save() + + self.assertEqual(instance.char_field, 'value changed by signal') diff --git a/tests/test_pagination.py b/tests/test_pagination.py index 3c581ddfb..cd84c8151 100644 --- a/tests/test_pagination.py +++ b/tests/test_pagination.py @@ -259,6 +259,37 @@ class TestPageNumberPagination: with pytest.raises(exceptions.NotFound): self.paginate_queryset(request) + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': unpaginated_schema, + }, + } + class TestPageNumberPaginationOverride: """ @@ -535,6 +566,37 @@ class TestLimitOffset: assert content.get('next') == next_url assert content.get('previous') == prev_url + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': unpaginated_schema, + }, + } + class CursorPaginationTestsMixin: @@ -630,6 +692,52 @@ class CursorPaginationTestsMixin: assert isinstance(self.pagination.to_html(), str) + def test_cursor_pagination_current_page_empty_forward(self): + # Regression test for #6504 + self.pagination.base_url = "/" + + # We have a cursor on the element at position 100, but this element doesn't exist + # anymore. + cursor = pagination.Cursor(reverse=False, offset=0, position=100) + url = self.pagination.encode_cursor(cursor) + self.pagination.base_url = "/" + + # Loading the page with this cursor doesn't crash + (previous, current, next, previous_url, next_url) = self.get_pages(url) + + # The previous url doesn't crash either + (previous, current, next, previous_url, next_url) = self.get_pages(previous_url) + + # And point to things that are not completely off. + assert previous == [7, 7, 7, 8, 9] + assert current == [9, 9, 9, 9, 9] + assert next == [] + assert previous_url is not None + assert next_url is not None + + def test_cursor_pagination_current_page_empty_reverse(self): + # Regression test for #6504 + self.pagination.base_url = "/" + + # We have a cursor on the element at position 100, but this element doesn't exist + # anymore. + cursor = pagination.Cursor(reverse=True, offset=0, position=100) + url = self.pagination.encode_cursor(cursor) + self.pagination.base_url = "/" + + # Loading the page with this cursor doesn't crash + (previous, current, next, previous_url, next_url) = self.get_pages(url) + + # The previous url doesn't crash either + (previous, current, next, previous_url, next_url) = self.get_pages(next_url) + + # And point to things that are not completely off. + assert previous == [7, 7, 7, 7, 8] + assert current == [] + assert next is None + assert previous_url is not None + assert next_url is None + def test_cursor_pagination_with_page_size(self): (previous, current, next, previous_url, next_url) = self.get_pages('/?page_size=20') @@ -788,6 +896,33 @@ class CursorPaginationTestsMixin: assert current == [1, 1, 1, 1, 1] assert next == [1, 2, 3, 4, 4] + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': unpaginated_schema, + }, + } + class TestCursorPagination(CursorPaginationTestsMixin): """ diff --git a/tests/test_permissions.py b/tests/test_permissions.py index 9c9300694..03b80aae8 100644 --- a/tests/test_permissions.py +++ b/tests/test_permissions.py @@ -1,21 +1,20 @@ import base64 import unittest -import warnings from unittest import mock import django import pytest +from django.conf import settings from django.contrib.auth.models import AnonymousUser, Group, Permission, User from django.db import models from django.test import TestCase from django.urls import ResolverMatch from rest_framework import ( - HTTP_HEADER_ENCODING, RemovedInDRF310Warning, authentication, generics, - permissions, serializers, status, views + HTTP_HEADER_ENCODING, authentication, generics, permissions, serializers, + status, views ) -from rest_framework.compat import PY36, is_guardian_installed -from rest_framework.filters import DjangoObjectPermissionsFilter +from rest_framework.compat import PY36 from rest_framework.routers import DefaultRouter from rest_framework.test import APIRequestFactory from tests.models import BasicModel @@ -309,7 +308,7 @@ class GetQuerysetObjectPermissionInstanceView(generics.RetrieveUpdateDestroyAPIV get_queryset_object_permissions_view = GetQuerysetObjectPermissionInstanceView.as_view() -@unittest.skipUnless(is_guardian_installed(), 'django-guardian not installed') +@unittest.skipUnless('guardian' in settings.INSTALLED_APPS, 'django-guardian not installed') class ObjectPermissionsIntegrationTests(TestCase): """ Integration tests for the object level permissions API. @@ -418,37 +417,14 @@ class ObjectPermissionsIntegrationTests(TestCase): self.assertEqual(response.status_code, status.HTTP_200_OK) # Read list - def test_django_object_permissions_filter_deprecated(self): - with warnings.catch_warnings(record=True) as w: - warnings.simplefilter("always") - DjangoObjectPermissionsFilter() - - message = ("`DjangoObjectPermissionsFilter` has been deprecated and moved " - "to the 3rd-party django-rest-framework-guardian package.") - self.assertEqual(len(w), 1) - self.assertIs(w[-1].category, RemovedInDRF310Warning) - self.assertEqual(str(w[-1].message), message) - + # Note: this previously tested `DjangoObjectPermissionsFilter`, which has + # since been moved to a separate package. These now act as sanity checks. def test_can_read_list_permissions(self): request = factory.get('/', HTTP_AUTHORIZATION=self.credentials['readonly']) - object_permissions_list_view.cls.filter_backends = (DjangoObjectPermissionsFilter,) - # TODO: remove in version 3.10 - with warnings.catch_warnings(record=True): - warnings.simplefilter("always") - response = object_permissions_list_view(request) + response = object_permissions_list_view(request) self.assertEqual(response.status_code, status.HTTP_200_OK) self.assertEqual(response.data[0].get('id'), 1) - def test_cannot_read_list_permissions(self): - request = factory.get('/', HTTP_AUTHORIZATION=self.credentials['writeonly']) - object_permissions_list_view.cls.filter_backends = (DjangoObjectPermissionsFilter,) - # TODO: remove in version 3.10 - with warnings.catch_warnings(record=True): - warnings.simplefilter("always") - response = object_permissions_list_view(request) - self.assertEqual(response.status_code, status.HTTP_200_OK) - self.assertListEqual(response.data, []) - def test_cannot_method_not_allowed(self): request = factory.generic('METHOD_NOT_ALLOWED', '/', HTTP_AUTHORIZATION=self.credentials['readonly']) response = object_permissions_list_view(request) diff --git a/tests/test_renderers.py b/tests/test_renderers.py index d63dbcb9c..c79c0a766 100644 --- a/tests/test_renderers.py +++ b/tests/test_renderers.py @@ -631,8 +631,12 @@ class BrowsableAPIRendererTests(URLPatternsTestCase): def list_action(self, request): raise NotImplementedError + class AuthExampleViewSet(ExampleViewSet): + permission_classes = [permissions.IsAuthenticated] + router = SimpleRouter() router.register('examples', ExampleViewSet, basename='example') + router.register('auth-examples', AuthExampleViewSet, basename='auth-example') urlpatterns = [url(r'^api/', include(router.urls))] def setUp(self): @@ -657,6 +661,12 @@ class BrowsableAPIRendererTests(URLPatternsTestCase): assert '/api/examples/list_action/' in resp.content.decode() assert '>Extra list action<' in resp.content.decode() + def test_extra_actions_dropdown_not_authed(self): + resp = self.client.get('/api/unauth-examples/', HTTP_ACCEPT='text/html') + assert 'id="extra-actions-menu"' not in resp.content.decode() + assert '/api/examples/list_action/' not in resp.content.decode() + assert '>Extra list action<' not in resp.content.decode() + class AdminRendererTests(TestCase): diff --git a/tests/test_serializer.py b/tests/test_serializer.py index e0acf368b..0d4b50c1d 100644 --- a/tests/test_serializer.py +++ b/tests/test_serializer.py @@ -317,7 +317,8 @@ class TestBaseSerializer: class TestStarredSource: """ - Tests for `source='*'` argument, which is used for nested representations. + Tests for `source='*'` argument, which is often used for complex field or + nested representations. For example: @@ -337,11 +338,28 @@ class TestStarredSource: c = serializers.IntegerField() d = serializers.IntegerField() - class TestSerializer(serializers.Serializer): + class NestedBaseSerializer(serializers.Serializer): nested1 = NestedSerializer1(source='*') nested2 = NestedSerializer2(source='*') - self.Serializer = TestSerializer + # nullable nested serializer testing + class NullableNestedSerializer(serializers.Serializer): + nested = NestedSerializer1(source='*', allow_null=True) + + # nullable custom field testing + class CustomField(serializers.Field): + def to_representation(self, instance): + return getattr(instance, 'foo', None) + + def to_internal_value(self, data): + return {'foo': data} + + class NullableFieldSerializer(serializers.Serializer): + field = CustomField(source='*', allow_null=True) + + self.Serializer = NestedBaseSerializer + self.NullableNestedSerializer = NullableNestedSerializer + self.NullableFieldSerializer = NullableFieldSerializer def test_nested_validate(self): """ @@ -356,6 +374,12 @@ class TestStarredSource: 'd': 4 } + def test_nested_null_validate(self): + serializer = self.NullableNestedSerializer(data={'nested': None}) + + # validation should fail (but not error) since nested fields are required + assert not serializer.is_valid() + def test_nested_serialize(self): """ An object can be serialized into a nested representation. @@ -364,6 +388,20 @@ class TestStarredSource: serializer = self.Serializer(instance) assert serializer.data == self.data + def test_field_validate(self): + serializer = self.NullableFieldSerializer(data={'field': 'bar'}) + + # validation should pass since no internal validation + assert serializer.is_valid() + assert serializer.validated_data == {'foo': 'bar'} + + def test_field_null_validate(self): + serializer = self.NullableFieldSerializer(data={'field': None}) + + # validation should pass since no internal validation + assert serializer.is_valid() + assert serializer.validated_data == {'foo': None} + class TestIncorrectlyConfigured: def test_incorrect_field_name(self): diff --git a/tests/test_serializer_lists.py b/tests/test_serializer_lists.py index 12ed78b84..98e72385a 100644 --- a/tests/test_serializer_lists.py +++ b/tests/test_serializer_lists.py @@ -1,7 +1,9 @@ +import pytest from django.http import QueryDict from django.utils.datastructures import MultiValueDict from rest_framework import serializers +from rest_framework.exceptions import ErrorDetail class BasicObject: @@ -223,6 +225,49 @@ class TestNestedListSerializer: assert serializer.validated_data == expected_output +class TestNestedListSerializerAllowEmpty: + """Tests the behaviour of allow_empty=False when a ListSerializer is used as a field.""" + + @pytest.mark.parametrize('partial', (False, True)) + def test_allow_empty_true(self, partial): + """ + If allow_empty is True, empty lists should be allowed regardless of the value + of partial on the parent serializer. + """ + class ChildSerializer(serializers.Serializer): + id = serializers.IntegerField() + + class ParentSerializer(serializers.Serializer): + ids = ChildSerializer(many=True, allow_empty=True) + + serializer = ParentSerializer(data={'ids': []}, partial=partial) + assert serializer.is_valid() + assert serializer.validated_data == { + 'ids': [], + } + + @pytest.mark.parametrize('partial', (False, True)) + def test_allow_empty_false(self, partial): + """ + If allow_empty is False, empty lists should fail validation regardless of the value + of partial on the parent serializer. + """ + class ChildSerializer(serializers.Serializer): + id = serializers.IntegerField() + + class ParentSerializer(serializers.Serializer): + ids = ChildSerializer(many=True, allow_empty=False) + + serializer = ParentSerializer(data={'ids': []}, partial=partial) + assert not serializer.is_valid() + assert serializer.errors == { + 'ids': { + 'non_field_errors': [ + ErrorDetail(string='This list may not be empty.', code='empty')], + } + } + + class TestNestedListOfListsSerializer: def setup(self): class TestSerializer(serializers.Serializer): diff --git a/tests/test_serializer_nested.py b/tests/test_serializer_nested.py index 1cd0caf85..ab30fad22 100644 --- a/tests/test_serializer_nested.py +++ b/tests/test_serializer_nested.py @@ -1,4 +1,7 @@ +import pytest +from django.db import models from django.http import QueryDict +from django.test import TestCase from rest_framework import serializers @@ -241,3 +244,61 @@ class TestNotRequiredNestedSerializerWithMany: serializer = self.Serializer(data=input_data) assert serializer.is_valid() assert 'nested' in serializer.validated_data + + +class NestedWriteProfile(models.Model): + address = models.CharField(max_length=100) + + +class NestedWritePerson(models.Model): + profile = models.ForeignKey(NestedWriteProfile, on_delete=models.CASCADE) + + +class TestNestedWriteErrors(TestCase): + # tests for rests_framework.serializers.raise_errors_on_nested_writes + def test_nested_serializer_error(self): + class ProfileSerializer(serializers.ModelSerializer): + class Meta: + model = NestedWriteProfile + fields = ['address'] + + class NestedProfileSerializer(serializers.ModelSerializer): + profile = ProfileSerializer() + + class Meta: + model = NestedWritePerson + fields = ['profile'] + + serializer = NestedProfileSerializer(data={'profile': {'address': '52 festive road'}}) + assert serializer.is_valid() + assert serializer.validated_data == {'profile': {'address': '52 festive road'}} + with pytest.raises(AssertionError) as exc_info: + serializer.save() + + assert str(exc_info.value) == ( + 'The `.create()` method does not support writable nested fields by ' + 'default.\nWrite an explicit `.create()` method for serializer ' + '`tests.test_serializer_nested.NestedProfileSerializer`, or set ' + '`read_only=True` on nested serializer fields.' + ) + + def test_dotted_source_field_error(self): + class DottedAddressSerializer(serializers.ModelSerializer): + address = serializers.CharField(source='profile.address') + + class Meta: + model = NestedWritePerson + fields = ['address'] + + serializer = DottedAddressSerializer(data={'address': '52 festive road'}) + assert serializer.is_valid() + assert serializer.validated_data == {'profile': {'address': '52 festive road'}} + with pytest.raises(AssertionError) as exc_info: + serializer.save() + + assert str(exc_info.value) == ( + 'The `.create()` method does not support writable dotted-source ' + 'fields by default.\nWrite an explicit `.create()` method for ' + 'serializer `tests.test_serializer_nested.DottedAddressSerializer`, ' + 'or set `read_only=True` on dotted-source serializer fields.' + ) diff --git a/tests/test_templatetags.py b/tests/test_templatetags.py index 128160888..28d6b4011 100644 --- a/tests/test_templatetags.py +++ b/tests/test_templatetags.py @@ -540,7 +540,7 @@ class SchemaLinksTests(TestCase): ] ), 'create': coreapi.Link( - url='/aniamls/cat', + url='/animals/cat', action='post', fields=[] ) @@ -589,7 +589,7 @@ class SchemaLinksTests(TestCase): ] ), 'create': coreapi.Link( - url='/aniamls/cat', + url='/animals/cat', action='post', fields=[] ) diff --git a/tests/test_throttling.py b/tests/test_throttling.py index b20b6a809..d5a61232d 100644 --- a/tests/test_throttling.py +++ b/tests/test_throttling.py @@ -30,6 +30,11 @@ class User3MinRateThrottle(UserRateThrottle): scope = 'minutes' +class User6MinRateThrottle(UserRateThrottle): + rate = '6/min' + scope = 'minutes' + + class NonTimeThrottle(BaseThrottle): def allow_request(self, request, view): if not hasattr(self.__class__, 'called'): @@ -38,6 +43,13 @@ class NonTimeThrottle(BaseThrottle): return False +class MockView_DoubleThrottling(APIView): + throttle_classes = (User3SecRateThrottle, User6MinRateThrottle,) + + def get(self, request): + return Response('foo') + + class MockView(APIView): throttle_classes = (User3SecRateThrottle,) @@ -80,7 +92,8 @@ class ThrottlingTests(TestCase): """ Explicitly set the timer, overriding time.time() """ - view.throttle_classes[0].timer = lambda self: value + for cls in view.throttle_classes: + cls.timer = lambda self: value def test_request_throttling_expires(self): """ @@ -115,6 +128,58 @@ class ThrottlingTests(TestCase): """ self.ensure_is_throttled(MockView, 200) + def test_request_throttling_multiple_throttles(self): + """ + Ensure all throttle classes see each request even when the request is + already being throttled + """ + self.set_throttle_timer(MockView_DoubleThrottling, 0) + request = self.factory.get('/') + for dummy in range(4): + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 1 + + # At this point our client made 4 requests (one was throttled) in a + # second. If we advance the timer by one additional second, the client + # should be allowed to make 2 more before being throttled by the 2nd + # throttle class, which has a limit of 6 per minute. + self.set_throttle_timer(MockView_DoubleThrottling, 1) + for dummy in range(2): + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 200 + + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 59 + + # Just to make sure check again after two more seconds. + self.set_throttle_timer(MockView_DoubleThrottling, 2) + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 58 + + def test_throttle_rate_change_negative(self): + self.set_throttle_timer(MockView_DoubleThrottling, 0) + request = self.factory.get('/') + for dummy in range(24): + response = MockView_DoubleThrottling.as_view()(request) + assert response.status_code == 429 + assert int(response['retry-after']) == 60 + + previous_rate = User3SecRateThrottle.rate + try: + User3SecRateThrottle.rate = '1/sec' + + for dummy in range(24): + response = MockView_DoubleThrottling.as_view()(request) + + assert response.status_code == 429 + assert int(response['retry-after']) == 60 + finally: + # reset + User3SecRateThrottle.rate = previous_rate + def ensure_response_header_contains_proper_throttle_field(self, view, expected_headers): """ Ensure the response returns an Retry-After field with status and next attributes diff --git a/tests/test_utils.py b/tests/test_utils.py index a6f8b9d16..500c6a3fa 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -1,3 +1,5 @@ +from unittest import mock + from django.conf.urls import url from django.test import TestCase, override_settings @@ -6,6 +8,7 @@ from rest_framework.routers import SimpleRouter from rest_framework.serializers import ModelSerializer from rest_framework.utils import json from rest_framework.utils.breadcrumbs import get_breadcrumbs +from rest_framework.utils.formatting import lazy_format from rest_framework.utils.urls import remove_query_param, replace_query_param from rest_framework.views import APIView from rest_framework.viewsets import ModelViewSet @@ -171,7 +174,7 @@ class BreadcrumbTests(TestCase): class JsonFloatTests(TestCase): """ - Internaly, wrapped json functions should adhere to strict float handling + Internally, wrapped json functions should adhere to strict float handling """ def test_dumps(self): @@ -189,7 +192,7 @@ class JsonFloatTests(TestCase): json.loads("NaN") -@override_settings(STRICT_JSON=False) +@override_settings(REST_FRAMEWORK={'STRICT_JSON': False}) class NonStrictJsonFloatTests(JsonFloatTests): """ 'STRICT_JSON = False' should not somehow affect internal json behavior @@ -232,15 +235,6 @@ class UrlsRemoveQueryParamTests(TestCase): """ Tests the remove_query_param functionality. """ - def test_valid_unicode_preserved(self): - q = '/?q=%E6%9F%A5%E8%AF%A2' - new_key = 'page' - new_value = 2 - value = '%E6%9F%A5%E8%AF%A2' - - assert new_key in replace_query_param(q, new_key, new_value) - assert value in replace_query_param(q, new_key, new_value) - def test_valid_unicode_removed(self): q = '/?page=2345&q=%E6%9F%A5%E8%AF%A2' key = 'page' @@ -257,3 +251,19 @@ class UrlsRemoveQueryParamTests(TestCase): removed_key = 'page' assert key in remove_query_param(q, removed_key) + + +class LazyFormatTests(TestCase): + def test_it_formats_correctly(self): + formatted = lazy_format('Does {} work? {answer}: %s', 'it', answer='Yes') + assert str(formatted) == 'Does it work? Yes: %s' + assert formatted % 'it does' == 'Does it work? Yes: it does' + + def test_it_formats_lazily(self): + message = mock.Mock(wraps='message') + formatted = lazy_format(message) + assert message.format.call_count == 0 + str(formatted) + assert message.format.call_count == 1 + str(formatted) + assert message.format.call_count == 1 diff --git a/tox.ini b/tox.ini index fcd32f88a..699ca909c 100644 --- a/tox.ini +++ b/tox.ini @@ -1,7 +1,7 @@ [tox] envlist = - {py34,py35,py36}-django111, - {py34,py35,py36,py37}-django20, + {py35,py36}-django111, + {py35,py36,py37}-django20, {py35,py36,py37}-django21 {py35,py36,py37}-django22 {py36,py37}-djangomaster, @@ -51,7 +51,7 @@ deps = -rrequirements/requirements-testing.txt [testenv:docs] -basepython = python2.7 +basepython = python3.7 skip_install = true commands = mkdocs build deps =