More documentation

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

22 files changed, 155 insertions, 15 deletions

diff --git a/docs/base.rst b/docs/base.rst
index 7602704..86398a0 100644
--- a/docs/base.rst
+++ b/docs/base.rst
@@ -6,7 +6,7 @@ This module contains the basic FS interface and a number of other essential inte
 fs.base.FS
 ----------
 
-All Filesystem objects inherit from this class
+All Filesystem objects inherit from this class,
 
 .. autoclass:: fs.base.FS
     :members:
@@ -20,7 +20,7 @@ For example::
 
     from fs.osfs import OSFS
     home_fs = OSFS('foo')
-    bar_gs = home_fs.opendir('bar')
+    bar_fs = home_fs.opendir('bar')
 
 
 fs.base.NullFile
diff --git a/docs/concepts.rst b/docs/concepts.rst
index 614776f..a140b5a 100644
--- a/docs/concepts.rst
+++ b/docs/concepts.rst
@@ -1,20 +1,51 @@
 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.
+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).
+FS objects are not permitted to work with any files / directories outside of the Filesystem they represent. If you attempt to open a file or 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.
+There is no concept of a current working directory in PyFilesystem, since it is a common source of bugs and not all filesytems even have such a notion. If you want to work with a sub-directory of a FS object, you can use the `opendir` method which returns another FS object representing the sub-directory.
+
+For example, consider the following directory structure. The directory `foo` contains two sub-directories; `bar` and `baz`::
+
+	 --foo
+	   |--bar
+	   |  |--readme.txt
+	   |  `--photo.jpg
+	   `--baz
+	      |--private.txt
+	      `--dontopen.jpg
+
+We can open the `foo` directory with the following code::
+
+	from fs.osfs import OSFS
+	foo_fs = OSFS('foo')
+
+The `foo_fs` object can work with any of the contents of `bar` and `baz`, which may not be desirable, especially if we are passing `foo_fs` to an untrusted function or one that could potentially delete files. Fortunately we can isolate a single sub-directory with then `opendir` method::
+
+	bar_fs = foo_fs.opendir('bar')
+
+This creates a completely new FS object that represents everything in the `foo/bar` directory. The root directory of `bar_fs` has been re-position, so that from `bar_fs`'s point of view, the readment.txt and photo.jpg files are in the root::
+
+	--bar
+	  |--readme.txt
+	  `--photo.jpg
+
+PyFilesystem will catch any attempts to read outside of the root directory. For example, the following will not work::
+
+	bar_fs.open('../private.txt') # throws a ValueError
 
 
 Paths
 -----
 
-Paths used within a Filesystem object use the same common format, regardless of the underlaying Filesystem it represents.
+Paths used within an FS object use the same common format, regardless of the underlaying file system it represents (or the platform it resides on). 
+
+When working with paths in FS objects, keep in mind the following:
 
  * Path components are separated by a forward path (/)
  * Paths beginning with a forward slash are absolute (start at the root of the FS)
@@ -22,5 +53,36 @@ Paths used within a Filesystem object use the same common format, regardless of
  * 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.
+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 -- the format of which can be platform-dependant.
+
+System Paths
+++++++++++++
+
+Not all Python modules can use file-like objects, especially those which interface with C libraries. For these situations you will need to retrieve the `system path` from an FS object you are working with. You can do this with the `getsyspath` method which converts a valid path in the context of the FS object to an absolute path on the system, if one exists.
+
+For example::
+
+	>>> from fs.osfs import OSFS
+	>>> home_fs = OSFS('~/')
+	>>> home_fs.getsyspath('test.txt')
+	u'/home/will/test.txt'
+
+Not all FS implementation will map to a valid system path (e.g. the FTP FS object). If you call `getsyspath` on such FS objects you will either get a `NoSysPathError` exception or a return value of None, if you call `getsyspath` with `allow_none=True`.
+
+Errors
+------
+
+PyFilesystem converts all exceptions to a common type, so that you need only write your exception handling code once. For example, if you try to open a file that doesn't exist, PyFilesystem will throw a ``fs.errors.ResourceNotFoundError`` regardless of wether the filesystem is local, on a ftp server or in a zip file::
+
+	>>> from fs.osfs import OSFS
+	>>> root_fs = OSFS('/')
+	>>> root_fs.open('doesnotexist.txt')
+	Traceback (most recent call last):
+	  File "<stdin>", line 1, in <module>
+	  File "/usr/local/lib/python2.6/dist-packages/fs/errors.py", line 181, in wrapper
+	    return func(self,*args,**kwds)
+	  File "/usr/local/lib/python2.6/dist-packages/fs/osfs/__init__.py", line 107, in open
+	    return open(self.getsyspath(path), mode, kwargs.get("buffering", -1))
+	fs.errors.ResourceNotFoundError: Resource not found: doesnotexist.txt
 
