From 98c5370ef673bc83deaf24c197e0bb22a75071e3 Mon Sep 17 00:00:00 2001 From: Matt Seymour Date: Thu, 26 Mar 2015 08:33:01 +0000 Subject: [PATCH] Fixed #24510 -- Clarified FileField.upload_to docs. --- docs/ref/models/fields.txt | 44 ++++++++++++++++++++++++++++---------- 1 file 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() ` 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_/ + 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