From d3ee5080a0ff3894050442146083f9d4a2327c8f Mon Sep 17 00:00:00 2001 From: Rob Romano Date: Tue, 13 Nov 2012 15:03:42 -0800 Subject: Added documentation on how to use the token authentication login view. --- docs/api-guide/authentication.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 3137b9d4..50d8c054 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -97,6 +97,22 @@ If successfully authenticated, `TokenAuthentication` provides the following cred **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. +When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. + +REST framework provides a built-in login view. To use it, add a pattern to include the token login view for clients as follows: + + urlpatterns += patterns('', + url(r'^api-token-auth/', include('rest_framework.authtoken.urls', + namespace='rest_framework')) + ) + +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. + +The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: + + { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + + ## OAuthAuthentication This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests. OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf. -- cgit v1.2.3 From 4fd590f96f77eae433f1d5de281ed95f5a003745 Mon Sep 17 00:00:00 2001 From: Rob Romano Date: Tue, 13 Nov 2012 16:49:13 -0800 Subject: Renamed AuthTokenView to ObtainAuthToken, added obtain_auth_token var, updated tests & docs. Left authtoken.urls in place as example. --- docs/api-guide/authentication.md | 14 ++++---------- docs/topics/credits.md | 2 ++ docs/topics/release-notes.md | 1 + 3 files changed, 7 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 50d8c054..18620f49 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -97,21 +97,15 @@ If successfully authenticated, `TokenAuthentication` provides the following cred **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. -When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. - -REST framework provides a built-in login view. To use it, add a pattern to include the token login view for clients as follows: +REST framework provides a built-in login view for clients to retrieve the token called `rest_framework.authtoken.obtain_auth_token`. To use it, add a pattern to include the token login view for clients as follows: urlpatterns += patterns('', - url(r'^api-token-auth/', include('rest_framework.authtoken.urls', - namespace='rest_framework')) + url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. - -The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: - - { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: + { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } ## OAuthAuthentication diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 22d08df7..f378a521 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -59,6 +59,7 @@ The following people have helped make REST framework great. * Toni Michel - [tonimichel] * Ben Konrath - [benkonrath] * Marc Aymerich - [glic3rinu] +* Rob Romano - [robromano] Many thanks to everyone who's contributed to the project. @@ -153,3 +154,4 @@ To contact the author directly: [tonimichel]: https://github.com/tonimichel [benkonrath]: https://github.com/benkonrath [glic3rinu]: https://github.com/glic3rinu +[robromano]: https://github.com/robromano diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 35e8a8b3..daacc76f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,6 +7,7 @@ ## Master * Support for `read_only_fields` on `ModelSerializer` classes. +* Add convenience login view to get tokens when using `TokenAuthentication` ## 2.1.2 -- cgit v1.2.3 From 8b999c6bb500a045c6c32412009cbd3b1cd5a56b Mon Sep 17 00:00:00 2001 From: Ludwig Kraatz Date: Wed, 14 Nov 2012 11:46:16 +0100 Subject: polishing code and adding myself to auhtors file --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 22d08df7..8e71c937 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -59,6 +59,7 @@ The following people have helped make REST framework great. * Toni Michel - [tonimichel] * Ben Konrath - [benkonrath] * Marc Aymerich - [glic3rinu] +* Ludwig Kraatz - [ludwigkraatz] Many thanks to everyone who's contributed to the project. @@ -153,3 +154,4 @@ To contact the author directly: [tonimichel]: https://github.com/tonimichel [benkonrath]: https://github.com/benkonrath [glic3rinu]: https://github.com/glic3rinu +[ludwigkraatz]: https://github.com/ludwigkraatz -- cgit v1.2.3 From 33fe0d2bea5ce391a69047236c121ec5b33d9b2f Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Wed, 14 Nov 2012 16:08:14 +0100 Subject: added release note --- docs/topics/release-notes.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 35e8a8b3..40ce4352 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,6 +7,7 @@ ## Master * Support for `read_only_fields` on `ModelSerializer` classes. +* Support for `page_size` GET parameter in view which inherit ListModelMixin ## 2.1.2 -- cgit v1.2.3 From 5967f15f7f5c87987ab60e4b7dc682b06f3ab511 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Wed, 14 Nov 2012 16:11:35 +0100 Subject: updated docs --- docs/api-guide/generic-views.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 360ef1a2..9e5119cb 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -147,6 +147,10 @@ Provides a `.list(request, *args, **kwargs)` method, that implements listing a q Should be mixed in with [MultipleObjectAPIView]. +**Arguments**: + +* `page_size` - Hook to adjust page_size per request. + ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. -- cgit v1.2.3 From 1e83b60a43c26db921d6910092362feb3a76500d Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Wed, 14 Nov 2012 18:00:59 +0100 Subject: added description how to use the auth token --- docs/api-guide/authentication.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 3137b9d4..cb1e2645 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -97,6 +97,21 @@ If successfully authenticated, `TokenAuthentication` provides the following cred **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. +If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal. + + @receiver(post_save, sender=User) + def create_auth_token(sender, instance=None, created=False, **kwargs): + if created: + Token.objects.create(user=instance) + +If you've already created some User`'s, you can run a script like this. + + from django.contrib.auth.models import User + from rest_framework.authtoken.models import Token + + for user in User.objects.all(): + Token.objects.get_or_create(user=user) + ## OAuthAuthentication This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests. OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf. -- cgit v1.2.3 From eb20b5663e68ce01453eeb855922874001f42d0f Mon Sep 17 00:00:00 2001 From: Rob Romano Date: Tue, 13 Nov 2012 15:03:42 -0800 Subject: Added documentation on how to use the token authentication login view. --- docs/api-guide/authentication.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index cb1e2645..a55059a8 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -112,6 +112,21 @@ If you've already created some User`'s, you can run a script like this. for user in User.objects.all(): Token.objects.get_or_create(user=user) +When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. + +REST framework provides a built-in login view. To use it, add a pattern to include the token login view for clients as follows: + + urlpatterns += patterns('', + url(r'^api-token-auth/', include('rest_framework.authtoken.urls', + namespace='rest_framework')) + ) + +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. + +The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: + + { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + ## OAuthAuthentication This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests. OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf. -- cgit v1.2.3 From 321ba156ca45da8a4b3328c4aec6a9235f32e5f8 Mon Sep 17 00:00:00 2001 From: Rob Romano Date: Tue, 13 Nov 2012 16:49:13 -0800 Subject: Renamed AuthTokenView to ObtainAuthToken, added obtain_auth_token var, updated tests & docs. Left authtoken.urls in place as example. --- docs/api-guide/authentication.md | 11 ++++------- docs/topics/credits.md | 3 +++ docs/topics/release-notes.md | 1 + 3 files changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index a55059a8..a30bd22c 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -114,18 +114,15 @@ If you've already created some User`'s, you can run a script like this. When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. -REST framework provides a built-in login view. To use it, add a pattern to include the token login view for clients as follows: +REST framework provides a built-in login view for clients to retrieve the token called `rest_framework.authtoken.obtain_auth_token`. To use it, add a pattern to include the token login view for clients as follows: urlpatterns += patterns('', - url(r'^api-token-auth/', include('rest_framework.authtoken.urls', - namespace='rest_framework')) + url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: -The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: - - { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } ## OAuthAuthentication diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 8e71c937..939dfc57 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -60,6 +60,7 @@ The following people have helped make REST framework great. * Ben Konrath - [benkonrath] * Marc Aymerich - [glic3rinu] * Ludwig Kraatz - [ludwigkraatz] +* Rob Romano - [robromano] Many thanks to everyone who's contributed to the project. @@ -155,3 +156,5 @@ To contact the author directly: [benkonrath]: https://github.com/benkonrath [glic3rinu]: https://github.com/glic3rinu [ludwigkraatz]: https://github.com/ludwigkraatz +[robromano]: https://github.com/robromano + diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 35e8a8b3..daacc76f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,6 +7,7 @@ ## Master * Support for `read_only_fields` on `ModelSerializer` classes. +* Add convenience login view to get tokens when using `TokenAuthentication` ## 2.1.2 -- cgit v1.2.3 From 38e94bb8b4e04249b18b9b57ef2ddcb7cfc4efa4 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Thu, 15 Nov 2012 11:15:05 +0100 Subject: added global and per resource on/off switch + updated docs --- docs/api-guide/generic-views.md | 3 ++- docs/api-guide/settings.md | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 9e5119cb..734a91e9 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -149,7 +149,8 @@ Should be mixed in with [MultipleObjectAPIView]. **Arguments**: -* `page_size` - Hook to adjust page_size per request. +* `allow_page_size_param` - Allows you to overwrite the global settings `ALLOW_PAGE_SIZE_PARAM` for a specific view. +* `page_size_param` - Allows you to customize the page_size parameter. Default is `page_size`. ## CreateModelMixin diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 4f87b30d..2f90369b 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -150,4 +150,10 @@ Default: `'accept'` Default: `'format'` +## ALLOW_PAGE_SIZE_PARAM + +Allows you to globally pass a page size parameter for an individual request. + +Default: `'True'` + [cite]: http://www.python.org/dev/peps/pep-0020/ -- cgit v1.2.3 From b17a9818008cf3828adb896ae9be134fb63c5693 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Thu, 15 Nov 2012 11:24:17 +0100 Subject: updated release noted for page_size stuff --- docs/topics/release-notes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 40ce4352..f4a76c89 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,7 +7,9 @@ ## Master * Support for `read_only_fields` on `ModelSerializer` classes. -* Support for `page_size` GET parameter in view which inherit ListModelMixin +* Support for `page_size` GET parameter in views which inherit ListModelMixin. +* Support for customizing `page_size` param via `page_size_param` attribute. +* Support for allowing `page_size` param globally (via `ALLOW_PAGE_SIZE_PARAM`) and for individual views (via `allow_page_size_param`) ## 2.1.2 -- cgit v1.2.3 From 3ae203a0184d27318a8a828ce322b151ade0340f Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Thu, 15 Nov 2012 12:06:43 +0100 Subject: updated script to just use page_size_kwarg --- docs/api-guide/generic-views.md | 3 +-- docs/api-guide/settings.md | 8 ++++++-- docs/topics/release-notes.md | 4 +--- 3 files changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 734a91e9..3346c70a 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -149,8 +149,7 @@ Should be mixed in with [MultipleObjectAPIView]. **Arguments**: -* `allow_page_size_param` - Allows you to overwrite the global settings `ALLOW_PAGE_SIZE_PARAM` for a specific view. -* `page_size_param` - Allows you to customize the page_size parameter. Default is `page_size`. +* `page_size_kwarg` - Allows you to overwrite the global settings `PAGE_SIZE_KWARG` for a specific view. You can also turn it off for a specific view by setting it to `None`. Default is `page_size`. ## CreateModelMixin diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 2f90369b..8fce9e4e 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -150,10 +150,14 @@ Default: `'accept'` Default: `'format'` -## ALLOW_PAGE_SIZE_PARAM +## PAGE_SIZE_KWARG Allows you to globally pass a page size parameter for an individual request. -Default: `'True'` +The name of the GET parameter of views which inherit ListModelMixin for requesting data with an individual page size. + +If the value if this setting is `None` the passing a page size is turned off by default. + +Default: `'page_size'` [cite]: http://www.python.org/dev/peps/pep-0020/ diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index f4a76c89..85c19f5b 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,9 +7,7 @@ ## Master * Support for `read_only_fields` on `ModelSerializer` classes. -* Support for `page_size` GET parameter in views which inherit ListModelMixin. -* Support for customizing `page_size` param via `page_size_param` attribute. -* Support for allowing `page_size` param globally (via `ALLOW_PAGE_SIZE_PARAM`) and for individual views (via `allow_page_size_param`) +* Support for individual page sizes per request via `page_size` GET parameter in views which inherit ListModelMixin. ## 2.1.2 -- cgit v1.2.3 From b4cfb46a56c8f7d9bc4340d5443f3a2d57ba9b58 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Fri, 16 Nov 2012 00:22:08 +0100 Subject: WIP on docs for File- and ImageFileds. --- docs/api-guide/fields.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0485b158..0b25a6ef 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -165,6 +165,38 @@ A floating point representation. Corresponds to `django.db.models.fields.FloatField`. +## FileField + +A file representation. Performs Django's standard FileField validation. + +Corresponds to `django.forms.fields.FileField`. + +### Optional arguments + +#### `max_length` + +Maximum length for the file name. This value is obtained from the model when used with a ModelSerializer. + +Defaults to `None`, meaning validation is skipped. + +#### `allow_empty_file` + +Determines if empty file uploads are allowed. + +Defaults to `False` + +## ImageField + +An image representation. + +Corresponds to `django.forms.fields.ImageField`. + +### Optional arguments + +Same as FileField. + +Requires the `PIL` package. + --- # Relational Fields -- cgit v1.2.3 From c5765641a44ad2fb3b80f63f9a47e0dd7f432c94 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 17:28:08 +0000 Subject: Fix typo --- docs/api-guide/filtering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 14ab9a26..95d9d526 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -71,7 +71,7 @@ We can override `.get_queryset()` to deal with URLs such as `http://example.com/ by filtering against a `username` query parameter in the URL. """ queryset = Purchase.objects.all() - username = self.request.QUERY_PARAMS.get('username', None): + username = self.request.QUERY_PARAMS.get('username', None) if username is not None: queryset = queryset.filter(purchaser__username=username) return queryset -- cgit v1.2.3 From 2f2bde69e42825ad55318e5a5745ee9655b3f81b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 20:58:49 +0000 Subject: Docs, tox and travis use django-filter 0.5.4 --- docs/api-guide/filtering.md | 5 ++--- docs/index.md | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 95d9d526..53ea7cbc 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -84,9 +84,9 @@ As well as being able to override the default queryset, REST framework also incl REST framework supports pluggable backends to implement filtering, and provides an implementation which uses the [django-filter] package. -To use REST framework's default filtering backend, first install `django-filter`. +To use REST framework's filtering backend, first install `django-filter`. - pip install -e git+https://github.com/alex/django-filter.git#egg=django-filter + pip install django-filter You must also set the filter backend to `DjangoFilterBackend` in your settings: @@ -94,7 +94,6 @@ You must also set the filter backend to `DjangoFilterBackend` in your settings: 'FILTER_BACKEND': 'rest_framework.filters.DjangoFilterBackend' } -**Note**: The currently supported version of `django-filter` is the `master` branch. A PyPI release is expected to be coming soon. ## Specifying filter fields diff --git a/docs/index.md b/docs/index.md index fd834540..cc0f2a13 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,7 +34,7 @@ The following packages are optional: * [Markdown][markdown] (2.1.0+) - Markdown support for the browseable API. * [PyYAML][yaml] (3.10+) - YAML content-type support. -* [django-filter][django-filter] (master) - Filtering support. +* [django-filter][django-filter] (0.5.4+) - Filtering support. ## Installation @@ -43,7 +43,7 @@ Install using `pip`, including any optional packages you want... pip install djangorestframework pip install markdown # Markdown support for the browseable API. pip install pyyaml # YAML content-type support. - pip install -e git+https://github.com/alex/django-filter.git#egg=django-filter # Filtering support + pip install django-filter # Filtering support ...or clone the project from github. -- cgit v1.2.3 From 0076e2f462402dbb7bd7b3a446d2c397e6bf8d81 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Fri, 16 Nov 2012 23:23:34 +0100 Subject: Added brief docs for URLField and SlugField. --- docs/api-guide/fields.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0485b158..5977cae2 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -131,6 +131,18 @@ or `django.db.models.fields.TextField`. **Signature:** `CharField(max_length=None, min_length=None)` +## URLField + +Corresponds to `django.db.models.fields.URLField`. Uses Django's `django.core.validators.URLValidator` for validation. + +**Signature:** `CharField(max_length=200, min_length=None)` + +## SlugField + +Corresponds to `django.db.models.fields.SlugField`. + +**Signature:** `CharField(max_length=50, min_length=None)` + ## ChoiceField A field that can accept a value out of a limited set of choices. -- cgit v1.2.3 From f801e5d3050591403de04fde7d18522fabc8fe49 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Fri, 16 Nov 2012 23:44:55 +0100 Subject: Simplified docs a bit for FileField and ImageField. Added note about MultipartParser only supporting file uploads and Django's default upload handlers. --- docs/api-guide/fields.md | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0b25a6ef..7f42dc5e 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -171,19 +171,11 @@ A file representation. Performs Django's standard FileField validation. Corresponds to `django.forms.fields.FileField`. -### Optional arguments +**Signature:** `FileField(max_length=None, allow_empty_file=False)` -#### `max_length` - -Maximum length for the file name. This value is obtained from the model when used with a ModelSerializer. - -Defaults to `None`, meaning validation is skipped. - -#### `allow_empty_file` - -Determines if empty file uploads are allowed. - -Defaults to `False` + - `max_length` designates the maximum length for the file name. + + - `allow_empty_file` designates if empty files are allowed. ## ImageField @@ -191,11 +183,14 @@ An image representation. Corresponds to `django.forms.fields.ImageField`. -### Optional arguments +Requires the `PIL` package. -Same as FileField. +Signature and validation is the same as with `FileField`. -Requires the `PIL` package. +--- + +**Note:** `FileFields` and `ImageFields` are only suitable for use with MultiPartParser, since eg json doesn't support file uploads. +Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. --- @@ -318,3 +313,4 @@ This field is always read-only. * `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is to use the same value as given for `slug_field`. [cite]: http://www.python.org/dev/peps/pep-0020/ +[FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From 31f01bd6315f46bf28bb4c9c25a5298785fc4fc6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 22:45:57 +0000 Subject: Polishing to page size query parameters & more docs --- docs/api-guide/generic-views.md | 22 ++++++++++++++++++---- docs/api-guide/settings.md | 26 ++++++++++++++++---------- docs/topics/release-notes.md | 3 ++- 3 files changed, 36 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 3346c70a..33ec89d2 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -123,18 +123,36 @@ Each of the generic views provided is built by combining one of the base views b Extends REST framework's `APIView` class, adding support for serialization of model instances and model querysets. +**Attributes**: + +* `model` - The model that should be used for this view. Used as a fallback for determining the serializer if `serializer_class` is not set, and as a fallback for determining the queryset if `queryset` is not set. Otherwise not required. +* `serializer_class` - The serializer class that should be used for validating and deserializing input, and for serializing output. If unset, this defaults to creating a serializer class using `self.model`, with the `DEFAULT_MODEL_SERIALIZER_CLASS` setting as the base serializer class. + ## MultipleObjectAPIView Provides a base view for acting on a single object, by combining REST framework's `APIView`, and Django's [MultipleObjectMixin]. **See also:** ccbv.co.uk documentation for [MultipleObjectMixin][multiple-object-mixin-classy]. +**Attributes**: + +* `queryset` - The queryset that should be used for returning objects from this view. If unset, defaults to the default queryset manager for `self.model`. +* `paginate_by` - The size of pages to use with paginated data. If set to `None` then pagination is turned off. If unset this uses the same value as the `PAGINATE_BY` setting, which defaults to `None`. +* `paginate_by_param` - The name of a query parameter, which can be used by the client to overide the default page size to use for pagination. If unset this uses the same value as the `PAGINATE_BY_PARAM` setting, which defaults to `None`. + ## SingleObjectAPIView Provides a base view for acting on a single object, by combining REST framework's `APIView`, and Django's [SingleObjectMixin]. **See also:** ccbv.co.uk documentation for [SingleObjectMixin][single-object-mixin-classy]. +**Attributes**: + +* `queryset` - The queryset that should be used when retrieving an object from this view. If unset, defaults to the default queryset manager for `self.model`. +* `pk_kwarg` - The URL kwarg that should be used to look up objects by primary key. Defaults to `'pk'`. [Can only be set to non-default on Django 1.4+] +* `slug_kwarg` - The URL kwarg that should be used to look up objects by a slug. Defaults to `'slug'`. [Can only be set to non-default on Django 1.4+] +* `slug_field` - The field on the model that should be used to look up objects by a slug. If used, this should typically be set to a field with `unique=True`. Defaults to `'slug'`. + --- # Mixins @@ -147,10 +165,6 @@ Provides a `.list(request, *args, **kwargs)` method, that implements listing a q Should be mixed in with [MultipleObjectAPIView]. -**Arguments**: - -* `page_size_kwarg` - Allows you to overwrite the global settings `PAGE_SIZE_KWARG` for a specific view. You can also turn it off for a specific view by setting it to `None`. Default is `page_size`. - ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 8fce9e4e..7884d096 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -96,11 +96,21 @@ Default: `rest_framework.serializers.ModelSerializer` Default: `rest_framework.pagination.PaginationSerializer` -## FORMAT_SUFFIX_KWARG +## FILTER_BACKEND -**TODO** +The filter backend class that should be used for generic filtering. If set to `None` then generic filtering is disabled. -Default: `'format'` +## PAGINATE_BY + +The default page size to use for pagination. If set to `None`, pagination is disabled by default. + +Default: `None` + +## PAGINATE_BY_KWARG + +The name of a query parameter, which can be used by the client to overide the default page size to use for pagination. If set to `None`, clients may not override the default page size. + +Default: `None` ## UNAUTHENTICATED_USER @@ -150,14 +160,10 @@ Default: `'accept'` Default: `'format'` -## PAGE_SIZE_KWARG - -Allows you to globally pass a page size parameter for an individual request. - -The name of the GET parameter of views which inherit ListModelMixin for requesting data with an individual page size. +## FORMAT_SUFFIX_KWARG -If the value if this setting is `None` the passing a page size is turned off by default. +**TODO** -Default: `'page_size'` +Default: `'format'` [cite]: http://www.python.org/dev/peps/pep-0020/ diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 85c19f5b..869cabc8 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,7 +7,8 @@ ## Master * Support for `read_only_fields` on `ModelSerializer` classes. -* Support for individual page sizes per request via `page_size` GET parameter in views which inherit ListModelMixin. +* Support for clients overriding the pagination page sizes. Use the `PAGINATE_BY_PARAM` setting or set the `paginate_by_param` attribute on a generic view. +* 201 Responses now return a 'Location' header. ## 2.1.2 -- cgit v1.2.3 From 19b0516bfefe3398683b4f878774e3dd80bf653a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 22:49:15 +0000 Subject: Getting 2.1.3 release notes ready --- docs/topics/release-notes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 869cabc8..5931a75a 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -4,7 +4,9 @@ > > — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. -## Master +## 2.1.3 + +**Date**: 16th Nov 2012 * Support for `read_only_fields` on `ModelSerializer` classes. * Support for clients overriding the pagination page sizes. Use the `PAGINATE_BY_PARAM` setting or set the `paginate_by_param` attribute on a generic view. -- cgit v1.2.3 From 016ef5019ff43808540f948d674e8dd33247cb99 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 22:58:17 +0000 Subject: Version 2.1.3 --- docs/topics/release-notes.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 5931a75a..2a6fbe83 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -8,9 +8,12 @@ **Date**: 16th Nov 2012 +* Added `FileField` and `ImageField`. For use with `MultiPartParser`. +* Added `URLField` and `SlugField`. * Support for `read_only_fields` on `ModelSerializer` classes. * Support for clients overriding the pagination page sizes. Use the `PAGINATE_BY_PARAM` setting or set the `paginate_by_param` attribute on a generic view. * 201 Responses now return a 'Location' header. +* Bugfix: Serializer fields now respect `max_length`. ## 2.1.2 -- cgit v1.2.3 From 0eba278e1391604086dab1dfa1bd6ea86fea282e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 23:22:23 +0000 Subject: Improve pagination docs --- docs/api-guide/pagination.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 597baba4..39e6a32d 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -80,23 +80,21 @@ We could now use our pagination serializer in a view like this. ## Pagination in the generic views -The generic class based views `ListAPIView` and `ListCreateAPIView` provide pagination of the returned querysets by default. You can customise this behaviour by altering the pagination style, by modifying the default number of results, or by turning pagination off completely. +The generic class based views `ListAPIView` and `ListCreateAPIView` provide pagination of the returned querysets by default. You can customise this behaviour by altering the pagination style, by modifying the default number of results, by allowing clients to override the page size using a query parameter, or by turning pagination off completely. -The default pagination style may be set globally, using the `PAGINATION_SERIALIZER` and `PAGINATE_BY` settings. For example. +The default pagination style may be set globally, using the `DEFAULT_PAGINATION_SERIALIZER_CLASS`, `PAGINATE_BY` and `PAGINATE_BY_PARAM` settings. For example. REST_FRAMEWORK = { - 'PAGINATION_SERIALIZER': ( - 'example_app.pagination.CustomPaginationSerializer', - ), - 'PAGINATE_BY': 10 + 'PAGINATE_BY': 10, + 'PAGINATE_BY_PARAM': 'page_size' } You can also set the pagination style on a per-view basis, using the `ListAPIView` generic class-based view. class PaginatedListView(ListAPIView): model = ExampleModel - pagination_serializer_class = CustomPaginationSerializer paginate_by = 10 + paginate_by_param = 'page_size' For more complex requirements such as serialization that differs depending on the requested media type you can override the `.get_paginate_by()` and `.get_pagination_serializer_class()` methods. @@ -122,4 +120,20 @@ For example, to nest a pair of links labelled 'prev' and 'next', and set the nam results_field = 'objects' +## Using your custom pagination serializer + +To have your custom pagination serializer be used by default use the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting: + + REST_FRAMEWORK = { + 'DEFAULT_PAGINATION_SERIALIZER_CLASS': + 'example_app.pagination.CustomPaginationSerializer', + } + +Alternatively, to set your custom pagination serializer on a per-view basis, use the `pagination_serializer_class` attribute on a generic class based view: + + class PaginatedListView(ListAPIView): + model = ExampleModel + pagination_serializer_class = CustomPaginationSerializer + paginate_by = 10 + [cite]: https://docs.djangoproject.com/en/dev/topics/pagination/ -- cgit v1.2.3 From 2263ed8b9409c709f6dbad2157f8debffb16c1d8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 23:24:36 +0000 Subject: Tweak --- docs/api-guide/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 39e6a32d..5a35ed75 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -122,7 +122,7 @@ For example, to nest a pair of links labelled 'prev' and 'next', and set the nam ## Using your custom pagination serializer -To have your custom pagination serializer be used by default use the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting: +To have your custom pagination serializer be used by default, use the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting: REST_FRAMEWORK = { 'DEFAULT_PAGINATION_SERIALIZER_CLASS': -- cgit v1.2.3 From 4068323df4a8a8ad8825d5e0ed1d31ee2a36484f Mon Sep 17 00:00:00 2001 From: Eugene MechanisM Date: Sat, 17 Nov 2012 04:03:43 +0400 Subject: Missing import of "Permission" model in docs Missing import of "Permission" model in docs--- docs/tutorial/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md index 93da1a59..9a36a2b0 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -8,7 +8,7 @@ Create a new Django project, and start a new app called `quickstart`. Once you' First up we're going to define some serializers in `quickstart/serializers.py` that we'll use for our data representations. - from django.contrib.auth.models import User, Group + from django.contrib.auth.models import User, Group, Permission from rest_framework import serializers -- cgit v1.2.3 From 346a79b170b0a25fd28354de765c5aa5aca9a119 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 17 Nov 2012 00:29:15 +0000 Subject: Added @MechanisM - Thanks! (That's a mighty kick ass Gravatar)--- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 8e71c937..f037e816 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -60,6 +60,7 @@ The following people have helped make REST framework great. * Ben Konrath - [benkonrath] * Marc Aymerich - [glic3rinu] * Ludwig Kraatz - [ludwigkraatz] +* Eugene Mechanism - [mechanism] Many thanks to everyone who's contributed to the project. @@ -155,3 +156,4 @@ To contact the author directly: [benkonrath]: https://github.com/benkonrath [glic3rinu]: https://github.com/glic3rinu [ludwigkraatz]: https://github.com/ludwigkraatz +[mechanism]: https://github.com/mechanism -- cgit v1.2.3 From f131e533edf58dc8ba7b712b4c3486a3ab053ffc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 18 Nov 2012 17:57:02 +0000 Subject: Docs, docs, docs, docs, docs, docs --- docs/api-guide/generic-views.md | 18 ++++++++++++++++++ docs/api-guide/pagination.md | 5 +++-- 2 files changed, 21 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 33ec89d2..428323b8 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -163,30 +163,48 @@ The mixin classes provide the actions that are used to provide the basic view be Provides a `.list(request, *args, **kwargs)` method, that implements listing a queryset. +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` reponse, unless the `.allow_empty` attribute on the view is set to `False`, in which case it will return a `404 Not Found`. + Should be mixed in with [MultipleObjectAPIView]. ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. +If an object is created this returns a `201 Created` response, with a serialized representation of the object as the body of the response. If the representation contains a key named `url`, then the `Location` header of the response will be populated with that value. + +If the request data provided for creating the object was invalid, a `400 Bad Request` response will be returned, with the error details as the body of the response. + Should be mixed in with any [GenericAPIView]. ## RetrieveModelMixin Provides a `.retrieve(request, *args, **kwargs)` method, that implements returning an existing model instance in a response. +If an object can be retrieve this returns a `200 OK` response, with a serialized representation of the object as the body of the response. Otherwise it will return a `404 Not Found`. + Should be mixed in with [SingleObjectAPIView]. ## UpdateModelMixin Provides a `.update(request, *args, **kwargs)` method, that implements updating and saving an existing model instance. +If an object is updated this returns a `200 OK` response, with a serialized representation of the object as the body of the response. + +If an object is created, for example when making a `DELETE` request followed by a `PUT` request to the same URL, this returns a `201 Created` response, with a serialized representation of the object as the body of the response. + +If the request data provided for updating the object was invalid, a `400 Bad Request` response will be returned, with the error details as the body of the response. + Should be mixed in with [SingleObjectAPIView]. ## DestroyModelMixin Provides a `.destroy(request, *args, **kwargs)` method, that implements deletion of an existing model instance. +If an object is deleted this returns a `204 No Content` response, otherwise it will return a `404 Not Found`. + Should be mixed in with [SingleObjectAPIView]. [cite]: https://docs.djangoproject.com/en/dev/ref/class-based-views/#base-vs-generic-views diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 5a35ed75..ab335e6e 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -70,11 +70,12 @@ We could now use our pagination serializer in a view like this. # If page is not an integer, deliver first page. users = paginator.page(1) except EmptyPage: - # If page is out of range (e.g. 9999), deliver last page of results. + # If page is out of range (e.g. 9999), + # deliver last page of results. users = paginator.page(paginator.num_pages) serializer_context = {'request': request} - serializer = PaginatedUserSerializer(instance=users, + serializer = PaginatedUserSerializer(users, context=serializer_context) return Response(serializer.data) -- cgit v1.2.3 From de5b071d677074ab3b6b33a843c4b05ba2052a6b Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Mon, 19 Nov 2012 17:22:17 +0000 Subject: Add SerializerMethodField --- docs/api-guide/fields.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index d1c31ecc..b19c324a 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -324,5 +324,11 @@ This field is always read-only. * `pk_url_kwarg` - The named url parameter for the pk field lookup. Default is `pk`. * `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is to use the same value as given for `slug_field`. +# Other Fields + +## SerializerMethodField + +This is a read-only field gets its value by calling a method on the serializer class it's attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. + [cite]: http://www.python.org/dev/peps/pep-0020/ [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From 3ab8c4966d065e930bd6e8bc6c26934ae5c5918c Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Mon, 19 Nov 2012 17:24:08 +0000 Subject: Tweaks to SerializerMethodField docs --- docs/api-guide/fields.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index b19c324a..ebfb5d47 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -328,7 +328,7 @@ This field is always read-only. ## SerializerMethodField -This is a read-only field gets its value by calling a method on the serializer class it's attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. +This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. [cite]: http://www.python.org/dev/peps/pep-0020/ [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From ce5b186ca869b693c945200581ba893123a63ce8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Nov 2012 21:42:33 +0000 Subject: Docs tweaks. --- docs/api-guide/authentication.md | 21 ++++++++++++--------- docs/topics/release-notes.md | 4 +++- 2 files changed, 15 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index a30bd22c..05575f57 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -68,7 +68,7 @@ This policy uses [HTTP Basic Authentication][basicauth], signed against a user's If successfully authenticated, `BasicAuthentication` provides the following credentials. -* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.user` will be a Django `User` instance. * `request.auth` will be `None`. **Note:** If you use `BasicAuthentication` in production you must ensure that your API is only available over `https` only. You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage. @@ -92,7 +92,7 @@ For clients to authenticate, the token key should be included in the `Authorizat If successfully authenticated, `TokenAuthentication` provides the following credentials. -* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.user` will be a Django `User` instance. * `request.auth` will be a `rest_framework.tokenauth.models.BasicToken` instance. **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. @@ -104,7 +104,7 @@ If you want every user to have an automatically generated Token, you can simply if created: Token.objects.create(user=instance) -If you've already created some User`'s, you can run a script like this. +If you've already created some User's, you can run a script like this. from django.contrib.auth.models import User from rest_framework.authtoken.models import Token @@ -112,26 +112,29 @@ If you've already created some User`'s, you can run a script like this. for user in User.objects.all(): Token.objects.get_or_create(user=user) -When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. - -REST framework provides a built-in login view for clients to retrieve the token called `rest_framework.authtoken.obtain_auth_token`. To use it, add a pattern to include the token login view for clients as follows: +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: urlpatterns += patterns('', url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. + +The `obtain_auth_token` view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using form data or JSON: { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + ## SessionAuthentication @@ -139,7 +142,7 @@ This policy uses Django's default session backend for authentication. Session a If successfully authenticated, `SessionAuthentication` provides the following credentials. -* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.user` will be a Django `User` instance. * `request.auth` will be `None`. # Custom authentication diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index d43f892f..81f4e332 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -4,7 +4,9 @@ > > — Eric S. Raymond, [The Cathedral and the Bazaar][cite]. -* Add convenience login view to get tokens when using `TokenAuthentication` +## Master + +* Added `obtain_token_view` to get tokens when using `TokenAuthentication` ## 2.1.3 -- cgit v1.2.3 From 83f3770af12061185289ac9e4b9c0a24e82f10c3 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Nov 2012 21:47:34 +0000 Subject: Adding folks to the credits makes me happy. Good work @jonlil! --- docs/topics/credits.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index 34590109..bd9e4f48 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -62,6 +62,7 @@ The following people have helped make REST framework great. * Ludwig Kraatz - [ludwigkraatz] * Rob Romano - [robromano] * Eugene Mechanism - [mechanism] +* Jonas Liljestrand - [jonlil] Many thanks to everyone who's contributed to the project. @@ -159,4 +160,4 @@ To contact the author directly: [ludwigkraatz]: https://github.com/ludwigkraatz [robromano]: https://github.com/robromano [mechanism]: https://github.com/mechanism - +[jonlil]: https://github.com/jonlil -- cgit v1.2.3 From 588e4dda6d97fad08b39e65df1ef25e643261977 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Nov 2012 21:49:07 +0000 Subject: Added release notes --- docs/topics/release-notes.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 81f4e332..ec83387f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -7,6 +7,7 @@ ## Master * Added `obtain_token_view` to get tokens when using `TokenAuthentication` +* Bugfix: Django 1.5 configurable user support for `TokenAuthentication` ## 2.1.3 -- cgit v1.2.3 From a44a94dd6ea2d9497264e267a0354cb684d398f6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Nov 2012 22:08:38 +0000 Subject: More docs tweaking. --- docs/api-guide/authentication.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 05575f57..8ed6ef31 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -104,7 +104,7 @@ If you want every user to have an automatically generated Token, you can simply if created: Token.objects.create(user=instance) -If you've already created some User's, you can run a script like this. +If you've already created some users, you can generate tokens for all existing users like this: from django.contrib.auth.models import User from rest_framework.authtoken.models import Token @@ -112,16 +112,16 @@ If you've already created some User's, you can run a script like this. for user in User.objects.all(): Token.objects.get_or_create(user=user) -When using TokenAuthentication, you may want to provide a mechanism for clients to obtain a token, given the username and password. +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: urlpatterns += patterns('', url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. +Note that the URL part of the pattern can be whatever you want to use. -The `obtain_auth_token` view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using form data or JSON: +The `obtain_auth_token` view will return a JSON response when valid `username` and `password` fields are POSTed to the view using form data or JSON: { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } -- cgit v1.2.3 From 5f4c385a86b877217c1e1bc2eaff58206eabb747 Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Tue, 20 Nov 2012 13:25:21 +0000 Subject: Add example use of SerializerMethodField to docs --- docs/api-guide/fields.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index ebfb5d47..914d0861 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -328,7 +328,21 @@ This field is always read-only. ## SerializerMethodField -This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. +This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. For example: + + from rest_framework import serializers + from django.contrib.auth.models import User + from django.utils.timezone import now + + class UserSerializer(serializers.ModelSerializer): + + days_since_joined = serializers.SerializerMethodField('get_days_since_joined') + + class Meta: + model = User + + def get_days_since_joined(self, obj): + return (now() - obj.date_joined).days [cite]: http://www.python.org/dev/peps/pep-0020/ [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From 3227a357cec2475b8295a67e9fd66f644ea5b0cd Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 20 Nov 2012 23:19:11 +0000 Subject: Added @irrelative for the mighty fine work. --- docs/topics/credits.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index bd9e4f48..955870d2 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -63,6 +63,7 @@ The following people have helped make REST framework great. * Rob Romano - [robromano] * Eugene Mechanism - [mechanism] * Jonas Liljestrand - [jonlil] +* Justin Davis - [irrelative] Many thanks to everyone who's contributed to the project. @@ -161,3 +162,4 @@ To contact the author directly: [robromano]: https://github.com/robromano [mechanism]: https://github.com/mechanism [jonlil]: https://github.com/jonlil +[irrelative]: https://github.com/irrelative -- cgit v1.2.3 From 3268c67343f6fc6364a0127a7bfabeb907a4751d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 20 Nov 2012 23:33:56 +0000 Subject: Update docs/topics/release-notes.md --- docs/topics/release-notes.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index ec83387f..0b8a7a8f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -6,6 +6,8 @@ ## Master +* Added `SerializerMethodField` +* Serializer performance improvements. * Added `obtain_token_view` to get tokens when using `TokenAuthentication` * Bugfix: Django 1.5 configurable user support for `TokenAuthentication` -- cgit v1.2.3