From 48b02f016a827bc254aba2aedb81b472189c2165 Mon Sep 17 00:00:00 2001 From: Kyle Valade Date: Sun, 27 Jul 2014 14:01:43 -0700 Subject: Issue #1707: Add documentation to api-docs.viewsets notifying users that they should use the get_queryset() method when overriding a ModelViewSet method, such as list(). Otherwise, since queryset is a static property, the value will be cached for every instance of that ViewSet. --- docs/api-guide/viewsets.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 23b16575..774e11b7 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -70,6 +70,21 @@ There are two main advantages of using a `ViewSet` class over using a `View` cla Both of these come with a trade-off. Using regular views and URL confs is more explicit and gives you more control. ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout. +## Overriding ModelViewSet Methods + +Overriding the ModelViewSet is the same as overriding anything else, except you will need to remember to clone `self.queryset` before you use it, which you can do by using the built-in `get_queryset` method. For example: + + class UserViewSet(viewsets.ModelViewSet): + """ + A viewset for viewing and editing user instances. + """ + queryset = User.objects.all() + + def list(self, request): + queryset = self.get_queryset() + serializer = UserSerializer(queryset, many=True) + return Response(serializer.data) + ## Marking extra methods for routing The default routers included with REST framework will provide routes for a standard set of create/retrieve/update/destroy style operations, as shown below: @@ -142,7 +157,7 @@ The `@action` decorator will route `POST` requests by default, but may also acce @action(methods=['POST', 'DELETE']) def unset_password(self, request, pk=None): ... - + The two new actions will then be available at the urls `^users/{pk}/set_password/$` and `^users/{pk}/unset_password/$` -- cgit v1.2.3 From e40ffd60d44d736d7e27ff454cba1905f0becc26 Mon Sep 17 00:00:00 2001 From: Kyle Date: Mon, 28 Jul 2014 10:11:40 -0700 Subject: Issue #1707 - Add documentation about the caching of `GenericAPIView.queryset` to the `queryset` property, `get_queryset()`, and do generic-views.md; remove changes to the viewsets.md documentation from my last commit. --- docs/api-guide/generic-views.md | 8 +++++++- docs/api-guide/viewsets.md | 15 --------------- 2 files changed, 7 insertions(+), 16 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 7d06f246..b76c18cf 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -43,6 +43,12 @@ For more complex cases you might also want to override various methods on the vi return 20 return 100 + def list(self, request): + # Note the use of `get_queryset()` instead of `self.queryset` + queryset = self.get_queryset() + serializer = UserSerializer(queryset, many=True) + return Response(serializer.data) + For very simple cases you might want to pass through any class attributes using the `.as_view()` method. For example, your URLconf might include something the following entry. url(r'^/users/', ListCreateAPIView.as_view(model=User), name='user-list') @@ -63,7 +69,7 @@ Each of the concrete generic views provided is built by combining `GenericAPIVie The following attributes control the basic view behavior. -* `queryset` - The queryset that should be used for returning objects from this view. Typically, you must either set this attribute, or override the `get_queryset()` method. +* `queryset` - The queryset that should be used for returning objects from this view. Typically, you must either set this attribute, or override the `get_queryset()` method. If you are overriding a view method, it is important that you call `get_queryset()` instead of accessing this property directly, as `queryset` will get evaluated once, and those results will be cached for all subsequent requests. * `serializer_class` - The serializer class that should be used for validating and deserializing input, and for serializing output. Typically, you must either set this attribute, or override the `get_serializer_class()` method. * `lookup_field` - The model field that should be used to for performing object lookup of individual model instances. Defaults to `'pk'`. Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes set the lookup fields if you need to use a custom value. * `lookup_url_kwarg` - The URL keyword argument that should be used for object lookup. The URL conf should include a keyword argument corresponding to this value. If unset this defaults to using the same value as `lookup_field`. diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 774e11b7..4f345abb 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -70,21 +70,6 @@ There are two main advantages of using a `ViewSet` class over using a `View` cla Both of these come with a trade-off. Using regular views and URL confs is more explicit and gives you more control. ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout. -## Overriding ModelViewSet Methods - -Overriding the ModelViewSet is the same as overriding anything else, except you will need to remember to clone `self.queryset` before you use it, which you can do by using the built-in `get_queryset` method. For example: - - class UserViewSet(viewsets.ModelViewSet): - """ - A viewset for viewing and editing user instances. - """ - queryset = User.objects.all() - - def list(self, request): - queryset = self.get_queryset() - serializer = UserSerializer(queryset, many=True) - return Response(serializer.data) - ## Marking extra methods for routing The default routers included with REST framework will provide routes for a standard set of create/retrieve/update/destroy style operations, as shown below: -- cgit v1.2.3 From fc8eb76c2259ea64a19876f040db4d93e834d39d Mon Sep 17 00:00:00 2001 From: Kyle Date: Mon, 28 Jul 2014 10:19:42 -0700 Subject: Issue #1707 - Add info about queryset property caching to get_queryset() docs. Add documentation to the get_queryset() method of generic-views.md regarding the caching of the queryset property. --- docs/api-guide/generic-views.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index b76c18cf..43c5782f 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -99,6 +99,8 @@ The following attributes are used to control pagination when used with list view Returns the queryset that should be used for list views, and that should be used as the base for lookups in detail views. Defaults to returning the queryset specified by the `queryset` attribute, or the default queryset for the model if the `model` shortcut is being used. +This method should always be used rather than accessing `self.queryset` directly, as `self.queryset` gets evaluated only once, and those results are cached for all subsequent requests. + May be overridden to provide dynamic behavior such as returning a queryset that is specific to the user making the request. For example: -- cgit v1.2.3 From 57d6e04ff5512f11594e29bf49c47b610594666c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 30 Jul 2014 12:50:36 +0100 Subject: Add django-rest-framework-mongoengine link. Closes #1722 Closes #1562 Closes #1545 --- docs/api-guide/serializers.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index cedf1ff7..72568e53 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -580,7 +580,16 @@ The following custom model serializer could be used as a base class for model se def get_pk_field(self, model_field): return None +--- + +# Third party packages + +The following third party packages are also available. + +## MongoengineModelSerializer +The [django-rest-framework-mongoengine][mongoengine] package provides a `MongoEngineModelSerializer` serializer class that supports using MongoDB as the storage layer for Django REST framework. [cite]: https://groups.google.com/d/topic/django-users/sVFaOfQi4wY/discussion [relations]: relations.md +[mongoengine]: https://github.com/umutbozkurt/django-rest-framework-mongoengine -- cgit v1.2.3 From c0f002b09d07275d8dbba7266d1180623b78f6a5 Mon Sep 17 00:00:00 2001 From: Kevin London Date: Thu, 31 Jul 2014 12:41:15 -0700 Subject: Updated Permissions doc link to Django docs The previous link went to version 1 docs so it was a dead link.--- docs/api-guide/permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index c44b22de..38ae3d0a 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -244,7 +244,7 @@ The [REST Condition][rest-condition] package is another extension for building c [authentication]: authentication.md [throttling]: throttling.md [filtering]: filtering.md -[contribauth]: https://docs.djangoproject.com/en/1.0/topics/auth/#permissions +[contribauth]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#custom-permissions [objectpermissions]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#handling-object-permissions [guardian]: https://github.com/lukaszb/django-guardian [get_objects_for_user]: http://pythonhosted.org/django-guardian/api/guardian.shortcuts.html#get-objects-for-user -- cgit v1.2.3 From 3217842346cebda578e9398b89fe60fed7d1b2d8 Mon Sep 17 00:00:00 2001 From: Rob Terhaar Date: Wed, 6 Aug 2014 18:55:08 -0400 Subject: minor doc fix, @api_view() needs an iterable --- docs/api-guide/throttling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index b7c320f0..92f4c22b 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -58,7 +58,7 @@ using the `APIView` class based views. Or, if you're using the `@api_view` decorator with function based views. - @api_view('GET') + @api_view(['GET']) @throttle_classes([UserRateThrottle]) def example_view(request, format=None): content = { -- cgit v1.2.3 From 5eb901cd2a7dc2e33034f49e076bf7af7656655a Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Fri, 8 Aug 2014 14:25:02 +0200 Subject: docs: added reference to DRF-gis in fields added django-rest-framework-gis to third party packages section in /docs/api-guide/fields.md--- docs/api-guide/fields.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 813fc381..dd279541 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -361,6 +361,9 @@ The [drf-compound-fields][drf-compound-fields] package provides "compound" seria The [drf-extra-fields][drf-extra-fields] package provides extra serializer fields for REST framework, including `Base64ImageField` and `PointField` classes. +## django-rest-framework-gis + +The [django-rest-framework-gis][django-rest-framework-gis] package provides geographic addons for django rest framework like a `GeometryField` field and a GeoJSON serializer. [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data @@ -370,3 +373,4 @@ The [drf-extra-fields][drf-extra-fields] package provides extra serializer field [iso8601]: http://www.w3.org/TR/NOTE-datetime [drf-compound-fields]: http://drf-compound-fields.readthedocs.org [drf-extra-fields]: https://github.com/Hipo/drf-extra-fields +[django-rest-framework-gis]: https://github.com/djangonauts/django-rest-framework-gis -- cgit v1.2.3 From c462a43a872b45d27def08a3d17799b930950860 Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Fri, 8 Aug 2014 14:39:56 +0200 Subject: docs: added reference to gis serializer added reference to GeoFeatureModelSerializer of django-rest-framework-gis--- docs/api-guide/serializers.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 72568e53..29b7851b 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -590,6 +590,11 @@ The following third party packages are also available. The [django-rest-framework-mongoengine][mongoengine] package provides a `MongoEngineModelSerializer` serializer class that supports using MongoDB as the storage layer for Django REST framework. +## GeoFeatureModelSerializer + +The [django-rest-framework-gis][django-rest-framework-gis] package provides a `GeoFeatureModelSerializer` serializer class that supports GeoJSON both for read and write operations. + [cite]: https://groups.google.com/d/topic/django-users/sVFaOfQi4wY/discussion [relations]: relations.md [mongoengine]: https://github.com/umutbozkurt/django-rest-framework-mongoengine +[django-rest-framework-gis]: https://github.com/djangonauts/django-rest-framework-gis -- cgit v1.2.3 From 6edbabe0e1ffa8111284c0af94a8f878f7056413 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 18 Aug 2014 10:58:00 +0100 Subject: Link to Django docs on widgets. Closes #1760. --- docs/api-guide/fields.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index dd279541..b41e0ebc 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -62,7 +62,7 @@ A dictionary of error codes to error messages. ### `widget` Used only if rendering the field to HTML. -This argument sets the widget that should be used to render the field. +This argument sets the widget that should be used to render the field. For more details, and a list of available widgets, see [the Django documentation on form widgets][django-widgets]. ### `label` @@ -370,6 +370,7 @@ The [django-rest-framework-gis][django-rest-framework-gis] package provides geog [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS [ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior +[django-widgets]: https://docs.djangoproject.com/en/dev/ref/forms/widgets/ [iso8601]: http://www.w3.org/TR/NOTE-datetime [drf-compound-fields]: http://drf-compound-fields.readthedocs.org [drf-extra-fields]: https://github.com/Hipo/drf-extra-fields -- cgit v1.2.3