Merge pull request #502 from PyFilesystem/update-docs

Update documentation for `v2.4.14`

CONTRIBUTORS.md

@@ -6,6 +6,7 @@ Many thanks to the following developers for contributing to this project:
 - [Andreas Tollkötter](https://github.com/atollk)
 - [Andrew Scheller](https://github.com/lurch)
 - [Andrey Serov](https://github.com/zmej-serow)
+- [Ben Lindsay](https://github.com/benlindsay)
 - [Bernhard M. Wiedemann](https://github.com/bmwiedemann)
 - [@chfw](https://github.com/chfw)
 - [Dafna Hirschfeld](https://github.com/kamomil)
@@ -17,6 +18,7 @@ Many thanks to the following developers for contributing to this project:
 - [George Macon](https://github.com/gmacon)
 - [Giampaolo Cimino](https://github.com/gpcimino)
 - [@Hoboneer](https://github.com/Hoboneer)
+- [Jon Hagg](https://github.com/jon-hagg)
 - [Joseph Atkins-Turkish](https://github.com/Spacerat)
 - [Joshua Tauberer](https://github.com/JoshData)
 - [Justin Charlong](https://github.com/jcharlong)

docs/source/extension.rst

@@ -29,7 +29,8 @@ Here's an example taken from an Amazon S3 Filesystem::
 
   __all__ = ['S3FSOpener']
 
-  from fs.opener import Opener, OpenerError
+  from fs.opener import Opener
+  from fs.opener.errors import OpenerError
 
   from ._s3fs import S3FS
 

docs/source/openers.rst

@@ -56,3 +56,25 @@ To open a filesysem with a FS URL, you can use :meth:`~fs.opener.registry.Regist
 
     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

fs/base.py

@@ -910,7 +910,8 @@ def geturl(self, path, purpose="download"):
                 to retrieve for the given path (if there is more than
                 one). The default is ``'download'``, which should return
                 a URL that serves the file. Other filesystems may support
-                other values for ``purpose``.
+                other values for ``purpose``: for instance, `OSFS` supports
+                ``'fs'``, which returns a FS URL (see :ref:`fs-urls`).
 
         Returns:
             str: a URL.

fs/subfs.py

@@ -21,7 +21,7 @@
 
 @six.python_2_unicode_compatible
 class SubFS(WrapFS[_F], typing.Generic[_F]):
-    """A sub-directory on another filesystem.
+    """A sub-directory on a parent filesystem.
 
     A SubFS is a filesystem object that maps to a sub-directory of
     another filesystem. This is the object that is returned by