diff options
-rw-r--r-- | docs/commands.rst | 2 | ||||
-rw-r--r-- | docs/conf.py | 4 | ||||
-rw-r--r-- | docs/index.rst | 1 | ||||
-rw-r--r-- | docs/opener.rst | 3 | ||||
-rw-r--r-- | fs/opener.py | 41 | ||||
-rw-r--r-- | fs/wrapfs/subfs.py | 5 |
6 files changed, 47 insertions, 9 deletions
diff --git a/docs/commands.rst b/docs/commands.rst new file mode 100644 index 0000000..f7f9eb9 --- /dev/null +++ b/docs/commands.rst @@ -0,0 +1,2 @@ +fs.commands +===========
\ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 6100996..ba1d75b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,9 +53,9 @@ copyright = u'2009-2010, Will McGugan, Ryan Kelly' # built documents. # # The short X.Y version. -version = '0.3' +version = '0.4' # The full version, including alpha/beta/rc tags. -release = '0.3.0' +release = '0.4.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index f245219..80fcd74 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,6 +38,7 @@ Code Documentation mountfs.rst multifs.rst osfs.rst + opener.rst path.rst remote.rst rpcfs.rst diff --git a/docs/opener.rst b/docs/opener.rst new file mode 100644 index 0000000..32c123e --- /dev/null +++ b/docs/opener.rst @@ -0,0 +1,3 @@ + +.. automodule:: fs.opener + :members:
\ No newline at end of file diff --git a/fs/opener.py b/fs/opener.py index 7df8a1e..0bb7b5c 100644 --- a/fs/opener.py +++ b/fs/opener.py @@ -1,5 +1,36 @@ """ - fs.opener: open file systems from a FS url +fs.opener +========= + +Open filesystems via a URI. + +There are occasions when you want to specify a filesytem from the command line or in a config file. +This module enables that functionality, and can return a FS object given a URI like syntax (http://commons.apache.org/vfs/filesystems.html). + +The `OpenerRegistry` class maps the protocol (file, ftp etc.) on to an Opener object, which returns an appropriate filesystem object and path. +You can create a custom opener registry that opens just the filesystems you require, or use the opener registry defined here (also called `opener`) that can open any supported filesystem. +The `parse` method of an `OpenerRegsitry` object returns a tuple of an FS object a path. Here's an example of how to use the default opener registry:: + + >>> from fs.opener import opener + >>> opener.parse('ftp://ftp.mozilla.org') + (<fs.ftpfs.FTPFS object at 0x96e66ec>, u'pub') + +You can use use the `opendir` method, which just returns an FS object. In the example above, `opendir` will return a FS object for the directory `pub`:: + + >>> opener.opendir('ftp://ftp.mozilla.org/pub') + <SubFS: <FTPFS ftp.mozilla.org>/pub> + +If you are just interested in a single file, use the `open` method of a registry which returns a file-like object, and has the same signature as FS objects and the `open` builtin:: + + >>> opener.open('ftp://ftp.mozilla.org/pub/README') + <fs.ftpfs._FTPFile object at 0x973764c> + +The `opendir` and `open` methods can also be imported from the top-level of this module for sake of convenience. +To avoid shadowing the builtin `open` methd, they are named `fsopendir` and `fsopen`. Here's how you might import them:: + + from fs.opener import fsopendir, fsopen + + """ @@ -8,7 +39,7 @@ __all__ = ['OpenerError', 'OpenerRegistry', 'opener', 'fsopen', - 'fsopendir', + 'fsopendir', 'OpenerRegistry', 'Opener', 'OSFSOpener', @@ -33,9 +64,11 @@ import re from urlparse import urlparse class OpenerError(Exception): + """The base exception thrown by openers""" pass class NoOpenerError(OpenerError): + """Thrown when there is no opener for the given protocol""" pass def _expand_syspath(path): @@ -78,7 +111,7 @@ def _split_url_path(url): class OpenerRegistry(object): - """An opener stores a number of opener objects that are used to parse FS URLs""" + """An opener registry that stores a number of opener objects used to parse FS URIs""" re_fs_url = re.compile(r''' ^ @@ -632,5 +665,3 @@ opener = OpenerRegistry([OSFSOpener, fsopen = opener.open fsopendir = opener.opendir - - diff --git a/fs/wrapfs/subfs.py b/fs/wrapfs/subfs.py index 1b6b24a..973e906 100644 --- a/fs/wrapfs/subfs.py +++ b/fs/wrapfs/subfs.py @@ -30,10 +30,11 @@ class SubFS(WrapFS): return abspath(normpath(path))[len(self.sub_dir):] def __str__(self): - return self.wrapped_fs.desc(self.sub_dir) + #return self.wrapped_fs.desc(self.sub_dir) + return '<SubFS: %s%s>' % (self.wrapped_fs, self.sub_dir) def __unicode__(self): - return u'<SubFS: %s!%s>' % (self.wrapped_fs, self.sub_dir) + return u'<SubFS: %s%s>' % (self.wrapped_fs, self.sub_dir) def __repr__(self): return str(self) |