From 57554442fe3e209c135e15dda4ea45123e579e58 Mon Sep 17 00:00:00 2001
From: Marc Tamlyn <marc.tamlyn@gmail.com>
Date: Thu, 24 Jul 2014 13:57:24 +0100
Subject: Fixed #2443 -- Added DurationField.

A field for storing periods of time - modeled in Python by timedelta. It
is stored in the native interval data type on PostgreSQL and as a bigint
of microseconds on other backends.

Also includes significant changes to the internals of time related maths
in expressions, including the removal of DateModifierNode.

Thanks to Tim and Josh in particular for reviews.
---
 docs/ref/forms/fields.txt  | 17 +++++++++++++++++
 docs/ref/models/fields.txt | 17 +++++++++++++++++
 docs/ref/utils.txt         |  9 +++++++++
 3 files changed, 43 insertions(+)

(limited to 'docs/ref')

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 0f13adc249..b63826d9b1 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -546,6 +546,23 @@ For each field, we describe the default widget used if you don't specify
 
         The maximum number of decimal places permitted.
 
+``DurationField``
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.8
+
+.. class:: DurationField(**kwargs)
+
+    * Default widget: :class:`TextInput`
+    * Empty value: ``None``
+    * Normalizes to: A Python :class:`~python:datetime.timedelta`.
+    * Validates that the given value is a string which can be converted into a
+      ``timedelta``.
+    * Error message keys: ``required``, ``invalid``.
+
+    Accepts any format understood by
+    :func:`~django.utils.dateparse.parse_duration`.
+
 ``EmailField``
 ~~~~~~~~~~~~~~
 
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 2429406d68..203241ae5f 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -542,6 +542,23 @@ The default form widget for this field is a :class:`~django.forms.TextInput`.
     :class:`FloatField` and :class:`DecimalField` classes, please
     see :ref:`FloatField vs. DecimalField <floatfield_vs_decimalfield>`.
 
+``DurationField``
+-----------------
+
+.. versionadded:: 1.8
+
+.. class:: DurationField([**options])
+
+A field for storing periods of time - modeled in Python by
+:class:`~python:datetime.timedelta`. When used on PostgreSQL, the data type
+used is an ``interval``, otherwise a ``bigint`` of microseconds is used.
+
+.. note::
+
+    Arithmetic with ``DurationField`` works in most cases. However on all
+    databases other than PostgreSQL, comparing the value of a ``DurationField``
+    to arithmetic on ``DateTimeField`` instances will not work as expected.
+
 ``EmailField``
 --------------
 
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 5939ff6fb1..327f44bbfc 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -158,6 +158,15 @@ The functions defined in this module share the following properties:
     ``tzinfo`` attribute is a :class:`~django.utils.tzinfo.FixedOffset`
     instance.
 
+.. function:: parse_duration(value)
+
+    .. versionadded:: 1.8
+
+    Parses a string and returns a :class:`datetime.timedelta`.
+
+    Expects data in the format ``"DD HH:MM:SS.uuuuuu"`` or as specified by ISO
+    8601 (e.g. ``P4DT1H15M20S`` which is equivalent to ``4 1:15:20``).
+
 ``django.utils.decorators``
 ===========================
 
-- 
cgit v1.3