fs.opener¶
Open filesystems via a URI.
There are occasions when you want to specify a filesystem from the command line or in a config file. This module enables that functionality, and can return an FS object given a filesystem specification in a URI-like syntax (inspired by the syntax of 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/pub')
(<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 method, they are named fsopendir and fsopen. Here’s how you might import them:
from fs.opener import fsopendir, fsopen
-
exception
fs.opener.
OpenerError
¶ The base exception thrown by openers
-
exception
fs.opener.
NoOpenerError
¶ Thrown when there is no opener for the given protocol
-
class
fs.opener.
OpenerRegistry
(openers=[])¶ An opener registry that stores a number of opener objects used to parse FS URIs
-
add
(opener)¶ Adds an opener to the registry
Parameters: opener – a class derived from fs.opener.Opener
-
get_opener
(name)¶ Retrieve an opener for the given protocol
Parameters: name – name of the opener to open Raises: NoOpenerError – if no opener has been registered of that name
-
getcontents
(fs_url, mode='rb', encoding=None, errors=None, newline=None)¶ Gets the contents from a given FS url (if it references a file)
Parameters: fs_url – a FS URL e.g. ftp://ftp.mozilla.org/README
-
open
(fs_url, mode='r', **kwargs)¶ Opens a file from a given FS url
If you intend to do a lot of file manipulation, it would likely be more efficient to do it directly through the an FS instance (from parse or opendir). This method is fine for one-offs though.
Parameters: - fs_url – a FS URL, e.g. ftp://ftp.mozilla.org/README
- mode – mode to open file file
Return type: a file
-
opendir
(fs_url, writeable=True, create_dir=False)¶ Opens an FS object from an FS URL
Parameters: - fs_url – an FS URL e.g. ftp://ftp.mozilla.org
- writeable – set to True (the default) if the FS must be writeable
- create_dir – create the directory references by the FS URL, if it doesn’t already exist
-
parse
(fs_url, default_fs_name=None, writeable=False, create_dir=False, cache_hint=True)¶ Parses a FS url and returns an fs object a path within that FS object (if indicated in the path). A tuple of (<FS instance>, <path>) is returned.
Parameters: - fs_url – an FS url
- default_fs_name – the default FS to use if none is indicated (defaults is OSFS)
- writeable – if True, a writeable FS will be returned
- create_dir – if True, then the directory in the FS will be created
-
-
class
fs.opener.
OpenerRegistry
(openers=[]) An opener registry that stores a number of opener objects used to parse FS URIs
-
add
(opener) Adds an opener to the registry
Parameters: opener – a class derived from fs.opener.Opener
-
get_opener
(name) Retrieve an opener for the given protocol
Parameters: name – name of the opener to open Raises: NoOpenerError – if no opener has been registered of that name
-
getcontents
(fs_url, mode='rb', encoding=None, errors=None, newline=None) Gets the contents from a given FS url (if it references a file)
Parameters: fs_url – a FS URL e.g. ftp://ftp.mozilla.org/README
-
open
(fs_url, mode='r', **kwargs) Opens a file from a given FS url
If you intend to do a lot of file manipulation, it would likely be more efficient to do it directly through the an FS instance (from parse or opendir). This method is fine for one-offs though.
Parameters: - fs_url – a FS URL, e.g. ftp://ftp.mozilla.org/README
- mode – mode to open file file
Return type: a file
-
opendir
(fs_url, writeable=True, create_dir=False) Opens an FS object from an FS URL
Parameters: - fs_url – an FS URL e.g. ftp://ftp.mozilla.org
- writeable – set to True (the default) if the FS must be writeable
- create_dir – create the directory references by the FS URL, if it doesn’t already exist
-
parse
(fs_url, default_fs_name=None, writeable=False, create_dir=False, cache_hint=True) Parses a FS url and returns an fs object a path within that FS object (if indicated in the path). A tuple of (<FS instance>, <path>) is returned.
Parameters: - fs_url – an FS url
- default_fs_name – the default FS to use if none is indicated (defaults is OSFS)
- writeable – if True, a writeable FS will be returned
- create_dir – if True, then the directory in the FS will be created
-
-
class
fs.opener.
Opener
¶ The base class for openers
Opener follow a very simple protocol. To create an opener, derive a class from Opener and define a classmethod called get_fs, which should have the following signature:
@classmethod def get_fs(cls, registry, fs_name, fs_name_params, fs_path, writeable, create_dir):
The parameters of get_fs are as follows:
- fs_name the name of the opener, as extracted from the protocol part of the url,
- fs_name_params reserved for future use
- fs_path the path part of the url
- writeable if True, then get_fs must return an FS that can be written to
- create_dir if True then get_fs should attempt to silently create the directory references in path
In addition to get_fs an opener class should contain two class attributes: names and desc. names is a list of protocols that list opener will opener. desc is an English description of the individual opener syntax.