From ffdf633aa53526d2868e485ecffe0411a4ce0874 Mon Sep 17 00:00:00 2001 From: Areski Belaid Date: Wed, 5 Jun 2013 14:19:36 +0200 Subject: Fix on documentation - wrong reference at previous created view UserList / UserDetail --- docs/tutorial/6-viewsets-and-routers.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index 4ed10e82..d40ef781 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -10,7 +10,9 @@ A `ViewSet` class is only bound to a set of method handlers at the last moment, Let's take our current set of views, and refactor them into view sets. -First of all let's refactor our `UserListView` and `UserDetailView` views into a single `UserViewSet`. We can remove the two views, and replace then with a single class: +First of all let's refactor our `UserList` and `UserDetail` views into a single `UserViewSet`. We can remove the two views, and replace then with a single class: + + from rest_framework import viewsets class UserViewSet(viewsets.ReadOnlyModelViewSet): """ @@ -23,15 +25,14 @@ Here we've used `ReadOnlyModelViewSet` class to automatically provide the defaul Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. - from rest_framework import viewsets from rest_framework.decorators import link class SnippetViewSet(viewsets.ModelViewSet): """ This viewset automatically provides `list`, `create`, `retrieve`, `update` and `destroy` actions. - - Additionally we also provide an extra `highlight` action. + + Additionally we also provide an extra `highlight` action. """ queryset = Snippet.objects.all() serializer_class = SnippetSerializer @@ -107,7 +108,7 @@ Here's our re-wired `urls.py` file. router = DefaultRouter() router.register(r'snippets', views.SnippetViewSet) router.register(r'users', views.UserViewSet) - + # The API URLs are now determined automatically by the router. # Additionally, we include the login URLs for the browseable API. urlpatterns = patterns('', @@ -131,7 +132,7 @@ With an incredibly small amount of code, we've now got a complete pastebin Web A We've walked through each step of the design process, and seen how if we need to customize anything we can gradually work our way down to simply using regular Django views. -You can review the final [tutorial code][repo] on GitHub, or try out a live example in [the sandbox][sandbox]. +You can review the final [tutorial code][repo] on GitHub, or try out a live example in [the sandbox][sandbox]. ## Onwards and upwards -- cgit v1.2.3 From f317699d47e89882ee446ebec0388a1444223754 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 5 Jun 2013 14:36:40 +0200 Subject: Added @areski for docs fix #912. Thanks! --- 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 bbe209c7..db522922 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -139,6 +139,7 @@ The following people have helped make REST framework great. * Pascal Borreli - [pborreli] * Alex Burgel - [aburgel] * David Medina - [copitux] +* Areski Belaid - [areski] Many thanks to everyone who's contributed to the project. @@ -314,3 +315,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [pborreli]: https://github.com/pborreli [aburgel]: https://github.com/aburgel [copitux]: https://github.com/copitux +[areski]: https://github.com/areski -- cgit v1.2.3 From fdb689f9b552f219dd677b3b8421ceebcfd5b1e2 Mon Sep 17 00:00:00 2001 From: gnunamed Date: Wed, 5 Jun 2013 13:53:00 -0500 Subject: Update serializers.md --- docs/api-guide/serializers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 71f0abb7..9b6a547f 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -39,7 +39,7 @@ Declaring a serializer looks very similar to declaring a form: an existing model instance, or create a new model instance. """ if instance is not None: - instance.title = attrs.get('title', instance.title) + instance.email = attrs.get('email', instance.email) instance.content = attrs.get('content', instance.content) instance.created = attrs.get('created', instance.created) return instance -- cgit v1.2.3 From 40e09472d8b32988ef8284f66569cd26b3204ac6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 6 Jun 2013 08:56:39 +0100 Subject: Never deepcopy validators. Closes #913 --- docs/api-guide/generic-views.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 20b9440b..c8216954 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -131,7 +131,7 @@ You may want to override this method to provide more complex behavior such as mo For example: def get_paginate_by(self): - self.request.accepted_renderer.format == 'html': + if self.request.accepted_renderer.format == 'html': return 20 return 100 -- cgit v1.2.3 From e483c4fed686d7e3c7787d2e3eaa5ec4665399ff Mon Sep 17 00:00:00 2001 From: Ryan Kaskel Date: Fri, 7 Jun 2013 10:07:42 +0100 Subject: Remove pass statement before docstring. --- docs/api-guide/viewsets.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 2783da98..79257e2a 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -209,8 +209,6 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope mixins.ListMixin, mixins.RetrieveMixin, viewsets.GenericViewSet): - pass - """ A viewset that provides `retrieve`, `update`, and `list` actions. -- cgit v1.2.3 From 5ce1d6c86bb0831916ba4137560d84295ac7ec95 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 8 Jun 2013 09:38:21 +0200 Subject: Added @mindlace for work on #922. Thx! --- 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 db522922..b4bd3561 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -140,6 +140,7 @@ The following people have helped make REST framework great. * Alex Burgel - [aburgel] * David Medina - [copitux] * Areski Belaid - [areski] +* Ethan Freman - [mindlace] Many thanks to everyone who's contributed to the project. @@ -316,3 +317,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [aburgel]: https://github.com/aburgel [copitux]: https://github.com/copitux [areski]: https://github.com/areski +[mindlace]: https://github.com/mindlace -- cgit v1.2.3 From 777ecb5141d5d4f1a6b4e10e376965148022822c Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 10 Jun 2013 09:05:44 +0100 Subject: Add renderer_classes kwarg when binding snippet_highlight explicitly. Closes #923 --- docs/tutorial/6-viewsets-and-routers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index d40ef781..f16add39 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -74,7 +74,7 @@ In the `urls.py` file we bind our `ViewSet` classes into a set of concrete views }) snippet_highlight = SnippetViewSet.as_view({ 'get': 'highlight' - }) + }, renderer_classes=[renderers.StaticHTMLRenderer]) user_list = UserViewSet.as_view({ 'get': 'list' }) -- cgit v1.2.3 From 5d0aeef69ecec70242513195c19edcb622e14371 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 10 Jun 2013 17:46:55 +0100 Subject: Better docs related to lookup_field and hyperlinked serializers. Closes #920. --- docs/api-guide/generic-views.md | 2 +- docs/api-guide/serializers.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index c8216954..cd1bc7a1 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -60,7 +60,7 @@ The following attributes control the basic view behavior. * `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. * `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. -* `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. +* `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. **Shortcuts**: diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 9b6a547f..0885eb52 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -387,7 +387,7 @@ There needs to be a way of determining which views should be used for hyperlinki 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. -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: +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: class AccountSerializer(serializers.HyperlinkedModelSerializer): class Meta: @@ -395,6 +395,8 @@ You can change the field that is used for object lookups by setting the `lookup_ fields = ('url', 'account_name', 'users', 'created') lookup_field = 'slug' +Not that the `lookup_field` will be used as the default on *all* hyperlinked fields, including both the URL identity, and any hyperlinked relationships. + 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: class AccountSerializer(serializers.HyperlinkedModelSerializer): -- cgit v1.2.3 From 1cc2a7b25e78fcb41f44dc5b580f0f00a0a6318a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 12 Jun 2013 22:46:07 +0200 Subject: Added @davesque for work on #926. Thanks! :) --- docs/topics/credits.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/topics/credits.md b/docs/topics/credits.md index b4bd3561..3f0ee429 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -141,6 +141,7 @@ The following people have helped make REST framework great. * David Medina - [copitux] * Areski Belaid - [areski] * Ethan Freman - [mindlace] +* David Sanders - [davesque] Many thanks to everyone who's contributed to the project. @@ -318,3 +319,5 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [copitux]: https://github.com/copitux [areski]: https://github.com/areski [mindlace]: https://github.com/mindlace +[davesque]: https://github.com/davesque + -- cgit v1.2.3 From 250dfef158b107178ff9bea1743c767af9210d5e Mon Sep 17 00:00:00 2001 From: Toby Champion Date: Wed, 12 Jun 2013 13:53:39 -0700 Subject: Changes 'python' to 'Python' when used in prose. --- docs/api-guide/fields.md | 12 ++++++------ docs/api-guide/responses.md | 4 ++-- docs/api-guide/serializers.md | 6 +++--- docs/api-guide/settings.md | 18 +++++++++--------- docs/index.md | 2 +- docs/tutorial/1-serialization.md | 4 ++-- 6 files changed, 23 insertions(+), 23 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 94fff7e2..d69730c9 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -214,10 +214,10 @@ In the case of JSON this means the default datetime representation uses the [ECM **Signature:** `DateTimeField(format=None, input_formats=None)` -* `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. +* `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. * `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']`. -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'`) +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'`) ## DateField @@ -227,10 +227,10 @@ Corresponds to `django.db.models.fields.DateField` **Signature:** `DateField(format=None, input_formats=None)` -* `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. +* `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. * `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']`. -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'`) +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'`) ## TimeField @@ -242,10 +242,10 @@ Corresponds to `django.db.models.fields.TimeField` **Signature:** `TimeField(format=None, input_formats=None)` -* `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. +* `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. * `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']`. -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'`) +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'`) ## IntegerField diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index 374276dc..f83b8194 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -8,7 +8,7 @@ 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. -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. +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. 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. @@ -22,7 +22,7 @@ Unless you want to heavily customize REST framework for some reason, you should **Signature:** `Response(data, status=None, template_name=None, headers=None, content_type=None)` -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. +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. 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. diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 0885eb52..f8761cb2 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -8,7 +8,7 @@ will take some serious design work. > > — Russell Keith-Magee, [Django users group][cite] -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. +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. @@ -57,7 +57,7 @@ We can now use `CommentSerializer` to serialize a comment, or list of comments. serializer.data # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)} -At this point we've translated the model instance into python native datatypes. To finalise the serialization process we render the data into `json`. +At this point we've translated the model instance into Python native datatypes. To finalise the serialization process we render the data into `json`. json = JSONRenderer().render(serializer.data) json @@ -65,7 +65,7 @@ At this point we've translated the model instance into python native datatypes. ## Deserializing objects -Deserialization is similar. First we parse a stream into python native datatypes... +Deserialization is similar. First we parse a stream into Python native datatypes... stream = StringIO(json) data = JSONParser().parse(stream) diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 8d8c00cf..4a5164c9 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -199,9 +199,9 @@ Default: `'format'` #### DATETIME_FORMAT -A format string that should be used by default for rendering the output of `DateTimeField` serializer fields. If `None`, then `DateTimeField` serializer fields will return python `datetime` objects, and the datetime encoding will be determined by the renderer. +A format string that should be used by default for rendering the output of `DateTimeField` serializer fields. If `None`, then `DateTimeField` serializer fields will return Python `datetime` objects, and the datetime encoding will be determined by the renderer. -May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. +May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. Default: `None` @@ -209,15 +209,15 @@ Default: `None` A list of format strings that should be used by default for parsing inputs to `DateTimeField` serializer fields. -May be a list including the string `'iso-8601'` or python [strftime format][strftime] strings. +May be a list including the string `'iso-8601'` or Python [strftime format][strftime] strings. Default: `['iso-8601']` #### DATE_FORMAT -A format string that should be used by default for rendering the output of `DateField` serializer fields. If `None`, then `DateField` serializer fields will return python `date` objects, and the date encoding will be determined by the renderer. +A format string that should be used by default for rendering the output of `DateField` serializer fields. If `None`, then `DateField` serializer fields will return Python `date` objects, and the date encoding will be determined by the renderer. -May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. +May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. Default: `None` @@ -225,15 +225,15 @@ Default: `None` A list of format strings that should be used by default for parsing inputs to `DateField` serializer fields. -May be a list including the string `'iso-8601'` or python [strftime format][strftime] strings. +May be a list including the string `'iso-8601'` or Python [strftime format][strftime] strings. Default: `['iso-8601']` #### TIME_FORMAT -A format string that should be used by default for rendering the output of `TimeField` serializer fields. If `None`, then `TimeField` serializer fields will return python `time` objects, and the time encoding will be determined by the renderer. +A format string that should be used by default for rendering the output of `TimeField` serializer fields. If `None`, then `TimeField` serializer fields will return Python `time` objects, and the time encoding will be determined by the renderer. -May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. +May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. Default: `None` @@ -241,7 +241,7 @@ Default: `None` A list of format strings that should be used by default for parsing inputs to `TimeField` serializer fields. -May be a list including the string `'iso-8601'` or python [strftime format][strftime] strings. +May be a list including the string `'iso-8601'` or Python [strftime format][strftime] strings. Default: `['iso-8601']` diff --git a/docs/index.md b/docs/index.md index 0fb5706e..b04e2346 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,7 +43,7 @@ The following packages are optional: * [django-oauth-plus][django-oauth-plus] (2.0+) and [oauth2][oauth2] (1.5.211+) - OAuth 1.0a support. * [django-oauth2-provider][django-oauth2-provider] (0.2.3+) - OAuth 2.0 support. -**Note**: The `oauth2` python package is badly misnamed, and actually provides OAuth 1.0a support. Also note that packages required for both OAuth 1.0a, and OAuth 2.0 are not yet Python 3 compatible. +**Note**: The `oauth2` Python package is badly misnamed, and actually provides OAuth 1.0a support. Also note that packages required for both OAuth 1.0a, and OAuth 2.0 are not yet Python 3 compatible. ## Installation diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index bbb9b73c..bc31d234 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -175,13 +175,13 @@ We've now got a few snippet instances to play with. Let's take a look at serial serializer.data # {'pk': 2, 'title': u'', 'code': u'print "hello, world"\n', 'linenos': False, 'language': u'python', 'style': u'friendly'} -At this point we've translated the model instance into python native datatypes. To finalize the serialization process we render the data into `json`. +At this point we've translated the model instance into Python native datatypes. To finalize the serialization process we render the data into `json`. content = JSONRenderer().render(serializer.data) content # '{"pk": 2, "title": "", "code": "print \\"hello, world\\"\\n", "linenos": false, "language": "python", "style": "friendly"}' -Deserialization is similar. First we parse a stream into python native datatypes... +Deserialization is similar. First we parse a stream into Python native datatypes... import StringIO -- cgit v1.2.3 From ef38886fe8379c8bea318f7a6aa000a3ae85db51 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 14 Jun 2013 15:40:20 +0100 Subject: Update release notes --- docs/topics/release-notes.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 9ac51f42..f49dd5c8 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,6 +40,14 @@ You can determine your currently installed version using `pip freeze`: ## 2.3.x series +### Master + +* Added `trailing_slash` option to routers. +* Support wider range of default serializer validation when used with custom model fields. +* Bugfix: Return error correctly when OAuth non-existent consumer occurs. +* Bugfix: Allow `FileUploadParser` to correctly filename if provided as URL kwarg. +* Bugfix: Fix `ScopedRateThrottle`. + ### 2.3.5 **Date**: 3rd June 2013 -- cgit v1.2.3 From c875a27edfb5769de95ecd6252fa2a9c3a2f6792 Mon Sep 17 00:00:00 2001 From: bigsassy Date: Sun, 16 Jun 2013 18:32:33 -0300 Subject: Update 1-serialization.md Fixed typo in documentation (Testarea to Textarea)--- docs/tutorial/1-serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index bc31d234..2b214d6a 100644 --- a/docs/tutorial/1-serialization.md +++ b/docs/tutorial/1-serialization.md @@ -146,7 +146,7 @@ The first thing we need to get started on our Web API is provide a way of serial 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. -Notice that we can also use various attributes that would typically be used on form fields, such as `widget=widgets.Testarea`. These can be used to control how the serializer should render when displayed as an HTML form. This is particularly useful for controlling how the browsable API should be displayed, as we'll see later in the tutorial. +Notice that we can also use various attributes that would typically be used on form fields, such as `widget=widgets.Textarea`. These can be used to control how the serializer should render when displayed as an HTML form. This is particularly useful for controlling how the browsable API should be displayed, as we'll see later in the tutorial. We can actually also save ourselves some time by using the `ModelSerializer` class, as we'll see later, but for now we'll keep our serializer definition explicit. -- cgit v1.2.3 From aa706f581c84209d83acf04ccd8854e205057e50 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 17 Jun 2013 09:27:12 +0100 Subject: Add Django OAuth Toolkit to docs --- docs/api-guide/authentication.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 09491f02..8cf995b3 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -303,6 +303,10 @@ The command line to test the authentication looks like: curl -H "Authorization: Bearer " http://localhost:8000/api/ +### Alternative OAuth 2 implementations + +Note that [Django OAuth Toolkit][django-oauth-toolkit] is an alternative external package that also includes OAuth 2.0 support for REST framework. + --- # Custom authentication @@ -347,6 +351,10 @@ The following third party packages are also available. 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. +## Django OAuth Toolkit + +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. + [cite]: http://jacobian.org/writing/rest-worst-practices/ [http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 [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 [django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider [django-oauth2-provider-docs]: https://django-oauth2-provider.readthedocs.org/en/latest/ [rfc6749]: http://tools.ietf.org/html/rfc6749 +[django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit +[evonove]: https://github.com/evonove/ +[oauthlib]: https://github.com/idan/oauthlib -- cgit v1.2.3 From f3529f1f4a3b01c2821278da3bafbc04c1c00553 Mon Sep 17 00:00:00 2001 From: Philip Douglas Date: Fri, 21 Jun 2013 16:26:28 +0100 Subject: Correct docs' incorrect usage of action decorator If you don't call it, it doesn't work. --- docs/api-guide/viewsets.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 79257e2a..25d11bfb 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -27,7 +27,7 @@ Let's define a simple viewset that can be used to list or retrieve all the users queryset = User.objects.all() serializer = UserSerializer(queryset, many=True) return Response(serializer.data) - + def retrieve(self, request, pk=None): queryset = User.objects.all() user = get_object_or_404(queryset, pk=pk) @@ -69,7 +69,7 @@ The default routers included with REST framework will provide routes for a stand """ Example empty viewset demonstrating the standard actions that will be handled by a router class. - + If you're using format suffixes, make sure to also include the `format=None` keyword argument for each action. """ @@ -103,12 +103,12 @@ For example: class UserViewSet(viewsets.ModelViewSet): """ - A viewset that provides the standard actions + A viewset that provides the standard actions """ queryset = User.objects.all() serializer_class = UserSerializer - - @action + + @action() def set_password(self, request, pk=None): user = self.get_object() serializer = PasswordSerializer(data=request.DATA) @@ -197,7 +197,7 @@ As with `ModelViewSet`, you'll normally need to provide at least the `queryset` Again, as with `ModelViewSet`, you can use any of the standard attributes and method overrides available to `GenericAPIView`. -# Custom ViewSet base classes +# Custom ViewSet base classes You may need to provide custom `ViewSet` classes that do not have the full set of `ModelViewSet` actions, or that customize the behavior in some other way. @@ -211,7 +211,7 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope viewsets.GenericViewSet): """ A viewset that provides `retrieve`, `update`, and `list` actions. - + To use it, override the class and set the `.queryset` and `.serializer_class` attributes. """ -- cgit v1.2.3 From 2d5f7f201ffcc8c371e9f36821c2ae0e13dcecca Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 21 Jun 2013 22:19:14 +0100 Subject: Update router docs on base_name. Refs #933. --- docs/api-guide/routers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index f16fa946..b74b6e13 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -26,7 +26,7 @@ There are two mandatory arguments to the `register()` method: Optionally, you may also specify an additional argument: -* `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. +* `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. The example above would generate the following URL patterns: -- cgit v1.2.3 From a68f473dd8438c7d7b0f8ec4b4dc74aa0544143d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 21 Jun 2013 23:25:14 +0200 Subject: Brackets not required on decorator without arguments --- docs/api-guide/viewsets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 25d11bfb..ad961636 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -108,7 +108,7 @@ For example: queryset = User.objects.all() serializer_class = UserSerializer - @action() + @action def set_password(self, request, pk=None): user = self.get_object() serializer = PasswordSerializer(data=request.DATA) -- cgit v1.2.3 From 4f7f93e20ef53fbc0b66766158bca75ebddce2ed Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 21 Jun 2013 22:28:36 +0100 Subject: Added @freakydug, for changes in #941. Thanks :) --- 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 3f0ee429..a7c09b5b 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -142,6 +142,7 @@ The following people have helped make REST framework great. * Areski Belaid - [areski] * Ethan Freman - [mindlace] * David Sanders - [davesque] +* Philip Douglas - [freakydug] Many thanks to everyone who's contributed to the project. @@ -320,4 +321,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [areski]: https://github.com/areski [mindlace]: https://github.com/mindlace [davesque]: https://github.com/davesque - +[freakydug]: https://github.com/freakydug -- cgit v1.2.3 From 8cc63b09f6065e0197e060cc4d62b560196c8877 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 21 Jun 2013 22:42:04 +0100 Subject: Add support for StreamingHttpResponse. Closes #939 --- docs/api-guide/responses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index f83b8194..399b7c23 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -10,7 +10,7 @@ REST framework supports HTTP content negotiation by providing a `Response` class 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. -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. +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. 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. -- cgit v1.2.3 From fb6bcd9f06daaca51441c6b851d6411621d32c26 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 21 Jun 2013 22:43:01 +0100 Subject: Update release notes, noting support for StreamingHttpResponse. Refs #939 --- 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 f49dd5c8..b08ac058 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -43,6 +43,7 @@ You can determine your currently installed version using `pip freeze`: ### Master * Added `trailing_slash` option to routers. +* Include support for `HttpStreamingResponse`. * Support wider range of default serializer validation when used with custom model fields. * Bugfix: Return error correctly when OAuth non-existent consumer occurs. * Bugfix: Allow `FileUploadParser` to correctly filename if provided as URL kwarg. -- cgit v1.2.3 From 8d83ff8e6c8513d0a88d6b1fecb34ed86f1e2085 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 21 Jun 2013 23:12:16 +0100 Subject: Add decorator brackets back. Refs #941 --- docs/api-guide/viewsets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index ad961636..25d11bfb 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -108,7 +108,7 @@ For example: queryset = User.objects.all() serializer_class = UserSerializer - @action + @action() def set_password(self, request, pk=None): user = self.get_object() serializer = PasswordSerializer(data=request.DATA) -- cgit v1.2.3 From 13a3c993ab20e7af510d615a5eafaa87667b8efb Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 26 Jun 2013 11:30:27 +0100 Subject: Fix incorrect example --- docs/api-guide/generic-views.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index cd1bc7a1..67853ed0 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -92,7 +92,8 @@ May be overridden to provide dynamic behavior such as returning a queryset that For example: def get_queryset(self): - return self.user.accounts.all() + user = self.request.user + return user.accounts.all() #### `get_object(self)` -- cgit v1.2.3 From 494703fc8e916a9b7a318ec8bc7d774ef31de14e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 26 Jun 2013 22:40:14 +0100 Subject: Update 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 b08ac058..ce4df83c 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -45,6 +45,7 @@ You can determine your currently installed version using `pip freeze`: * Added `trailing_slash` option to routers. * Include support for `HttpStreamingResponse`. * Support wider range of default serializer validation when used with custom model fields. +* OAuth2 provider usez timezone aware datetimes when supported. * Bugfix: Return error correctly when OAuth non-existent consumer occurs. * Bugfix: Allow `FileUploadParser` to correctly filename if provided as URL kwarg. * Bugfix: Fix `ScopedRateThrottle`. -- cgit v1.2.3 From cb83bc373f8044ec21f5affabda0540ed0876357 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 26 Jun 2013 22:44:44 +0100 Subject: Added @trwired for fix #943. Thanks :) --- 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 a7c09b5b..94760c74 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -143,6 +143,7 @@ The following people have helped make REST framework great. * Ethan Freman - [mindlace] * David Sanders - [davesque] * Philip Douglas - [freakydug] +* Igor Kalat - [trwired] Many thanks to everyone who's contributed to the project. @@ -322,3 +323,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [mindlace]: https://github.com/mindlace [davesque]: https://github.com/davesque [freakydug]: https://github.com/freakydug +[trwired]: https://github.com/trwired -- cgit v1.2.3 From af2fdc03a6f4cafe6e2f19b2adcf59c8918088f2 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 26 Jun 2013 22:45:39 +0100 Subject: Update 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 ce4df83c..4fecbf1f 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -45,6 +45,7 @@ You can determine your currently installed version using `pip freeze`: * Added `trailing_slash` option to routers. * Include support for `HttpStreamingResponse`. * Support wider range of default serializer validation when used with custom model fields. +* UTF-8 Support for browsable API descriptions. * OAuth2 provider usez timezone aware datetimes when supported. * Bugfix: Return error correctly when OAuth non-existent consumer occurs. * Bugfix: Allow `FileUploadParser` to correctly filename if provided as URL kwarg. -- cgit v1.2.3 From 4d22a65e78432a2aa70ddc80395a014a7c9e299e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 26 Jun 2013 23:26:35 +0100 Subject: Fix sidebar styling when browser window is too small --- docs/css/default.css | 4 ++++ docs/template.html | 9 +++++++++ 2 files changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/css/default.css b/docs/css/default.css index a4f05daa..af6a9cc0 100644 --- a/docs/css/default.css +++ b/docs/css/default.css @@ -303,3 +303,7 @@ table { border-color: white; margin-bottom: 0.6em; } + +.side-nav { + overflow-y: scroll; +} diff --git a/docs/template.html b/docs/template.html index 53656e7d..14ecc9c7 100644 --- a/docs/template.html +++ b/docs/template.html @@ -198,5 +198,14 @@ $('.dropdown-menu').on('click touchstart', function(event) { event.stopPropagation(); }); + + // Dynamically force sidenav to no higher than browser window + $('.side-nav').css('max-height', window.innerHeight - 125); + + $(function(){ + $(window).resize(function(){ + $('.side-nav').css('max-height', window.innerHeight - 125); + }); + }); -- cgit v1.2.3 From 124ae8c2c88d48b67fbaee77e337e8a6f37d1b70 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 27 Jun 2013 12:58:38 +0100 Subject: Tweak styling for max-height of sidenav --- docs/template.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/template.html b/docs/template.html index 14ecc9c7..21771025 100644 --- a/docs/template.html +++ b/docs/template.html @@ -200,11 +200,11 @@ }); // Dynamically force sidenav to no higher than browser window - $('.side-nav').css('max-height', window.innerHeight - 125); + $('.side-nav').css('max-height', window.innerHeight - 130); $(function(){ $(window).resize(function(){ - $('.side-nav').css('max-height', window.innerHeight - 125); + $('.side-nav').css('max-height', window.innerHeight - 130); }); }); -- cgit v1.2.3 From 7ba2f44a0f0e5ed7bac0fbdbb0112bbfe43f6d24 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 27 Jun 2013 13:00:05 +0100 Subject: Version 2.3.6 --- docs/topics/release-notes.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 4fecbf1f..d379ab74 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,13 +40,15 @@ You can determine your currently installed version using `pip freeze`: ## 2.3.x series -### Master +### 2.3.6 + +**Date**: 27th June 2013 * Added `trailing_slash` option to routers. * Include support for `HttpStreamingResponse`. * Support wider range of default serializer validation when used with custom model fields. * UTF-8 Support for browsable API descriptions. -* OAuth2 provider usez timezone aware datetimes when supported. +* OAuth2 provider uses timezone aware datetimes when supported. * Bugfix: Return error correctly when OAuth non-existent consumer occurs. * Bugfix: Allow `FileUploadParser` to correctly filename if provided as URL kwarg. * Bugfix: Fix `ScopedRateThrottle`. -- cgit v1.2.3 From 1f6a59d76da286e7a89e8e41317beb16a4aab7c7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 27 Jun 2013 13:41:42 +0100 Subject: Moar hyperlinks --- docs/index.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index b04e2346..de4b01c6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,11 +15,11 @@ Django REST framework is a powerful and flexible toolkit that makes it easy to b Some reasons you might want to use REST framework: -* The Web browseable API is a huge usability win for your developers. -* Authentication policies including OAuth1a and OAuth2 out of the box. -* Serialization that supports both ORM and non-ORM data sources. -* Customizable all the way down - just use regular function-based views if you don't need the more powerful features. -* Extensive documentation, and great community support. +* The [Web browseable API][sandbox] is a huge usability win for your developers. +* [Authentication policies][authentication] including [OAuth1a][oauth1-section] and [OAuth2][oauth2-section] out of the box. +* [Serialization][serializers] that supports both [ORM][modelserializer-section] and [non-ORM][serializer-section] data sources. +* 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]. +* [Extensive documentation][index], and [great community support][group]. There is a live example API for testing purposes, [available here][sandbox]. @@ -250,6 +250,12 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider [0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X [image]: img/quickstart.png +[index]: . +[oauth1-section]: api-guide/authentication.html#oauthauthentication +[oauth2-section]: api-guide/authentication.html#oauth2authentication +[serializer-section]: api-guide/serializers.html#serializers +[modelserializer-section]: api-guide/serializers.html#modelserializer +[functionview-section]: api-guide/views.html#function-based-views [sandbox]: http://restframework.herokuapp.com/ [quickstart]: tutorial/quickstart.md -- cgit v1.2.3