Documentation, fixes, A ReadOnlyFS wrapper and a plain old FTP FS class

git-svn-id: http://pyfilesystem.googlecode.com/svn/trunk@309 67cdc799-7952-0410-af00-57a81ceafa0f

18 files changed, 225 insertions, 4 deletions

diff --git a/docs/base.rst b/docs/base.rst
index 2cf3117..7602704 100644
--- a/docs/base.rst
+++ b/docs/base.rst
@@ -1,3 +1,48 @@
+fs.base
+=======
+
+This module contains the basic FS interface and a number of other essential interfaces.
+
+fs.base.FS
+----------
+
+All Filesystem objects inherit from this class
+
 .. autoclass:: fs.base.FS
     :members:
-    
\ No newline at end of file
+    
+fs.base.SubFS
+-------------
+
+A SubFS is an FS implementation that represents a directory on another Filesystem. When you use the `opendir` method it will return a SubFS instance. You should not need to instantiate a SubFS directly.
+
+For example::
+
+    from fs.osfs import OSFS
+    home_fs = OSFS('foo')
+    bar_gs = home_fs.opendir('bar')
+
+
+fs.base.NullFile
+----------------
+
+A NullFile is a file-like object with no functionality. It is used in situations where a file-like object is required but the caller doesn't have any data to read or write.
+
+The `safeopen` method returns an NullFile instance, which can reduce error-handling code.
+
+For example, the following code may be written to append some text to a log file::
+
+    logfile = None
+    try:
+        logfile = myfs.open('log.txt', 'a')
+        logfile.writeline('operation successful!')
+    finally:
+        if logfile is not None:
+            logfile.close()
+
+This could be re-written using the `safeopen` method::
+
+    myfs.safeopen('log.txt', 'a').writeline('operation successful!')
+
+If the file doesn't exist then the call to writeline will be a null-operation (i.e. not do anything)
+
diff --git a/docs/browsewin.rst b/docs/browsewin.rst
new file mode 100644
index 0000000..30f7e0e
--- /dev/null
+++ b/docs/browsewin.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.browsewin
+    :members:
\ No newline at end of file
diff --git a/docs/concepts.rst b/docs/concepts.rst
new file mode 100644
index 0000000..614776f
--- /dev/null
+++ b/docs/concepts.rst
@@ -0,0 +1,26 @@
+Concepts
+========
+
+It is generally quite easy to get in to the mind-set of using PyFilesystem interface over lower level interfaces -- since the code tends to be simpler -- but there are a few concepts which you will need to keep in mind.
+
+Sandboxing
+----------
+
+FS objects are not permitted to work with any files / directories outside of the Filesystem they represent. If you attempt to open a file / directory outside the root of the FS (by using "../" in the path, you will get a ValueError).
+
+It is advisable to write functions that takes FS objects as parameters, possibly with an additional path relative to the root of the FS. This allows you to write code that works with files / directories, but is independant of where they are located.
+
+
+Paths
+-----
+
+Paths used within a Filesystem object use the same common format, regardless of the underlaying Filesystem it represents.
+
+ * Path components are separated by a forward path (/)
+ * Paths beginning with a forward slash are absolute (start at the root of the FS)
+ * Paths not beginning with a forward slash are relative
+ * A single dot means 'current directory'
+ * A double dot means 'previous directory'
+ 
+Note that paths used by the FS interface will use this format, but the constructor or additional methods may not. Notably the osfs.OSFS constructor which requires an OS path.
+
diff --git a/docs/errors.rst b/docs/errors.rst
new file mode 100644
index 0000000..f142a5d
--- /dev/null
+++ b/docs/errors.rst
@@ -0,0 +1,5 @@
+fs.errors
+=========
+
+.. automodule:: fs.errors
+    :members:
\ No newline at end of file
diff --git a/docs/filesystems.rst b/docs/filesystems.rst
new file mode 100644
index 0000000..18d4bb1
--- /dev/null
+++ b/docs/filesystems.rst
@@ -0,0 +1,39 @@
+Filesystems
+===========
+
+This page lists the builtin filesystems.
+
+
+fs.osfs.OSFS
+------------
+An interface to the OS Filesystem
+
+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)
+
+fs.multifs.MultiFS
+------------------
+A filesystem that overlays other filesystems
+
+fs.sftpfs.SFTPFS
+----------------
+A secure FTP filesystem
+
+fs.s3fs.S3FS
+------------
+A filesystem to access an Amazon S3 service
+
+fs.tempfs.TempFS
+----------------
+Creates a temporary filesystem in an OS provided location
+
+fs.zipfs.ZipFS
+--------------
+A filesystem for zip files
+
+
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index c015b1b..8e073e1 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -16,7 +16,7 @@ This will install the latest stable release. If you would prefer to install the
     cd pyfilesystem-read-only
     python setup.py install
 
