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
-
abstract
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
orftp
.- 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
- 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 toFalse
.
-
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
- 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
) – anOpener
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
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
Caution
The
writeable
parameter only controls whether the filesystem needs to be writable, which is relevant for some archive filesystems. Passingwriteable=False
will not make the return filesystem read-only. For this, consider usingfs.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.