From d8eb9e6d45c227582559ec4318b1f92562c718da Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 29 Aug 2014 10:48:16 +0100 Subject: Docs whitespace fix. --- docs/api-guide/generic-views.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index b1c4e65a..d30b7f9b 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -19,8 +19,8 @@ Typically when using the generic views, you'll override the view, and set severa from django.contrib.auth.models import User from myapp.serializers import UserSerializer - from rest_framework import generics - from rest_framework.permissions import IsAdminUser + from rest_framework import generics + from rest_framework.permissions import IsAdminUser class UserList(generics.ListCreateAPIView): queryset = User.objects.all() -- cgit v1.2.3 From 0f8fdf4e72b67ff46474c13c8b532bf319a58099 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 29 Aug 2014 10:57:24 +0100 Subject: Remove `allow_empty`. Closes #1774. --- docs/api-guide/generic-views.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index d30b7f9b..49be0cae 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -212,8 +212,6 @@ Provides a `.list(request, *args, **kwargs)` method, that implements listing a q If the queryset is populated, this returns a `200 OK` response, with a serialized representation of the queryset as the body of the response. The response data may optionally be paginated. -If the queryset is empty this returns a `200 OK` response, unless the `.allow_empty` attribute on the view is set to `False`, in which case it will return a `404 Not Found`. - ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. -- cgit v1.2.3 From fe06d96dec0182f56fd4e72bcd71a26c923bb834 Mon Sep 17 00:00:00 2001 From: Darren Maki Date: Sun, 7 Sep 2014 12:53:21 -0400 Subject: Fixing quotes in filtering.md Incorrect quotes used in examples.--- docs/api-guide/filtering.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index ec5ab61f..cfeb4334 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -193,7 +193,7 @@ filters using `Manufacturer` name. For example: class ProductFilter(django_filters.FilterSet): class Meta: model = Product - fields = ['category', 'in_stock', 'manufacturer__name`] + fields = ['category', 'in_stock', 'manufacturer__name'] This enables us to make queries like: @@ -211,7 +211,7 @@ This is nice, but it exposes the Django's double underscore convention as part o class Meta: model = Product - fields = ['category', 'in_stock', 'manufacturer`] + fields = ['category', 'in_stock', 'manufacturer'] And now you can execute: -- cgit v1.2.3 From e76f56a3d687159327b8bef5bf9bc2ad28c99ea3 Mon Sep 17 00:00:00 2001 From: S. Andrew Sheppard Date: Wed, 10 Sep 2014 11:55:43 -0500 Subject: add django rest pandas --- docs/api-guide/renderers.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 7a3429bf..20eed70d 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -444,6 +444,11 @@ Comma-separated values are a plain-text tabular data format, that can be easily [djangorestframework-camel-case] provides camel case JSON renderers and parsers for REST framework. This allows serializers to use Python-style underscored field names, but be exposed in the API as Javascript-style camel case field names. It is maintained by [Vitaly Babiy][vbabiy]. +## Pandas (CSV, Excel, PNG) + +[Django REST Pandas] provides a serializer and renderers that support additional data processing and output via the [Pandas] DataFrame API. Django REST Pandas includes renderers for Pandas-style CSV files, Excel workbooks (both `.xls` and `.xlsx`), and a number of [other formats]. It is maintained by [S. Andrew Sheppard][sheppard] as part of the [wq Project][wq]. + + [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/#the-rendering-process [conneg]: content-negotiation.md [browser-accept-headers]: http://www.gethifi.com/blog/browser-rest-http-accept-headers @@ -466,4 +471,9 @@ Comma-separated values are a plain-text tabular data format, that can be easily [ultrajson]: https://github.com/esnme/ultrajson [hzy]: https://github.com/hzy [drf-ujson-renderer]: https://github.com/gizmag/drf-ujson-renderer -[djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case \ No newline at end of file +[djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case +[Django REST Pandas]: https://github.com/wq/django-rest-pandas +[Pandas]: http://pandas.pydata.org/ +[other formats]: https://github.com/wq/django-rest-pandas#supported-formats +[sheppard]: https://github.com/sheppard +[wq]: https://github.com/wq -- cgit v1.2.3 From 19b8f779de82fa4737b37fb4359145af0b07a56c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 11 Sep 2014 20:43:44 +0100 Subject: Throttles now use Retry-After header and no longer support the custom style --- docs/api-guide/throttling.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index 832304f1..16a7457b 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -178,6 +178,8 @@ To create a custom throttle, override `BaseThrottle` and implement `.allow_reque Optionally you may also override the `.wait()` method. If implemented, `.wait()` should return a recommended number of seconds to wait before attempting the next request, or `None`. The `.wait()` method will only be called if `.allow_request()` has previously returned `False`. +If the `.wait()` method is implemented and the request is throttled, then a `Retry-After` header will be included in the response. + ## Example The following is an example of a rate throttle, that will randomly throttle 1 in every 10 requests. -- cgit v1.2.3 From f95e7fae38968f58e742b93842bda9110a61b9f7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 12 Sep 2014 12:40:53 +0100 Subject: Updating docs --- docs/api-guide/renderers.md | 29 +++++---------------------- docs/api-guide/settings.md | 48 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 50 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 7a3429bf..b1adf31f 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -74,37 +74,18 @@ If your API includes views that can serve both regular webpages and API response Renders the request data into `JSON`, using utf-8 encoding. -Note that non-ascii characters will be rendered using JSON's `\uXXXX` character escape. For example: +Note that the default style is to include unicode characters, and render the response using a compact style with no uneccessary whitespace: - {"unicode black star": "\u2605"} + {"unicode black star":"★","value":999} The client may additionally include an `'indent'` media type parameter, in which case the returned `JSON` will be indented. For example `Accept: application/json; indent=4`. { - "unicode black star": "\u2605" + "unicode black star": "★", + "value": 999 } -**.media_type**: `application/json` - -**.format**: `'.json'` - -**.charset**: `None` - -## UnicodeJSONRenderer - -Renders the request data into `JSON`, using utf-8 encoding. - -Note that non-ascii characters will not be character escaped. For example: - - {"unicode black star": "★"} - -The client may additionally include an `'indent'` media type parameter, in which case the returned `JSON` will be indented. For example `Accept: application/json; indent=4`. - - { - "unicode black star": "★" - } - -Both the `JSONRenderer` and `UnicodeJSONRenderer` styles conform to [RFC 4627][rfc4627], and are syntactically valid JSON. +The default JSON encoding style can be altered using the `UNICODE_JSON` and `COMPACT_JSON` settings keys. **.media_type**: `application/json` diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 27a09163..6a855c92 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -265,7 +265,7 @@ A format string that should be used by default for rendering the output of `Date May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. -Default: `None` +Default: `'iso-8601'` #### DATETIME_INPUT_FORMATS @@ -281,7 +281,7 @@ A format string that should be used by default for rendering the output of `Date May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. -Default: `None` +Default: `'iso-8601'` #### DATE_INPUT_FORMATS @@ -297,7 +297,7 @@ A format string that should be used by default for rendering the output of `Time May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. -Default: `None` +Default: `'iso-8601'` #### TIME_INPUT_FORMATS @@ -309,6 +309,46 @@ Default: `['iso-8601']` --- +## Encodings + +#### UNICODE_JSON + +When set to `True`, JSON responses will allow unicode characters in responses. For example: + + {"unicode black star":"★"} + +When set to `False`, JSON responses will escape non-ascii characters, like so: + + {"unicode black star":"\u2605"} + +Both styles conform to [RFC 4627][rfc4627], and are syntactically valid JSON. The unicode style is prefered as being more user-friendly when inspecting API responses. + +Default: `True` + +#### COMPACT_JSON + +When set to `True`, JSON responses will return compact representations, with no spacing after `':'` and `','` characters. For example: + + {"is_admin":false,"email":"jane@example"} + +When set to `False`, JSON responses will return slightly more verbose representations, like so: + + {"is_admin": false, "email": "jane@example"} + +The default style is to return minified responses, in line with [Heroku's API design guidelines][heroku-minified-json]. + +Default: `True` + +#### COERCE_DECIMAL_TO_STRING + +When returning decimal objects in API representations that do not support a native decimal type, it is normally best to return the value as a string. This avoids the loss of precision that occurs with binary floating point implementations. + +When set to `True`, the serializer `DecimalField` class will return strings instead of `Decimal` objects. When set to `False`, serializers will return `Decimal` objects, which the default JSON encoder will return as floats. + +Default: `True` + +--- + ## View names and descriptions **The following settings are used to generate the view names and descriptions, as used in responses to `OPTIONS` requests, and as used in the browsable API.** @@ -378,4 +418,6 @@ An integer of 0 or more, that may be used to specify the number of application p Default: `None` [cite]: http://www.python.org/dev/peps/pep-0020/ +[rfc4627]: http://www.ietf.org/rfc/rfc4627.txt +[heroku-minified-json]: https://github.com/interagent/http-api-design#keep-json-minified-in-all-responses [strftime]: http://docs.python.org/2/library/time.html#time.strftime -- cgit v1.2.3 From 4fceceae7d1abf4d841677daee2636273ff09de8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 12 Sep 2014 20:09:08 +0100 Subject: DecimalField documentation --- docs/api-guide/fields.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index bfbff2ad..f0778318 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -274,7 +274,27 @@ Corresponds to `django.db.models.fields.FloatField`. ## DecimalField -A decimal representation. +A decimal representation, represented in Python by a Decimal instance. + +Has two required arguments: + +- `max_digits` The maximum number of digits allowed in the number. Note that this number must be greater than or equal to decimal_places. + +- `decimal_places` The number of decimal places to store with the number. + +For example, to validate numbers up to 999 with a resolution of 2 decimal places, you would use: + + serializers.DecimalField(max_digits=5, decimal_places=2) + +And to validate numbers up to anything lesss than one billion with a resolution of 10 decimal places: + + serializers.DecimalField(max_digits=19, decimal_places=10) + +This field also takes an optional argument, `coerce_to_string`. If set to `True` the representation will be output as a string. If set to `False` the representation will be left as a `Decimal` instance and the final representation will be determined by the renderer. + +If unset, this will default to the same value as the `COERCE_DECIMAL_TO_STRING` setting, which is `True` unless set otherwise. + +**Signature:** `DecimalField(max_digits, decimal_places, coerce_to_string=None)` Corresponds to `django.db.models.fields.DecimalField`. -- cgit v1.2.3 From 96c21b81f5031a81b42b89371af48677081a6323 Mon Sep 17 00:00:00 2001 From: José Padilla Date: Sat, 13 Sep 2014 13:53:40 -0400 Subject: Add Third Party Resources Topic section --- docs/index.md | 4 +- docs/template.html | 1 + docs/topics/third-party-resources.md | 87 ++++++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 docs/topics/third-party-resources.md (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 1888bfe4..6dcb962f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -195,6 +195,7 @@ General guides to using REST framework. * [Browser enhancements][browser-enhancements] * [The Browsable API][browsableapi] * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] +* [Third Party Resources][third-party-resources] * [Contributing to REST framework][contributing] * [2.0 Announcement][rest-framework-2-announcement] * [2.2 Announcement][2.2-announcement] @@ -312,11 +313,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [browsableapi]: topics/browsable-api.md [rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md [contributing]: topics/contributing.md +[third-party-resources]: topics/third-party-resources.md [rest-framework-2-announcement]: topics/rest-framework-2-announcement.md [2.2-announcement]: topics/2.2-announcement.md [2.3-announcement]: topics/2.3-announcement.md [2.4-announcement]: topics/2.4-announcement.md -[kickstarter-announcement]: topics/kickstarter-announcement.md +[kickstarter-announcement]: topics/kickstarter-announcement.md [release-notes]: topics/release-notes.md [credits]: topics/credits.md diff --git a/docs/template.html b/docs/template.html index 19542bfe..bb3ae221 100644 --- a/docs/template.html +++ b/docs/template.html @@ -117,6 +117,7 @@ a.fusion-poweredby {
  • Browser enhancements
  • The Browsable API
  • REST, Hypermedia & HATEOAS
    • +
  • Third Party Resources
  • Contributing to REST framework
  • 2.0 Announcement
  • 2.2 Announcement
    • diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md new file mode 100644 index 00000000..da92eb33 --- /dev/null +++ b/docs/topics/third-party-resources.md @@ -0,0 +1,87 @@ +# Third Party Resources + +Django REST Framework has a growing community of developers, packages, and resources. + +Check out a grid detailing all the packages and ecosystem around Django REST Framework at [Django Packages](https://www.djangopackages.com/grids/g/django-rest-framework/). + +## Libraries and Extensions + +### Authentication + +* [djangorestframework-digestauth](https://github.com/juanriaza/django-rest-framework-digestauth) - Provides Digest Access Authentication support. +* [django-oauth-toolkit](https://github.com/evonove/django-oauth-toolkit) - Provides OAuth 2.0 support. +* [doac](https://github.com/Rediker-Software/doac) - Provides OAuth 2.0 support. +* [djangorestframework-jwt](https://github.com/GetBlimp/django-rest-framework-jwt) - Provides JSON Web Token Authentication support. +* [hawkrest](https://github.com/kumar303/hawkrest) - Provides Hawk HTTP Authorization. +* [djangorestframework-httpsignature](https://github.com/etoccalino/django-rest-framework-httpsignature) - Provides an easy to use HTTP Signature Authentication mechanism. + +### Permissions + +* [drf-any-permissions](https://github.com/kevin-brown/drf-any-permissions) - Provides alternative permission handling. +* [djangorestframework-composed-permissions](https://github.com/niwibe/djangorestframework-composed-permissions) - Provides a simple way to define complex permissions. +* [rest_condition](https://github.com/caxap/rest_condition) - Another extension for building complex permissions in a simple and convenient way. + +### Serializers + +* [django-rest-framework-mongoengine](https://github.com/umutbozkurt/django-rest-framework-mongoengine) - Serializer class that supports using MongoDB as the storage layer for Django REST framework. +* [djangorestframework-gis](https://github.com/djangonauts/django-rest-framework-gis) - Geographic add-ons +* [djangorestframework-hstore](https://github.com/djangonauts/django-rest-framework-hstore) - Serializer class to support django-hstore DictionaryField model field and its schema-mode feature. + +### Serializer fields + +* [drf-compound-fields](https://github.com/estebistec/drf-compound-fields) - Provides "compound" serializer fields, such as lists of simple values. +* [django-extra-fields](https://github.com/Hipo/drf-extra-fields) - Provides extra serializer fields. + +### Views + +* [djangorestframework-bulk](https://github.com/miki725/django-rest-framework-bulk) - Implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. + +### Routers + +* [drf-nested-routers](https://github.com/alanjds/drf-nested-routers) - Provides routers and relationship fields for working with nested resources. + +### Parsers + +* [djangorestframework-msgpack](https://github.com/juanriaza/django-rest-framework-msgpack) - Provides MessagePack renderer and parser support. +* [djangorestframework-camel-case](https://github.com/vbabiy/djangorestframework-camel-case) - Provides camel case JSON renderers and parsers. + +### Renderers + +* [djangorestframework-csv](https://github.com/mjumbewu/django-rest-framework-csv) - Provides CSV renderer support. +* [drf_ujson](https://github.com/gizmag/drf-ujson-renderer) - Implements JSON rendering using the UJSON package. + +### Filtering + +* [djangorestframework-chain](https://github.com/philipn/django-rest-framework-chain) - Allows arbitrary chaining of both relations and lookup filters. + +### Misc + +* [djangorestrelationalhyperlink](https://github.com/fredkingham/django_rest_model_hyperlink_serializers_project) - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer. +* [django-rest-swagger](https://github.com/marcgibbons/django-rest-swagger) - An API documentation generator for Swagger UI. +* [django-rest-framework-proxy ](https://github.com/eofs/django-rest-framework-proxy) - Proxy to redirect incoming request to another API server. +* [gaiarestframework](https://github.com/AppsFuel/gaiarestframework) - Utils for django-rest-framewok +* [drf-extensions](https://github.com/chibisov/drf-extensions) - A collection of custom extensions +* [ember-data-django-rest-adapter](https://github.com/toranb/ember-data-django-rest-adapter) - An ember-data adapter + +## Tutorials + +* [Beginner's Guide to the Django Rest Framework](http://code.tutsplus.com/tutorials/beginners-guide-to-the-django-rest-framework--cms-19786) +* [Getting Started with Django Rest Framework and AngularJS](http://blog.kevinastone.com/getting-started-with-django-rest-framework-and-angularjs.html) +* [End to end web app with Django-Rest-Framework & AngularJS](http://blog.mourafiq.com/post/55034504632/end-to-end-web-app-with-django-rest-framework) +* [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/) +* [Django Rest Framework User Endpoint](http://richardtier.com/2014/02/25/django-rest-framework-user-endpoint/) +* [Check credentials using Django Rest Framework](http://richardtier.com/2014/03/06/110/) + +## Videos + +* [Ember and Django Part 1 (Video)](http://www.neckbeardrepublic.com/screencasts/ember-and-django-part-1) +* [Django Rest Framework Part 1 (Video)](http://www.neckbeardrepublic.com/screencasts/django-rest-framework-part-1) +* [Pyowa July 2013 - Django Rest Framework (Video)](http://www.youtube.com/watch?v=E1ZrehVxpBo) +* [django-rest-framework and angularjs (Video)](http://www.youtube.com/watch?v=Q8FRBGTJ020) + +## Articles + +* [Web API performance: profiling Django REST framework](http://dabapps.com/blog/api-performance-profiling-django-rest-framework/) +* [API Development with Django and Django REST Framework](https://bnotions.com/api-development-with-django-and-django-rest-framework/) -- cgit v1.2.3 From 4871dbdc73632be4fb00befbc816bc670bb609cc Mon Sep 17 00:00:00 2001 From: José Padilla Date: Sat, 13 Sep 2014 16:20:37 -0400 Subject: Add invitation to add new content --- docs/topics/third-party-resources.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md index da92eb33..2df13ef8 100644 --- a/docs/topics/third-party-resources.md +++ b/docs/topics/third-party-resources.md @@ -4,6 +4,8 @@ Django REST Framework has a growing community of developers, packages, and resou Check out a grid detailing all the packages and ecosystem around Django REST Framework at [Django Packages](https://www.djangopackages.com/grids/g/django-rest-framework/). +To submit new content, [open an issue](https://github.com/tomchristie/django-rest-framework/issues/new) or [create a pull request](https://github.com/tomchristie/django-rest-framework/). Pull requests will be given higher priority since they are easier to include. + ## Libraries and Extensions ### Authentication -- cgit v1.2.3 From 915dfb9b3d6c235437a6459493cf26d248022e75 Mon Sep 17 00:00:00 2001 From: José Padilla Date: Sun, 14 Sep 2014 10:19:54 -0400 Subject: Update third-party-resources.md --- docs/topics/third-party-resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md index 2df13ef8..e337cbd5 100644 --- a/docs/topics/third-party-resources.md +++ b/docs/topics/third-party-resources.md @@ -4,7 +4,7 @@ Django REST Framework has a growing community of developers, packages, and resou Check out a grid detailing all the packages and ecosystem around Django REST Framework at [Django Packages](https://www.djangopackages.com/grids/g/django-rest-framework/). -To submit new content, [open an issue](https://github.com/tomchristie/django-rest-framework/issues/new) or [create a pull request](https://github.com/tomchristie/django-rest-framework/). Pull requests will be given higher priority since they are easier to include. +To submit new content, [open an issue](https://github.com/tomchristie/django-rest-framework/issues/new) or [create a pull request](https://github.com/tomchristie/django-rest-framework/). ## Libraries and Extensions -- cgit v1.2.3 From 3725a1e77dafef4c6bdb7847bace92ff61f7f4e5 Mon Sep 17 00:00:00 2001 From: S. Andrew Sheppard Date: Mon, 15 Sep 2014 14:46:09 -0500 Subject: add wq.db router and django-rest-pandas renderers --- docs/topics/third-party-resources.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/topics/third-party-resources.md b/docs/topics/third-party-resources.md index e337cbd5..1ca91742 100644 --- a/docs/topics/third-party-resources.md +++ b/docs/topics/third-party-resources.md @@ -41,6 +41,7 @@ To submit new content, [open an issue](https://github.com/tomchristie/django-res ### Routers * [drf-nested-routers](https://github.com/alanjds/drf-nested-routers) - Provides routers and relationship fields for working with nested resources. +* [wq.db.rest](http://wq.io/docs/about-rest) - Provides an admin-style model registration API with reasonable default URLs and viewsets. ### Parsers @@ -51,6 +52,7 @@ To submit new content, [open an issue](https://github.com/tomchristie/django-res * [djangorestframework-csv](https://github.com/mjumbewu/django-rest-framework-csv) - Provides CSV renderer support. * [drf_ujson](https://github.com/gizmag/drf-ujson-renderer) - Implements JSON rendering using the UJSON package. +* [Django REST Pandas](https://github.com/wq/django-rest-pandas) - Pandas DataFrame-powered renderers including Excel, CSV, and SVG formats. ### Filtering -- cgit v1.2.3 From e5af0bbb353e772473b1d9fcfc896bfd7365db2a Mon Sep 17 00:00:00 2001 From: Matthew J Morrison Date: Wed, 17 Sep 2014 07:49:54 -0500 Subject: Clarify "raised inside REST framework" I ran into an issue today where I was not seeing the rest_framework.views.exception_handler do what I thought it should be doing. It turned out that I had imported View from rest_framework.views rather than importing APIView from rest_framework.views. The phrase "raised inside REST framework" was confusing as I was debugging this issue. I was unsure if that meant that I could raise those exceptions in my code or if it had to originate from within framework code. I'm not sure if the proposed wording is ideal, I just wanted to point out what I found to be confusing.--- docs/api-guide/exceptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index 66e18173..33c4dc91 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -84,7 +84,7 @@ Note that the exception handler will only be called for responses generated by r **Signature:** `APIException()` -The **base class** for all exceptions raised inside REST framework. +The **base class** for all exceptions raised inside an APIView class or @api_view. To provide a custom exception, subclass `APIException` and set the `.status_code` and `.default_detail` properties on the class. -- cgit v1.2.3 From 764366b2e11ad9ad85dd34500e95721011cae7d4 Mon Sep 17 00:00:00 2001 From: Matthew J Morrison Date: Wed, 17 Sep 2014 11:29:15 -0500 Subject: Fixed code formatting --- docs/api-guide/exceptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index 33c4dc91..e61dcfa9 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -84,7 +84,7 @@ Note that the exception handler will only be called for responses generated by r **Signature:** `APIException()` -The **base class** for all exceptions raised inside an APIView class or @api_view. +The **base class** for all exceptions raised inside an `APIView` class or `@api_view`. To provide a custom exception, subclass `APIException` and set the `.status_code` and `.default_detail` properties on the class. -- cgit v1.2.3 From 6d73b5969a9d415a6d43175e77bc10ba76151e97 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 19 Sep 2014 14:02:17 +0100 Subject: Initial release notes --- docs/topics/3.0-announcement.md | 239 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 docs/topics/3.0-announcement.md (limited to 'docs') diff --git a/docs/topics/3.0-announcement.md b/docs/topics/3.0-announcement.md new file mode 100644 index 00000000..029d9896 --- /dev/null +++ b/docs/topics/3.0-announcement.md @@ -0,0 +1,239 @@ +**THIS DOCUMENT IS CURRENTLY A WORK IN PROGRESS** + +See the [Version 3.0 GitHub issue](https://github.com/tomchristie/django-rest-framework/pull/1800) for more details. + +# REST framework 3.0 + +**Note incremental nature, discuss upgrading.** + +## Motivation + +**TODO** + +--- + +## Request objects + +#### The `request.data` property. + +**TODO** + +#### The parser API. + +**TODO** + +## Serializers + +#### Single-step object creation. + +**TODO**: Drop `.restore_object()`, use `.create()` and `.update()` which should save the instance. + +**TODO**: Drop`.object`, use `.validated_data` or get the instance with `.save()`. + +#### Always use `fields`, not `exclude`. + +The `exclude` option is no longer available. You should use the more explicit `fields` option instead. + +#### The `extra_kwargs` option. + +The `read_only_fields` and `write_only_fields` options have been removed and replaced with a more generic `extra_kwargs`. + + class MySerializer(serializer.ModelSerializer): + class Meta: + model = MyModel + fields = ('id', 'email', 'notes', 'is_admin') + extra_kwargs = { + 'is_admin': {'read_only': True} + } + +Alternatively, specify the field explicitly on the serializer class: + + class MySerializer(serializer.ModelSerializer): + is_admin = serializers.BooleanField(read_only=True) + + class Meta: + model = MyModel + fields = ('id', 'email', 'notes', 'is_admin') + +#### Changes to `HyperlinkedModelSerializer`. + +The `view_name` and `lookup_field` options have been removed. They are no longer required, as you can use the `extra_kwargs` argument instead: + + class MySerializer(serializer.HyperlinkedModelSerializer): + class Meta: + model = MyModel + fields = ('url', 'email', 'notes', 'is_admin') + extra_kwargs = { + 'url': {'lookup_field': 'uuid'} + } + +Alternatively, specify the field explicitly on the serializer class: + + class MySerializer(serializer.HyperlinkedModelSerializer): + url = serializers.HyperlinkedIdentityField( + view_name='mymodel-detail', + lookup_field='uuid' + ) + + class Meta: + model = MyModel + fields = ('url', 'email', 'notes', 'is_admin') + +#### Fields for model methods and properties. + +You can now specify field names in the `fields` option that refer to model methods or properties. For example, suppose you have the following model: + + class Invitation(models.Model): + created = models.DateTimeField() + to_email = models.EmailField() + message = models.CharField(max_length=1000) + + def expiry_date(self): + return self.created + datetime.timedelta(days=30) + +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') + +These fields will be mapped to `serializers.ReadOnlyField()` instances. + + >>> serializer = InvitationSerializer() + >>> print repr(serializer) + InvitationSerializer(): + to_email = EmailField(max_length=75) + message = CharField(max_length=1000) + expiry_date = ReadOnlyField() + + +## Serializer fields + +#### The `Field` and `ReadOnly` field classes. + +**TODO** + +#### Coercing output types. + +**TODO** + +#### The `ListSerializer` class. + +**TODO** + +#### The `MultipleChoiceField` class. + +**TODO** + +#### Changes to the custom field API. + +**TODO** `to_representation`, `to_internal_value`. + +#### Explicit `querysets` required on relational fields. + +**TODO** + +#### Optional argument to `SerializerMethodField`. + +**TODO** + +## Generic views + +#### Simplification of view logic. + +**TODO** + +#### Removal of pre/post save hooks. + +The following method hooks no longer exist on the new, simplified, generic views: `pre_save`, `post_save`, `pre_delete`, `post_delete`. + +If you do need custom behavior, you might choose to instead override the `.save()` method on your serializer class. For example: + + def save(self, *args, **kwargs): + instance = super(MySerializer).save(*args, **kwarg) + send_email(instance.to_email, instance.message) + return instance + +Alternatively write your view logic exlpicitly, or tie your pre/post save behavior into the model class or model manager. + +#### Removal of view attributes. + +The `.object` and `.object_list` attributes are no longer set on the view instance. Treating views as mutable object instances that store state during the processing of the view tends to be poor design, and can lead to obscure flow logic. + +I would personally recommend that developers treat view instances as immutable objects in their application code. + +#### PUT as create. + +**TODO** + +## API style + +There are some improvements in the default style we use in our API responses. + +#### Unicode JSON by default. + +Unicode JSON is now the default. The `UnicodeJSONRenderer` class no longer exists, and the `UNICODE_JSON` setting has been added. To revert this behavior use the new setting: + + REST_FRAMEWORK = { + 'UNICODE_JSON': False + } + +#### Compact JSON by default. + +We now output compact JSON in responses by default. For example, we return: + + {"email":"amy@example.com","is_admin":true} + +Instead of the following: + + {"email": "amy@example.com", "is_admin": true} + +The `COMPACT_JSON` setting has been added, and can be used to revert this behavior if needed: + + REST_FRAMEWORK = { + 'COMPACT_JSON': False + } + +#### Throttle headers using `Retry-After`. + +The custom `X-Throttle-Wait-Second` header has now been dropped in favor of the standard `Retry-After` header. You can revert this behavior if needed by writing a custom exception handler for your application. + +#### Date and time objects as ISO-8859-1 strings in serializer data. + +Date and Time objects are now coerced to strings by default in the serializer output. Previously they were returned as `Date`, `Time` and `DateTime` objects, and later coerced to strings by the renderer. + +You can modify this behavior globally by settings the existing `DATE_FORMAT`, `DATETIME_FORMAT` and `TIME_FORMAT` settings keys. Setting these values to `None` instead of their default value of `'iso-8859-1'` will result in native objects being returned in serializer data. + + REST_FRAMEWORK = { + # Return native `Date` and `Time` objects in `serializer.data` + 'DATETIME_FORMAT': None + 'DATE_FORMAT': None + 'TIME_FORMAT': None + } + +You can also modify serializer fields individually, using the `date_format`, `time_format` and `datetime_format` arguments: + + # Return `DateTime` instances in `serializer.data`, not strings. + created = serializers.DateTimeField(format=None) + +#### Decimals as strings in serializer data. + +Decimals are now coerced to strings by default in the serializer output. Previously they were returned as `Decimal` objects, and later coerced to strings by the renderer. + +You can modify this behavior globally by using the `COERCE_DECIMAL_TO_STRING` settings key. + + REST_FRAMEWORK = { + 'COERCE_DECIMAL_TO_STRING': False + } + +Or modify it on an individual serializer field, using the `corece_to_string` keyword argument. + + # Return `Decimal` instances in `serializer.data`, not strings. + amount = serializers.DecimalField( + max_digits=10, + decimal_places=2, + coerce_to_string=False + ) + +The default JSON renderer will return float objects for uncoerced `Decimal` instances. This allows you to easily switch between string or float representations for decimals depending on your API design needs. -- cgit v1.2.3