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

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

Type:str

username

A username, or None.

Type:str, optional

password

A password, or None.

Type:str, optional

resource

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

Type:str

params

A dictionary of parameters extracted from the query string.

Type:dict

path

A path within the filesystem, or None.

Type:str, optional

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='osfs', load_extern=False)

A registry for Opener instances.

__init__(default_opener='osfs', load_extern=False)

Create a registry object.

Parameters:

• default_opener (str, optional) – The protocol to use, if one is not supplied. The default is to use ‘osfs’, so that the FS URL is treated as a system path if no protocol is given.
• load_extern (bool, optional) – Set to True to load openers from PyFilesystem2 extensions. Defaults to False.

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(fs_url, create=False, writeable=False, cwd='.')

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

The manage_fs method can be used to define a small utility function:

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

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

Parameters:

• fs_url (str) – A filesystem URL. If a filesystem instance is given instead, it will be returned transparently.
• 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

Caution

The writeable parameter only controls whether the filesystem needs to be writable, which is relevant for some archive filesystems. Passing writeable=False will not make the return filesystem read-only. For this, consider using fs.wrap.read_only to wrap the returned instance.

protocols

the list of supported protocols.

Type:list

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

Base exception for opener related errors.

exception fs.opener.errors.ParseError

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