Hello, world
' return Response(data) @@ -300,7 +300,7 @@ The following is an example plaintext renderer that will return a response with class PlainTextRenderer(renderers.BaseRenderer): media_type = 'text/plain' format = 'txt' - + def render(self, data, media_type=None, renderer_context=None): return data.encode(self.charset) @@ -340,7 +340,7 @@ You can do some pretty flexible things using REST framework's renderers. Some e * Provide either flat or nested representations from the same endpoint, depending on the requested media type. * Serve both regular HTML webpages, and JSON based API responses from the same endpoints. * Specify multiple types of HTML representation for API clients to use. -* Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. +* Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. ## Varying behaviour by media type diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 87425ed1b..77000ffa2 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -1,4 +1,10 @@ - +source: request.py + +--- + +**Note**: This is the documentation for the **version 3.0** of REST framework. Documentation for [version 2.4](http://tomchristie.github.io/rest-framework-2-docs/) is also available. + +--- # Requests @@ -14,26 +20,29 @@ REST framework's `Request` class extends the standard `HttpRequest`, adding supp REST framework's Request objects provide flexible request parsing that allows you to treat requests with JSON data or other media types in the same way that you would normally deal with form data. -## .DATA +## .data -`request.DATA` returns the parsed content of the request body. This is similar to the standard `request.POST` attribute except that: +`request.data` returns the parsed content of the request body. This is similar to the standard `request.POST` and `request.FILES` attributes except that: +* It includes all parsed content, including *file and non-file* inputs. * It supports parsing the content of HTTP methods other than `POST`, meaning that you can access the content of `PUT` and `PATCH` requests. * It supports REST framework's flexible request parsing, rather than just supporting form data. For example you can handle incoming JSON data in the same way that you handle incoming form data. For more details see the [parsers documentation]. -## .FILES +## .query_params -`request.FILES` returns any uploaded files that may be present in the content of the request body. This is the same as the standard `HttpRequest` behavior, except that the same flexible request parsing is used for `request.DATA`. +`request.query_params` is a more correctly named synonym for `request.GET`. -For more details see the [parsers documentation]. +For clarity inside your code, we recommend using `request.query_params` instead of the Django's standard `request.GET`. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just `GET` requests. + +## .DATA and .FILES + +The old-style version 2.x `request.data` and `request.FILES` attributes are still available, but are now pending deprecation in favor of the unified `request.data` attribute. ## .QUERY_PARAMS -`request.QUERY_PARAMS` is a more correctly named synonym for `request.GET`. - -For clarity inside your code, we recommend using `request.QUERY_PARAMS` instead of the usual `request.GET`, as *any* HTTP method type may include query parameters. +The old-style version 2.x `request.QUERY_PARAMS` attribute is still available, but is now pending deprecation in favor of the more pythonic `request.query_params`. ## .parsers @@ -43,7 +52,7 @@ You won't typically need to access this property. --- -**Note:** If a client sends malformed content, then accessing `request.DATA` or `request.FILES` may raise a `ParseError`. By default REST framework's `APIView` class or `@api_view` decorator will catch the error and return a `400 Bad Request` response. +**Note:** If a client sends malformed content, then accessing `request.data` may raise a `ParseError`. By default REST framework's `APIView` class or `@api_view` decorator will catch the error and return a `400 Bad Request` response. If a client sends a request with a content-type that cannot be parsed then a `UnsupportedMediaType` exception will be raised, which by default will be caught and return a `415 Unsupported Media Type` response. @@ -105,7 +114,7 @@ REST framework supports a few browser enhancements such as browser-based `PUT`, Browser-based `PUT`, `PATCH` and `DELETE` forms are transparently supported. -For more information see the [browser enhancements documentation]. +For more information see the [browser enhancements documentation]. ## .content_type @@ -115,7 +124,7 @@ You won't typically need to directly access the request's content type, as you'l If you do need to access the content type of the request you should use the `.content_type` property in preference to using `request.META.get('HTTP_CONTENT_TYPE')`, as it provides transparent support for browser-based non-form content. -For more information see the [browser enhancements documentation]. +For more information see the [browser enhancements documentation]. ## .stream @@ -125,7 +134,7 @@ You won't typically need to directly access the request's content, as you'll nor If you do need to access the raw content directly, you should use the `.stream` property in preference to using `request.content`, as it provides transparent support for browser-based non-form content. -For more information see the [browser enhancements documentation]. +For more information see the [browser enhancements documentation]. --- diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index 5a42aa923..97f312710 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -1,4 +1,4 @@ - +source: response.py # Responses @@ -90,6 +90,6 @@ The `Response` class extends `SimpleTemplateResponse`, and all the usual attribu As with any other `TemplateResponse`, this method is called to render the serialized data of the response into the final response content. When `.render()` is called, the response content will be set to the result of calling the `.render(data, accepted_media_type, renderer_context)` method on the `accepted_renderer` instance. You won't typically need to call `.render()` yourself, as it's handled by Django's standard response cycle. - + [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/ [statuscodes]: status-codes.md diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md index 383eca4ce..71fb83f9e 100644 --- a/docs/api-guide/reverse.md +++ b/docs/api-guide/reverse.md @@ -1,4 +1,4 @@ - +source: reverse.py # Returning URLs @@ -30,7 +30,7 @@ You should **include the request as a keyword argument** to the function, for ex from rest_framework.reverse import reverse from rest_framework.views import APIView from django.utils.timezone import now - + class APIRootView(APIView): def get(self, request): year = now().year diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index 61a476b8b..080230faf 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -1,4 +1,4 @@ - +source: routers.py # Routers @@ -56,10 +56,10 @@ For example, given a method like this on the `UserViewSet` class: from myapp.permissions import IsAdminOrIsSelf from rest_framework.decorators import detail_route - + class UserViewSet(ModelViewSet): ... - + @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf]) def set_password(self, request, pk=None): ... @@ -228,7 +228,7 @@ For another example of setting the `.routes` attribute, see the source code for ## Advanced custom routers -If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method. The method should inspect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute. +If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method. The method should inspect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute. You may also want to override the `get_default_base_name(self, viewset)` method, or else always explicitly set the `base_name` argument when registering your viewsets with the router. diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index eeeffa136..0ee80d53f 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -1,4 +1,10 @@ - +source: serializers.py + +--- + +**Note**: This is the documentation for the **version 3.0** of REST framework. Documentation for [version 2.4](http://tomchristie.github.io/rest-framework-2-docs/) is also available. + +--- # Serializers @@ -10,7 +16,7 @@ will take some serious design work. Serializers allow complex data such as querysets and model instances to be converted to native Python datatypes that can then be easily rendered into `JSON`, `XML` or other content types. Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data. -REST framework's serializers work very similarly to Django's `Form` and `ModelForm` classes. It provides a `Serializer` class which gives you a powerful, generic way to control the output of your responses, as well as a `ModelSerializer` class which provides a useful shortcut for creating serializers that deal with model instances and querysets. +The serializers in REST framework work very similarly to Django's `Form` and `ModelForm` classes. We provide a `Serializer` class which gives you a powerful, generic way to control the output of your responses, as well as a `ModelSerializer` class which provides a useful shortcut for creating serializers that deal with model instances and querysets. ## Declaring Serializers @@ -21,10 +27,10 @@ Let's start by creating a simple object we can use for example purposes: self.email = email self.content = content self.created = created or datetime.datetime.now() - + comment = Comment(email='leila@example.com', content='foo bar') -We'll declare a serializer that we can use to serialize and deserialize `Comment` objects. +We'll declare a serializer that we can use to serialize and deserialize data that corresponds to `Comment` objects. Declaring a serializer looks very similar to declaring a form: @@ -35,25 +41,9 @@ Declaring a serializer looks very similar to declaring a form: content = serializers.CharField(max_length=200) created = serializers.DateTimeField() - def restore_object(self, attrs, instance=None): - """ - Given a dictionary of deserialized field values, either update - an existing model instance, or create a new model instance. - """ - if instance is not None: - instance.email = attrs.get('email', instance.email) - instance.content = attrs.get('content', instance.content) - instance.created = attrs.get('created', instance.created) - return instance - return Comment(**attrs) - -The first part of serializer class defines the fields that get serialized/deserialized. The `restore_object` method defines how fully fledged instances get created when deserializing data. - -The `restore_object` method is optional, and is only required if we want our serializer to support deserialization into fully fledged object instances. If we don't define this method, then deserializing data will simply return a dictionary of items. - ## Serializing objects -We can now use `CommentSerializer` to serialize a comment, or list of comments. Again, using the `Serializer` class looks a lot like using a `Form` class. +We can now use `CommentSerializer` to serialize a comment, or list of comments. Again, using the `Serializer` class looks a lot like using a `Form` class. serializer = CommentSerializer(comment) serializer.data @@ -67,24 +57,9 @@ At this point we've translated the model instance into Python native datatypes. json # '{"email": "leila@example.com", "content": "foo bar", "created": "2012-08-22T16:20:09.822"}' -### Customizing field representation - -Sometimes when serializing objects, you may not want to represent everything exactly the way it is in your model. - -If you need to customize the serialized value of a particular field, you can do this by creating a `transform_
-
Django REST framework is a powerful and flexible toolkit that makes it easy to build Web APIs.
@@ -204,6 +203,7 @@ General guides to using REST framework.
* [2.2 Announcement][2.2-announcement]
* [2.3 Announcement][2.3-announcement]
* [2.4 Announcement][2.4-announcement]
+* [3.0 Announcement][3.0-announcement]
* [Kickstarter Announcement][kickstarter-announcement]
* [Release Notes][release-notes]
* [Credits][credits]
@@ -297,7 +297,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[serializers]: api-guide/serializers.md
[fields]: api-guide/fields.md
[relations]: api-guide/relations.md
-[validation]: api-guide/validation.md
+[validators]: api-guide/validators.md
[authentication]: api-guide/authentication.md
[permissions]: api-guide/permissions.md
[throttling]: api-guide/throttling.md
@@ -322,6 +322,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[2.2-announcement]: topics/2.2-announcement.md
[2.3-announcement]: topics/2.3-announcement.md
[2.4-announcement]: topics/2.4-announcement.md
+[3.0-announcement]: topics/3.0-announcement.md
[kickstarter-announcement]: topics/kickstarter-announcement.md
[release-notes]: topics/release-notes.md
[credits]: topics/credits.md
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index a91fb9785..000000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1 +0,0 @@
-markdown>=2.1.0
diff --git a/docs/template.html b/docs/template.html
deleted file mode 100644
index f36cffc6d..000000000
--- a/docs/template.html
+++ /dev/null
@@ -1,239 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md
index a997c7829..1df52cff2 100644
--- a/docs/topics/2.2-announcement.md
+++ b/docs/topics/2.2-announcement.md
@@ -42,7 +42,7 @@ The 2.2 release makes a few changes to the API, in order to make it more consist
The `ManyRelatedField()` style is being deprecated in favor of a new `RelatedField(many=True)` syntax.
-For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following:
+For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following:
class UserSerializer(serializers.HyperlinkedModelSerializer):
questions = serializers.PrimaryKeyRelatedField(many=True)
@@ -58,10 +58,10 @@ The change also applies to serializers. If you have a nested serializer, you sh
class Meta:
model = Track
fields = ('name', 'duration')
-
+
class AlbumSerializer(serializer.ModelSerializer):
tracks = TrackSerializer(many=True)
-
+
class Meta:
model = Album
fields = ('album_name', 'artist', 'tracks')
@@ -87,7 +87,7 @@ For example, is a user account has an optional foreign key to a company, that yo
This is in line both with the rest of the serializer fields API, and with Django's `Form` and `ModelForm` API.
-Using `required` throughout the serializers API means you won't need to consider if a particular field should take `blank` or `null` arguments instead of `required`, and also means there will be more consistent behavior for how fields are treated when they are not present in the incoming data.
+Using `required` throughout the serializers API means you won't need to consider if a particular field should take `blank` or `null` arguments instead of `required`, and also means there will be more consistent behavior for how fields are treated when they are not present in the incoming data.
The `null=True` argument will continue to function, and will imply `required=False`, but will raise a `PendingDeprecationWarning`.
diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md
index 7c800afa0..9c9f3e9f6 100644
--- a/docs/topics/2.3-announcement.md
+++ b/docs/topics/2.3-announcement.md
@@ -27,7 +27,7 @@ As an example of just how simple REST framework APIs can now be, here's an API w
class GroupViewSet(viewsets.ModelViewSet):
model = Group
-
+
# Routers provide an easy way of automatically determining the URL conf
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
@@ -197,13 +197,13 @@ Usage of the old-style attributes continues to be supported, but will raise a `P
For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering `Decimal` instances to your renderer implementation.
-## ModelSerializers and reverse relationships
+## ModelSerializers and reverse relationships
The support for adding reverse relationships to the `fields` option on a `ModelSerializer` class means that the `get_related_field` and `get_nested_field` method signatures have now changed.
In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now `(self, model_field, related_model, to_many)`. For reverse relationships `model_field` will be `None`.
-The old-style signature will continue to function but will raise a `PendingDeprecationWarning`.
+The old-style signature will continue to function but will raise a `PendingDeprecationWarning`.
## View names and descriptions
@@ -211,7 +211,7 @@ The mechanics of how the names and descriptions used in the browseable API are g
If you've been customizing this behavior, for example perhaps to use `rst` markup for the browseable API, then you'll need to take a look at the implementation to see what updates you need to make.
-Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated.
+Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated.
---
diff --git a/docs/topics/3.0-announcement.md b/docs/topics/3.0-announcement.md
index 694ad8a5c..8791ad089 100644
--- a/docs/topics/3.0-announcement.md
+++ b/docs/topics/3.0-announcement.md
@@ -1,27 +1,17 @@
-## Pre-release notes:
-
-The 3.0 release is now in beta and ready for final testing. You can install the development version directly from GitHub like so:
-
- pip install https://github.com/tomchristie/django-rest-framework/archive/3.0-beta.zip
-
-Currently the only known remaining blockers are documentation issues and tickets. Any critical bugs raised in the next week or two will be resolved for the 3.0 release, but otherwise consider this as code-complete.
-
-Please work through this document throughly in order to understand the API differences that exist between 2.4 and 3.0.
-
-**Your feedback on the upgrade process and 3.0 changes is hugely important!**
-
-Please do get in touch via twitter, IRC, a GitHub ticket, or the discussion group.
-
----
-
-# REST framework 3.0
+# Django REST framework 3.0
The 3.0 release of Django REST framework is the result of almost four years of iteration and refinement. It comprehensively addresses some of the previous remaining design issues in serializers, fields and the generic views.
-This release is incremental in nature. There *are* some breaking API changes, and upgrading *will* require you to read the release notes carefully, but the migration path should otherwise be relatively straightforward.
+**This release is incremental in nature. There *are* some breaking API changes, and upgrading *will* require you to read the release notes carefully, but the migration path should otherwise be relatively straightforward.**
The difference in quality of the REST framework API and implementation should make writing, maintaining and debugging your application far easier.
+3.0 is the first of three releases that have been funded by our recent [Kickstarter campaign][kickstarter].
+
+As ever, a huge thank you to our many [wonderful sponsors][sponsors]. If you're looking for a Django gig, and want to work with smart community-minded folks, you should probably check out that list and see who's hiring.
+
+---
+
## New features
Notable features of this new release include:
@@ -63,6 +53,8 @@ Instead of passing the files argument separately:
The usage of `request.QUERY_PARAMS` is now pending deprecation in favor of the lowercased `request.query_params`.
+---
+
## Serializers
#### Single-step object creation.
@@ -161,7 +153,7 @@ Previously `serializers.ValidationError` error was simply a synonym for `django.
The reason behind this is that Django's `ValidationError` class is intended for use with HTML forms and its API makes using it slightly awkward with nested validation errors that can occur in serializers.
-For most users this change shouldn't require any updates to your codebase, but it is worth ensuring that whenever raising validation errors you are always using the `serializers.ValidationError` exception class, and not Django's built-in exception.
+For most users this change shouldn't require any updates to your codebase, but it is worth ensuring that whenever raising validation errors you should prefer using the `serializers.ValidationError` exception class, and not Django's built-in exception.
We strongly recommend that you use the namespaced import style of `import serializers` and not `from serializers import ValidationError` in order to avoid any potential confusion.
@@ -170,7 +162,7 @@ We strongly recommend that you use the namespaced import style of `import serial
The `validate_
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- {{ content }}
-
- -
-
- Divio -
- Lulu -
- Potato -
- Wiredrive -
- Cyan -
- Runscope -
- Simple Energy -
- VOKAL Interactive -
- Purple Bit -
- KuwaitNET +
- Divio +
- Lulu +
- Potato +
- Wiredrive +
- Cyan +
- Runscope +
- Simple Energy +
- VOKAL Interactive +
- Purple Bit +
- KuwaitNET
-
-
- LaterPay -
- Schuberg Philis -
- ProReNata AB -
- SGA Websites -
- Sirono -
- Vinta Software Studio -
- Rapasso -
- Mirus Research -
- Hipo -
- Byte -
- Lightning Kite -
- Opbeat -
- Koordinates -
- Pulsecode Inc. -
- Singing Horse Studio Ltd. -
- Heroku -
- Galileo Press -
- Security Compass -
- Django Software Foundation -
- Hipflask -
- Crate -
- Cryptico Corp -
- NextHub -
- Compile -
- WusaWork +
- LaterPay +
- Schuberg Philis +
- ProReNata AB +
- SGA Websites +
- Sirono +
- Vinta Software Studio +
- Rapasso +
- Mirus Research +
- Hipo +
- Byte +
- Lightning Kite +
- Opbeat +
- Koordinates +
- Pulsecode Inc. +
- Singing Horse Studio Ltd. +
- Heroku +
- Galileo Press +
- Security Compass +
- Django Software Foundation +
- Hipflask +
- Crate +
- Cryptico Corp +
- NextHub +
- Compile +
- WusaWork
- Envision Linux
-
-
- IMT Computer Services -
- Wildfish -
- Thermondo GmbH -
- Providenz -
- alwaysdata.com -
- Triggered Messaging -
- PushPull Technology Ltd -
- Transcode -
- Garfo -
- Shippo -
- Gizmag -
- Tivix -
- Safari -
- Bright Loop -
- ABA Systems -
- beefarm.ru -
- Vzzual.com -
- Infinite Code -
- Crossword Tracker -
- PkgFarm -
- Life. The Game. -
- Blimp -
- Pathwright -
- Fluxility -
- Teonite -
- TrackMaven -
- Phurba -
- Nephila -
- Aditium -
- OpenEye Scientific Software -
- Holvi -
- Cantemo -
- MakeSpace -
- AX Semantics -
- ISL +
- IMT Computer Services +
- Wildfish +
- Thermondo GmbH +
- Providenz +
- alwaysdata.com +
- Triggered Messaging +
- PushPull Technology Ltd +
- Transcode +
- Garfo +
- Shippo +
- Gizmag +
- Tivix +
- Safari +
- Bright Loop +
- ABA Systems +
- beefarm.ru +
- Vzzual.com +
- Infinite Code +
- Crossword Tracker +
- PkgFarm +
- Life. The Game. +
- Blimp +
- Pathwright +
- Fluxility +
- Teonite +
- TrackMaven +
- Phurba +
- Nephila +
- Aditium +
- OpenEye Scientific Software +
- Holvi +
- Cantemo +
- MakeSpace +
- AX Semantics +
- ISL
-
-
-
+
+
-
-
-