fs.opener

Open filesystems from a URL.

fs.opener.base

Defines the Opener abstract base class.

class fs.opener.base.Opener

The opener base class.

An opener is responsible for opening a filesystem for a given protocol.

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

fs.opener.registry

Defines the Registry, which maps protocols and FS URLs to their respective Opener.

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

A registry for Opener instances.

class 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

Registry.get_opener(protocol)

Get the opener class associated to a given protocol.

Parameters:

protocol (str) – A filesystem protocol.
Return type:

Opener.
Raises:
  • UnsupportedProtocol – If no opener could be found.
  • EntryPointLoadingError – If the returned entry point is not an Opener subclass or could not be loaded successfully.
Registry.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)
Registry.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>)
Registry.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
classmethod Registry.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

fs.opener.errors

Errors raised when attempting to open a filesystem.

exception fs.opener.errors.EntryPointError

Raised by the registry when an entry point cannot be loaded.

exception fs.opener.errors.OpenerError

Base class for opener related errors.

exception fs.opener.errors.ParseError

Raised when attempting to parse an invalid FS URL.

exception fs.opener.errors.UnsupportedProtocol

May be raised if no opener could be found for a given protocol.