Add rspace_client.fs: the Gallery, Inventory and ELN Workspace as one fsspec filesystem

CHANGELOG.md

@@ -8,6 +8,36 @@ All notable changes to this project will be documented in this file
 
 ## 2.8.0 (unreleased)
 
+- New `rspace_client.fs`: RSpace as an [fsspec](https://filesystem-spec.readthedocs.io)
+  filesystem. `RSpaceFilesystem` mounts `gallery/`, `inventory/` and `workspace/` (Gallery
+  folders and files; Inventory benches, containers, samples, subsamples, templates and
+  instruments as folders of their records and attachments, attachment fields as one-file
+  folders; ELN folders, notebooks and documents, a document as a folder of its text fields
+  and a field as a folder of its linked files). Paths are record names; duplicate names
+  and names that read as addresses carry their global ID (`data [GL112].csv`);
+  `path_style="labelled"` / `"id"` for stable paths. Read-only by default (`writable=True`,
+  `allow_delete=True`). Uploads into Inventory and the Workspace go through the Gallery and
+  link; `cp_file` from any Gallery-backed file links instead of copying bytes. Transactions
+  defer uploads. `rspace://host` URLs via `fsspec.open`, `fsspec.filesystem("rspace")` and
+  `UPath` (registered as an `fsspec.specs` entry point), key from `RSPACE_API_KEY` only. `glob("<dir>/*<text>*")` answers Galaxy's search
+  including bracketed names. New dependency `fsspec`.
+- Deprecated `rspace_client.eln.fs.GalleryFilesystem` and
+  `rspace_client.inv.attachment_fs.InventoryAttachmentFilesystem` (PyFilesystem2, unmaintained
+  upstream). Unchanged in behaviour apart from the fixes below, now emit a `DeprecationWarning`; removal together with
+  the `fs` dependency in 3.0, after Galaxy's shipped plugin has moved to `rspace_client.fs`.
+- Fix: uploads accept a file object that forwards `read` through `__getattr__`. requests 2.34
+  refuses such objects on Python 3.12+, which broke exports from Galaxy 26.1 (it pins requests
+  2.34.2) to RSpace through Galaxy's shipped `rspace` file source.
+- Fix: `GalleryFilesystem` reports a file's `created` date as `+00:00` instead of RSpace's
+  trailing `Z` (the same UTC instant). Galaxy's shipped `rspace` file source parses it with
+  `datetime.fromisoformat`, which rejects `Z` before Python 3.11, so on Python 3.10 Galaxy
+  failed to list any Gallery folder holding files.
+- `rspace_client/tests/galaxy_plugin_contract_test.py` pins what Galaxy's shipped plugin relies
+  on; a failure there is a release blocker.
+- Tests: the Link-field integration tests always run instead of needing
+  `RSPACE_SUPPORTS_LINK_FIELDS=1`; current RSpace releases support Link fields.
+- `tools/galaxy/rspace_fsspec_source.py`: the reference Galaxy file source for the new
+  filesystem, to be proposed upstream.
 - Security: the client never follows an HTTP redirect, since `requests` would carry the
   `apiKey` header to the new host.
 - Client-level changes: `_links` URLs are rebased onto the configured base URL, path prefix

DEVELOPING.md

@@ -58,6 +58,10 @@ All top-level methods for use by client code should be unit-tested.
 
 RSpace can be run on Docker on a developer machine, providing access to a sandbox environment.
 
+#### Galaxy's RSpace file source
+
+Galaxy ships an `rspace` file source built on this library's deprecated `rspace_client.eln.fs.GalleryFilesystem`, so changes here can break Galaxy. `rspace_client/tests/galaxy_plugin_contract_test.py` pins what it relies on and runs with the normal suite; a failure there is a release blocker. [tools/galaxy/README.md](tools/galaxy/README.md) shows how to drive Galaxy's real plugin without a Galaxy server, and how to try the fsspec file source proposed for Galaxy. Why the contract looks the way it does is in [docs/fsspec-filesystem-design.md](docs/fsspec-filesystem-design.md), section 8.
+
 
 ### Making a release
 

README.md

@@ -45,7 +45,7 @@ Full REST API reference is served by your own RSpace instance at `https://<YOUR_
 | Inventory: samples, subsamples, containers                       | Create and manage samples, split/duplicate subsamples, organise items into containers                                                                                                    |
 | Instruments & Instrument Templates *(new in 2.7.0, RSpace 2.24)* | Create, update, and manage Inventory instruments and instrument templates                                                                                                                |
 | Export                                                           | Async export of a user's or group's work (or specific documents/notebooks/folders) to HTML or XML, with progress polling                                                                 |
-| PyFilesystem access                                              | `GalleryFilesystem` and `InventoryAttachmentFilesystem` implement the [PyFilesystem](https://docs.pyfilesystem.org/en/latest/index.html) API for Gallery files and Inventory attachments |
+| Filesystem access (fsspec)                                      | `rspace_client.fs.RSpaceFilesystem` presents the Gallery, Inventory and Workspace as one [fsspec](https://filesystem-spec.readthedocs.io) filesystem (`rspace://` URLs, `UPath`, Galaxy); the PyFilesystem `GalleryFilesystem` and `InventoryAttachmentFilesystem` are deprecated |
 | Notebook / Jupyter / R interop (`notebook_sync`)                 | Helpers for round-tripping data between RSpace notebook entries and Jupyter or R workflows                                                                                               |
 | Activity / audit trail                                           | Query "who did what, when" for a record or across a date range                                                                                                                           |
 | Forms                                                            | Create, publish, share, and list custom forms; create documents from them                                                                                                                |