mediagoblin/storage.py

   1 # GNU Mediagoblin -- federated, autonomous media hosting
   2 # Copyright (C) 2011 Free Software Foundation, Inc
   3 #
   4 # This program is free software: you can redistribute it and/or modify
   5 # it under the terms of the GNU Affero General Public License as published by
   6 # the Free Software Foundation, either version 3 of the License, or
   7 # (at your option) any later version.
   8 #
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU Affero General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU Affero General Public License
  15 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 import os
  18
  19 from werkzeug.utils import secure_filename
  20
  21
  22 class Error(Exception): pass
  23 class InvalidFilepath(Error): pass
  24
  25 class NotImplementedError(Error): pass
  26
  27
  28 def clean_listy_filepath(listy_filepath):
  29     """
  30     Take a listy filepath (like ['dir1', 'dir2', 'filename.jpg']) and
  31     clean out any nastiness from it.
  32
  33     For example:
  34     >>> clean_listy_filepath([u'/dir1/', u'foo/../nasty', u'linooks.jpg'])
  35     [u'dir1', u'foo_.._nasty', u'linooks.jpg']
  36
  37     Args:
  38     - listy_filepath: a list of filepath components, mediagoblin
  39       storage API style.
  40
  41     Returns:
  42       A cleaned list of unicode objects.
  43     """
  44     cleaned_filepath = [
  45         unicode(secure_filename(filepath))
  46         for filepath in listy_filepath]
  47
  48     if u'' in cleaned_filepath:
  49         raise InvalidFilepath(
  50             "A filename component could not be resolved into a usable name.")
  51
  52     return cleaned_filepath
  53
  54
  55 class StorageInterface(object):
  56     """
  57     Interface for the storage API.
  58
  59     This interface doesn't actually provide behavior, but it defines
  60     what kind of storage patterns subclasses should provide.
  61
  62     It is important to note that the storage API idea of a "filepath"
  63     is actually like ['dir1', 'dir2', 'file.jpg'], so keep that in
  64     mind while reading method documentation.
  65     """
  66     # def __init__(self, *args, **kwargs):
  67     #     pass
  68
  69     def __raise_not_implemented(self):
  70         """
  71         Raise a warning about some component not implemented by a
  72         subclass of this interface.
  73         """
  74         raise NotImplementedError(
  75             "This feature not implemented in this storage API implementation.")
  76
  77     def file_exists(self, filepath):
  78         """
  79         Return a boolean asserting whether or not file at filepath
  80         exists in our storage system.
  81
  82         Returns:
  83          True / False depending on whether file exists or not.
  84         """
  85         # Subclasses should override this method.
  86         self.__raise_not_implemented()
  87
  88     def get_file(self, filepath, mode):
  89         """
  90         Return a file-like object for reading/writing from this filepath.
  91
  92         Should create directories, buckets, whatever, as necessary.
  93         """
  94         # Subclasses should override this method.
  95         self.__raise_not_implemented()
  96
  97     def delete_file(self, filepath):
  98         """
  99         Delete or dereference the file at filepath.
 100
 101         This might need to delete directories, buckets, whatever, for
 102         cleanliness.  (Be sure to avoid race conditions on that though)
 103         """
 104         # Subclasses should override this method.
 105         self.__raise_not_implemented()
 106
 107     def url_for_file(self, filepath):
 108         """
 109         Get the URL for this file.  This assumes our storage has been
 110         mounted with some kind of URL which makes this possible.
 111         """
 112         # Subclasses should override this method.
 113         self.__raise_not_implemented()
 114
 115     def get_unique_filename(self, filepath):
 116         """
 117         If a filename at filepath already exists, generate a new name.
 118
 119         Eg, if the filename doesn't exist:
 120         >>> storage_handler.get_unique_filename(['dir1', 'dir2', 'fname.jpg'])
 121         [u'dir1', u'dir2', u'fname.jpg']
 122
 123         But if a file does exist, let's get one back with at uuid tacked on:
 124         >>> storage_handler.get_unique_filename(['dir1', 'dir2', 'fname.jpg'])
 125         [u'dir1', u'dir2', u'd02c3571-dd62-4479-9d62-9e3012dada29-fname.jpg']
 126         """
 127         if self.file_exists(filepath):
 128             return filepath[:-1] + ["%s-%s" % (uuid.uuid4(), filepath[-1])]
 129         else:
 130             return filepath
 131
 132
 133 class BasicFileStorage(StorageInterface):
 134     """
 135     Basic local filesystem implementation of storage API
 136     """
 137
 138     def __init__(self, base_dir, serve_url=None):
 139         """
 140         Keyword arguments:
 141         - base_dir: Base directory things will be served out of.  MUST
 142           be an absolute path.
 143         - serve_url: URL files will be served from
 144         """
 145         self.base_dir = base_dir
 146         self.serve_url = serve_url
 147
 148     def _resolve_filepath(self, filepath):
 149         """
 150         Transform the given filepath into a local filesystem filepath.
 151         """
 152         return os.path.join(
 153             self.base_dir, *clean_listy_filepath(filepath))
 154
 155     def file_exists(self, filepath):
 156         return os.path.exists(self._resolve_filepath(filepath))
 157
 158     def get_file(self, filepath, mode):
 159         pass
 160
 161     def delete_file(self, filepath):
 162         pass
 163
 164     def url_for_file(self, filepath):
 165         pass