Fixed #24510 -- Clarified FileField.upload_to docs.

1 files changed, 33 insertions, 11 deletions

diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 3746813bfb..3dd0e41e7a 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -598,19 +598,32 @@ Has two optional arguments:
 
 .. attribute:: FileField.upload_to
 
-    A local filesystem path that will be appended to your :setting:`MEDIA_ROOT`
-    setting to determine the value of the
-    :attr:`~django.db.models.fields.files.FieldFile.url` attribute.
+    This attribute provides a way of setting the upload directory and file name,
+    and can be set in two ways. In both cases, the value is passed to the
+    :meth:`Storage.save() <django.core.files.storage.Storage.save>` method.
 
-    This path may contain :func:`~time.strftime` formatting, which will be
-    replaced by the date/time of the file upload (so that uploaded files don't
-    fill up the given directory).
+    If you specify a string value, it may contain :func:`~time.strftime`
+    formatting, which will be replaced by the date/time of the file upload (so
+    that uploaded files don't fill up the given directory). For example::
 
-    This may also be a callable, such as a function, which will be called to
-    obtain the upload path, including the filename. This callable must be able
-    to accept two arguments, and return a Unix-style path (with forward slashes)
-    to be passed along to the storage system. The two arguments that will be
-    passed are:
+        class MyModel(models.Model):
+            # file will be uploaded to MEDIA_ROOT/uploads
+            upload = models.FileField(upload_to='uploads/')
+            # or...
+            # file will be saved to MEDIA_ROOT/uploads/2015/01/30
+            upload = models.FileField(upload_to='uploads/%Y/%m/%d/')
+
+    If you are using the default
+    :class:`~django.core.files.storage.FileSystemStorage`, the string value
+    will be appended to your :setting:`MEDIA_ROOT` path to form the location on
+    the local filesystem where uploaded files will be stored. If you are using
+    a different storage, check that storage's documentation to see how it
+    handles ``upload_to``.
+
+    ``upload_to`` may also be a callable, such as a function. This will be
+    called to obtain the upload path, including the filename. This callable must
+    accept two arguments and return a Unix-style path (with forward slashes)
+    to be passed along to the storage system. The two arguments are:
 
     ======================  ===============================================
     Argument                Description
@@ -630,6 +643,15 @@ Has two optional arguments:
                             when determining the final destination path.
     ======================  ===============================================
 
+    For example::
+
+        def user_directory_path(instance, filename):
+            # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
+            return 'user_{0}/{1}'.format(instance.user.id, filename)
+
+        class MyModel(models.Model):
+            upload = models.FileField(upload_to=user_directory_path)
+
 .. attribute:: FileField.storage
 
     A storage object, which handles the storage and retrieval of your