Skip to content

Commit f627b5f

Browse files
authored
docs: add cloud storage access documentation (#567)
## Summary Document the `fsspec`-based cloud storage access feature (added in PR #523) which was never documented. ## Content New "Cloud Storage Access" section in `docs/io.rst` covering: - Supported protocols: `s3://`, `gs://`, `az://`, `azureml://` - Backend package installation (`s3fs`, `gcsfs`, `adlfs`) - Usage examples with `rdrecord` and `rdann` - Authentication guidance - Note clarifying that cloud URIs go in `record_name`, not `pn_dir` Closes #547
2 parents 6850ad1 + 1db260d commit f627b5f

1 file changed

Lines changed: 52 additions & 0 deletions

File tree

docs/io.rst

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,58 @@ WFDB Annotations
3030
:members: wrann
3131

3232

33+
Cloud Storage Access
34+
--------------------
35+
36+
WFDB-Python supports reading records and annotations directly from cloud
37+
storage via the ``fsspec`` library. Pass a cloud URI as the
38+
``record_name`` argument instead of a local path.
39+
40+
**Supported protocols:** ``s3://`` (Amazon S3), ``gs://`` (Google Cloud
41+
Storage), ``az://`` (Azure Blob Storage), and ``azureml://`` (Azure ML).
42+
43+
**Prerequisites:** Install the ``fsspec`` backend for your cloud provider:
44+
45+
.. code-block:: bash
46+
47+
pip install s3fs # Amazon S3
48+
pip install gcsfs # Google Cloud Storage
49+
pip install adlfs # Azure Blob Storage
50+
51+
``fsspec`` itself is already included as a core dependency of ``wfdb``.
52+
53+
**Usage examples:**
54+
55+
.. code-block:: python
56+
57+
import wfdb
58+
59+
# Read a record from Amazon S3
60+
record = wfdb.rdrecord("s3://my-bucket/wfdb-data/100")
61+
62+
# Read from Google Cloud Storage
63+
record = wfdb.rdrecord("gs://my-bucket/wfdb-data/100")
64+
65+
# Read annotations from S3
66+
ann = wfdb.rdann("s3://my-bucket/wfdb-data/100", "atr")
67+
68+
# For PhysioNet databases, use pn_dir with the database name:
69+
record = wfdb.rdrecord("100", pn_dir="mitdb")
70+
ann = wfdb.rdann("100", "atr", pn_dir="mitdb")
71+
72+
**Authentication:** Configure credentials through the standard
73+
provider-specific mechanism (e.g., ``~/.aws/credentials`` for S3,
74+
``GOOGLE_APPLICATION_CREDENTIALS`` for GCS). The ``fsspec`` library
75+
handles credential discovery automatically.
76+
77+
.. note::
78+
79+
Cloud URIs must be passed as ``record_name``, not ``pn_dir``.
80+
The ``pn_dir`` parameter is reserved for PhysioNet database names
81+
(e.g., ``"mitdb"`` or ``"mimic4wdb/0.1.0"``), which are resolved
82+
against the configured PhysioNet index URL.
83+
84+
3385
Downloading
3486
-----------
3587

0 commit comments

Comments
 (0)