Merge lp:~jderose/filestore/docs-update into lp:filestore

[Jason Gerard DeRose]

Updates the docs in a few places where they no longer reflected the current API.

=== modified file 'doc/conf.py'
--- doc/conf.py	2011-11-09 00:46:01 +0000
+++ doc/conf.py	2011-12-08 11:35:30 +0000
@@ -48,7 +48,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '11.11'
+version = '11.12'
 # The full version, including alpha/beta/rc tags.
 release = version
 
 
=== modified file 'doc/filestore.rst'
--- doc/filestore.rst	2011-09-22 10:42:13 +0000
+++ doc/filestore.rst	2011-12-08 11:35:30 +0000
@@ -99,7 +99,7 @@
         A ``bytes`` instance containing the concatenated leaf-hashes
 
 
-.. class:: Stat(id, size, mtime)
+.. class:: Stat(id, name, size, mtime)
 
     Returned by :meth:`FileStore.stat()`, yielded by :meth:`FileStore.__iter__()`.
 
@@ -107,6 +107,10 @@
 
         The dmedia file ID
 
+    .. attribute:: name
+
+        The absolute path of the file as returned by :meth:`FileStore.path()`
+
     .. attribute:: size
 
         The file-size in bytes as reported by the file-system
@@ -135,7 +139,7 @@
 
 .. class:: Batch(files, size, count)
 
-    Returned by :func:`scandir()`.
+    Returned by :func:`scandir()`, argument for :func:`batch_import_iter()`.
 
     .. attribute:: files
 
@@ -164,16 +168,12 @@
         A ``bytes`` instance with the leaf content
 
 
-.. class:: StatVFS(avail, size, used)
+.. class:: StatVFS(size, used, avail, readonly, frsize)
 
-    Returned by :meth:`FileStore.statvfs()`.
+    Returned by :func:`statvfs()` and :meth:`FileStore.statvfs()`.
 
     All sizes are in bytes:
 
-    .. attribute:: avail
-
-        Free space available to non-privileged users
-
     .. attribute:: size
 
         Total file-system size
@@ -182,6 +182,20 @@
 
         Space consumed by existing files on file-system
 
+    .. attribute:: avail
+
+        Free space available to non-privileged users
+
+    .. attribute:: readonly
+
+        ``True`` if filesystem is mounted read-only
+
+    .. attribute:: frsize
+    
+        Block-size from ``os.statvfs()``, useful for deciding if an import batch
+        will fit in a given :class:`FileStore`
+
+
 
 
 Exceptions
@@ -512,7 +526,7 @@
     Read leaves from all files in *batch* and put them into the *queue*.
 
 
-.. function:: batch_import_iter(batch, *filestores)
+.. function:: batch_import_iter(batch, *filestores, callback=None)
 
     Import the files in *batch* into one or more destination *filestores*.
 
@@ -546,19 +560,86 @@
     code in dmedia.  However, the empty file does not get copied into the target
     *filestores*.
 
+    If you supply the *callback* keyword argument, it must be a callable that
+    takes two arguments, like this:
+
+    >>> def progress(count, size):
+    ...     print(count, size)
+
+    Where *count* is the number of files that have been completely imported, and
+    *size* is total bytes thus far imported.
+
+    The callback is called at the end of processing each file, plus whenever the
+    next 128 MiB (16 leaves) have been completed and at least one more leaf
+    remains.
+
+    For example, say you have a batch with one file and the file is exactly 33
+    leaves in size (264 MiB).  The callback would be called 3 times, like this:
+ 
+    >>> MiB = 1024 * 1024
+    >>> progress(0, 128 * MiB)
+    0 134217728
+    >>> progress(0, 256 * MiB)
+    0 268435456
+    >>> progress(1, 264 * MiB)
+    1 276824064
+
+
+
+Misc functions
+--------------
+
+
+.. function:: ensuredir(dirname)
+
+    Ensure that *dirname* exists, is a directory, and is not a symlink.
+    
+    This function is used by :meth:`FileStore.init_dirs()`.
+
+
+.. function:: statvfs(pathname)
+
+    Return usage information for filesystem containing *pathname*.
+
+    This takes the information from ``os.statvfs()`` and presents it in a
+    slightly higher-level way more fitting for filestore and Dmedia.  A
+    :class:`StatVFS` namedtuple is returned with the following attributes:
+
+        * size - the filesystem size in bytes
+        * used - space in bytes consumed by existing files
+        * avail - space in bytes available to non-privileged users
+        * readonly - ``True`` if filesystem is mounted read-only
+        * frsize - filesystem block size
+
+    This function is used by :meth:`FileStore.statvfs()`.
+
 
 
 The :class:`FileStore` class
 ----------------------------
 
 
-.. class:: FileStore(parentdir)
+.. class:: FileStore(parentdir, _id=None, copies=0)
 
     Arranges files in a special layout according to their content-hash.
 
     .. attribute:: parentdir
 
-        The parent directory provided when this instance was created.
+        The parent directory provided when instance was created.
+
+    .. attribute:: id
+
+        ID of file-store provided when instance was created.
+
+        This can be used by higher-level code like Dmedia, but is ignored by the
+        :class:`FileStore` itself.
+
+    .. attribute:: copies
+
+        Durability of file-store as provided when instance was created.
+
+        This can be used by higher-level code like Dmedia, but is ignored by the
+        :class:`FileStore` itself.
 
     .. attribute:: basedir
 
@@ -585,7 +666,9 @@
 
         >>> fs = FileStore('/home/jderose')  #doctest: +SKIP
         >>> fs.statvfs()  #doctest: +SKIP
-        StatVFS(avail=1791768784896, size=1936526733312, used=46388051968)
+        StatVFS(size=1965511450624, used=812883484672, avail=1054258069504, readonly=False, frsize=4096)
+        
+        This method uses the :func:`statvfs()` function.
 
 
     .. method:: catch_traversal(untrusted)