fs.opener

Open filesystems from a URL.

fs.opener.base

Opener abstract base class.

class fs.opener.base.Opener[source]

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

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

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

A registry for Opener instances.

get_opener(protocol)[source]

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

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

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

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

the list of supported protocols.

Type:list

fs.opener.errors

Errors raised when attempting to open a filesystem.

exception fs.opener.errors.EntryPointError[source]

Bases: fs.opener.errors.OpenerError

An entry point could not be loaded.

exception fs.opener.errors.NotWriteable[source]

Bases: fs.opener.errors.OpenerError

A writable FS could not be created.

exception fs.opener.errors.OpenerError[source]

Bases: exceptions.Exception

Base exception for opener related errors.

exception fs.opener.errors.ParseError[source]

Bases: exceptions.ValueError

Attempt to parse an invalid FS URL.

exception fs.opener.errors.UnsupportedProtocol[source]

Bases: fs.opener.errors.OpenerError

No opener found for the given protocol.