1 import os

     2 import errno

     3 import urlparse

     4 

     5 from django.conf import settings

     6 from django.core.exceptions import ImproperlyConfigured, SuspiciousOperation

     7 from django.core.files import locks, File

     8 from django.core.files.move import file_move_safe

     9 from django.utils.encoding import force_unicode, smart_str

    10 from django.utils.functional import LazyObject

    11 from django.utils.importlib import import_module

    12 from django.utils.text import get_valid_filename

    13 from django.utils._os import safe_join

    14 

    15 __all__ = ('Storage', 'FileSystemStorage', 'DefaultStorage', 'default_storage')

    16 

    17 class Storage(object):

    18     """

    19     A base storage class, providing some default behaviors that all other

    20     storage systems can inherit or override, as necessary.

    21     """

    22 

    23     # The following methods represent a public interface to private methods.

    24     # These shouldn't be overridden by subclasses unless absolutely necessary.

    25 

    26     def open(self, name, mode='rb', mixin=None):

    27         """

    28         Retrieves the specified file from storage, using the optional mixin

    29         class to customize what features are available on the File returned.

    30         """

    31         file = self._open(name, mode)

    32         if mixin:

    33             # Add the mixin as a parent class of the File returned from storage.

    34             file.__class__ = type(mixin.__name__, (mixin, file.__class__), {})

    35         return file

    36 

    37     def save(self, name, content):

    38         """

    39         Saves new content to the file specified by name. The content should be a

    40         proper File object, ready to be read from the beginning.

    41         """

    42         # Get the proper name for the file, as it will actually be saved.

    43         if name is None:

    44             name = content.name

    45 

    46         name = self.get_available_name(name)

    47         name = self._save(name, content)

    48 

    49         # Store filenames with forward slashes, even on Windows

    50         return force_unicode(name.replace('\\', '/'))

    51 

    52     # These methods are part of the public API, with default implementations.

    53 

    54     def get_valid_name(self, name):

    55         """

    56         Returns a filename, based on the provided filename, that's suitable for

    57         use in the target storage system.

    58         """

    59         return get_valid_filename(name)

    60 

    61     def get_available_name(self, name):

    62         """

    63         Returns a filename that's free on the target storage system, and

    64         available for new content to be written to.

    65         """

    66         dir_name, file_name = os.path.split(name)

    67         file_root, file_ext = os.path.splitext(file_name)

    68         # If the filename already exists, keep adding an underscore (before the

    69         # file extension, if one exists) to the filename until the generated

    70         # filename doesn't exist.

    71         while self.exists(name):

    72             file_root += '_'

    73             # file_ext includes the dot.

    74             name = os.path.join(dir_name, file_root + file_ext)

    75         return name

    76 

    77     def path(self, name):

    78         """

    79         Returns a local filesystem path where the file can be retrieved using

    80         Python's built-in open() function. Storage systems that can't be

    81         accessed using open() should *not* implement this method.

    82         """

    83         raise NotImplementedError("This backend doesn't support absolute paths.")

    84 

    85     # The following methods form the public API for storage systems, but with

    86     # no default implementations. Subclasses must implement *all* of these.

    87 

    88     def delete(self, name):

    89         """

    90         Deletes the specified file from the storage system.

    91         """

    92         raise NotImplementedError()

    93 

    94     def exists(self, name):

    95         """

    96         Returns True if a file referened by the given name already exists in the

    97         storage system, or False if the name is available for a new file.

    98         """

    99         raise NotImplementedError()

   100 

   101     def listdir(self, path):

   102         """

   103         Lists the contents of the specified path, returning a 2-tuple of lists;

   104         the first item being directories, the second item being files.

   105         """

   106         raise NotImplementedError()

   107 

   108     def size(self, name):

   109         """

   110         Returns the total size, in bytes, of the file specified by name.

   111         """

   112         raise NotImplementedError()

   113 

   114     def url(self, name):

   115         """

   116         Returns an absolute URL where the file's contents can be accessed

   117         directly by a web browser.

   118         """

   119         raise NotImplementedError()

   120 

   121     # Needed by django.utils.functional.LazyObject (via DefaultStorage).

   122     def get_all_members(self):

   123         return self.__members__

   124 

   125 class FileSystemStorage(Storage):

   126     """

   127     Standard filesystem storage

   128     """

   129 

   130     def __init__(self, location=None, base_url=None):

   131         if location is None:

   132             location = settings.MEDIA_ROOT

   133         if base_url is None:

   134             base_url = settings.MEDIA_URL

   135         self.location = os.path.abspath(location)

   136         self.base_url = base_url

   137 

   138     def _open(self, name, mode='rb'):

   139         return File(open(self.path(name), mode))

   140 

   141     def _save(self, name, content):

   142         full_path = self.path(name)

   143 

   144         directory = os.path.dirname(full_path)

   145         if not os.path.exists(directory):

   146             os.makedirs(directory)

   147         elif not os.path.isdir(directory):

   148             raise IOError("%s exists and is not a directory." % directory)

   149 

   150         # There's a potential race condition between get_available_name and

   151         # saving the file; it's possible that two threads might return the

   152         # same name, at which point all sorts of fun happens. So we need to

   153         # try to create the file, but if it already exists we have to go back

   154         # to get_available_name() and try again.

   155 

   156         while True:

   157             try:

   158                 # This file has a file path that we can move.

   159                 if hasattr(content, 'temporary_file_path'):

   160                     file_move_safe(content.temporary_file_path(), full_path)

   161                     content.close()

   162 

   163                 # This is a normal uploadedfile that we can stream.

   164                 else:

   165                     # This fun binary flag incantation makes os.open throw an

   166                     # OSError if the file already exists before we open it.

   167                     fd = os.open(full_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, 'O_BINARY', 0))

   168                     try:

   169                         locks.lock(fd, locks.LOCK_EX)

   170                         for chunk in content.chunks():

   171                             os.write(fd, chunk)

   172                     finally:

   173                         locks.unlock(fd)

   174                         os.close(fd)

   175             except OSError, e:

   176                 if e.errno == errno.EEXIST:

   177                     # Ooops, the file exists. We need a new file name.

   178                     name = self.get_available_name(name)

   179                     full_path = self.path(name)

   180                 else:

   181                     raise

   182             else:

   183                 # OK, the file save worked. Break out of the loop.

   184                 break

   185 

   186         if settings.FILE_UPLOAD_PERMISSIONS is not None:

   187             os.chmod(full_path, settings.FILE_UPLOAD_PERMISSIONS)

   188 

   189         return name

   190 

   191     def delete(self, name):

   192         name = self.path(name)

   193         # If the file exists, delete it from the filesystem.

   194         if os.path.exists(name):

   195             os.remove(name)

   196 

   197     def exists(self, name):

   198         return os.path.exists(self.path(name))

   199 

   200     def listdir(self, path):

   201         path = self.path(path)

   202         directories, files = [], []

   203         for entry in os.listdir(path):

   204             if os.path.isdir(os.path.join(path, entry)):

   205                 directories.append(entry)

   206             else:

   207                 files.append(entry)

   208         return directories, files

   209 

   210     def path(self, name):

   211         try:

   212             path = safe_join(self.location, name)

   213         except ValueError:

   214             raise SuspiciousOperation("Attempted access to '%s' denied." % name)

   215         return smart_str(os.path.normpath(path))

   216 

   217     def size(self, name):

   218         return os.path.getsize(self.path(name))

   219 

   220     def url(self, name):

   221         if self.base_url is None:

   222             raise ValueError("This file is not accessible via a URL.")

   223         return urlparse.urljoin(self.base_url, name).replace('\\', '/')

   224 

   225 def get_storage_class(import_path=None):

   226     if import_path is None:

   227         import_path = settings.DEFAULT_FILE_STORAGE

   228     try:

   229         dot = import_path.rindex('.')

   230     except ValueError:

   231         raise ImproperlyConfigured("%s isn't a storage module." % import_path)

   232     module, classname = import_path[:dot], import_path[dot+1:]

   233     try:

   234         mod = import_module(module)

   235     except ImportError, e:

   236         raise ImproperlyConfigured('Error importing storage module %s: "%s"' % (module, e))

   237     try:

   238         return getattr(mod, classname)

   239     except AttributeError:

   240         raise ImproperlyConfigured('Storage module "%s" does not define a "%s" class.' % (module, classname))

   241 

   242 class DefaultStorage(LazyObject):

   243     def _setup(self):

   244         self._wrapped = get_storage_class()()

   245 

   246 default_storage = DefaultStorage()