-You should now have the _fs_ module on your path:
+You should now have the `fs` module on your path:
 
     >>> import fs
     >>> fs.__version__
diff --git a/docs/index.rst b/docs/index.rst
index 3eeecc5..30cfcca 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,13 +6,39 @@
 Welcome to PyFilesystem's documentation!
 ========================================
 
-Contents:
+PyFilesystem provides a simplified common interface to a variety of different filesystems, such as the local filesystem, zip files, ftp servers etc.
+
+Guide
+-----
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
+   concepts.rst
    getting_started.rst
+   interface.rst
+   filesystems.rst
+   
+Code Documentation
+------------------
+   
+.. toctree::
+   :maxdepth: 3
+   
    base.rst
+   browsewin.rst
+   errors.rst
+   memoryfs.rst
+   mountfs.rst
+   osfs.rst
+   path.rst
+   s3fs.rst
+   sftpfs.rst
+   tempfs.rst
+   utils.rst
+   wrapfs.rst
+   zipfs.rst
+   
 
 Indices and tables
 ==================
diff --git a/docs/interface.rst b/docs/interface.rst
new file mode 100644
index 0000000..87edea5
--- /dev/null
+++ b/docs/interface.rst
@@ -0,0 +1,52 @@
+Filesystem Interface
+====================
+
+It requires a relatively small number of methods to implement a working Filesystem object.
+
+
+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
+    
+
+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
+
+
+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
\ No newline at end of file
diff --git a/docs/memoryfs.rst b/docs/memoryfs.rst
new file mode 100644
index 0000000..1ca0921
--- /dev/null
+++ b/docs/memoryfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.memoryfs
+    :members:
\ No newline at end of file
diff --git a/docs/mountfs.rst b/docs/mountfs.rst
new file mode 100644
index 0000000..02b4e92
--- /dev/null
+++ b/docs/mountfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.mountfs
+    :members:
\ No newline at end of file
diff --git a/docs/osfs.rst b/docs/osfs.rst
new file mode 100644
index 0000000..18af7ef
--- /dev/null
+++ b/docs/osfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.osfs
+    :members:
\ No newline at end of file
diff --git a/docs/path.rst b/docs/path.rst
new file mode 100644
index 0000000..b52ffca
--- /dev/null
+++ b/docs/path.rst
@@ -0,0 +1,5 @@
+fs.path
+=========
+
+.. automodule:: fs.path
+    :members:
\ No newline at end of file
diff --git a/docs/s3fs.rst b/docs/s3fs.rst
new file mode 100644
index 0000000..e798f5b
--- /dev/null
+++ b/docs/s3fs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.s3fs
+    :members:
\ No newline at end of file
diff --git a/docs/sftpfs.rst b/docs/sftpfs.rst
new file mode 100644
index 0000000..d1a9538
--- /dev/null
+++ b/docs/sftpfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.sftpfs
+    :members:
\ No newline at end of file
diff --git a/docs/tempfs.rst b/docs/tempfs.rst
new file mode 100644
index 0000000..beabc6a
--- /dev/null
+++ b/docs/tempfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.tempfs
+    :members:
\ No newline at end of file
diff --git a/docs/utils.rst b/docs/utils.rst
new file mode 100644
index 0000000..0a988fe
--- /dev/null
+++ b/docs/utils.rst
@@ -0,0 +1,5 @@
+fs.utils
+========
+
+.. automodule:: fs.utils
+    :members:
\ No newline at end of file
diff --git a/docs/wrapfs.rst b/docs/wrapfs.rst
new file mode 100644
index 0000000..e52fa3e
--- /dev/null
+++ b/docs/wrapfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.wrapfs
+    :members:
\ No newline at end of file
diff --git a/docs/zipfs.rst b/docs/zipfs.rst
new file mode 100644
index 0000000..b3d85ff
--- /dev/null
+++ b/docs/zipfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.zipfs
+    :members:
\ No newline at end of file