Updates to documentation to reflect current recommended patterns

Author: chad-earthscope

CHANGELOG.md

@@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `MS3Record.pack()` functionality, use `MS3Record.generate()` instead.
 - `MS3TraceList.pack()` functionality, use `MS3TraceList.generate()` instead.
 
+### Changed
+- Examples updated to reflect current recommended patterns
+
 ### Changed
 - libmseed updated to v3.2.0
 

examples/stream_stats.py

@@ -50,15 +50,15 @@ def to_dict(self):
             "sourceids": sourceids_copy,
         }
 
-    def update(self, record):
+    def update(self, msr):
         """Update statistics with data from a miniSEED record."""
         # Update global statistics
         self.record_count += 1
-        self.sample_count += record.samplecnt
-        self.bytes += record.reclen
+        self.sample_count += msr.samplecnt
+        self.bytes += msr.reclen
 
         # Track per-sourceid statistics
-        sid = record.sourceid
+        sid = msr.sourceid
         if sid not in self.sourceids:
             self.sourceids[sid] = {
                 "record_count": 0,
@@ -70,14 +70,14 @@ def update(self, record):
 
         sid_stats = self.sourceids[sid]
         sid_stats["record_count"] += 1
-        sid_stats["sample_count"] += record.samplecnt
-        sid_stats["bytes"] += record.reclen
+        sid_stats["sample_count"] += msr.samplecnt
+        sid_stats["bytes"] += msr.reclen
 
-        if sid_stats["earliest"] is None or record.starttime < sid_stats["earliest"]:
-            sid_stats["earliest"] = record.starttime
+        if sid_stats["earliest"] is None or msr.starttime < sid_stats["earliest"]:
+            sid_stats["earliest"] = msr.starttime
 
-        if sid_stats["latest"] is None or record.endtime > sid_stats["latest"]:
-            sid_stats["latest"] = record.endtime
+        if sid_stats["latest"] is None or msr.endtime > sid_stats["latest"]:
+            sid_stats["latest"] = msr.endtime
 
 
 def main():
@@ -86,15 +86,15 @@ def main():
 
     # Read miniSEED from stdin and accumulate stats for each record
     stats = StreamStats()
-    with MS3Record.from_file(sys.stdin.fileno()) as reader:
-        for record in reader:
-            # Update statistics with data from the record
-            stats.update(record)
+    for msr in MS3Record.from_file(sys.stdin.fileno()):
+        # Update statistics with data from the record
+        stats.update(msr)
 
-            # Write raw miniSEED record to stdout
-            sys.stdout.buffer.write(record.record)
+        # Write raw miniSEED record to stdout
+        sys.stdout.buffer.write(msr.record)
 
     print(stats, file=sys.stderr)
 
+
 if __name__ == "__main__":
     main()

examples/stream_timewindow.py

@@ -26,27 +26,24 @@ def process_stream(args):
     print("Reading miniSEED from stdin, writing to stdout", file=sys.stderr)
 
     # Read miniSEED from stdin
-    with MS3Record.from_file(sys.stdin.fileno()) as msreader:
-        for msr in msreader:
-            # Skip records completely outside the time window
-            if (args.earliest and msr.endtime < args.earliest) or (
-                args.latest and msr.starttime > args.latest
-            ):
-                continue
-
-            # Trim if record overlaps with time window boundaries
-            output_record = msr.record
-            if (args.earliest and msr.starttime < args.earliest <= msr.endtime) or (
-                args.latest and msr.starttime <= args.latest < msr.endtime
-            ):
-                trimmed_record = trim_record(msr, args.earliest, args.latest)
-                if trimmed_record:
-                    output_record = trimmed_record
-
-            # Write record to stdout
-            sys.stdout.buffer.write(output_record)
-            records_written += 1
-            bytes_written += msr.reclen
+    for msr in MS3Record.from_file(sys.stdin.fileno()):
+        # Skip records completely outside the time window
+        if (args.earliest and msr.endtime < args.earliest) or (
+            args.latest and msr.starttime > args.latest
+        ):
+            continue
+        # Trim if record overlaps with time window boundaries
+        output_record = msr.record
+        if (args.earliest and msr.starttime < args.earliest <= msr.endtime) or (
+            args.latest and msr.starttime <= args.latest < msr.endtime
+        ):
+            trimmed_record = trim_record(msr, args.earliest, args.latest)
+            if trimmed_record:
+                output_record = trimmed_record
+        # Write record to stdout
+        sys.stdout.buffer.write(output_record)
+        records_written += 1
+        bytes_written += msr.reclen
 
     print(f"Wrote {records_written} records, {bytes_written} bytes", file=sys.stderr)
 
@@ -57,17 +54,17 @@ def trim_record(msr, earliest, latest):
     if msr.samplecnt == 0 and msr.samprate == 0.0:
         return None
 
-    # Re-parse the record and decode the data samples
+    # Re-parse the single miniSEED record and decode the data samples
     buffer = bytearray(msr.record)  # Mutable/writable buffer required
     with MS3Record.from_buffer(buffer, unpack_data=True) as msreader:
 
         # Read/parse the single record
-        record = msreader.read()
+        msr_trimmed = msreader.read()
 
-        data_samples = record.datasamples[:]
-        start_time = record.starttime
-        end_time = record.endtime
-        sample_period_ns = int(NSTMODULUS / record.samprate)
+        data_samples = msr_trimmed.datasamples[:]
+        start_time = msr_trimmed.starttime
+        end_time = msr_trimmed.endtime
+        sample_period_ns = int(NSTMODULUS / msr_trimmed.samprate)
 
         # Trim early samples to the earliest time
         if earliest and start_time < earliest <= end_time:
@@ -90,10 +87,10 @@ def trim_record(msr, earliest, latest):
             return None
 
         # Pack the trimmed record
-        record.starttime = start_time
+        msr_trimmed.starttime = start_time
         record_buffer = b""
-        for packed_record in record.generate(
-            data_samples=data_samples, sample_type=record.sampletype
+        for packed_record in msr_trimmed.generate(
+            data_samples=data_samples, sample_type=msr_trimmed.sampletype
         ):
             record_buffer += packed_record
 

src/pymseed/msrecord.py

@@ -1264,8 +1264,12 @@ def to_file(
     def from_file(cls, filename, **kwargs):
         """Create a record reader for miniSEED files.
 
-        This convenience method returns an MS3RecordReader that can iterate
-        over all records in a miniSEED file.
+        This convenience method returns an MS3RecordReader that can iterate over
+        all records in a miniSEED file.
+
+        Note that the objects returned by this iterator are only valid during
+        the lifetime of the iterator. Once the iterator is exhausted, the
+        objects are no longer valid and should not be used.
 
         Args:
             filename: Path to miniSEED file
@@ -1287,8 +1291,12 @@ def from_file(cls, filename, **kwargs):
     def from_buffer(cls, buffer, **kwargs):
         """Create a record reader for miniSEED data in memory.
 
-        This convenience method returns an MS3RecordBufferReader that can iterate
-        over records stored in a memory buffer (bytes-like object).
+        This convenience method returns an MS3RecordBufferReader that can
+        iterate over records stored in a memory buffer (bytes-like object).
+
+        Note that the objects returned by this iterator are only valid during
+        the lifetime of the iterator. Once the iterator is exhausted, the
+        objects are no longer valid and should not be used.
 
         Args:
             buffer: Bytes-like object containing miniSEED data

src/pymseed/msrecord_buffer_reader.py

@@ -24,6 +24,10 @@ class MS3RecordBufferReader:
     parsed sequentially from the beginning of the buffer using the underlying
     libmseed library.
 
+    Note that the objects returned by this iterator are only valid during
+    the lifetime of the iterator. Once the iterator is exhausted, the objects
+    are no longer valid and should not be used.
+
     Args:
         buffer: A buffer-like object containing miniSEED records. Must support
             the buffer protocol (e.g., bytearray, bytes, memoryview, numpy.ndarray).
@@ -45,11 +49,10 @@ class MS3RecordBufferReader:
     >>> with open('examples/example_data.mseed', 'rb') as f:
     ...     buffer = f.read()
 
-    >>> with MS3Record.from_buffer(buffer, unpack_data=True) as reader:
-    ...     total_samples = 0
-    ...     for msr in reader:
-    ...         total_samples += msr.numsamples
-    ...     print(f"Total samples: {total_samples}")
+    >>> total_samples = 0
+    >>> for msr in MS3Record.from_buffer(buffer, unpack_data=True):
+    ...     total_samples += msr.numsamples
+    >>> print(f"Total samples: {total_samples}")
     Total samples: 12600
 
     Notes:

src/pymseed/msrecord_reader.py

@@ -21,21 +21,29 @@ class MS3RecordReader:
     The reader can be used as an iterator to process records sequentially, or as
     a context manager for automatic resource cleanup.
 
+    Note that the objects returned by this iterator are only valid during
+    the lifetime of the iterator. Once the iterator is exhausted, the results
+    are no longer valid and should not be used.
+
     Args:
         input (Union[str, int]): File path (string) or open file descriptor (integer).
             If an integer, it must be a valid open file descriptor. The file or
             descriptor will be automatically closed when close() is called or when
             the object is used as a context manager.
+
         unpack_data (bool, optional): Whether to decode/unpack the data samples from
             the records. If False, only metadata is parsed and data remains in
             compressed format. Defaults to False for better performance when only
             metadata is needed.
+
         skip_not_data (bool, optional): Whether to skip non-data bytes in the input
             stream until a valid miniSEED record is found. Useful for reading from
             streams that may contain other data mixed with miniSEED records.
             Defaults to False.
+
         validate_crc (bool, optional): If True, validate CRC checksums when present in records.
             miniSEED v3 records contain CRCs, but v2 records do not. Default is True.
+
         verbose (int, optional): Verbosity level for for libmseed operations. Higher values
             produce more detailed output. 0 = no output, 1+ = increasing verbosity.
             Defaults to 0 (silent).
@@ -48,11 +56,10 @@ class MS3RecordReader:
 
     >>> from pymseed import MS3Record
 
-    >>> with MS3Record.from_file('examples/example_data.mseed', unpack_data=True) as reader:
-    ...     total_samples = 0
-    ...     for msr in reader:
-    ...         total_samples += msr.numsamples
-    ...     print(f"Total samples: {total_samples}")
+    >>> total_samples = 0
+    >>> for msr in MS3Record.from_file('examples/example_data.mseed', unpack_data=True):
+    ...     total_samples += msr.numsamples
+    >>> print(f"Total samples: {total_samples}")
     Total samples: 12600
 
 
@@ -61,9 +68,10 @@ class MS3RecordReader:
     >>> import os
     >>> fd = os.open('examples/example_data.mseed', os.O_RDONLY)
 
-    >>> with MS3Record.from_file(fd, unpack_data=True) as reader:
-    ...     msrs = list(reader)  # Read all records
-    ...     print(f"Total records: {len(msrs)}")
+    >>> total_records = 0
+    >>> for msr in MS3Record.from_file(fd, unpack_data=False):
+    ...     total_records += 1
+    >>> print(f"Total records: {total_records}")
     Total records: 107
 
     Note: