More documentation

docs/filesystems.rst

@@ -4,36 +4,52 @@ Filesystems
 This page lists the builtin filesystems.
 
 
-fs.osfs.OSFS
-------------
-An interface to the OS Filesystem
+FTP (File Transfer Protocol)
+----------------------------
+An interface to FTP servers. See :mod:`fs.ftpfs`
 
-fs.memoryfs.MemoryFS
---------------------
-A filesystem that exists entirely in memory
 
-fs.mountfs.MountFS
-------------------
-A filesystem that can map directories in to other filesystems (like a symlink)
+Memory
+------
+A filesystem that exists entirely in memory. See :mod:`fs.memoryfs`
 
-fs.multifs.MultiFS
-------------------
-A filesystem that overlays other filesystems
 
-fs.sftpfs.SFTPFS
-----------------
-A secure FTP filesystem
+Mount
+-----
+A filesystem that can map directories in to other filesystems (like a symlink). See :mod:`fs.mountfs`
 
-fs.s3fs.S3FS
-------------
-A filesystem to access an Amazon S3 service
 
-fs.tempfs.TempFS
-----------------
-Creates a temporary filesystem in an OS provided location
+Multi
+-----
+A filesystem that overlays other filesystems. See :mod:`fs.multifs`
 
-fs.zipfs.ZipFS
---------------
-A filesystem for zip files
+
+OS
+--
+An interface to the OS Filesystem. See :mod:`fs.osfs`
+
+Secure FTP (Secure FTP)
+----------------------
+A secure FTP filesystem. See :mod:`fs.sftpfs`
+
+
+S3
+--
+A filesystem to access an Amazon S3 service. See :mod:`fs.s3fs`
+
+
+Temporary
+---------
+Creates a temporary filesystem in an OS provided location. See :mod:`fs.tempfs`
+
+
+Wrap
+----
+A collection of wrappers that add new behaviour / features to existing FS instances. See :mod:`fs.wrapfs`
+
+
+Zip
+---
+An interface to zip files. See :mod:`fs.zipfs`
 
 

docs/index.rst

@@ -14,6 +14,7 @@ Guide
 .. toctree::
    :maxdepth: 3
 
+   introduction.rst
    concepts.rst
    getting_started.rst
    interface.rst
@@ -28,8 +29,10 @@ Code Documentation
    base.rst
    browsewin.rst
    errors.rst
+   ftpfs.rst
    memoryfs.rst
    mountfs.rst
+   multifs.rst
    osfs.rst
    path.rst
    s3fs.rst

docs/interface.rst

@@ -9,15 +9,15 @@ Essential Methods
 
 The following methods are required for a minimal Filesystem interface:
 
-    * `open` Opens a file for read/writing
-    * `isfile` Check wether the path exists and is a file
-    * `isdir` Check wether a path exists and is a directory
-    * `listdir` List the contents of a directory
-    * `makedir` Create a new directory
-    * `remove` Remove an existing file
-    * `removedir` Remove an existing directory
-    * `rename` Automically rename a file or directory
-    * `getinfo` Return information about the path e.h. size, mtime
+    * :meth:`~fs.base.FS.open` Opens a file for read/writing
+    * :meth:`~fs.base.FS.isfile` Check wether the path exists and is a file
+    * :meth:`~fs.base.FS.isdir` Check wether a path exists and is a directory
+    * :meth:`~fs.base.FS.listdir` List the contents of a directory
+    * :meth:`~fs.base.FS.makedir` Create a new directory
+    * :meth:`~fs.base.FS.remove` Remove an existing file
+    * :meth:`~fs.base.FS.removedir` Remove an existing directory
+    * :meth:`~fs.base.FS.rename` Automically rename a file or directory
+    * :meth:`~fs.base.FS.getinfo` Return information about the path e.h. size, mtime
     
 
 Non - Essential Methods
@@ -25,16 +25,16 @@ Non - Essential Methods
 
 The following methods have default implementations in fs.base.FS and aren't required for a functional FS interface. They may be overriden if an alternative implementation can be supplied:
 
-    * `copy` Copy a file to a new location
-    * `copydir` Recursively copy a directory to a new location
-    * `desc` Return a short destriptive text regarding a path
-    * `exists` Check whether a path exists as file or directory    
-    * `getsyspath` Get a file's name in the local filesystem, if possible
-    * `hassyspath` Check if a path maps to a system path (recognised by the OS)
-    * `move` Move a file to a new location        
-    * `movedir` Recursively move a directory to a new location
-    * `opendir` Opens a directory and returns an FS object that represents it
-    * `safeopen` Like `open` but returns a NullFile if the file could not be opened
+    * :meth:`~fs.base.FS.copy` Copy a file to a new location
+    * :meth:`~fs.base.FS.copydir` Recursively copy a directory to a new location
+    * :meth:`~fs.base.FS.desc` Return a short destriptive text regarding a path
+    * :meth:`~fs.base.FS.exists` Check whether a path exists as file or directory    
+    * :meth:`~fs.base.FS.getsyspath` Get a file's name in the local filesystem, if possible
+    * :meth:`~fs.base.FS.hassyspath` Check if a path maps to a system path (recognised by the OS)
+    * :meth:`~fs.base.FS.move` Move a file to a new location        
+    * :meth:`~fs.base.FS.movedir` Recursively move a directory to a new location
+    * :meth:`~fs.base.FS.opendir` Opens a directory and returns an FS object that represents it
+    * :meth:`~fs.base.FS.safeopen` Like :meth:`~fs.base.open` but returns a NullFile if the file could not be opened
 
 
 Utility Methods
@@ -42,11 +42,12 @@ Utility Methods
 
 The following members have implementations in fs.base.FS but will probably never need a non-default implementation, although there is nothing to prevent a derived class from implementing these:
 
-    * `createfile` Create a file with data
-    * `getcontents` Returns the contents of a file as a string
-    * `getsize` Returns the number of bytes used for a given file or directory
-    * `isdirempty` Checks if a directory contains no files
-    * `makeopendir` Creates a directroy (if it exists) and returns an FS object for that directory
-    * `walk` Like `listdir` but descends in to sub-directories
-    * `walkfiles` Returns an iterable of file paths in a directory, and its sub-directories
-    * `walkdirs` Returns an iterable of paths to sub-directories
+    * :meth:`~fs.base.FS.createfile` Create a file with data
+    * :meth:`~fs.base.FS.getcontents` Returns the contents of a file as a string
+    * :meth:`~fs.base.FS.getsize` Returns the number of bytes used for a given file or directory
+    * :meth:`~fs.base.FS.isdirempty` Checks if a directory contains no files
+    * :meth:`~fs.base.FS.makeopendir` Creates a directroy (if it exists) and returns an FS object for that directory
+    * :meth:`~fs.base.FS.walk` Like `listdir` but descends in to sub-directories
+    * :meth:`~fs.base.FS.walkfiles` Returns an iterable of file paths in a directory, and its sub-directories
+    * :meth:`~fs.base.FS.walkdirs` Returns an iterable of paths to sub-directories
\ No newline at end of file
+    
\ No newline at end of file

docs/introduction.rst

 Introduction
 ============
 
-PyFilesystem is a Python module that provides a common interface to disparate filesystems -- which allows you to write code that works with files and directories regardless of their source and location.
+PyFilesystem is a Python module that provides a common interface to disparate filesystems, which allows the developer to write code that works with files and directories regardless of their source and location.
 
 Think of PyFilesystem (FS) objects as the next logical step to Python's _file_ objects. Just as file-like objects abstract a single file, FS objects abstract the whole filesystem by providing a common interface to operations such as reading directories, getting file information, opening/copying/deleting files etc.
 
-For example, if you had written a method that reads a few files from the local filesystem, it would be a trivial change if you later decided to read those files from a zip file or even over the Internet.
+For example, if you had written a method that reads a few files from the local filesystem, it would be a trivial change if you later decided to read those files from a zip file or even over the Internet.
\ No newline at end of file

docs/path.rst

-fs.path
-=========
-
 .. automodule:: fs.path
     :members:
\ No newline at end of file

fs/ftpfs.py

@@ -2,7 +2,7 @@
 fs.ftpfs
 ========
 
-Filesystem for accessing an FTP server (uses ftplib in standard library)
+FTPS is a filesystem for accessing an FTP server (uses ftplib in standard library)
 
 """
 
@@ -26,6 +26,8 @@ except ImportError:
 import time
 import sys
 
+__all__ = ['FTPFS']
+
 # -----------------------------------------------
 # Taken from http://www.clapper.org/software/python/grizzled/
 # -----------------------------------------------

fs/multifs.py

 """
 fs.multifs
 ==========
+
+A MultiFS is a filesytem composed of a sequence of other filesystems, where
+the directory structure of each filesystem is overlaid over the previous filesystem.
+When you attempt to access a file from the MultiFS it will try each 'child'
+FS in order, until it either finds a path that exists or raises a ResourceNotFoundError.
+
+One use for such a filesystem would be to selectively override a set of files,
+to customize behaviour. For example, to create a filesystem that could be used
+to *theme* a web application::
+
+    from fs.osfs import OSFS
+    from fs.multifs import MultiFS
+
+    themed_template_fs.addfs('templates', OSFS('templates'))
+    themed_template_fs.addfs('theme', OSFS('themes'))
+
+    index_template = themed_template_fs.getcontent('index.html')
+
+This will read the contents of *themes/index.html*, if it exists, otherwise
+it will look for it in *templates/index.html*.
+
 """
 
-from fs.base import FS, FSError
+from fs.base import FS, FSError, synchronize
 from fs.path import *
 from fs import _thread_syncronize_default
 
@@ -66,7 +87,7 @@ class MultiFS(FS):
 
     @synchronize
     def __iter__(self):
-        return iter(self.fs_sequence[:])
+        return reversed(self.fs_sequence[:])
 
     def _delegate_search(self, path):
         for fs in self:
@@ -107,7 +128,7 @@ class MultiFS(FS):
         return "%s, on %s (%s)" % (fs.desc(path), name, fs)
 
     @synchronize
-    def open(self, path, mode="r",**kwargs):
+    def open(self, path, mode="r", **kwargs):
         for fs in self:
             if fs.exists(path):
                 fs_file = fs.open(path, mode, **kwargs)

fs/path.py

 """
+fs.path
+=======
+
 Useful functions for FS path manipulation.
 
 This is broadly similar to the standard 'os.path' module but works with