Skip to content

Commit 58d38d6

Browse files
lovelydinosaurlovelydinosaur
committed
Merge branch 'master' into writable-nested-modelserializer
2 parents de00ec9 + 1f6a59d commit 58d38d6

38 files changed

+574
-176
lines changed

‎README.md

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ Django REST framework is a powerful and flexible toolkit that makes it easy to b
1212

1313
Some reasons you might want to use REST framework:
1414

15-
* The Web browseable API is a huge useability win for your developers.
16-
* Authentication policies including OAuth1a and OAuth2 out of the box.
17-
* Serialization that supports both ORM and non-ORM data sources.
18-
* Customizable all the way down - just use regular function-based views if you don't need the more powerful features.
19-
* Extensive documentation, and great community support.
15+
* The [Web browseable API][sandbox] is a huge useability win for your developers.
16+
* [Authentication policies][authentication] including [OAuth1a][oauth1-section] and [OAuth2][oauth2-section] out of the box.
17+
* [Serialization][serializers] that supports both [ORM][modelserializer-section] and [non-ORM][serializer-section] data sources.
18+
* Customizable all the way down - just use [regular function-based views][functionview-section] if you don't need the [more][generic-views] [powerful][viewsets] [features][routers].
19+
* [Extensive documentation][index], and [great community support][group].
2020

2121
There is a live example API for testing purposes, [available here][sandbox].
2222

