Documentation

sohstationviewer/model/mseed/read_mseed_experiment/mseed_helper.py

@@ -16,8 +16,9 @@ class Unpacker:
 
     def unpack(self, format: str, buffer: bytes):
         """
-
-        :param format:
+        Unpack a string of bytes into a tuple of values based on the given
+        format
+        :param format: the format used to unpack the byte string
         :param buffer: the byte string
         :return: a tuple containing the unpacked values.
         """
@@ -31,6 +32,10 @@ class Unpacker:
 
 @dataclass
 class FixedHeader:
+    """
+    The fixed portion of the header of a data record. All fields are stored as
+    bytes to minimize time wasted on decoding unused values.
+    """
     sequence_number: bytes
     data_header_quality_indicator: bytes
     reserved: bytes
@@ -53,6 +58,10 @@ class FixedHeader:
 
 @dataclass
 class Blockette1000:
+    """
+    Blockette 100 of a data record. All fields are stored as bytes to minimize
+    time wasted on decoding unused values.
+    """
     blockette_type: bytes
     next_blockette_offset: bytes
     encoding_format: bytes
@@ -63,6 +72,9 @@ class Blockette1000:
 
 @dataclass
 class RecordMetadata:
+    """
+    The metadata of a data record.
+    """
     station: str
     location: str
     channel: str
@@ -94,12 +106,11 @@ def get_header_endianness(header: FixedHeader):
     not affect it. Similarly, 257 is also 2-octet-palindromic. Meanwhile, 1 and
     256 are counterparts when encoded as pairs of octets. Because they are both
     valid values for day of year, it is impossible to make a conclusion about
-    endianness based on day of year if it is either 1 or 256 in big-endian. On
-    the other hand, 257 is a palindrome. These two facts combined means that we
-    cannot determine the endianness of the header that starts on the
-    aforementioned dates. The way this function was written, the endianness
-    will be determined to be big in these cases. This problem is also recorded
-    in libmseed.
+    endianness based on day of year if it is either 1 or 256 in big-endian.
+    These facts combined means that we cannot determine the endianness of the
+    header whose record starts on the aforementioned dates. The way this
+    function was written, the endianness will be recorded as big in these
+    cases. This problem is also recorded in libmseed.
 
     :param header: the fixed header of the data record
     :return: either of the string 'big' or 'little' depending on the extracted
@@ -122,7 +133,6 @@ def get_data_endianness(blockette_1000: Blockette1000):
     """
     Get endianness of a data record by examining blockette 1000.
 
-    :param fixed_header: the fixed header of the data record.
     :param blockette_1000: the blockette 1000 of the data record.
     """
     # The byte order is only one byte so using big or little endian does not
@@ -160,6 +170,14 @@ def calculate_sample_rate(factor: int, multiplier: int) -> float:
 
 
 def get_record_metadata(header: FixedHeader, header_unpacker: Unpacker):
+    """
+    Extract and parse the metadata of a data record from its fixed header.
+
+    :param header: the fixed header of the data record
+    :param header_unpacker: the unpacker corresponding to the data record;
+        needed so that the correct byte order can be used
+    :return: the extract record metadata
+    """
     station = header.station.decode('utf-8').rstrip()
     location = header.location.decode('utf-8').rstrip()
     channel = header.channel.decode('utf-8').rstrip()