fs.opener

Open filesystems from a URL.

fs.opener._base

Defines the Opener abstract base class.

class fs.opener._base.Opener[source]

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)[source]

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='osfs')[source]

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.install(opener)[source]

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']
Registry.manage_fs(*args, **kwds)[source]

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='.', default_protocol='osfs')[source]

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='.', default_protocol='osfs')[source]

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)[source]

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.OpenerError[source]

Base class for opener related errors.

exception fs.opener._errors.ParseError[source]

Raised when attempting to parse an invalid FS URL.

exception fs.opener._errors.Unsupported[source]

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