From 5d2e92fafe7b1d887c3972bb07726cdf972f2ace Mon Sep 17 00:00:00 2001 From: Radoslav Georgiev Date: Tue, 26 Jul 2016 18:22:25 +0300 Subject: [PATCH 1/3] Change signature of `DateTimeField` and add detail to `format` - Signature is saying `format=None` while it is `format=empty`. This can lead to confusion, thinking the default behavior of the field is with `format=None` --- docs/api-guide/fields.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index f95608afb..576e4e92e 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -290,9 +290,9 @@ A date and time representation. Corresponds to `django.db.models.fields.DateTimeField`. -**Signature:** `DateTimeField(format=None, input_formats=None)` +**Signature:** `DateTimeField(format=empty, input_formats=None)` -* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. 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 the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer. The default value is [`empty`](https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/fields.py#L42), not `None`. You need to explicitly set `format=None` in order to get Python `datetime` object. * `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']`. #### `DateTimeField` format strings. From a15c02f7013af332b991b5a56b02535cc2d87b10 Mon Sep 17 00:00:00 2001 From: Radoslav Georgiev Date: Wed, 27 Jul 2016 18:50:38 +0300 Subject: [PATCH 2/3] Set default to `DATETIME_FORMAT` * Split the two cases for `format` into sub-bullets for easier reading of the documentation --- docs/api-guide/fields.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 576e4e92e..edc6cf0ce 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -290,9 +290,11 @@ A date and time representation. Corresponds to `django.db.models.fields.DateTimeField`. -**Signature:** `DateTimeField(format=empty, input_formats=None)` +**Signature:** `DateTimeField(format=DATETIME_FORMAT, input_formats=None)` -* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. In this case the datetime encoding will be determined by the renderer. The default value is [`empty`](https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/fields.py#L42), not `None`. You need to explicitly set `format=None` in order to get Python `datetime` object. +* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DATETIME_FORMAT` settings key, which will be `'iso-8601'` unless set. + * Setting to a format string indicates that `to_representation` return values should be coerced to string output. Format strings are described below. + * Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. 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']`. #### `DateTimeField` format strings. From 835284df6feec7cf0c8f7fd4c8ed5c4d7996e2e9 Mon Sep 17 00:00:00 2001 From: Radoslav Georgiev Date: Wed, 27 Jul 2016 22:15:29 +0300 Subject: [PATCH 3/3] Add code example for default and `format=None` --- docs/api-guide/fields.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index edc6cf0ce..4d11b7a43 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -297,6 +297,46 @@ Corresponds to `django.db.models.fields.DateTimeField`. * Setting this value to `None` indicates that Python `datetime` objects should be returned by `to_representation`. 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']`. +For example, lets have the following model: + +```python +from django.db import models + + +class Comment(models.Model): + created_at = models.DateTimeField(auto_now_add=True) +``` + +And the following serializers: + +```python +from rest_framework import serializers + + +class CommentSerializerWithDefaultDateTimeField(serializers.Serializer): + created_at = serializers.DateTimeField() + + +class CommentSerializerWithFormatNone(serializers.Serializer): + created_at = serializers.DateTimeField(format=None) +``` + +Now we have the following types: + +```python +import datetime + +c = Comment.objects.create() + +s1 = CommentSerializerWithDefaultDateTimeField(c) +s2 = CommentSerializerWithFormatNone(c) + + +assert type(s1.data['created_at']) is str +assert type(s2.data['created_at']) is datetime.datetime +``` + + #### `DateTimeField` format strings. 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'`)