Fixed #26058 -- Delegated os.path bits of FileField's filename generation to the Storage.

3 files changed, 42 insertions, 0 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 23dd56576b..b3d03dd37a 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -165,6 +165,9 @@ details on these changes.
 
 * Support for ``Widget._format_value()`` will be removed.
 
+* ``FileField`` methods ``get_directory_name()`` and ``get_filename()`` 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 be197f7210..dd0670137c 100644
--- a/docs/ref/files/storage.txt
+++ b/docs/ref/files/storage.txt
@@ -164,6 +164,21 @@ The ``Storage`` class
         Returns a filename based on the ``name`` parameter that's suitable
         for use on the target storage system.
 
+    .. method:: generate_filename(filename)
+
+        .. versionadded:: 1.10
+
+        Validates the ``filename`` by calling :attr:`get_valid_name()` and
+        returns a filename to be passed to the :meth:`save` method.
+
+        The ``filename`` argument may include a path as returned by
+        :attr:`FileField.upload_to <django.db.models.FileField.upload_to>`.
+        In that case, the path won't be passed to :attr:`get_valid_name()` but
+        will be prepended back to the resulting name.
+
+        The default implementation uses :mod:`os.path` operations. Override
+        this method if that's not appropriate for your storage.
+
     .. method:: listdir(path)
 
         Lists the contents of the specified path, returning a 2-tuple of lists;
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index 8de01e4fc7..3eac9bb311 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -251,6 +251,10 @@ File Storage
   timezone-aware ``datetime`` if :setting:`USE_TZ` is ``True`` and a naive
   ``datetime`` in the local timezone otherwise.
 
+* The new :meth:`Storage.generate_filename()
+  <django.core.files.storage.Storage.generate_filename>` method makes it easier
+  to implement custom storages that don't use the ``os.path`` calls previously
+  in :class:`~django.db.models.FileField`.
 
 File Uploads
 ~~~~~~~~~~~~
@@ -789,6 +793,21 @@ Miscellaneous
 * The ``Model._deferred`` attribute is removed as dynamic model classes when
   using ``QuerySet.defer()`` and ``only()`` is removed.
 
+* :meth:`Storage.save() <django.core.files.storage.Storage.save>` no longer
+  replaces ``'\'`` with ``'/'``. This behavior is moved to
+  :class:`~django.core.files.storage.FileSystemStorage` since this is a storage
+  specific implementation detail. Any Windows user with a custom storage
+  implementation that relies on this behavior will need to implement it in the
+  custom storage's ``save()`` method.
+
+* Private :class:`~django.db.models.FileField` methods ``get_directory_name()``
+  and ``get_filename()`` are no longer called (and are now deprecated) which is
+  a backwards incompatible change for users overriding those methods on custom
+  fields. To adapt such code, override ``FileField.generate_filename()`` or
+  :meth:`Storage.generate_filename()
+  <django.core.files.storage.Storage.generate_filename>` instead. It
+  might be possible to use :attr:`~django.db.models.FileField.upload_to` also.
+
 .. _deprecated-features-1.10:
 
 Features deprecated in 1.10
@@ -998,6 +1017,11 @@ Miscellaneous
   :meth:`~django.forms.Widget.format_value`. The old name will work
   through a deprecation period.
 
+* Private ``FileField`` methods ``get_directory_name()`` and ``get_filename()``
+  are deprecated in favor of performing this work in
+  :meth:`Storage.generate_filename()
+  <django.core.files.storage.Storage.generate_filename>`).
+
 .. _removed-features-1.10:
 
 Features removed in 1.10