@@ -139,6 +139,19 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
139139
[group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework
140140
[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X
141141
[sandbox]: http://restframework.herokuapp.com/
142+
143+
[index]: http://django-rest-framework.org/
144+
[oauth1-section]: http://django-rest-framework.org/api-guide/authentication.html#oauthauthentication
145+
[oauth2-section]: http://django-rest-framework.org/api-guide/authentication.html#oauth2authentication
146+
[serializer-section]: http://django-rest-framework.org/api-guide/serializers.html#serializers
147+
[modelserializer-section]: http://django-rest-framework.org/api-guide/serializers.html#modelserializer
148+
[functionview-section]: http://django-rest-framework.org/api-guide/views.html#function-based-views
149+
[generic-views]: http://django-rest-framework.org/api-guide/generic-views.html
150+
[viewsets]: http://django-rest-framework.org/api-guide/viewsets.html
151+
[routers]: http://django-rest-framework.org/api-guide/routers.html
152+
[serializers]: http://django-rest-framework.org/api-guide/serializers.html
153+
[authentication]: http://django-rest-framework.org/api-guide/authentication.html
154+
142155
[rest-framework-2-announcement]: http://django-rest-framework.org/topics/rest-framework-2-announcement.html
143156
[2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion
144157
[image]: http://django-rest-framework.org/img/quickstart.png

‎docs/api-guide/authentication.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,10 @@ The command line to test the authentication looks like:
303303

304304
curl -H "Authorization: Bearer <your-access-token>" http://localhost:8000/api/
305305

306+
### Alternative OAuth 2 implementations
307+
308+
Note that [Django OAuth Toolkit][django-oauth-toolkit] is an alternative external package that also includes OAuth 2.0 support for REST framework.
309+
306310
---
307311

308312
# Custom authentication
@@ -347,6 +351,10 @@ The following third party packages are also available.
347351

348352
HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. [Juan Riaza][juanriaza] maintains the [djangorestframework-digestauth][djangorestframework-digestauth] package which provides HTTP digest authentication support for REST framework.
349353

354+
## Django OAuth Toolkit
355+
356+
The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by [Evonove][evonove] and uses the excelllent [OAuthLib][oauthlib]. The package is well documented, and comes as a recommended alternative for OAuth 2.0 support.
357+
350358
[cite]: http://jacobian.org/writing/rest-worst-practices/
351359
[http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2
352360
[http403]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4
@@ -365,3 +373,6 @@ HTTP digest authentication is a widely implemented scheme that was intended to r
365373
[django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider
366374
[django-oauth2-provider-docs]: https://django-oauth2-provider.readthedocs.org/en/latest/
367375
[rfc6749]: http://tools.ietf.org/html/rfc6749
376+
[django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit
377+
[evonove]: https://github.com/evonove/
378+
[oauthlib]: https://github.com/idan/oauthlib

‎docs/api-guide/fields.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -214,10 +214,10 @@ In the case of JSON this means the default datetime representation uses the [ECM
214214

215215
**Signature:** `DateTimeField(format=None, input_formats=None)`
216216

217-
* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that python `datetime` objects should be returned by `to_native`. In this case the datetime encoding will be determined by the renderer.
217+
* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `datetime` objects should be returned by `to_native`. In this case the datetime encoding will be determined by the renderer.
218218
* `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
219219

220-
DateTime format strings may either be [python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)
220+
DateTime format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`)
221221

222222
## DateField
223223

@@ -227,10 +227,10 @@ Corresponds to `django.db.models.fields.DateField`
227227

228228
**Signature:** `DateField(format=None, input_formats=None)`
229229

230-
* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that python `date` objects should be returned by `to_native`. In this case the date encoding will be determined by the renderer.
230+
* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `date` objects should be returned by `to_native`. In this case the date encoding will be determined by the renderer.
231231
* `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATE_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
232232

233-
Date format strings may either be [python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`)
233+
Date format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`)
234234

235235
## TimeField
236236

@@ -242,10 +242,10 @@ Corresponds to `django.db.models.fields.TimeField`
242242

243243
**Signature:** `TimeField(format=None, input_formats=None)`
244244

245-
* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that python `time` objects should be returned by `to_native`. In this case the time encoding will be determined by the renderer.
245+
* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `time` objects should be returned by `to_native`. In this case the time encoding will be determined by the renderer.
246246
* `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `TIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`.
247247

248-
Time format strings may either be [python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`)
248+
Time format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`)
249249

250250
## IntegerField
251251

‎docs/api-guide/generic-views.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ The following attributes control the basic view behavior.
6060

6161
* `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.
6262
* `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.
63-
* `lookup_field` - The field that should be used to lookup individual model instances. Defaults to `'pk'`. The URL conf should include a keyword argument corresponding to this value. More complex lookup styles can be supported by overriding the `get_object()` method.
63+
* `lookup_field` - The field that should be used to lookup individual model instances. Defaults to `'pk'`. The URL conf should include a keyword argument corresponding to this value. More complex lookup styles can be supported by overriding the `get_object()` method. Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes use lookup fields that correctly correspond with the URL conf.
6464

6565
**Shortcuts**:
6666

@@ -92,7 +92,8 @@ May be overridden to provide dynamic behavior such as returning a queryset that
9292
For example:
9393

9494
def get_queryset(self):
95-
return self.user.accounts.all()
95+
user = self.request.user
96+
return user.accounts.all()
9697

9798
#### `get_object(self)`
9899

@@ -131,7 +132,7 @@ You may want to override this method to provide more complex behavior such as mo
131132
For example:
132133

133134
def get_paginate_by(self):
134-
self.request.accepted_renderer.format == 'html':
135+
if self.request.accepted_renderer.format == 'html':
135136
return 20
136137
return 100
137138

‎docs/api-guide/responses.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88
99
REST framework supports HTTP content negotiation by providing a `Response` class which allows you to return content that can be rendered into multiple content types, depending on the client request.
1010

11-
The `Response` class subclasses Django's `SimpleTemplateResponse`. `Response` objects are initialised with data, which should consist of native python primatives. REST framework then uses standard HTTP content negotiation to determine how it should render the final response content.
11+
The `Response` class subclasses Django's `SimpleTemplateResponse`. `Response` objects are initialised with data, which should consist of native Python primitives. REST framework then uses standard HTTP content negotiation to determine how it should render the final response content.
1212

13-
There's no requirement for you to use the `Response` class, you can also return regular `HttpResponse` objects from your views if you want, but it provides a nicer interface for returning Web API responses.
13+
There's no requirement for you to use the `Response` class, you can also return regular `HttpResponse` or `StreamingHttpResponse` objects from your views if required. Using the `Response` class simply provides a nicer interface for returning content-negotiated Web API responses, that can be rendered to multiple formats.
1414

1515
Unless you want to heavily customize REST framework for some reason, you should always use an `APIView` class or `@api_view` function for views that return `Response` objects. Doing so ensures that the view can perform content negotiation and select the appropriate renderer for the response, before it is returned from the view.
1616

@@ -22,7 +22,7 @@ Unless you want to heavily customize REST framework for some reason, you should
2222

2323
**Signature:** `Response(data, status=None, template_name=None, headers=None, content_type=None)`
2424

25-
Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content. Instead you pass in unrendered data, which may consist of any python primatives.
25+
Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content. Instead you pass in unrendered data, which may consist of any Python primitives.
2626

2727
The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primative datatypes before creating the `Response` object.
2828

‎docs/api-guide/routers.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ There are two mandatory arguments to the `register()` method:
2626

2727
Optionally, you may also specify an additional argument:
2828

29-
* `base_name` - The base to use for the URL names that are created. If unset the basename will be automatically generated based on the `model` or `queryset` attribute on the viewset, if it has one.
29+
* `base_name` - The base to use for the URL names that are created. If unset the basename will be automatically generated based on the `model` or `queryset` attribute on the viewset, if it has one. Note that if the viewset does not include a `model` or `queryset` attribute then you must set `base_name` when registering the viewset.
3030

3131
The example above would generate the following URL patterns:
3232

‎docs/api-guide/serializers.md

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ will take some serious design work.
88
>
99
> &mdash; Russell Keith-Magee, [Django users group][cite]
1010
11-
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.
11+
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.
1212

1313
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.
1414

@@ -39,7 +39,7 @@ Declaring a serializer looks very similar to declaring a form:
3939
an existing model instance, or create a new model instance.
4040
"""
4141
if instance is not None:
42-
instance.title = attrs.get('title', instance.title)
42+
instance.email = attrs.get('email', instance.email)
4343
instance.content = attrs.get('content', instance.content)
4444
instance.created = attrs.get('created', instance.created)
4545
return instance
@@ -57,15 +57,15 @@ We can now use `CommentSerializer` to serialize a comment, or list of comments.
5757
serializer.data
5858
# {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)}
5959

60-
At this point we've translated the model instance into python native datatypes. To finalise the serialization process we render the data into `json`.
60+
At this point we've translated the model instance into Python native datatypes. To finalise the serialization process we render the data into `json`.
6161

6262
json = JSONRenderer().render(serializer.data)
6363
json
6464
# '{"email": "leila@example.com", "content": "foo bar", "created": "2012-08-22T16:20:09.822"}'
6565

6666
## Deserializing objects
6767
68-
Deserialization is similar. First we parse a stream into python native datatypes...
68+
Deserialization is similar. First we parse a stream into Python native datatypes...
6969

7070
stream = StringIO(json)
7171
data = JSONParser().parse(stream)
@@ -387,14 +387,16 @@ There needs to be a way of determining which views should be used for hyperlinki
387387

388388
By default hyperlinks are expected to correspond to a view name that matches the style `'{model_name}-detail'`, and looks up the instance by a `pk` keyword argument.
389389

390-
You can change the field that is used for object lookups by setting the `lookup_field` option. The value of this option should correspond both with a kwarg in the URL conf, and with an field on the model. For example:
390+
You can change the field that is used for object lookups by setting the `lookup_field` option. The value of this option should correspond both with a kwarg in the URL conf, and with a field on the model. For example:
391391

392392
class AccountSerializer(serializers.HyperlinkedModelSerializer):
393393
class Meta:
394394
model = Account
395395
fields = ('url', 'account_name', 'users', 'created')
396396
lookup_field = 'slug'
397397

398+
Not that the `lookup_field` will be used as the default on *all* hyperlinked fields, including both the URL identity, and any hyperlinked relationships.
399+
398400
For more specfic requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly. For example:
399401

400402
class AccountSerializer(serializers.HyperlinkedModelSerializer):

0 commit comments

Comments
 (0)