+All PyFilesystem exceptions are derived from ``fs.errors.FSError``, so you may use that if you want to catch all possible exceptions.
diff --git a/docs/expose.rst b/docs/expose.rst
new file mode 100644
index 0000000..487788b
--- /dev/null
+++ b/docs/expose.rst
@@ -0,0 +1,21 @@
+Exposing FS objects
+===================
+
+The ``fs.expose`` module offers a number of ways of making an FS implementation available over an internet connection, or to other processes on the system. 
+
+
+FUSE
+----
+Makes an FS object available to other applications on the system. See :mod:`fs.expose.fuse`.
+
+Secure FTP
+----------
+Makes an FS object available via Secure FTP. See :mod:`fs.expose.sftp`.
+
+XMLRPC
+------
+Makes an FS object available over XMLRPC. See :mod:`fs.expose.xmlrpc`
+
+Django Storate
+--------------
+Connects FS objects to Django. See :mod:`fs.expose.django_storage`
\ No newline at end of file
diff --git a/docs/expose/django_storage.rst b/docs/expose/django_storage.rst
new file mode 100644
index 0000000..e02ce1e
--- /dev/null
+++ b/docs/expose/django_storage.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.expose.django_storage
+    :members:
\ No newline at end of file
diff --git a/docs/expose/fuse.rst b/docs/expose/fuse.rst
new file mode 100644
index 0000000..e74ea3d
--- /dev/null
+++ b/docs/expose/fuse.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.expose.fuse
+    :members:
\ No newline at end of file
diff --git a/docs/expose/index.rst b/docs/expose/index.rst
new file mode 100644
index 0000000..0ddc111
--- /dev/null
+++ b/docs/expose/index.rst
@@ -0,0 +1,12 @@
+fs.expose
+=========
+
+The ``fs.expose`` module contains a number of options for making an FS implementation available over the internet, or to other applications.
+
+.. toctree::
+   :maxdepth: 3
+   
+   fuse.rst
+   sftp.rst
+   xmlrpc.rst
+   django_storage.rst
\ No newline at end of file
diff --git a/docs/expose/sftp.rst b/docs/expose/sftp.rst
new file mode 100644
index 0000000..81563ab
--- /dev/null
+++ b/docs/expose/sftp.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.expose.sftp
+    :members:
\ No newline at end of file
diff --git a/docs/expose/xmlrpc.rst b/docs/expose/xmlrpc.rst
new file mode 100644
index 0000000..f715ae4
--- /dev/null
+++ b/docs/expose/xmlrpc.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.expose.xmlrpc
+    :members:
\ No newline at end of file
diff --git a/docs/ftpfs.rst b/docs/ftpfs.rst
new file mode 100644
index 0000000..fa7f98c
--- /dev/null
+++ b/docs/ftpfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.ftpfs
+    :members:
\ No newline at end of file
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index 8e073e1..937f52f 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -43,6 +43,6 @@ The following will list all the files in your home directory::
     >>> home_fs = OSFS('~/') # 'c:\Users\<login name>' on Windows
     >>> home_fs.listdir()
     
-This will display the total number of bytes store in your home directory::
+This will display the total number of bytes store in '.py' files your home directory::
 
-    >>> sum(home_fs.getsize(f) for f in home_fs.listdir())
+    >>> sum(home_fs.getsize(f) for f in home_fs.walkfiles(wildcard='*.py'))
diff --git a/docs/index.rst b/docs/index.rst
index 3a9205b..1b9e095 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,10 +15,11 @@ Guide
    :maxdepth: 3
 
    introduction.rst
-   concepts.rst
    getting_started.rst
+   concepts.rst
    interface.rst
    filesystems.rst
+   expose.rst
    
 Code Documentation
 ------------------
@@ -29,17 +30,19 @@ Code Documentation
    base.rst
    browsewin.rst
    errors.rst
+   expose/index.rst
    ftpfs.rst
    memoryfs.rst
    mountfs.rst
    multifs.rst
    osfs.rst
    path.rst
