Document reserved characters in FS URL resources

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   Closes [#459](https://github.com/PyFilesystem/pyfilesystem2/issues/459).
 
 ### Fixed
+- Documented reserved characters in FS URL resources.
+  Closes [#562](https://github.com/PyFilesystem/pyfilesystem2/issues/562).
 - Elaborated documentation of `filter_dirs` and `exclude_dirs` in `fs.walk.Walker`.
   Closes [#371](https://github.com/PyFilesystem/pyfilesystem2/issues/371).
 - Fixes a backward incompatibility where `fs.move.move_file` raises `DestinationExists`

CONTRIBUTORS.md

@@ -20,6 +20,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)
+- [@Hugohong258](https://github.com/Hugohong258)
 - [Jen Hagg](https://github.com/jenhagg)
 - [Joseph Atkins-Turkish](https://github.com/Spacerat)
 - [Joshua Tauberer](https://github.com/JoshData)

docs/source/openers.rst

@@ -36,6 +36,17 @@ If ``<type>`` is not specified then it is assumed to be an :class:`~fs.osfs.OSFS
 .. 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>`_.
 
+The characters ``!`` and ``?`` have special meanings in an FS URL: ``!``
+separates an optional path within the filesystem, and ``?`` starts the query
+string. Percent-encode them when they are part of the resource itself. For
+example, to open an OS directory named ``!active`` under ``projects``, use::
+
+    from fs import open_fs
+    projects_fs = open_fs("osfs://projects/%21active")
+
+This also applies when the protocol is omitted. An unescaped ``!`` would be
+interpreted as the path separator, and ``open_fs`` ignores that path component.
+
 
 URL Parameters
 --------------