Skip to content

Commit b76696b

Browse files
committed
docs: add cloud URI access documentation
Document the fsspec-based cloud/remote file access feature that was added in PR #523 but never documented. Covers: - Supported protocols (S3, GCS, Azure, HTTPS) - Installation of cloud extras - Usage examples for rdrecord and rdann with remote paths - Authentication guidance for credentialed cloud providers Closes #547
1 parent 6850ad1 commit b76696b

1 file changed

Lines changed: 43 additions & 0 deletions

File tree

docs/io.rst

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

3232

33+
Cloud and Remote Access
34+
-----------------------
35+
36+
WFDB-Python supports reading records and annotations directly from cloud
37+
storage and remote URLs via the ``fsspec`` library. Instead of downloading
38+
entire databases, you can access individual files on demand.
39+
40+
**Supported protocols** include ``s3://`` (Amazon S3), ``gs://`` (Google
41+
Cloud Storage), ``az://`` (Azure Blob Storage), ``https://``, and any
42+
other protocol supported by ``fsspec``.
43+
44+
**Installation:**
45+
46+
.. code-block:: bash
47+
48+
pip install wfdb[cloud]
49+
# or: pip install fsspec s3fs (for S3 specifically)
50+
51+
**Usage examples:**
52+
53+
.. code-block:: python
54+
55+
import wfdb
56+
57+
# Read a record from an HTTPS URL
58+
record = wfdb.rdrecord("100", pn_dir="https://physionet.org/files/mitdb/1.0.0/")
59+
60+
# Read from Amazon S3
61+
record = wfdb.rdrecord("s3://my-bucket/wfdb-data/100")
62+
63+
# Read annotations from a remote path
64+
ann = wfdb.rdann("100", "atr", pn_dir="https://physionet.org/files/mitdb/1.0.0/")
65+
66+
**Authentication:** For cloud providers requiring credentials (S3, GCS,
67+
Azure), configure authentication through the standard provider-specific
68+
mechanism (e.g., ``~/.aws/credentials`` for S3, ``GOOGLE_APPLICATION_CREDENTIALS``
69+
for GCS). The ``fsspec`` library handles credential discovery automatically.
70+
71+
For PhysioNet databases that require credentialed access, you can pass
72+
credentials via ``fsspec`` storage options or configure them in your
73+
environment before calling ``wfdb`` functions.
74+
75+
3376
Downloading
3477
-----------
3578

0 commit comments

Comments
 (0)