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:
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:
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.