sqlfuse: extend and fix documentation

sqlfuse/__init__.py

@@ -4,9 +4,9 @@ This module gets a description of a filesystem and returns a object derived
 from llfuse.Operations, that could be used for mounting with llfuse.
 
 The description of the filesystem is a list of *Path (namely QPath and FPath)
-object, that will be used to generate the filesystem.
+objects, that will be used to generate the filesystem.
 
-To give an example. Assume you want the following filesystem:
+To give an example: Assume you want the following filesystem:
 /
 |- Dir1
 |   \- <q1>
@@ -30,9 +30,8 @@ In this case use a Where object like Where(function, "<q1>", 'some_attribute').
 
 The queries have to be sqlalchemy.sql.select objects.
 
-To use this module construct a filesystem like the above one and give it to the
-module with the init function. The init functions returns then a valid
-Operations object.
+To use this module pass a filesystem like the above datastructure to the
+init function. The init function then returns a valid Operations object.
 """
 import sqlfuse.data
 import sqlfuse.operations
@@ -47,7 +46,7 @@ __all__ = ['FPath', 'QPath', 'Where', 'Functions', 'init']
 def init(session, fs):
     """Take a fs pseudofilesystem and returns an llfuse.Operations object.
 
-    The the module description for details about the pseudofilesystem.
+    Read the module description for details about the pseudofilesystem.
 
     Arguments:
     session -- A sqlalchemy session.

sqlfuse/model.py

@@ -222,7 +222,7 @@ class Special(Node):
         return self._session.execute(self._query)
 
     def is_special(self):
-        """Indicates whether this object is special. Returns always false."""
+        """Indicates whether this object is special. Returns always true."""
         return True
 
     def get_fileattr(self, row):
@@ -237,6 +237,7 @@ class Special(Node):
         """Apply a where clause, where placeholder is replaced with object."""
         for pwhere in self._where:
             if pwhere.ph_obj == placeholder:
+                # if is for faster execution in non debug mode
                 if self.logger.isEnabledFor(logging.DEBUG):
                     self.logger.debug("apply where clause with function '{}', \
 attribute {}, object items: {}".format('.'.join([str(pwhere.function.__self__),
@@ -292,23 +293,31 @@ class FuseDir(FuseIO, Node):
         special -- The special object.
         row     -- The row of the query result.
         """
+        # check if object with filename already in children
         name = special.get_obj_fname(row)
         if name in self._children:
             return None, None
 
+        # construct the new FuseIO object
         if special.is_leaf():
             (gid, path) = special.get_fileattr(row)
             f = FuseFile(None, -1, self, gid, path, self._data)
         else:
             f = FuseDir(None, -1, self, name, self._data)
+            # copy all children from the special object to the new FuseDir
+            # and apply the Where to all child special objects with the
+            # now known real value
             for (fname, child) in special.get_children().items():
                 f.add_fuseio(child.deepcopy_and_register(special.get_name(),
                                                          row),
                              fname)
-            for s_special in special.get_specials():
-                s_special = copy.copy(s_special)
-                s_special.apply_where(special.get_name(), row)
-                f.add_special(s_special)
+            # copy all specials from the special object to the new FuseDir
+            # and apply the Where with the now known real value
+            for child_special in special.get_specials():
+                child_special = copy.copy(child_special)
+                child_special.apply_where(special.get_name(), row)
+                f.add_special(child_special)
+        # pin and add the object
         self._data.pin_inode(f)
         self.add_fuseio(f, name)
         return name, f
@@ -317,7 +326,7 @@ class FuseDir(FuseIO, Node):
         """Constructs a deepcopy of the directory and assign an inode.
 
         If the directory or a subdirectory contains special nodes with
-        where clauses, this where clause are applied via apply_where().
+        where clauses, this where clauses are applied via apply_where().
 
         Arguments:
         placeholder -- The placeholder argument for apply_where().
@@ -337,7 +346,7 @@ class FuseDir(FuseIO, Node):
         return pcopy
 
     def query_name(self, filename):
-        """Query the directory contents after a given filename.
+        """Query the directory contents with a given filename.
 
         This models more less the behaviour of the lookup syscall. If the
         directory contains special objects, the relevant queries are executed.
@@ -367,7 +376,7 @@ class FuseDir(FuseIO, Node):
         return fuseio
 
     def opendir(self):
-        """Will be called by Operations before readdir(), not function yet."""
+        """Will be called by Operations before readdir(), no function yet."""
         pass
 
     def readdir(self, offset):
@@ -399,7 +408,7 @@ class FuseFile(FuseIO, Node):
         mode   -- The read/write/execute rights of the directory.
         inode  -- Superclass argument, see FuseIO.
         parent -- Superclass argument, see Node.
-        gid    -- The unique gid of the file.
+        gid    -- The unique gid (identifier) of the file.
         path   -- The filepath of the real file.
         data   -- Superclass argument, see Node.
         """