From 48b72d8247c4f11769b40fd4f66125fb8432acc0 Mon Sep 17 00:00:00 2001 From: Hugohong258 <282228220+Hugohong258@users.noreply.github.com> Date: Thu, 29 Oct 2026 09:05:27 +0800 Subject: [PATCH] Document reserved characters in FS URL resources --- CHANGELOG.md | 2 ++ CONTRIBUTORS.md | 1 + docs/source/openers.rst | 11 +++++++++++ 3 files changed, 14 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ef16734e..89c594a4 100644 --- a/CHANGELOG.md +++ b/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` diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 78102487..0c83dd51 100644 --- a/CONTRIBUTORS.md +++ b/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) diff --git a/docs/source/openers.rst b/docs/source/openers.rst index b5a2a823..5a2ad96d 100644 --- a/docs/source/openers.rst +++ b/docs/source/openers.rst @@ -36,6 +36,17 @@ If ```` 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 `_. +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 --------------