Add support for reading and writing .wfdb archive files (#541)

As discussed in wfdb/wfdb-spec#21 and
#540 we would like to allow
WFDB Records to be saved to a single file `.wfdb`.

This pull request introduces support for reading and writing `.wfdb`
archive files: a ZIP file that holds the header, signal and annotation
files of a single record.

## Implementation

The pull request has three commits:

1. **Reading.** `rdrecord`, `rdsamp`, `rdheader` and `rdann` read from
an archive when given its path, including the `.wfdb` extension (for
example `wfdb.rdrecord("100.wfdb")`).
- The header is the file named after the archive (`100.hea` in
`100.wfdb`), or the only header in the archive. Signal and annotation
files are read by the names that follow from the header, and a missing
file is an error.
- `rdrecord` reads the header and signals from a single open archive.
Archives are opened and closed within each call, so nothing is cached
between calls.
- Headers larger than 1 MB are rejected, as a guard against damaged or
malicious archives.
2. **Writing.** `wrsamp` and `Record.wrsamp` take a `wfdb_archive`
argument: a path, or an open `WFDBArchive`.
- A new archive is written to a temporary file and moved into place only
when writing succeeds. A failed write leaves no partial archive, and an
existing archive at the same path is either fully replaced or left
unchanged.
- New archives get the permissions of the archive they replace, or the
default permissions for new files.
- `create_archive(file_paths, archive_path)` puts the files of an
existing record into an archive.
3. **Docs.** A section on archives in the I/O docs, and a changelog
entry.

Format details:

- **One record per archive.** `WFDBArchive` refuses to write a second
header file, so it's always clear which record an archive holds.
Annotation and other files can be added alongside the record.
- **Compression.** Header files are compressed. Signal files are stored
without compression, so that reading a range of samples doesn't require
decompressing the whole file.

Not supported yet: multi-segment records, and archives in cloud storage
or on PhysioNet. These raise a clear error. Multi-segment support would
extend the one-record rule to "the main header plus the segment headers
it lists", and is planned as a follow-up.

## Example usage

```python
import numpy as np
import wfdb
from wfdb.io.archive import WFDBArchive, create_archive

# Write a record straight into an archive
record = wfdb.rdrecord("sample-data/test01_00s", physical=False)
record.wrsamp(wfdb_archive="test01_00s.wfdb")

# Read it back, in full or in part
archive_record = wfdb.rdrecord("test01_00s.wfdb", physical=False)
np.testing.assert_array_equal(archive_record.d_signal, record.d_signal)
part = wfdb.rdrecord("test01_00s.wfdb", sampfrom=100, sampto=200, channels=[0, 2])
signals, fields = wfdb.rdsamp("test01_00s.wfdb")
header = wfdb.rdheader("test01_00s.wfdb")

# Or with the wrsamp function
wfdb.wrsamp(
    "ecg",
    fs=250,
    units=["mV", "mV"],
    sig_name=["I", "II"],
    p_signal=np.random.default_rng(0).standard_normal((1000, 2)),
    fmt=["16", "16"],
    wfdb_archive="ecg.wfdb",
)

# Put an existing record and its annotations into an archive
create_archive(
    ["sample-data/100.hea", "sample-data/100.dat", "sample-data/100.atr"],
    "100.wfdb",
)
annotation = wfdb.rdann("100.wfdb", "atr")

# Add an annotation file while writing a record
with WFDBArchive("100_copy.wfdb", mode="w") as archive:
    wfdb.rdrecord("sample-data/100", physical=False).wrsamp(wfdb_archive=archive)
    archive.add_file("sample-data/100.atr")
```

Note: `Record.wrsamp` writes the digital signal, so the record is read
with `physical=False` above. Calling it on a record read with physical
signals fails with an unclear `TypeError`. That's existing behaviour,
not specific to archives, and could be improved separately.

## Tests

`tests/test_archive.py` compares records read from archives with the
same records read from separate files, including FLAC formats, multiple
samples per frame and sample ranges. It also covers writing,
annotations, the one-record rule, permissions, failed writes, and error
cases such as missing files and unsupported multi-segment records.

Author: tompollard

docs/changes.rst

@@ -74,6 +74,9 @@ Unreleased
 **Allow None for annotations without notes in wrann**
   ``wrann`` now accepts ``None`` in ``aux_note`` for annotations without a note, as the docstring says, and writes it the same way as an empty string. It used to raise a ``TypeError``.
 
+**Read and write .wfdb archive files**
+  A record can be stored in a single ``.wfdb`` archive file (a ZIP file containing the header and signal files). ``rdrecord``, ``rdsamp``, ``rdheader`` and ``rdann`` read a record or its annotations from an archive when given the path of the archive, and ``wrsamp`` writes a record into an archive with the new ``wfdb_archive`` argument.
+
 Version 4.3.1 (Feb 2026)
 -----------------------------
 

docs/io.rst

@@ -34,6 +34,54 @@ WFDB Annotations
     :members: wrann
 
 
+WFDB Archives
+-------------
+
+A ``.wfdb`` archive is a ZIP file containing the files of a single
+record: its header file, the signal files listed in the header, and
+optionally annotation files. The files are at the top level of the
+archive, and the header file is named after the archive (for example,
+``100.wfdb`` contains ``100.hea``).
+Files are stored without compression, so that part of a signal can be
+read without decompressing the whole file. Archives made by other tools
+may compress their files, and can still be read.
+
+To read a record from an archive, pass the path of the archive,
+including the ``.wfdb`` extension, to ``rdrecord``, ``rdsamp`` or
+``rdheader``. Annotations are read the same way with ``rdann``. To
+write a record into an archive, pass the path of the archive as the
+``wfdb_archive`` argument of ``wrsamp``.
+
+.. code-block:: python
+
+    import wfdb
+
+    # Write a record into an archive
+    wfdb.wrsamp("100", fs=360, units=["mV"], sig_name=["MLII"],
+                p_signal=signal, fmt=["212"], wfdb_archive="100.wfdb")
+
+    # Read the record back, or part of it
+    record = wfdb.rdrecord("100.wfdb")
+    record = wfdb.rdrecord("100.wfdb", sampfrom=1000, sampto=2000)
+
+    # Put the files of an existing record, including its annotations,
+    # into an archive, and read the annotations
+    from wfdb.io.archive import create_archive
+    create_archive(["100.hea", "100.dat", "100.atr"], "100.wfdb")
+    annotation = wfdb.rdann("100.wfdb", "atr")
+
+An archive holds a single record, so only one header file can be
+written to it. Annotation files can be added alongside the record.
+Multi-segment records, and archives in cloud storage or on PhysioNet,
+are not supported yet.
+
+.. autofunction:: wfdb.io.archive.create_archive
+
+.. autoclass:: wfdb.io.archive.WFDBArchive
+    :members: namelist, exists, file_size, open, header_file_name,
+              read_header, write, add_file, close, abort
+
+
 Cloud Storage Access
 --------------------
 

src/wfdb/io/_header.py

@@ -290,7 +290,7 @@ def set_defaults(self):
         for f in sfields:
             self.set_default(f)
 
-    def wrheader(self, write_dir="", expanded=True):
+    def wrheader(self, write_dir="", expanded=True, wfdb_archive=None):
         """Write a WFDB header file.
 
         The signals are not used. Before writing:
@@ -307,6 +307,9 @@ def wrheader(self, write_dir="", expanded=True):
             Whether the header file should include `samps_per_frame` (this
             should only be true if the signal files are written using
             `expanded=True`).
+        wfdb_archive : WFDBArchive, optional
+            An open .wfdb archive to write the header file to, instead of
+            `write_dir`.
 
         Returns
         -------
@@ -338,7 +341,7 @@ def wrheader(self, write_dir="", expanded=True):
         self.check_field_cohesion(rec_write_fields, list(sig_write_fields))
 
         # Write the header file using the specified fields
-        self.wr_header_file(rec_write_fields, sig_write_fields, write_dir)
+        self.wr_header_file(rec_write_fields, sig_write_fields, write_dir, wfdb_archive)
 
     def get_write_fields(self):
         """Get the header fields to write, split into record and signal fields.
@@ -514,7 +517,9 @@ def check_field_cohesion(self, rec_write_fields, sig_write_fields):
                                 "Each file_name (dat file) specified must have the same byte offset"
                             )
 
