Most of the StorageInterface stubs in place and documented.

mediagoblin/storage.py

@@ -21,6 +21,8 @@ from werkzeug.utils import secure_filename
 class Error(Exception): pass
 class InvalidFilepath(Error): pass
 
+class NotImplementedError(Error): pass
+
 
 def clean_listy_filepath(listy_filepath):
     """
@@ -49,3 +51,58 @@ def clean_listy_filepath(listy_filepath):
     return cleaned_filepath
 
 
+class StorageInterface(object):
+    """
+    Interface for the storage API.
+
+    This interface doesn't actually provide behavior, but it defines
+    what kind of storage patterns subclasses should provide.
+
+    It is important to note that the storage API idea of a "filepath"
+    is actually like ['dir1', 'dir2', 'file.jpg'], so keep that in
+    mind while reading method documentation.
+    """
+    # def __init__(self, *args, **kwargs):
+    #     pass
+
+    def __raise_not_implemented(self):
+        """
+        Raise a warning about some component not implemented by a
+        subclass of this interface.
+        """
+        raise NotImplementedError(
+            "This feature not implemented in this storage API implementation.")
+
+    def file_exists(self, filepath):
+        """
+        Return a boolean asserting whether or not file at filepath
+        exists in our storage system.
+
+        Returns:
+         True / False depending on whether file exists or not.
+        """
+        # Subclasses should override this method.
+        self.__raise_not_implemented()
+
+    def get_unique_filename(self, filepath):
+        """
+        If a filename at filepath already exists, generate a new name.
+
+        Eg, if the filename doesn't exist:
+        >>> storage_handler.get_unique_filename(['dir1', 'dir2', 'fname.jpg'])
+        [u'dir1', u'dir2', u'fname.jpg']
+        
+        But if a file does exist, let's get one back with at uuid tacked on:
+        >>> storage_handler.get_unique_filename(['dir1', 'dir2', 'fname.jpg'])
+        ['dir1', 'dir2', 'd02c3571-dd62-4479-9d62-9e3012dada29-fname.jpg']
+        """
+        # Subclasses should override this method.
+        self.__raise_not_implemented()
+
+    def get_file(self, filepath):
+        # Subclasses should override this method.
+        self.__raise_not_implemented()
+
+    def delete_file(self, filepath):
+        # Subclasses should override this method.
+        self.__raise_not_implemented()