Merge branch 'master' into fix-484

Author: Diego Argueta

CHANGELOG.md

@@ -8,18 +8,21 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+
+## [2.4.14] - 2021-11-16
+
 ### Added
 
-- Added `fs.copy.copy_file_if`, `fs.copy.copy_dir_if`, and `fs.copy.copy_fs_if`. 
+- Added `fs.copy.copy_file_if`, `fs.copy.copy_dir_if`, and `fs.copy.copy_fs_if`.
   Closes [#458](https://github.com/PyFilesystem/pyfilesystem2/issues/458).
 - Added `fs.base.FS.getmodified`.
-  
+
 ### Changed
 
 - FTP servers that do not support the MLST command now try to use the MDTM command to
-  retrieve the last modification timestamp of a resource. 
+  retrieve the last modification timestamp of a resource.
   Closes [#456](https://github.com/PyFilesystem/pyfilesystem2/pull/456).
-  
+
 ### Fixed
 
 - Fixed performance bugs in `fs.copy.copy_dir_if_newer`. Test cases were adapted to catch those bugs in the future.

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/requirements.txt

@@ -1,3 +1,4 @@
 # the bare requirements for building docs
 Sphinx ~=3.0
 sphinx-rtd-theme ~=0.5.1
+recommonmark ~=0.6

docs/source/conf.py

@@ -39,7 +39,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx'
+    'sphinx.ext.intersphinx',
+    "recommonmark",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -63,7 +64,7 @@
 
 # General information about the project.
 project = u'PyFilesystem'
-copyright = u'2016-2017, Will McGugan'
+copyright = u'2016-2021, Will McGugan and the PyFilesystem2 contributors'
 author = u'Will McGugan'
 
 # The version info for the project you're documenting, acts as replacement for

docs/source/contributing.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

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/index.rst

@@ -25,7 +25,7 @@ Contents:
    external.rst
    interface.rst
    reference.rst
-
+   contributing.md
 
 
 Indices and tables

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/_version.py

@@ -1,3 +1,3 @@
 """Version, used in module and setup.py.
 """
-__version__ = "2.4.13"
+__version__ = "2.4.14"

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.