diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/internals/deprecation.txt | 3 | ||||
| -rw-r--r-- | docs/ref/files/storage.txt | 52 | ||||
| -rw-r--r-- | docs/releases/1.10.txt | 23 |
3 files changed, 73 insertions, 5 deletions
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index d1f877aa06..6e593c787d 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -135,6 +135,9 @@ details on these changes. * Support for the template ``Context.has_key()`` method will be removed. +* Support for the ``django.core.files.storage.Storage.accessed_time()``, + ``created_time()``, and ``modified_time()`` methods will be removed. + .. _deprecation-removed-in-1.10: 1.10 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 diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index 8bff4e99c6..d4428ebfda 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -203,7 +203,13 @@ Email File Storage ~~~~~~~~~~~~ -* ... +* Storage backends now present a timezone-aware API with new methods + :meth:`~django.core.files.storage.Storage.get_accessed_time`, + :meth:`~django.core.files.storage.Storage.get_created_time`, and + :meth:`~django.core.files.storage.Storage.get_modified_time`. They return a + timezone-aware ``datetime`` if :setting:`USE_TZ` is ``True`` and a naive + ``datetime`` in the local timezone otherwise. + File Uploads ~~~~~~~~~~~~ @@ -623,6 +629,21 @@ added in Django 1.9:: This prevents confusion about an assignment resulting in an implicit save. +Non-timezone-aware :class:`~django.core.files.storage.Storage` API +------------------------------------------------------------------ + +The old, non-timezone-aware methods ``accessed_time()``, ``created_time()``, +and ``modified_time()`` are deprecated in favor of the new ``get_*_time()`` +methods. + +Third-party storage backends should implement the new methods and mark the old +ones as deprecated. Until then, the new ``get_*_time()`` methods on the base +:class:`~django.core.files.storage.Storage` class convert ``datetime``\s from +the old methods as required and emit a deprecation warning as they do so. + +Third-party storage backends may retain the old methods as long as they +wish to support earlier versions of Django. + :mod:`django.contrib.gis` ------------------------- |