-    def wr_header_file(self, rec_write_fields, sig_write_fields, write_dir):
+    def wr_header_file(
+        self, rec_write_fields, sig_write_fields, write_dir, wfdb_archive=None
+    ):
         """Write a header file using the specified fields.
 
         Converts Record attributes into appropriate WFDB format strings.
@@ -528,6 +533,9 @@ def wr_header_file(self, rec_write_fields, sig_write_fields, write_dir):
             being equal to a list of channels to write for each field.
         write_dir : str
             The directory in which to write the header file.
+        wfdb_archive : WFDBArchive, optional
+            An open .wfdb archive to write the header file to, instead of
+            `write_dir`.
 
         Returns
         -------
@@ -572,7 +580,11 @@ def wr_header_file(self, rec_write_fields, sig_write_fields, write_dir):
             comment_lines = ["# " + comment for comment in self.comments]
             header_lines += comment_lines
 
-        util.lines_to_file(self.record_name + ".hea", write_dir, header_lines)
+        if wfdb_archive is not None:
+            content = "".join(f"{line}\n" for line in header_lines)
+            wfdb_archive.write(self.record_name + ".hea", content.encode("utf-8"))
+        else:
+            util.lines_to_file(self.record_name + ".hea", write_dir, header_lines)
 
 
 class MultiHeaderMixin(BaseHeaderMixin):