1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
.. _fs-urls:
FS URLs
=======
PyFilesystem can open a filesystem via an *FS URL*, which is similar to a URL you might enter in to a browser. FS URLs are useful if you want to specify a filesystem dynamically, such as in a conf file or from the command line.
Format
------
FS URLs are formatted in the following way::
<protocol>://<username>:<password>@<resource>
The components are as follows:
* ``<protocol>`` Identifies the type of filesystem to create. e.g. ``osfs``, ``ftp``.
* ``<username>`` Optional username.
* ``<password>`` Optional password.
* ``<resource>`` A *resource*, which may be a domain, path, or both.
Here are a few examples::
osfs://~/projects
osfs://c://system32
ftp://ftp.example.org/pub
mem://
ftp://will:daffodil@ftp.example.org/private
If ``<type>`` is not specified then it is assumed to be an :class:`~fs.osfs.OSFS`, i.e. the following FS URLs are equivalent::
osfs://~/projects
~/projects
.. note::
The `username` and `passwords` fields may not contain a colon (``:``) or an ``@`` symbol. If you need these symbols they may be `percent encoded <https://en.wikipedia.org/wiki/Percent-encoding>`_.
URL Parameters
--------------
FS URLs may also be appended with a ``?`` symbol followed by a url-encoded query string. For example::
myprotocol://example.org?key1=value1&key2
The query string would be decoded as ``{"key1": "value1", "key2": ""}``.
Query strings are used to provide additional filesystem-specific information used when opening. See the filesystem documentation for information on what query string parameters are supported.
Opening FS URLS
---------------
To open a filesysem with a FS URL, you can use :meth:`~fs.opener.registry.Registry.open_fs`, which may be imported and used as follows::
from fs import open_fs
projects_fs = open_fs('osfs://~/projects')
Manually registering Openers
----------------------------
The ``fs.opener`` registry uses an entry point to install external openers
(see :ref:`extension`), and it does so once, when you import `fs` for the first
time. In some rare cases where entry points are not available (for instance,
when running an embedded interpreter) or when extensions are installed *after*
the interpreter has started (for instance in a notebook, see
`PyFilesystem2#485 <https://github.com/PyFilesystem/pyfilesystem2/issues/485>`_).
However, a new opener can be installed manually at any time with the
`fs.opener.registry.install` method. For instance, here's how the opener for
the `s3fs <https://github.com/PyFilesystem/s3fs>`_ extension can be added to
the registry::
import fs.opener
from fs_s3fs.opener import S3FSOpener
fs.opener.registry.install(S3FSOpener)
# fs.open_fs("s3fs://...") should now work
|
