8000 Merge remote-tracking branch 'upstream/master' into writable-nested-s… · martync/django-rest-framework@d0c1cb2 · GitHub
[go: up one dir, main page]
Skip to content

Commit d0c1cb2

Browse files
maspwrmaspwr
committed
Merge remote-tracking branch 'upstream/master' into writable-nested-serializers
Conflicts: rest_framework/serializers.py
2 parents ba32973 + 239758e commit d0c1cb2

27 files changed

+926
-159
lines changed

‎MANIFEST.in

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
recursive-include rest_framework/static *.js *.css *.png
2-
recursive-include rest_framework/templates *.txt *.html
2+
recursive-include rest_framework/templates *.html

‎README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@ To run the tests.
7979

8080
./rest_framework/runtests/runtests.py
8181

82+
To run the tests against all supported configurations, first install [the tox testing tool][tox] globally, using `pip install tox`, then simply run `tox`:
83+
84+
tox
85+
8286
# License
8387

8488
Copyright (c) 2011-2013, Tom Christie
@@ -113,6 +117,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
113117
[rest-framework-2-announcement]: http://django-rest-framework.org/topics/rest-framework-2-announcement.html
114118
[2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion
115119

120+
[tox]: http://testrun.org/tox/latest/
121+
116122
[docs]: http://django-rest-framework.org/
117123
[urlobject]: https://github.com/zacharyvoase/urlobject
118124
[markdown]: http://pypi.python.org/pypi/Markdown/

‎docs/api-guide/authentication.md

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,12 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401
113113

114114
This authentication scheme uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for client-server setups, such as native desktop and mobile clients.
115115

116-
To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in your `INSTALLED_APPS` setting.
116+
To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in your `INSTALLED_APPS` setting:
117+
118+
INSTALLED_APPS = (
119+
...
120+
'rest_framework.authtoken'
121+
)
117122

118123
You'll also need to create tokens for your users.
119124

@@ -135,10 +140,14 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401
135140

136141
WWW-Authenticate: Token
137142

143+
---
144+
138145
**Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only.
139146

140147
---
141148

149+
#### Generating Tokens
150+
142151
If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal.
143152

144153
@receiver(post_save, sender=User)
@@ -154,8 +163,7 @@ If you've already created some users, you can generate tokens for all existing u
154163
for user in User.objects.all():
155164
Token.objects.get_or_create(user=user)
156165

157-
When using `TokenAuthentication`, you may want to provide a mechanism for clients to obtain a token given the username and password.
158-
REST framework provides a built-in view to provide this behavior. To use it, add the `obtain_auth_token` view to your URLconf:
166+
When using `TokenAuthentication`, you may want to provide a mechanism for clients to obtain a token given the username and password. REST framework provides a built-in view to provide this behavior. To use it, add the `obtain_auth_token` view to your URLconf:
159167

160168
urlpatterns += patterns('',
161169
url(r'^api-token-auth/', 'rest_framework.authtoken.views.obtain_auth_token')
@@ -169,6 +177,23 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a
169177

170178
Note that the default `obtain_auth_token` view explicitly uses JSON requests and responses, rather than using default renderer and parser classes in your settings. If you need a customized version of the `obtain_auth_token` view, you can do so by overriding the `ObtainAuthToken` view class, and using that in your url conf instead.
171179

180+
#### Custom user models
181+
182+
The `rest_framework.authtoken` app includes a south migration that will create the authtoken table. If you're using a [custom user model][custom-user-model] you'll need to make sure that any initial migration that creates the user table runs before the authtoken table is created.
183+
184+
You can do so by inserting a `needed_by` attribute in your user migration:
185+
186+
class Migration:
187+
188+
needed_by = (
189+
('authtoken', '0001_initial'),
190+
)
191+
192+
def forwards(self):
193+
...
194+
195+
For more details, see the [south documentation on dependencies][south-dependencies].
196+
172197
## SessionAuthentication
173198

174199
This authentication scheme uses Django's default session backend for authentication. Session authentication is appropriate for AJAX clients that are running in the same session context as your website.
@@ -233,5 +258,7 @@ HTTP digest authentication is a widely implemented scheme that was intended to r
233258
[throttling]: throttling.md
234259
[csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/contrib/csrf/#ajax
235260
[mod_wsgi_official]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization
261+
[custom-user-model]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#specifying-a-custom-user-model
262+
[south-dependencies]: http://south.readthedocs.org/en/latest/dependencies.html
236263
[juanriaza]: https://github.com/juanriaza
237264
[djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth

‎docs/api-guide/fields.md

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# Serializer fields
44

5-
> Each field in a Form class is responsible not only for validating data, but also for "cleaning" it -- normalizing it to a consistent format.
5+
> Each field in a Form class is responsible not only for validating data, but also for "cleaning" it — normalizing it to a consistent format.
66
>
77
> — [Django documentation][cite]
88
@@ -181,12 +181,6 @@ Corresponds to `django.forms.fields.RegexField`
181181

182182
**Signature:** `RegexField(regex, max_length=None, min_length=None)`
183183

184-
## DateField
185-
186-
A date representation.
187-
188-
Corresponds to `django.db.models.fields.DateField`
189-
190184
## DateTimeField
191185

192186
A date and time representation.
@@ -203,12 +197,41 @@ If you want to override this behavior, you'll need to declare the `DateTimeField
203197
class Meta:
204198
model = Comment
205199

200+
**Signature:** `DateTimeField(format=None, input_formats=None)`
201+
202+
* `format` - A string representing the output format. If not specified, the `DATETIME_FORMAT` setting will be used, which defaults to `'iso-8601'`.
203+
* `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']`.
204+
205+
DateTime format strings may either be [python strftime formats][strftime] which explicitly specifiy 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.000000'`)
206+
207+
## DateField
208+
209+
A date representation.
210+
211+
Corresponds to `django.db.models.fields.DateField`
212+
213+
**Signature:** `DateField(format=None, input_formats=None)`
214+
215+
* `format` - A string representing the output format. If not specified, the `DATE_FORMAT` setting will be used, which defaults to `'iso-8601'`.
216+
* `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']`.
217+
218+
Date format strings may either be [python strftime formats][strftime] which explicitly specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`)
219+
206220
## TimeField
207221

208222
A time representation.
209223

224+
Optionally takes `format` as parameter to replace the matching pattern.
225+
210226
Corresponds to `django.db.models.fields.TimeField`
211227

228+
**Signature:** `TimeField(format=None, input_formats=None)`
229+
230+
* `format` - A string representing the output format. If not specified, the `TIME_FORMAT` setting will be used, which defaults to `'iso-8601'`.
231+
* `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']`.
232+
233+
Time format strings may either be [python strftime formats][strftime] which explicitly specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`)
234+
212235
## IntegerField
213236

214237
An integer representation.
@@ -252,3 +275,5 @@ Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files.
252275

253276
[cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data
254277
[FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS
278+
[strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior
279+
[iso8601]: http://www.w3.org/TR/NOTE-datetime

‎docs/api-guide/filtering.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,14 @@ For more details on using filter sets see the [django-filter documentation][djan
140140

141141
---
142142

143+
### Filtering and object lookups
144+
145+
Note that if a filter backend is configured for a view, then as well as being used to filter list views, it will also be used to filter the querysets used for returning a single object.
146+
147+
For instance, given the previous example, and a product with an id of `4675`, the following URL would either return the corresponding object, or return a 404 response, depending on if the filtering conditions were met by the given product instance:
148+
149+
http://example.com/api/products/4675/?category=clothing&max_price=10.00
150+
143151
## Overriding the initial queryset
144152

145153
Note that you can use both an overridden `.get_queryset()` and generic filtering together, and everything will work as expected. For example, if `Product` had a many-to-many relationship with `User`, named `purchase`, you might want to write a view like this:

‎docs/api-guide/permissions.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,12 +90,17 @@ This permission is suitable if you want to your API to allow read permissions to
9090

9191
## DjangoModelPermissions
9292

93-
This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth]. When applied to a view that has a `.model` property, authorization will only be granted if the user has the relevant model permissions assigned.
93+
This permission class ties into Django's standard `django.contrib.auth` [model permissions][contribauth]. When applied to a view that has a `.model` property, authorization will only be granted if the user *is authenticated* and has the *relevant model permissions* assigned.
9494

9595
* `POST` requests require the user to have the `add` permission on the model.
9696
* `PUT` and `PATCH` requests require the user to have the `change` permission on the model.
9797
* `DELETE` requests require the user to have the `delete` permission on the model.
9898

99+
If you want to use `DjangoModelPermissions` but also allow unauthenticated users to have read permission, override the class and set the `authenticated_users_only` property to `False`. For example:
100+
101+
class HasModelPermissionsOrReadOnly(DjangoModelPermissions):
102+
authenticated_users_only = False
103+
99104
The default behaviour can also be overridden to support custom model permissions. For example, you might want to include a `view` model permission for `GET` requests.
100105

101106
To use custom model permissions, override `DjangoModelPermissions` and set the `.perms_map` property. Refer to the source code for details.

‎docs/api-guide/serializers.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ To serialize a queryset instead of an object instance, you should pass the `many
9393

9494
When deserializing data, you always need to call `is_valid()` before attempting to access the deserialized object. If any validation errors occur, the `.errors` and `.non_field_errors` properties will contain the resulting error messages.
9595

96+
When deserialising a list of items, errors will be returned as a list of tuples. The first item in an error tuple will be the index of the item with the error in the original data; The second item in the tuple will be a dict with the individual errors for that item.
97+
9698
### Field-level validation
9799

98100
You can specify custom field-level validation by adding `.validate_<fieldname>` methods to your `Serializer` subclass. These are analagous to `.clean_<fieldname>` methods on Django forms, but accept slightly different arguments.

0 commit comments

Comments
 (0)
0