Fixed #23832 -- Added timezone aware Storage API.

New Storage.get_{accessed,created,modified}_time() methods convert the
naive time from now-deprecated {accessed,created_modified}_time()
methods into aware objects in UTC if USE_TZ=True.

1 files changed, 48 insertions, 4 deletions

diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt
index 71354829c7..be197f7210 100644
--- a/docs/ref/files/storage.txt
+++ b/docs/ref/files/storage.txt
@@ -73,10 +73,9 @@ The ``Storage`` class
     as necessary.
 
     .. note::
-        For methods returning naive ``datetime`` objects, the
-        effective timezone used will be the current value of
-        ``os.environ['TZ']``; note that this is usually set from
-        Django's :setting:`TIME_ZONE`.
+        When methods return naive ``datetime`` objects, the effective timezone
+        used will be the current value of ``os.environ['TZ']``; note that this
+        is usually set from Django's :setting:`TIME_ZONE`.
 
     .. method:: accessed_time(name)
 
@@ -85,6 +84,10 @@ The ``Storage`` class
         able to return the last accessed time this will raise
         ``NotImplementedError`` instead.
 
+        .. deprecated:: 1.10
+
+            Use :meth:`get_accessed_time` instead.
+
     .. method:: created_time(name)
 
         Returns a naive ``datetime`` object containing the creation
@@ -92,6 +95,10 @@ The ``Storage`` class
         return the creation time this will raise
         ``NotImplementedError`` instead.
 
+        .. deprecated:: 1.10
+
+            Use :meth:`get_created_time` instead.
+
     .. method:: delete(name)
 
         Deletes the file referenced by ``name``. If deletion is not supported
@@ -104,6 +111,17 @@ The ``Storage`` class
         in the storage system, or ``False`` if the name is available for a new
         file.
 
+    .. method:: get_accessed_time(name)
+
+        .. versionadded:: 1.10
+
+        Returns a :class:`~datetime.datetime` of the last accessed time of the
+        file. For storage systems unable to return the last accessed time this
+        will raise :exc:`NotImplementedError`.
+
+        If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
+        otherwise returns a naive ``datetime`` in the local timezone.
+
     .. method:: get_available_name(name, max_length=None)
 
         Returns a filename based on the ``name`` parameter that's free and
@@ -119,6 +137,28 @@ The ``Storage`` class
         7 character alphanumeric string is appended to the filename before
         the extension.
 
+    .. method:: get_created_time(name)
+
+        .. versionadded:: 1.10
+
+        Returns a :class:`~datetime.datetime` of the creation time of the file.
+        For storage systems unable to return the creation time this will raise
+        :exc:`NotImplementedError`.
+
+        If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
+        otherwise returns a naive ``datetime`` in the local timezone.
+
+    .. method:: get_modified_time(name)
+
+        .. versionadded:: 1.10
+
+        Returns a :class:`~datetime.datetime` of the last modified time of the
+        file. For storage systems unable to return the last modified time this
+        will raise :exc:`NotImplementedError`.
+
+        If :setting:`USE_TZ` is ``True``, returns an aware ``datetime``,
+        otherwise returns a naive ``datetime`` in the local timezone.
+
     .. method:: get_valid_name(name)
 
         Returns a filename based on the ``name`` parameter that's suitable
@@ -138,6 +178,10 @@ The ``Storage`` class
         the last modified time, this will raise
         ``NotImplementedError`` instead.
 
+        .. deprecated:: 1.10
+
+            Use :meth:`get_modified_time` instead.
+
     .. method:: open(name, mode='rb')
 
         Opens the file given by ``name``. Note that although the returned file