fs.opener

Open filesystems from a URL.

class fs.opener.Opener

The opener base class.

An opener is responsible for opening a filesystems from one or more protocols. A list of supported protocols is supplied in a class attribute called protocols.

Openers should be registered with a Registry object, which picks an appropriate opener object for a given FS URL.

open_fs(fs_url, parse_result, writeable, create, cwd)

Open a filesystem object from a FS URL.

Parameters:
  • fs_url (str) – A filesystem URL
  • parse_result (ParseResult) – A parsed filesystem URL.
  • writeable (bool) – True if the filesystem must be writeable.
  • create (bool) – True if the filesystem should be created if it does not exist.
  • cwd (str) – The current working directory (generally only relevant for OS filesystems).
Returns:

FS object

exception fs.opener.OpenerError

Base class for opener related errors.

exception fs.opener.ParseError

Raised when attempting to parse an invalid FS URL.

class fs.opener.ParseResult(protocol, username, password, resource, path)
password

Alias for field number 2

path

Alias for field number 4

protocol

Alias for field number 0

resource

Alias for field number 3

username

Alias for field number 1

class fs.opener.Registry(default_opener=u'osfs')

A registry for Opener instances.

install(opener)

Install an opener.

Parameters:opener – An Opener instance, or a callable that returns an opener instance.

May be used as a class decorator. For example:

registry = Registry()

@registry.install
class ArchiveOpener(Opener):
    protocols = ['zip', 'tar']
open(fs_url, writeable=True, create=False, cwd=u'.', default_protocol=u'osfs')

Open a filesystem from a FS URL. Returns a tuple of a filesystem object and a path. If there is no path in the FS URL, the path value will be None.

Parameters:
  • fs_url (str) – A filesystem URL
  • writeable (bool) – True if the filesystem must be writeable.
  • create (bool) – True if the filesystem should be created if it does not exist.
  • cwd (str or None) – The current working directory.
Return type:

Tuple of (<filesystem>, <path from url>)

open_fs(fs_url, writeable=True, create=False, cwd=u'.', default_protocol=u'osfs')

Open a filesystem object from a FS URL (ignoring the path component).

Parameters:
  • fs_url (str) – A filesystem URL
  • parse_result (ParseResult) – A parsed filesystem URL.
  • writeable (bool) – True if the filesystem must be writeable.
  • create (bool) – True if the filesystem should be created if it does not exist.
  • cwd (str) – The current working directory (generally only relevant for OS filesystems).
  • default_protocol (str) – The protocol to use if one is not supplied in the FS URL (defaults to "osfs").
Returns:

FS object

exception fs.opener.Unsupported

May be raised by opener if the opener fails to open a FS.

fs.opener.manage_fs(*args, **kwds)

A context manager opens / closes a filesystem.

Parameters:
  • fs_url (str or FS) – A FS instance or a FS URL.
  • create (bool) – If True, then create the filesytem if it doesn’t already exist.
  • writeable (bool) – If True, then the filesystem should be writeable.
  • cwd (str) – The current working directory, if opening a OSFS.

Sometimes it is convenient to be able to pass either a FS object or an FS URL to a function. This context manager handles the required logic for that.

Here’s an example:

def print_ls(list_fs):
    """List a directory."""
    with manage_fs(list_fs) as fs:
        print(" ".join(fs.listdir()))

This function may be used in two ways. You may either pass either a str, as follows:

print_list('zip://projects.zip')

Or, an FS instance:

from fs.osfs import OSFS
projects_fs = OSFS('~/')
print_list(projects_fs)
fs.opener.parse(fs_url)

Parse a Filesystem URL and return a ParseResult, or raise ParseError (subclass of ValueError) if the FS URL is not value.

Parameters:fs_url (str) – A filesystem URL
Return type:ParseResult