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