+   rpcfsfs.rst
    s3fs.rst
    sftpfs.rst
    tempfs.rst
    utils.rst
-   wrapfs.rst
+   wrapfs/index.rst
    zipfs.rst
    
 
diff --git a/docs/introduction.rst b/docs/introduction.rst
index 7bfd2f2..3f03765 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,8 +1,9 @@
 Introduction
 ============
 
-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.
+PyFilesystem is a Python module that provides a common interface to any filesystem.
 
-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.
+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.
+
+Even if you only want to work with the local filesystem, FS simplifies a number of common operations and reduces the chance of error. A typical problem when working with the filesystem is writing a function that changes the current working directory, but doesn't set it back. This can be a tricky bug to identify since the problem will only manifest itself when you next try to work with the filesystem. PyFilesytem doesn't have this problem, because it doesn't modify the current working directory. It is also possible to restrict any file operations to a specific directory, which elliminates the possibility of accidently overwriting / deleting files outside of the specified directory.
 
-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
diff --git a/docs/mountfs.rst b/docs/mountfs.rst
index 02b4e92..fc62729 100644
--- a/docs/mountfs.rst
+++ b/docs/mountfs.rst
@@ -1,2 +1,6 @@
 .. automodule:: fs.mountfs
-    :members:
\ No newline at end of file
+    
+    .. automethod:: fs.mountfs.MountFS.mount(self, path, fs)
+    .. automethod:: fs.mountfs.MountFS.mountdir(self, path, fs)
+    .. automethod:: fs.mountfs.MountFS.mountfile(self, path, open_callable=None, info_callable=None)
+    .. automethod:: fs.mountfs.MountFS.unmount(path)
\ No newline at end of file
diff --git a/docs/multifs.rst b/docs/multifs.rst
new file mode 100644
index 0000000..ce0e8fd
--- /dev/null
+++ b/docs/multifs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.multifs
+    :members:
\ No newline at end of file
diff --git a/docs/rpcfs.rst b/docs/rpcfs.rst
new file mode 100644
index 0000000..c00f078
--- /dev/null
+++ b/docs/rpcfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.rpcfs
+    :members:
\ No newline at end of file
diff --git a/docs/wrapfs/.tmp_index.html.90192~ b/docs/wrapfs/.tmp_index.html.90192~
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/wrapfs/.tmp_index.html.90192~
diff --git a/docs/wrapfs/base.rst b/docs/wrapfs/base.rst
new file mode 100644
index 0000000..e52fa3e
--- /dev/null
+++ b/docs/wrapfs/base.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.wrapfs
+    :members:
\ No newline at end of file
diff --git a/docs/wrapfs/hidedotfiles.rst b/docs/wrapfs/hidedotfiles.rst
new file mode 100644
index 0000000..190b83c
--- /dev/null
+++ b/docs/wrapfs/hidedotfiles.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.wrapfs.hidedotfilesfs
+    :members:
\ No newline at end of file
diff --git a/docs/wrapfs/index.rst b/docs/wrapfs/index.rst
new file mode 100644
index 0000000..f7d3de6
--- /dev/null
+++ b/docs/wrapfs/index.rst
@@ -0,0 +1,13 @@
+fs.wrapfs
+=========
+
+The ``fs.wrapfs`` module adds aditional functionality to existing FS objects. 
+
+.. toctree::
+   :maxdepth: 3
+   
+   base.rst
+   hidedotfiles.rst
+   lazyfs.rst
+   limitsize.rst
+   readonlyfs.rst
\ No newline at end of file
diff --git a/docs/wrapfs/lazyfs.rst b/docs/wrapfs/lazyfs.rst
new file mode 100644
index 0000000..9bcad0c
--- /dev/null
+++ b/docs/wrapfs/lazyfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.wrapfs.lazyfs
+    :members:
\ No newline at end of file
diff --git a/docs/wrapfs/limitsize.rst b/docs/wrapfs/limitsize.rst
new file mode 100644
index 0000000..e08c0c4
--- /dev/null
+++ b/docs/wrapfs/limitsize.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.wrapfs.limitsizefs
+    :members:
\ No newline at end of file
diff --git a/docs/wrapfs/readonlyfs.rst b/docs/wrapfs/readonlyfs.rst
new file mode 100644
index 0000000..efd496a
--- /dev/null
+++ b/docs/wrapfs/readonlyfs.rst
@@ -0,0 +1,2 @@
+.. automodule:: fs.wrapfs.readonlyfs
+    :members:
\ No newline at end of file