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

[Copilot]

Exposes the new filesystem keyword from cfdm PR #393 at the cf.read level. All logic lives in cfdm; this is purely a wrapper update.

Changes

• cf/read_write/read.py — adds filesystem=None to cf.read.__new__ signature and documents it via template reference in the docstring. Forwarding is handled by the existing kwargs = locals() / super().__new__(**kwargs) mechanism — no new logic required.
• cf/docstring/docstring.py — adds the {{read filesystem: optional}} substitution definition (mirrors the cfdm PR definition; can be dropped once a cfdm release includes it, as cfdm templates take precedence).

Usage

import fsspec
fs = fsspec.filesystem("s3", anon=True)

# filesystem.open(path, "rb") is called directly; local glob/expansion is bypassed
fields = cf.read("s3://bucket/path/data.nc", filesystem=fs)

NEXTVERSION placeholders in the docstrings follow the same convention used in the prerequisite cfdm PR and will be resolved at release time.

---

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

[davidhassell]

All good, once the docstring bit is removed.

Also, could we add to the Changelog, after the **2026-??-??** line:

* New keyword to `cf.read`: ``filesystem``
  (https://github.com/NCAS-CMS/cf-python/issues/931)

Thanks!

[davidhassell]

Good to go, once NCAS-CMS/cfdm#393 is merged.