From b2dc66448503c2120d943a2f282eab235afc67ba Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 19 Mar 2013 14:26:48 +0000 Subject: Basic bulk create and bulk update --- docs/api-guide/serializers.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 42edf9af..ee7208a3 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -37,9 +37,6 @@ Declaring a serializer looks very similar to declaring a form: """ Given a dictionary of deserialized field values, either update an existing model instance, or create a new model instance. - - Note that if we don't define this method, then deserializing - data will simply return a dictionary of items. """ if instance is not None: instance.title = attrs.get('title', instance.title) @@ -48,7 +45,9 @@ Declaring a serializer looks very similar to declaring a form: return instance return Comment(**attrs) -The first part of serializer class defines the fields that get serialized/deserialized. The `restore_object` method defines how fully fledged instances get created when deserializing data. The `restore_object` method is optional, and is only required if we want our serializer to support deserialization. +The first part of serializer class defines the fields that get serialized/deserialized. The `restore_object` method defines how fully fledged instances get created when deserializing data. + +The `restore_object` method is optional, and is only required if we want our serializer to support deserialization into fully fledged object instances. If we don't define this method, then deserializing data will simply return a dictionary of items. ## Serializing objects @@ -88,18 +87,22 @@ By default, serializers must be passed values for all required fields or they wi serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True) # Update `instance` with partial data -## Serializing querysets +## Serializing multiple objects -To serialize a queryset instead of an object instance, you should pass the `many=True` flag when instantiating the serializer. +To serialize a queryset or list of objects instead of a single object instance, you should pass the `many=True` flag when instantiating the serializer. queryset = Comment.objects.all() serializer = CommentSerializer(queryset, many=True) serializer.data - # [{'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)}, {'email': u'jamie@example.com', 'content': u'baz', 'created': datetime.datetime(2013, 1, 12, 16, 12, 45, 104445)}] + # [ + # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)}, + # {'email': u'jamie@example.com', 'content': u'baz', 'created': datetime.datetime(2013, 1, 12, 16, 12, 45, 104445)} + # ] ## Validation When deserializing data, you always need to call `is_valid()` before attempting to access the deserialized object. If any validation errors occur, the `.errors` property will contain a dictionary representing the resulting error messages. + Each key in the dictionary will be the field name, and the values will be lists of strings of any error messages corresponding to that field. The `non_field_errors` key may also be present, and will list any general validation errors. When deserializing a list of items, errors will be returned as a list of dictionaries representing each of the deserialized items. -- cgit v1.2.3 From 8adde506e865005a96cdeff996ec4b5b9bb73a8f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 21 Mar 2013 08:41:54 +0000 Subject: Default date/time fields now return python date/time objects again by default --- docs/api-guide/fields.md | 6 +++--- docs/api-guide/settings.md | 27 ++++++++++++++++++++------- 2 files changed, 23 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 9a745cf1..63bd5b1a 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -199,7 +199,7 @@ If you want to override this behavior, you'll need to declare the `DateTimeField **Signature:** `DateTimeField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, the `DATETIME_FORMAT` setting will be used, which defaults to `'iso-8601'`. +* `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 specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000'`) @@ -212,7 +212,7 @@ Corresponds to `django.db.models.fields.DateField` **Signature:** `DateField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, the `DATE_FORMAT` setting will be used, which defaults to `'iso-8601'`. +* `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 specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`) @@ -227,7 +227,7 @@ Corresponds to `django.db.models.fields.TimeField` **Signature:** `TimeField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, the `TIME_FORMAT` setting will be used, which defaults to `'iso-8601'`. +* `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 specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`) diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 11638696..c0d8d9ee 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -192,44 +192,56 @@ Default: `'format'` --- -## Date/Time formatting +## Date and time formatting *The following settings are used to control how date and time representations may be parsed and rendered.* #### DATETIME_FORMAT -A format string that should be used by default for rendering the output of `DateTimeField` serializer fields. +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. -Default: `'iso-8601'` +May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. + +Default: `None'` #### DATETIME_INPUT_FORMATS 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. + Default: `['iso-8601']` #### DATE_FORMAT -A format string that should be used by default for rendering the output of `DateField` serializer fields. +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. -Default: `'iso-8601'` +May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. + +Default: `None` #### DATE_INPUT_FORMATS 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. + Default: `['iso-8601']` #### TIME_FORMAT -A format string that should be used by default for rendering the output of `TimeField` serializer fields. +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. -Default: `'iso-8601'` +Default: `None` #### TIME_INPUT_FORMATS 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. + Default: `['iso-8601']` --- @@ -243,3 +255,4 @@ The name of a parameter in the URL conf that may be used to provide a format suf Default: `'format'` [cite]: http://www.python.org/dev/peps/pep-0020/ +[strftime]: http://docs.python.org/2/library/time.html#time.strftime \ No newline at end of file -- cgit v1.2.3 From 13794baf7016f7d44daffb55d29e3dbc56f7612d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 22 Mar 2013 17:01:06 +0000 Subject: Bit of extra tidying and plenty of docs --- docs/api-guide/fields.md | 43 ++++++++++ docs/api-guide/serializers.md | 189 ++++++++++++++++++++++++++++-------------- 2 files changed, 168 insertions(+), 64 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 9a745cf1..4d73eec7 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -273,6 +273,49 @@ Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. --- +# Custom fields + +If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods. These two methods are used to convert between the intial datatype, and a primative, serializable datatype. Primative datatypes may be any of a number, string, date/time/datetime or None. They may also be any list or dictionary like object that only contains other primative objects. + +The `.to_native()` method is called to convert the initial datatype into a primative, serializable datatype. The `from_native()` method is called to restore a primative datatype into it's initial representation. + +## Examples + +Let's look at an example of serializing a class that represents an RGB color value: + + class Color(object): + """ + A color represented in the RGB colorspace. + """ + def __init__(self, red, green, blue): + assert(red >= 0 and green >= 0 and blue >= 0) + assert(red < 256 and green < 256 and blue < 256) + self.red, self.green, self.blue = red, green, blue + + class ColourField(serializers.WritableField): + """ + Color objects are serialized into "rgb(#, #, #)" notation. + """ + def to_native(self, obj): + return "rgb(%d, %d, %d)" % (obj.red, obj.green, obj.blue) + + def from_native(self, data): + data = data.strip('rgb(').rstrip(')') + red, green, blue = [int(col) for col in data.split(',')] + return Color(red, green, blue) + + +By default field values are treated as mapping to an attribute on the object. If you need to customize how the field value is accessed and set you need to override `.field_to_native()` and/or `.field_from_native()`. + +As an example, let's create a field that can be used represent the class name of the object being serialized: + + class ClassNameField(serializers.Field): + def field_to_native(self, obj, field_name): + """ + Serialize the object's class name. + """ + return obj.__class__ + [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index ee7208a3..42e81cad 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -87,27 +87,21 @@ By default, serializers must be passed values for all required fields or they wi serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True) # Update `instance` with partial data -## Serializing multiple objects - -To serialize a queryset or list of objects instead of a single object instance, you should pass the `many=True` flag when instantiating the serializer. - - queryset = Comment.objects.all() - serializer = CommentSerializer(queryset, many=True) - serializer.data - # [ - # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)}, - # {'email': u'jamie@example.com', 'content': u'baz', 'created': datetime.datetime(2013, 1, 12, 16, 12, 45, 104445)} - # ] - ## Validation -When deserializing data, you always need to call `is_valid()` before attempting to access the deserialized object. If any validation errors occur, the `.errors` property will contain a dictionary representing the resulting error messages. +When deserializing data, you always need to call `is_valid()` before attempting to access the deserialized object. If any validation errors occur, the `.errors` property will contain a dictionary representing the resulting error messages. For example: + + serializer = CommentSerializer(data={'email': 'foobar', 'content': 'baz'}) + serializer.is_valid() + # False + serializer.errors + # {'email': [u'Enter a valid e-mail address.'], 'created': [u'This field is required.']} Each key in the dictionary will be the field name, and the values will be lists of strings of any error messages corresponding to that field. The `non_field_errors` key may also be present, and will list any general validation errors. When deserializing a list of items, errors will be returned as a list of dictionaries representing each of the deserialized items. -### Field-level validation +#### Field-level validation You can specify custom field-level validation by adding `.validate_` methods to your `Serializer` subclass. These are analagous to `.clean_` methods on Django forms, but accept slightly different arguments. @@ -130,7 +124,7 @@ Your `validate_` methods should either just return the `attrs` dictio raise serializers.ValidationError("Blog post is not about Django") return attrs -### Object-level validation +#### Object-level validation To do any other validation that requires access to multiple fields, add a method called `.validate()` to your `Serializer` subclass. This method takes a single argument, which is the `attrs` dictionary. It should raise a `ValidationError` if necessary, or just return `attrs`. For example: @@ -151,26 +145,44 @@ To do any other validation that requires access to multiple fields, add a method ## Saving object state -Serializers also include a `.save()` method that you can override if you want to provide a method of persisting the state of a deserialized object. The default behavior of the method is to simply call `.save()` on the deserialized object instance. +To save the deserialized objects created by a serializer, call the `.save()` method: + + if serializer.is_valid(): + serializer.save() + +The default behavior of the method is to simply call `.save()` on the deserialized object instance. You can override the default save behaviour by overriding the `.save_object(obj)` method on the serializer class. The generic views provided by REST framework call the `.save()` method when updating or creating entities. ## Dealing with nested objects -The previous example is fine for dealing with objects that only have simple datatypes, but sometimes we also need to be able to represent more complex objects, -where some of the attributes of an object might not be simple datatypes such as strings, dates or integers. +The previous examples are fine for dealing with objects that only have simple datatypes, but sometimes we also need to be able to represent more complex objects, where some of the attributes of an object might not be simple datatypes such as strings, dates or integers. The `Serializer` class is itself a type of `Field`, and can be used to represent relationships where one object type is nested inside another. class UserSerializer(serializers.Serializer): - email = serializers.Field() - username = serializers.Field() + email = serializers.EmailField() + username = serializers.CharField(max_length=100) class CommentSerializer(serializers.Serializer): user = UserSerializer() - title = serializers.Field() - content = serializers.Field() - created = serializers.Field() + content = serializers.CharField(max_length=200) + created = serializers.DateTimeField() + +If a nested representation may optionally accept the `None` value you should pass the `required=False` flag to the nested serializer. + + class CommentSerializer(serializers.Serializer): + user = UserSerializer(required=False) # May be an anonymous user. + content = serializers.CharField(max_length=200) + created = serializers.DateTimeField() + +Similarly if a nested representation should be a list of items, you should the `many=True` flag to the nested serialized. + + class CommentSerializer(serializers.Serializer): + user = UserSerializer(required=False) + edits = EditItemSerializer(many=True) # A nested list of 'edit' items. + content = serializers.CharField(max_length=200) + created = serializers.DateTimeField() --- @@ -178,58 +190,107 @@ The `Serializer` class is itself a type of `Field`, and can be used to represent --- -## Including extra context +## Dealing with multiple objects -There are some cases where you need to provide extra context to the serializer in addition to the object being serialized. One common case is if you're using a serializer that includes hyperlinked relations, which requires the serializer to have access to the current request so that it can properly generate fully qualified URLs. +The `Serializer` class can also handle serializing or deserializing lists of objects. -You can provide arbitrary additional context by passing a `context` argument when instantiating the serializer. For example: +#### Serializing multiple objects - serializer = AccountSerializer(account, context={'request': request}) +To serialize a queryset or list of objects instead of a single object instance, you should pass the `many=True` flag when instantiating the serializer. You can then pass a queryset or list of objects to be serialized. + + queryset = Book.objects.all() + serializer = BookSerializer(queryset, many=True) serializer.data - # {'id': 6, 'owner': u'denvercoder9', 'created': datetime.datetime(2013, 2, 12, 09, 44, 56, 678870), 'details': 'http://example.com/accounts/6/details'} + # [ + # {'id': 0, 'title': 'The electric kool-aid acid test', 'author': 'Tom Wolfe'}, + # {'id': 1, 'title': 'If this is a man', 'author': 'Primo Levi'}, + # {'id': 2, 'title': 'The wind-up bird chronicle', 'author': 'Haruki Murakami'} + # ] -The context dictionary can be used within any serializer field logic, such as a custom `.to_native()` method, by accessing the `self.context` attribute. +#### Deserializing multiple objects for creation -## Creating custom fields - -If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods. These two methods are used to convert between the intial datatype, and a primative, serializable datatype. Primative datatypes may be any of a number, string, date/time/datetime or None. They may also be any list or dictionary like object that only contains other primative objects. - -The `.to_native()` method is called to convert the initial datatype into a primative, serializable datatype. The `from_native()` method is called to restore a primative datatype into it's initial representation. - -Let's look at an example of serializing a class that represents an RGB color value: - - class Color(object): - """ - A color represented in the RGB colorspace. - """ - def __init__(self, red, green, blue): - assert(red >= 0 and green >= 0 and blue >= 0) - assert(red < 256 and green < 256 and blue < 256) - self.red, self.green, self.blue = red, green, blue - - class ColourField(serializers.WritableField): - """ - Color objects are serialized into "rgb(#, #, #)" notation. - """ - def to_native(self, obj): - return "rgb(%d, %d, %d)" % (obj.red, obj.green, obj.blue) - - def from_native(self, data): - data = data.strip('rgb(').rstrip(')') - red, green, blue = [int(col) for col in data.split(',')] - return Color(red, green, blue) - +To deserialize a list of object data, and create multiple object instances in a single pass, you should also set the `many=True` flag, and pass a list of data to be deserialized. + +This allows you to write views that create multiple items when a `POST` request is made. -By default field values are treated as mapping to an attribute on the object. If you need to customize how the field value is accessed and set you need to override `.field_to_native()` and/or `.field_from_native()`. +For example: + + data = [ + {'title': 'The bell jar', 'author': 'Sylvia Plath'}, + {'title': 'For whom the bell tolls', 'author': 'Ernest Hemingway'} + ] + serializer = BookSerializer(data=data, many=True) + serializer.is_valid() + # True + serializer.save() # `.save()` will be called on each deserialized instance + +#### Deserializing multiple objects for update + +You can also deserialize a list of objects as part of a bulk update of multiple existing items. +In this case you need to supply both an existing list or queryset of items, as well as a list of data to update those items with. + +This allows you to write views that update or create multiple items when a `PUT` request is made. + + # Capitalizing the titles of the books + queryset = Book.objects.all() + data = [ + {'id': 3, 'title': 'The Bell Jar', 'author': 'Sylvia Plath'}, + {'id': 4, 'title': 'For Whom the Bell Tolls', 'author': 'Ernest Hemingway'} + ] + serializer = BookSerializer(queryset, data=data, many=True) + serializer.is_valid() + # True + serialize.save() # `.save()` will be called on each updated or newly created instance. + +Bulk updates will update any instances that already exist, and create new instances for data items that do not have a corresponding instance. + +When performing a bulk update you may want any items that are not present in the incoming data to be deleted. To do so, pass `allow_delete=True` to the serializer. + + serializer = BookSerializer(queryset, data=data, many=True, allow_delete=True) + serializer.is_valid() + # True + serializer.save() # `.save()` will be called on each updated or newly created instance. + # `.delete()` will be called on any other items in the `queryset`. + +Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating any objects found in the incoming data. + +#### How identity is determined when performing bulk updates -As an example, let's create a field that can be used represent the class name of the object being serialized: +Performing a bulk update is slightly more complicated than performing a bulk creation, because the serializer needs a way of determining how the items in the incoming data should be matched against the existing object instances. - class ClassNameField(serializers.Field): - def field_to_native(self, obj, field_name): +By default the serializer class will use the `id` key on the incoming data to determine the canonical identity of an object. If you need to change this behavior you should override the `get_identity` method on the `Serializer` class. For example: + + class AccountSerializer(serializers.Serializer): + slug = serializers.CharField(max_length=100) + created = serializers.DateTimeField() + ... # Various other fields + + def get_identity(self, data): """ - Serialize the object's class name. + This hook is required for bulk update. + We need to override the default, to use the slug as the identity. + + Note that the data has not yet been validated at this point, + so we need to deal gracefully with incorrect datatypes. """ - return obj.__class__ + try: + return data.get('slug', None) + except AttributeError: + return None + +To map the incoming data items to their corresponding object instances, the `.get_identity()` method will be called both against the incoming data, and against the serialized representation of the existing objects. + +## Including extra context + +There are some cases where you need to provide extra context to the serializer in addition to the object being serialized. One common case is if you're using a serializer that includes hyperlinked relations, which requires the serializer to have access to the current request so that it can properly generate fully qualified URLs. + +You can provide arbitrary additional context by passing a `context` argument when instantiating the serializer. For example: + + serializer = AccountSerializer(account, context={'request': request}) + serializer.data + # {'id': 6, 'owner': u'denvercoder9', 'created': datetime.datetime(2013, 2, 12, 09, 44, 56, 678870), 'details': 'http://example.com/accounts/6/details'} + +The context dictionary can be used within any serializer field logic, such as a custom `.to_native()` method, by accessing the `self.context` attribute. --- -- cgit v1.2.3 From 9a2ba4bf54d72452c2800bb3e51ea718a72250bc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 22 Mar 2013 21:37:51 +0000 Subject: Update release notes --- 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 c45fff88..f506c610 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -42,6 +42,8 @@ You can determine your currently installed version using `pip freeze`: ### Master +* Regression fix: Date and time fields return date/time objects by default. Fixes regressions caused by 2.2.2. See [#743][743] for more details. +* Bugfix: Fix 500 error is OAuth not attempted with OAuthAuthentication class installed. * `Serializer.save()` now supports arbitrary keyword args which are passed through to the object `.save()` method. Mixins use `force_insert` and `force_update` where appropriate, resulting in one less database query. ### 2.2.4 @@ -434,6 +436,7 @@ This change will not affect user code, so long as it's following the recommended [django-deprecation-policy]: https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy [defusedxml-announce]: http://blog.python.org/2013/02/announcing-defusedxml-fixes-for-xml.html [2.2-announcement]: 2.2-announcement.md +[743]: https://github.com/tomchristie/django-rest-framework/pull/743 [staticfiles14]: https://docs.djangoproject.com/en/1.4/howto/static-files/#with-a-template-tag [staticfiles13]: https://docs.djangoproject.com/en/1.3/howto/static-files/#with-a-template-tag [2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion -- cgit v1.2.3 From 624ce250cd666d647a8498dd6610ab84b459ee6f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 22 Mar 2013 22:06:38 +0000 Subject: Updating contribution docs (still wip) --- docs/topics/contributing.md | 136 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 131 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index 7fd61c10..a13f4461 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -4,12 +4,138 @@ > > — [Tim Berners-Lee][cite] -## Running the tests +There are many ways you can contribute to Django REST framework. We'd like it to be a community-led project, so please get involved and help shape the future of the project. -## Building the docs +# Community -## Managing compatibility issues +If you use and enjoy REST framework please consider [staring the project on GitHub][github], and [upvoting it on Django packages][django-packages]. Doing so helps potential new users see that the project is well used, and help us continue to attract new users. -**Describe compat module** +You might also consider writing a blog post on your experience with using REST framework, writing a tutorial about using the project with a particular javascript framework, or simply sharing the love on Twitter. -[cite]: http://www.w3.org/People/Berners-Lee/FAQ.html \ No newline at end of file +Other really great ways you can help move the community forward include helping answer questions on the [discussion group][google-group], or setting up an [email alert on StackOverflow][so-filter] so that you get notified of any new questions with the `django-rest-framework` tag. + +When answering questions make sure to help future contributors find their way around by hyperlinking wherever possible to related threads and tickets, and include backlinks from those items if relevant. + +# Issues + +Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. + +Some tips on good issue reporting: + +* When decribing issues try to phrase your ticket in terms of the *behavior* you think needs changing rather than the *code* you think need changing. +* Search the issue list first for related items, and make sure you're running the latest version of REST framework before reporting an issue. +* If reporting a bug, then try to include a pull request with a failing test case. This'll help us quickly identify if there is a valid issue, and make sure that it gets fixed more quickly if there is one. + + + +* TODO: Triage + +# Development + +* git clone & PYTHONPATH +* Pep8 +* Recommend editor that runs pep8 + +### Pull requests + +* Make pull requests early +* Describe branching + +### Managing compatibility issues + +* Describe compat module + +# Testing + +* Running the tests +* tox + +# Documentation + +The documentation for REST framework is built from the [Markdown][markdown] source files in [the docs directory][docs]. + +There are many great markdown editors that make working with the documentation really easy. The [Mou editor for Mac][mou] is one such editor that comes highly recommended. + +## Building the documentation + +To build the documentation, simply run the `mkdocs.py` script. + + ./mkdocs.py + +This will build the html output into the `html` directory. + +You can build the documentation and open a preview in a browser window by using the `-p` flag. + + ./mkdocs.py -p + +## Language style + +Documentation should be in American English. The tone of the documentation is very important - try to stick to a simple, plain, objective and well-balanced style where possible. + +Some other tips: + +* Keep paragraphs reasonably short. +* Use double spacing after the end of sentences. +* Don't use the abbreviations such as 'e.g..' but instead use long form, such as 'For example'. + +## Markdown style + +There are a couple of conventions you should follow when working on the documentation. + +##### 1. Headers + +Headers should use the hash style. For example: + + ### Some important topic + +The underline style should not be used. **Don't do this:** + + Some important topic + ==================== + +##### 2. Links + +Links should always use the reference style, with the referenced hyperlinks kept at the end of the document. + + Here is a link to [some other thing][other-thing]. + + More text... + + [other-thing]: http://example.com/other/thing + +This style helps keep the documentation source consistent and readable. + +If you are hyperlinking to another REST framework document, you should use a relative link, and link to the `.md` suffix. For example: + + [authentication]: ../api-guide/authentication.md + +Linking in this style means you'll be able to click the hyperlink in your markdown editor to open the referenced document. When the documentation is built, these links will be converted into regular links to HTML pages. + +##### 3. Notes + +If you want to draw attention to a note or warning, use a pair of enclosing lines, like so: + + --- + + **Note:** Make sure you do this thing. + + --- + +# Third party packages + +* Django reusable app + +# Core committers + +* Still use pull reqs +* Credits + +[cite]: http://www.w3.org/People/Berners-Lee/FAQ.html +[github]: https://github.com/tomchristie/django-rest-framework +[django-packages]: https://www.djangopackages.com/grids/g/api/ +[google-group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework +[so-filter]: http://stackexchange.com/filters/66475/rest-framework +[issues]: https://github.com/tomchristie/django-rest-framework/issues?state=open +[markdown]: http://daringfireball.net/projects/markdown/basics +[docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs +[mou]: http://mouapp.com/ -- cgit v1.2.3 From dab158e1fd827285032e331c10acc60e9719ace3 Mon Sep 17 00:00:00 2001 From: Sitong Peng Date: Mon, 25 Mar 2013 09:27:12 -0700 Subject: Tiny typo --- docs/tutorial/4-authentication-and-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md index 3ee755a2..878672bb 100644 --- a/docs/tutorial/4-authentication-and-permissions.md +++ b/docs/tutorial/4-authentication-and-permissions.md @@ -179,7 +179,7 @@ Now, if you open a browser again, you find that the 'DELETE' and 'PUT' actions o ## Authenticating with the API -Because we now have a set of permissions on the API, we need to authenticate our requests to it if we want to edit any snippets. We havn't set up any [authentication classes][authentication], so the defaults are currently applied, which are `SessionAuthentication` and `BasicAuthentication`. +Because we now have a set of permissions on the API, we need to authenticate our requests to it if we want to edit any snippets. We haven't set up any [authentication classes][authentication], so the defaults are currently applied, which are `SessionAuthentication` and `BasicAuthentication`. When we interact with the API through the web browser, we can login, and the browser session will then provide the required authentication for the requests. -- cgit v1.2.3 From dca24cd91488af62152b7e711cd6869b2d60c0ec Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 25 Mar 2013 16:44:36 +0000 Subject: Added @stoneg for typo fix #754. Thank you! --- 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 b533daa9..7dd9cd2c 100644 --- a/docs/topics/credits.md +++ b/docs/topics/credits.md @@ -112,6 +112,7 @@ The following people have helped make REST framework great. * Bouke Haarsma - [bouke] * Pierre Dulac - [dulaccc] * Dave Kuhn - [kuhnza] +* Sitong Peng - [stoneg] Many thanks to everyone who's contributed to the project. @@ -258,3 +259,4 @@ You can also contact [@_tomchristie][twitter] directly on twitter. [bouke]: https://github.com/bouke [dulaccc]: https://github.com/dulaccc [kuhnza]: https://github.com/kuhnza +[stoneg]: https://github.com/stoneg -- cgit v1.2.3 From 7eefcf7e53f2bc37733a601041f23d354c7729f5 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 25 Mar 2013 20:26:34 +0000 Subject: Bulk update, allow_add_remove flag --- docs/api-guide/serializers.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 42e81cad..aaff760e 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -242,17 +242,17 @@ This allows you to write views that update or create multiple items when a `PUT` # True serialize.save() # `.save()` will be called on each updated or newly created instance. -Bulk updates will update any instances that already exist, and create new instances for data items that do not have a corresponding instance. +By default bulk updates will be limited to updating instances that already exist in the provided queryset. -When performing a bulk update you may want any items that are not present in the incoming data to be deleted. To do so, pass `allow_delete=True` to the serializer. +When performing a bulk update you may want to allow new items to be created, and missing items to be deleted. To do so, pass `allow_add_remove=True` to the serializer. - serializer = BookSerializer(queryset, data=data, many=True, allow_delete=True) + serializer = BookSerializer(queryset, data=data, many=True, allow_add_remove=True) serializer.is_valid() # True - serializer.save() # `.save()` will be called on each updated or newly created instance. + serializer.save() # `.save()` will be called on updated or newly created instances. # `.delete()` will be called on any other items in the `queryset`. -Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating any objects found in the incoming data. +Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating existing objects. #### How identity is determined when performing bulk updates -- cgit v1.2.3 From 8387cb5d1655e4d29cf8bca1919038091427e584 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 25 Mar 2013 20:28:17 +0000 Subject: Docs fix --- 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 aaff760e..dfa0cace 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -252,7 +252,7 @@ When performing a bulk update you may want to allow new items to be created, and serializer.save() # `.save()` will be called on updated or newly created instances. # `.delete()` will be called on any other items in the `queryset`. -Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating existing objects. +Passing `allow_add_remove=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating existing objects. #### How identity is determined when performing bulk updates -- cgit v1.2.3 From 92c929094c88125ea4a2fd359ec99d2b4114f081 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 26 Mar 2013 07:48:53 +0000 Subject: Version 2.2.5 --- docs/api-guide/fields.md | 7 ++++++- docs/api-guide/serializers.md | 2 +- docs/topics/release-notes.md | 5 ++++- 3 files changed, 11 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 02876936..42f89f46 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -197,12 +197,16 @@ If you want to override this behavior, you'll need to declare the `DateTimeField class Meta: model = Comment +Note that by default, datetime representations are deteremined by the renderer in use, although this can be explicitly overridden as detailed below. + +In the case of JSON this means the default datetime representation uses the [ECMA 262 date time string specification][ecma262]. This is a subset of ISO 8601 which uses millisecond precision, and includes the 'Z' suffix for the UTC timezone, for example: `2013-01-29T12:34:56.123Z`. + **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. * `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 specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000'`) +DateTime format strings may either be [python strftime formats][strftime] which explicitly specifiy the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`) ## DateField @@ -318,5 +322,6 @@ As an example, let's create a field that can be used represent the class name of [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS +[ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior [iso8601]: http://www.w3.org/TR/NOTE-datetime diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index dfa0cace..1a3c3431 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -256,7 +256,7 @@ Passing `allow_add_remove=True` ensures that any update operations will complete #### How identity is determined when performing bulk updates -Performing a bulk update is slightly more complicated than performing a bulk creation, because the serializer needs a way of determining how the items in the incoming data should be matched against the existing object instances. +Performing a bulk update is slightly more complicated than performing a bulk creation, because the serializer needs a way to determine how the items in the incoming data should be matched against the existing object instances. By default the serializer class will use the `id` key on the incoming data to determine the canonical identity of an object. If you need to change this behavior you should override the `get_identity` method on the `Serializer` class. For example: diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index f506c610..e63aee49 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,8 +40,11 @@ You can determine your currently installed version using `pip freeze`: ## 2.2.x series -### Master +### 2.2.5 +**Date**: 26th March 2013 + +* Serializer support for bulk create and bulk update operations. * Regression fix: Date and time fields return date/time objects by default. Fixes regressions caused by 2.2.2. See [#743][743] for more details. * Bugfix: Fix 500 error is OAuth not attempted with OAuthAuthentication class installed. * `Serializer.save()` now supports arbitrary keyword args which are passed through to the object `.save()` method. Mixins use `force_insert` and `force_update` where appropriate, resulting in one less database query. -- cgit v1.2.3 From b2cea84fae4f721e8eb6432b3d1bab1309e21a00 Mon Sep 17 00:00:00 2001 From: Fernando Rocha Date: Wed, 27 Mar 2013 19:00:36 -0300 Subject: Complete remove of client checks from oauth2 Signed-off-by: Fernando Rocha --- docs/api-guide/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 541c6575..f1dd6f5f 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -294,7 +294,7 @@ The only thing needed to make the `OAuth2Authentication` class work is to insert The command line to test the authentication looks like: - curl -H "Authorization: Bearer " http://localhost:8000/api/?client_id=YOUR_CLIENT_ID\&client_secret=YOUR_CLIENT_SECRET + curl -H "Authorization: Bearer " http://localhost:8000/api/ --- -- cgit v1.2.3 From fb105d138cdcb178ed08c6616c0c25f4a03fb2e1 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 28 Mar 2013 14:54:25 +0000 Subject: Minor tweak --- docs/topics/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topics/contributing.md b/docs/topics/contributing.md index a13f4461..1d1fe892 100644 --- a/docs/topics/contributing.md +++ b/docs/topics/contributing.md @@ -18,7 +18,7 @@ When answering questions make sure to help future contributors find their way ar # Issues -Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. +It's really helpful if you make sure you address issues to the correct channel. Usage questions should be directed to the [discussion group][google-group]. Feature requests, bug reports and other issues should be raised on the GitHub [issue tracker][issues]. Some tips on good issue reporting: -- cgit v1.2.3 From d243538547982781635e01d9b6e74afbbd628e16 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 28 Mar 2013 14:54:42 +0000 Subject: Note on using curl with token auth --- docs/api-guide/authentication.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 541c6575..757b8673 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -119,6 +119,8 @@ To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in y ... 'rest_framework.authtoken' ) + +Make sure to run `manage.py syncdb` after changing your settings. You'll also need to create tokens for your users. @@ -140,6 +142,10 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401 WWW-Authenticate: Token +The `curl` command line tool may be useful for testing token authenticated APIs. For example: + + curl -X GET http://127.0.0.1:8000/api/example/ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' + --- **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. -- cgit v1.2.3 From 69cbafc64f65a23b4ed4c652a8965873a18929a0 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 28 Mar 2013 15:58:53 +0000 Subject: Add search and next/prev --- docs/css/default.css | 11 +++++++++++ docs/template.html | 31 +++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) (limited to 'docs') diff --git a/docs/css/default.css b/docs/css/default.css index c160b63d..173d70e0 100644 --- a/docs/css/default.css +++ b/docs/css/default.css @@ -277,3 +277,14 @@ footer a { footer a:hover { color: gray; } + +.btn-inverse { + background-image: -webkit-gradient(linear, 0 0, 0 100%, from(#606060), to(#404040)) !important; + background-image: -webkit-linear-gradient(top, #606060, #404040) !important; +} + +.modal-open .modal,.btn:focus{outline:none;} + +@media (max-width: 650px) { + .repo-link.btn-inverse {display: none;} +} diff --git a/docs/template.html b/docs/template.html index 3e0f29aa..7e929762 100644 --- a/docs/template.html +++ b/docs/template.html @@ -41,6 +41,9 @@
GitHub + Next + Previous + Search @@ -118,6 +121,34 @@
+ + + +
-- cgit v1.2.3 From ea33511260c65ed339d0a418a1c0e8aeaf3966d3 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 28 Mar 2013 16:02:20 +0000 Subject: Change strapline --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 5357536d..1d47f497 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,9 +9,9 @@ # Django REST framework -**Web APIs for Django, made easy.** +**Awesome web-browseable Web APIs for Django.** -Django REST framework is a flexible, powerful library that makes it incredibly easy to build Web APIs. It is designed as a modular and easy to customize architecture, based on Django's class based views. +Django REST framework is a flexible, powerful Web API toolkit. It is designed as a modular and easy to customize architecture, based on Django's class based views. APIs built using REST framework are fully self-describing and web browseable - a huge useability win for your developers. It also supports a wide range of media types, authentication and permission policies out of the box. -- cgit v1.2.3 From 89f3c1f8c4cd8466cf8108b5ca042750c0064dfb Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 29 Mar 2013 13:44:50 +0000 Subject: Update release-notes.md --- docs/topics/release-notes.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index e63aee49..6551c1af 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -40,6 +40,12 @@ You can determine your currently installed version using `pip freeze`: ## 2.2.x series +### Master + +* OAuth2 authentication no longer requires unneccessary URL parameters in addition to the token. +* URL hyperlinking in browseable API no handles more cases correctly. +* Bugfix: Fix regression with DjangoFilterBackend not worthing correctly with single object views. + ### 2.2.5 **Date**: 26th March 2013 -- cgit v1.2.3 From 2e06f5c832479c8802f8bd8654fba5597ee228cc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 29 Mar 2013 17:26:58 +0000 Subject: Fix typo --- docs/topics/release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md index 6551c1af..62c31358 100644 --- a/docs/topics/release-notes.md +++ b/docs/topics/release-notes.md @@ -43,7 +43,7 @@ You can determine your currently installed version using `pip freeze`: ### Master * OAuth2 authentication no longer requires unneccessary URL parameters in addition to the token. -* URL hyperlinking in browseable API no handles more cases correctly. +* URL hyperlinking in browseable API now handles more cases correctly. * Bugfix: Fix regression with DjangoFilterBackend not worthing correctly with single object views. ### 2.2.5 -- cgit v1.2.3 From c4eda3a653ada3110dd6c128f176b15071cb8cfe Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 30 Mar 2013 15:39:25 +0000 Subject: Tweak strapline --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.md b/docs/index.md index 1d47f497..4c2720c8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ # Django REST framework -**Awesome web-browseable Web APIs for Django.** +**Awesome web-browseable Web APIs.** Django REST framework is a flexible, powerful Web API toolkit. It is designed as a modular and easy to customize architecture, based on Django's class based views. -- cgit v1.2.3