Ticket #12323: 12323.1.diff

django/conf/global_settings.py

@@ -265 +265 @@
 # 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',

django/conf/project_template/settings.py

@@ -43 +43 @@
 # 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/".

django/core/context_processors.py

@@ -10 +10 @@
 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):
     """

django/core/files/storage.py

@@ -10 +10 @@
 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 +128 @@
 
     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
 

new file django/utils/media.py

@@ +1 @@
+
+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

docs/faq/usage.txt

@@ -48 +48 @@
 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

docs/ref/files/file.txt

@@ -14 +14 @@
 
 .. 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
 

docs/ref/models/fields.txt

@@ -477 +477 @@
 
 .. 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 +526 @@
 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 +556 @@
 :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

docs/ref/settings.txt

@@ -1033 +1033 @@
 
 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 +1046 @@
 
 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 +1054 @@
 Good: ``"http://www.example.com/static/"``
 Bad: ``"http://www.example.com/static"``
 
+See also ``USER_MEDIA_URL``
+
 .. setting:: MIDDLEWARE_CLASSES
 
 MESSAGE_LEVEL
@@ -1757 +1762 @@
    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``

docs/topics/files.txt

@@ -8 +8 @@
 
 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 +129 @@
 ======================  ===================================================
 ``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