Changeset 7016

Timestamp:

7 Nov 2011, 08:12:38 (13 years ago)

Author:

uli

Message:

More docs.

File:

• main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/imagestorage.py (modified) (5 diffs)

main/waeup.sirp/branches/ulif-extimgstore/src/waeup/sirp/imagestorage.py

@@ -233 +233 @@
 class Basket(grok.Container):
     """A basket holds a set of image files with same hash.
+
+    It is used for storing files as blobs in ZODB. Current sites do
+    not use it.
+
+    .. deprecated:: 0.2
+
     """
 
@@ -353 +359 @@
 
     def storeFile(self, fd, filename):
+        """Store contents of file addressed by `fd` under filename `filename`.
+
+        Returns the internal file id (a string) for the file stored.
+        """
         fd.seek(0)
         digest = md5digest(fd)
@@ -371 +381 @@
 
 class ImageStorageFileRetrieval(Persistent):
+    """A persistent object to retrieve files stored in ZODB.
+
+    .. deprecated:: 0.2
+
+       Since we have :class:`ExtFileStore` now we do not need this
+       class anymore.
+    """
     grok.implements(IFileRetrieval)
 
@@ -487 +504 @@
         """Get a file stored under file ID `file_id`.
 
+        Returns a file already opened for reading.
+
         If the file cannot be found ``None`` is returned.
+
+        This methods takes into account registered handlers for any
+        marker put into the file_id.
         """
         marker, filename, base, ext = self.extractMarker(file_id)
@@ -565 +587 @@
 
 class DefaultFileStoreHandler(grok.GlobalUtility):
+    """A default handler for external file store.
+
+    This handler is the fallback called by external file stores when
+    there is no or an unknown marker in the file id.
+    """
     grok.implements(IFileStoreHandler)
 
     def pathFromFileID(self, store, root, file_id):
+        """Return the root path of external file store appended by file id.
+        """
         return os.path.join(root, file_id)
 
     def createFile(self, store, root, filename, file_id, f):
+        """Infos about what to store exactly and where.
+
+        When a file should be handled by an external file storage, it
+        looks up any handlers (like this one), passes runtime infos
+        like the storage object, root path, filename, file_id, and the
+        raw file object itself.
+
+        The handler can then change the file, raise exceptions or
+        whatever and return the result.
+
+        This handler returns the input file as-is, a path returned by
+        :meth:`pathFromFileID` and an instance of
+        :class:`hurry.file.HurryFile` for further operations.
+
+        Please note: although a handler has enough infos to store the
+        file itself, it should leave that task to the calling file
+        store.
+        """
         path = self.pathFromFileID(store, root, file_id)
         return f, path, HurryFile(filename, file_id)