Skip to content

Commit 641e2b4

Browse files
committed
Add base doc for DurationField format
1 parent ccfe0a9 commit 641e2b4

File tree

2 files changed

+15
-3
lines changed

2 files changed

+15
-3
lines changed

docs/api-guide/fields.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -377,13 +377,16 @@ A Duration representation.
377377
Corresponds to `django.db.models.fields.DurationField`
378378

379379
The `validated_data` for these fields will contain a `datetime.timedelta` instance.
380-
The representation is a string following this format `'[DD] [HH:[MM:]]ss[.uuuuuu]'`.
381380

382-
**Signature:** `DurationField(max_value=None, min_value=None)`
381+
**Signature:** `DurationField(format=api_settings.DURATION_FORMAT, max_value=None, min_value=None)`
383382

383+
* `format` - A string representing the output format. If not specified, this defaults to the same value as the `DURATION_FORMAT` settings key, which will be `'standard'` 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 `timedelta` objects should be returned by `to_representation`. In this case the date encoding will be determined by the renderer.
384384
* `max_value` Validate that the duration provided is no greater than this value.
385385
* `min_value` Validate that the duration provided is no less than this value.
386386

387+
#### `DurationField` format strings
388+
Format strings may either be the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style intervals should be used (eg `'P4DT1H15M20S'`), or the special string `'standard'`, which indicates that Django interval format `'[DD] [HH:[MM:]]ss[.uuuuuu]'` hould be used (eg: `'4 1:15:20'`).
389+
387390
---
388391

389392
# Choice selection fields
@@ -552,7 +555,7 @@ For further examples on `HiddenField` see the [validators](validators.md) docume
552555

553556
---
554557

555-
**Note:** `HiddenField()` does not appear in `partial=True` serializer (when making `PATCH` request). This behavior might change in future, follow updates on [github discussion](https://github.com/encode/django-rest-framework/discussions/8259).
558+
**Note:** `HiddenField()` does not appear in `partial=True` serializer (when making `PATCH` request). This behavior might change in future, follow updates on [github discussion](https://github.com/encode/django-rest-framework/discussions/8259).
556559

557560
---
558561

docs/api-guide/settings.md

+9
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,15 @@ May be a list including the string `'iso-8601'` or Python [strftime format][strf
314314

315315
Default: `['iso-8601']`
316316

317+
318+
#### DURATION_FORMAT
319+
320+
A format string that should be used by default for rendering the output of `DurationField` serializer fields. If `None`, then `DurationField` serializer fields will return Python `timedelta` objects, and the duration encoding will be determined by the renderer.
321+
322+
May be any of `None`, `'iso-8601'` or `'standard'` (the format accepted by `django.utils.dateparse.parse_duration`).
323+
324+
Default: `'standard'`
325+
317326
---
318327

319328
## Encodings

0 commit comments

Comments
 (0)