fs.opener

Open filesystems from a URL.

fs.opener.base

Opener abstract base class.

class fs.opener.base.Opener

The base class for filesystem openers.

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 writable.
• 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).

Raises:

fs.opener.errors.OpenerError – If a filesystem could not be opened for any reason.

Returns:

A filesystem instance.

Return type:

FS

fs.opener.parse

Function to parse FS URLs in to their constituent parts.

class fs.opener.parse.ParseResult

A named tuple containing fields of a parsed FS URL.

protocol

str – The protocol part of the url, e.g. osfs or ftp.

username

str, optional – A username, or None.

password

str, optional – A password, or None.

resource

str – A resource, typically a domain and path, e.g. ftp.example.org/dir.

params

dict – A dictionary of parameters extracted from the query string.

path

str, optional – A path within the filesystem, or None.

fs.opener.parse.parse_fs_url(fs_url)

Parse a Filesystem URL and return a ParseResult.

Parameters:fs_url (str) – A filesystem URL. Returns:a parse result instance. Return type:ParseResult Raises:ParseError – if the FS URL is not valid.

fs.opener.registry

Registry class mapping protocols and FS URLs to their Opener.

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

A registry for Opener instances.

get_opener(protocol)

Get the opener class associated to a given protocol.

Parameters:

protocol (str) – A filesystem protocol.

Returns:

an opener instance.

Return type:

Opener

Raises:

• UnsupportedProtocol – If no opener could be found for the given protocol.
• EntryPointLoadingError – If the returned entry point is not an Opener subclass or could not be loaded successfully.

install(opener)

Install an opener.

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

Note

May be used as a class decorator. For example::

registry = Registry() @registry.install class ArchiveOpener(Opener):

protocols = [‘zip’, ‘tar’]

manage_fs(*args, **kwds)

Get a context manager to open and close a filesystem.

Parameters:

• fs_url (FS or str) – A filesystem instance or a FS URL.
• create (bool, optional) – If True, then create the filesystem if it doesn’t already exist.
• writeable (bool, optional) – If True, then the filesystem must 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.

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 a str, as follows:

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

Or, an filesystem instance:

>>> from fs.osfs import OSFS
>>> projects_fs = OSFS('~/')
>>> print_list(projects_fs)

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, optional) – True if the filesystem must be writeable.
• create (bool, optional) – True if the filesystem should be created if it does not exist.
• cwd (str) – The current working directory.

Returns:

a tuple of (<filesystem>, <path from url>)

Return type:

(FS, str)

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

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

Parameters:

• fs_url (str) – A filesystem URL.
• writeable (bool, optional) – True if the filesystem must be writeable.
• create (bool, optional) – 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:

A filesystem instance.

Return type:

FS

protocols

list – the list of supported protocols.

fs.opener.errors

Errors raised when attempting to open a filesystem.

exception fs.opener.errors.EntryPointError

Bases: fs.opener.errors.OpenerError

An entry point could not be loaded.

exception fs.opener.errors.NotWriteable

Bases: fs.opener.errors.OpenerError

A writable FS could not be created.

exception fs.opener.errors.OpenerError

Bases: exceptions.Exception

Base exception for opener related errors.

exception fs.opener.errors.ParseError

Bases: exceptions.ValueError

Attempt to parse an invalid FS URL.

exception fs.opener.errors.UnsupportedProtocol

Bases: fs.opener.errors.OpenerError

No opener found for the given protocol.