Add filesystem parameter to cf.read as pass-through to cfdm.read (Part 1)

cf/docstring/docstring.py

@@ -686,4 +686,19 @@
                      The subspace is the smallest hyperrectangular
                      subspace that contains all of the selected
                      locations.""",
+    # read filesystem
+    "{{read filesystem: optional}}": """filesystem: optional
+            A pre-authenticated filesystem object (for example an
+            ``fsspec`` filesystem instance) to use for opening the
+            dataset. When provided, *datasets* values are treated as
+            paths understood by *filesystem*, and local string
+            pre-processing (tilde/variable expansion, globbing and
+            directory walking) is bypassed. The file is opened by
+            calling ``filesystem.open(dataset, "rb")``, which returns
+            a file-like object that is passed to the netCDF backend.
+
+            If `None` (the default) then the existing file-opening
+            logic is used.
+
+            .. versionadded:: NEXTVERSION""",
 }

cf/read_write/read.py

@@ -336,6 +336,10 @@ class read(cfdm.read):
 
             .. versionadded:: 3.19.0
 
+        {{read filesystem: optional}}
+
+            .. versionadded:: NEXTVERSION
+
         umversion: deprecated at version 3.0.0
             Use the *um* parameter instead.
 
@@ -455,6 +459,7 @@ def __new__(
         fmt=None,
         file_type=None,
         group_dimension_search="closest_ancestor",
+        filesystem=None,
     ):
         """Read field or domain constructs from a dataset."""
         kwargs = locals()