diff -r 4dd0391a8f6b django/conf/global_settings.py --- a/django/conf/global_settings.py Mon May 24 19:10:30 2010 +0000 +++ b/django/conf/global_settings.py Fri May 28 13:14:10 2010 +0100 @@ -265,6 +265,14 @@ # Example: "http://media.lawrence.com" MEDIA_URL = '' +# Absolute path to the directory that holds user uploaded media. +# If None, this will default to MEDIA_ROOT +USER_MEDIA_ROOT = None + +# URL that handles the media serverd from USER_MEDIA_ROOT +# If None, this will default to MEDIA_URL +USER_MEDIA_URL = None + # List of upload handler classes to be applied in order. FILE_UPLOAD_HANDLERS = ( 'django.core.files.uploadhandler.MemoryFileUploadHandler', diff -r 4dd0391a8f6b django/conf/project_template/settings.py --- a/django/conf/project_template/settings.py Mon May 24 19:10:30 2010 +0000 +++ b/django/conf/project_template/settings.py Fri May 28 13:14:10 2010 +0100 @@ -43,15 +43,20 @@ # calendars according to the current locale USE_L10N = True -# Absolute path to the directory that holds media. -# Example: "/home/media/media.lawrence.com/" -MEDIA_ROOT = '' - # URL that handles the media served from MEDIA_ROOT. Make sure to use a # trailing slash if there is a path component (optional in other cases). # Examples: "http://media.lawrence.com", "http://example.com/media/" MEDIA_URL = '' +# Absolute path to the directory that holds user uploaded media. +# Example: "/home/media/media.lawrence.com/" +USER_MEDIA_ROOT = '' + +# URL that handles the media served from USER_MEDIA_ROOT. Make sure to use a +# trailing slash if there is a path component (optional in other cases). +# Examples: "http://media.lawrence.com", "http://example.com/media/" +USER_MEDIA_URL = '' + # URL prefix for admin media -- CSS, JavaScript and images. Make sure to use a # trailing slash. # Examples: "http://foo.com/media/", "/media/". diff -r 4dd0391a8f6b django/core/context_processors.py --- a/django/core/context_processors.py Mon May 24 19:10:30 2010 +0000 +++ b/django/core/context_processors.py Fri May 28 13:14:10 2010 +0100 @@ -10,6 +10,7 @@ from django.conf import settings from django.middleware.csrf import get_token from django.utils.functional import lazy +from django.utils.media import get_user_media_url def auth(request): """ diff -r 4dd0391a8f6b django/core/files/storage.py --- a/django/core/files/storage.py Mon May 24 19:10:30 2010 +0000 +++ b/django/core/files/storage.py Fri May 28 13:14:10 2010 +0100 @@ -10,6 +10,7 @@ from django.utils.encoding import force_unicode from django.utils.functional import LazyObject from django.utils.importlib import import_module +from django.utils.media import get_user_media_url, get_user_media_root from django.utils.text import get_valid_filename from django.utils._os import safe_join @@ -127,9 +128,9 @@ def __init__(self, location=None, base_url=None): if location is None: - location = settings.MEDIA_ROOT + location = get_user_media_root() if base_url is None: - base_url = settings.MEDIA_URL + base_url = get_user_media_url() self.location = os.path.abspath(location) self.base_url = base_url diff -r 4dd0391a8f6b django/utils/media.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/django/utils/media.py Fri May 28 13:14:10 2010 +0100 @@ -0,0 +1,25 @@ + +def get_user_media_url(): + from django.conf import settings + url = settings.USER_MEDIA_URL + if url is None: + import warnings + warnings.warn( + 'Please define the USER_MEDIA_URL setting (falling back to MEDIA_URL for now).', + PendingDeprecationWarning + ) + return settings.MEDIA_ROOT + return settings.MEDIA_URL + return url + +def get_user_media_root(): + from django.conf import settings + root = settings.USER_MEDIA_ROOT + if root is None: + import warnings + warnings.warn( + 'The MEDIA_ROOT setting has been deprecated in favor of USER_MEDIA_ROOT.', + PendingDeprecationWarning + ) + return settings.MEDIA_ROOT + return root diff -r 4dd0391a8f6b docs/faq/usage.txt --- a/docs/faq/usage.txt Mon May 24 19:10:30 2010 +0000 +++ b/docs/faq/usage.txt Fri May 28 13:14:10 2010 +0100 @@ -48,21 +48,21 @@ Using a :class:`~django.db.models.FileField` or an :class:`~django.db.models.ImageField` in a model takes a few steps: - #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as - the full path to a directory where you'd like Django to store uploaded + #. In your settings file, you'll need to define :setting:`USER_MEDIA_ROOT` + as the full path to a directory where you'd like Django to store uploaded files. (For performance, these files are not stored in the database.) - Define :setting:`MEDIA_URL` as the base public URL of that directory. - Make sure that this directory is writable by the Web server's user - account. + Define :setting:`USER_MEDIA_URL` as the base public URL of that + directory. Make sure that this directory is writable by the Web server's + user account. #. Add the :class:`~django.db.models.FileField` or :class:`~django.db.models.ImageField` to your model, making sure to define the :attr:`~django.db.models.FileField.upload_to` option to tell - Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload - files. + Django to which subdirectory of :setting:`USER_MEDIA_ROOT` it should + upload files. - #. All that will be stored in your database is a path to the file - (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the + #. All that will be stored in your database is a path to the file (relative + to :setting:`USER_MEDIA_ROOT`). You'll most likely want to use the convenience :attr:`~django.core.files.File.url` attribute provided by Django. For example, if your :class:`~django.db.models.ImageField` is called ``mug_shot``, you can get the absolute URL to your image in a diff -r 4dd0391a8f6b docs/ref/files/file.txt --- a/docs/ref/files/file.txt Mon May 24 19:10:30 2010 +0000 +++ b/docs/ref/files/file.txt Fri May 28 13:14:10 2010 +0100 @@ -14,7 +14,7 @@ .. attribute:: File.name - The name of file including the relative path from :setting:`MEDIA_ROOT`. + The name of file including the relative path from :setting:`USER_MEDIA_ROOT`. .. attribute:: File.path diff -r 4dd0391a8f6b docs/ref/models/fields.txt --- a/docs/ref/models/fields.txt Mon May 24 19:10:30 2010 +0000 +++ b/docs/ref/models/fields.txt Fri May 28 13:14:10 2010 +0100 @@ -477,9 +477,9 @@ .. 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.core.files.File.url` - attribute. + A local filesystem path that will be appended to your + :setting:`USER_MEDIA_ROOT` setting to determine the value of the + :attr:`~django.core.files.File.url` attribute. This path may contain `strftime formatting`_, which will be replaced by the date/time of the file upload (so that uploaded files don't fill up the given @@ -526,24 +526,25 @@ Using a :class:`FileField` or an :class:`ImageField` (see below) in a model takes a few steps: - 1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the - full path to a directory where you'd like Django to store uploaded files. - (For performance, these files are not stored in the database.) Define - :setting:`MEDIA_URL` as the base public URL of that directory. Make sure - that this directory is writable by the Web server's user account. + 1. In your settings file, you'll need to define :setting:`USER_MEDIA_ROOT` + as the full path to a directory where you'd like Django to store uploaded + files. (For performance, these files are not stored in the database.) + Define :setting:`USER_MEDIA_URL` as the base public URL of that + directory. Make sure that this directory is writable by the Web server's + user account. 2. Add the :class:`FileField` or :class:`ImageField` to your model, making sure to define the :attr:`~FileField.upload_to` option to tell Django - to which subdirectory of :setting:`MEDIA_ROOT` it should upload files. + to which subdirectory of :setting:`USER_MEDIA_ROOT` it should upload files. 3. All that will be stored in your database is a path to the file - (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the + (relative to :setting:`USER_MEDIA_ROOT`). You'll most likely want to use the convenience :attr:`~django.core.files.File.url` function provided by Django. For example, if your :class:`ImageField` is called ``mug_shot``, you can get the absolute URL to your image in a template with ``{{ object.mug_shot.url }}``. -For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and +For example, say your :setting:`USER_MEDIA_ROOT` is set to ``'/home/media'``, and :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of :attr:`~FileField.upload_to` is `strftime formatting`_; ``'%Y'`` is the four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit @@ -555,6 +556,10 @@ :attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url` and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`. +.. versionchanged:: 1.3 + Up to Django 1.2, the ``MEDIA_ROOT`` and ``MEDIA_URL`` settings were used for + file storage, instead of ``USER_MEDIA_ROOT`` and ``USER_MEDIA_URL`` + Note that whenever you deal with uploaded files, you should pay close attention to where you're uploading them and what type of files they are, to avoid security holes. *Validate all uploaded files* so that you're sure the files are diff -r 4dd0391a8f6b docs/ref/settings.txt --- a/docs/ref/settings.txt Mon May 24 19:10:30 2010 +0000 +++ b/docs/ref/settings.txt Fri May 28 13:14:10 2010 +0100 @@ -1033,9 +1033,12 @@ Default: ``''`` (Empty string) -Absolute path to the directory that holds media for this installation. +Absolute path to the directory that holds static media for this installation. Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``. +.. deprecated:: 1.3 + This is now used only for backwards compatibility, see ``USER_MEDIA_ROOT`` + .. setting:: MEDIA_URL MEDIA_URL @@ -1043,7 +1046,7 @@ Default: ``''`` (Empty string) -URL that handles the media served from ``MEDIA_ROOT``. +URL that handles the static media stored in ``MEDIA_ROOT``. Example: ``"http://media.lawrence.com"`` Note that this should have a trailing slash if it has a path component. @@ -1051,6 +1054,8 @@ Good: ``"http://www.example.com/static/"`` Bad: ``"http://www.example.com/static"`` +See also ``USER_MEDIA_URL`` + .. setting:: MIDDLEWARE_CLASSES MESSAGE_LEVEL @@ -1757,3 +1762,33 @@ This setting has been replaced by :setting:`TEST_NAME` in :setting:`DATABASES`. +.. setting:: USER_MEDIA_ROOT + +USER_MEDIA_ROOT +--------------- + +.. versionadded:: 1.3 + +Default: ``None`` + +Absolute path to the directory that holds user uploaded media for this installation. +Example: ``"/home/media/media.lawrence.com/user/"`` See also ``USER_MEDIA_URL``. + +If ``None``, the value of ``MEDIA_ROOT`` is used as a fallback for this setting. + +.. setting:: USER_MEDIA_URL + +USER_MEDIA_URL +-------------- + +Default: ``None`` + +URL that handles the media stored in ``USER_MEDIA_ROOT``. +Example: ``"http://media.lawrence.com"`` + +Note that this should have a trailing slash if it has a path component. + +Good: ``"http://www.example.com/usermedia/"`` +Bad: ``"http://www.example.com/usermedia"`` + +See also ``MEDIA_URL`` diff -r 4dd0391a8f6b docs/topics/files.txt --- a/docs/topics/files.txt Mon May 24 19:10:30 2010 +0000 +++ b/docs/topics/files.txt Fri May 28 13:14:10 2010 +0100 @@ -8,9 +8,13 @@ This document describes Django's file access APIs. -By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and -:setting:`MEDIA_URL` settings. The examples below assume that you're using these -defaults. +.. versionchanged:: 1.3 + Up to Django 1.2, the ``MEDIA_ROOT`` and ``MEDIA_URL`` settings were used for + file storage, instead of ``USER_MEDIA_ROOT`` and ``USER_MEDIA_URL`` + +By default, Django stores files locally, using the :setting:`USER_MEDIA_ROOT` +and :setting:`USER_MEDIA_URL` settings. The examples below assume that you're +using these defaults. However, Django provides ways to write custom `file storage systems`_ that allow you to completely customize where and how Django stores files. The @@ -125,14 +129,14 @@ ====================== =================================================== ``location`` Optional. Absolute path to the directory that will hold the files. If omitted, it will be set to the - value of your ``MEDIA_ROOT`` setting. + value of your ``USER_MEDIA_ROOT`` setting. ``base_url`` Optional. URL that serves the files stored at this location. If omitted, it will default to the value - of your ``MEDIA_URL`` setting. + of your ``USER_MEDIA_URL`` setting. ====================== =================================================== For example, the following code will store uploaded files under -``/media/photos`` regardless of what your ``MEDIA_ROOT`` setting is:: +``/media/photos`` regardless of what your ``USER_MEDIA_ROOT`` setting is:: from django.db import models from django.core.files.storage import FileSystemStorage