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.

abstract open_fs(fs_url: Text, parse_result: ParseResult, writeable: bool, create: bool, cwd: Text) → FS[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: Text) → ParseResult[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: Text = 'osfs', load_extern: bool = False)[source]

A registry for Opener instances.

__init__(default_opener: Text = 'osfs', load_extern: bool = False) → None[source]

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: Text) → Opener[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: Union[Type[Opener], Opener, Callable[[], Opener]]) → 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(fs_url: Union[FS, Text], create: bool = False, writeable: bool = False, cwd: Text = '.') → Iterator[FS][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

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: Text, writeable: bool = True, create: bool = False, cwd: Text = '.', default_protocol: Text = 'osfs') → Tuple[FS, Text][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: Union[FS, Text], writeable: bool = False, create: bool = False, cwd: Text = '.', default_protocol: Text = 'osfs') → FS[source]

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.

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

Base exception for opener related errors.

exception fs.opener.errors.ParseError[source]

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