merge main; address PR suggestions; fix docs

Author: Teque5

docs/source/advanced.rst

@@ -22,26 +22,28 @@ the recording of the SigMF logo used in this example `from the specification
     signal = sigmffile.fromfile(path)
 
     # Get some metadata and all annotations
-    sample_rate = signal.get_global_field(SigMFFile.SAMPLE_RATE_KEY)
+    sample_rate = signal.get_global_field(sigmf.SAMPLE_RATE_KEY)
     sample_count = signal.sample_count
     signal_duration = sample_count / sample_rate
     annotations = signal.get_annotations()
 
     # Iterate over annotations
     for adx, annotation in enumerate(annotations):
-        annotation_start_idx = annotation[SigMFFile.START_INDEX_KEY]
-        annotation_length = annotation[SigMFFile.LENGTH_INDEX_KEY]
-        annotation_comment = annotation.get(SigMFFile.COMMENT_KEY, "[annotation {}]".format(adx))
+        annotation_start_idx = annotation[sigmf.SAMPLE_START_KEY]
+        annotation_length = annotation[sigmf.SAMPLE_COUNT_KEY]
+        annotation_comment = annotation.get(
+            sigmf.COMMENT_KEY, "[annotation {}]".format(adx)
+        )
 
         # Get capture info associated with the start of annotation
         capture = signal.get_capture_info(annotation_start_idx)
-        freq_center = capture.get(SigMFFile.FREQUENCY_KEY, 0)
+        freq_center = capture.get(sigmf.FREQUENCY_KEY, 0)
         freq_min = freq_center - 0.5 * sample_rate
         freq_max = freq_center + 0.5 * sample_rate
 
         # Get frequency edges of annotation (default to edges of capture)
-        freq_start = annotation.get(SigMFFile.FREQ_LOWER_EDGE_KEY)
-        freq_stop = annotation.get(SigMFFile.FREQ_UPPER_EDGE_KEY)
+        freq_start = annotation.get(sigmf.FREQ_LOWER_EDGE_KEY)
+        freq_stop = annotation.get(sigmf.FREQ_UPPER_EDGE_KEY)
 
         # Get the samples corresponding to annotation
         samples = signal.read_samples(annotation_start_idx, annotation_length)
@@ -72,19 +74,19 @@ First, create a single SigMF Recording and save it to disk:
     meta = SigMFFile(
         data_file="example_cf32.sigmf-data",  # extension is optional
         global_info={
-            SigMFFile.DATATYPE_KEY: get_data_type_str(data),  # in this case, 'cf32_le'
-            SigMFFile.SAMPLE_RATE_KEY: 48000,
-            SigMFFile.AUTHOR_KEY: "jane.doe@domain.org",
-            SigMFFile.DESCRIPTION_KEY: "All zero complex float32 example file.",
+            sigmf.DATATYPE_KEY: get_data_type_str(data),  # in this case, 'cf32_le'
+            sigmf.SAMPLE_RATE_KEY: 48000,
+            sigmf.AUTHOR_KEY: "jane.doe@domain.org",
+            sigmf.DESCRIPTION_KEY: "All zero complex float32 example file.",
         },
     )
 
     # create a capture key at time index 0
     meta.add_capture(
         0,
         metadata={
-            SigMFFile.FREQUENCY_KEY: 915000000,
-            SigMFFile.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
+            sigmf.FREQUENCY_KEY: 915000000,
+            sigmf.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
         },
     )
 
@@ -93,9 +95,9 @@ First, create a single SigMF Recording and save it to disk:
         100,
         200,
         metadata={
-            SigMFFile.FLO_KEY: 914995000.0,
-            SigMFFile.FHI_KEY: 915005000.0,
-            SigMFFile.COMMENT_KEY: "example annotation",
+            sigmf.FREQ_LOWER_EDGE_KEY: 914995000.0,
+            sigmf.FREQ_UPPER_EDGE_KEY: 915005000.0,
+            sigmf.COMMENT_KEY: "example annotation",
         },
     )
 
@@ -118,9 +120,9 @@ Now lets add another SigMF Recording and associate them with a SigMF Collection:
     meta_ci16 = SigMFFile(
         data_file="example_ci16.sigmf-data",  # extension is optional
         global_info={
-            SigMFFile.DATATYPE_KEY: "ci16_le",  # get_data_type_str() is only valid for numpy types
-            SigMFFile.SAMPLE_RATE_KEY: 48000,
-            SigMFFile.DESCRIPTION_KEY: "All zero complex int16 file.",
+            sigmf.DATATYPE_KEY: "ci16_le",  # get_data_type_str() is only valid for numpy types
+            sigmf.SAMPLE_RATE_KEY: 48000,
+            sigmf.DESCRIPTION_KEY: "All zero complex int16 file.",
         },
     )
     meta_ci16.add_capture(0, metadata=meta.get_capture_info(0))
@@ -153,59 +155,34 @@ The SigMF Collection and its associated Recordings can now be loaded like this:
 Load a SigMF Archive and slice without untaring
 -----------------------------------------------
 
-Since an *archive* is a tarball (uncompressed by default), and since there are many
-excellent tools for manipulating tar files, it's fairly straightforward to
-access the *data* part of a SigMF archive without un-taring it. This is a
-compelling feature because **1** archives make it harder for the ``-data`` and
-the ``-meta`` to get separated, and **2** some datasets are so large that it
-can be impractical (due to available disk space, or slow network speeds if the
-archive file resides on a network file share) or simply obnoxious to untar it
-first.
+Since an *archive* is a tarball (uncompressed by default), you can access the
+*data* part of a SigMF archive without un-taring it. This is a compelling
+feature because **1** archives make it harder for the ``-data`` and the
+``-meta`` to get separated, and **2** some datasets are so large that it can be
+impractical (due to available disk space, or slow network speeds if the archive
+file resides on a network file share) or simply obnoxious to untar it first.
 
 ::
 
     >>> import sigmf
-    >>> arc = sigmf.SigMFArchiveReader('/src/LTE.sigmf')
-    >>> arc.shape
+    >>> signal = sigmf.fromarchive('/src/LTE.sigmf')
+    >>> signal.shape
     (15379532,)
-    >>> arc.ndim
+    >>> signal.ndim
     1
-    >>> arc[:10]
+    >>> signal[:10]
     array([-20.+11.j, -21. -6.j, -17.-20.j, -13.-52.j,   0.-75.j,  22.-58.j,
             48.-44.j,  49.-60.j,  31.-56.j,  23.-47.j], dtype=complex64)
 
-The preceeding example exhibits another feature of this approach; the archive
-``LTE.sigmf`` is actually ``complex-int16``'s on disk, for which there is no
-corresponding type in ``numpy``. However, the ``.sigmffile`` member keeps track of
-this, and converts the data to ``numpy.complex64`` *after* slicing it, that is,
-after reading it from disk.
+If the archive contains ``complex-int16`` data on disk (which has no
+corresponding ``numpy`` type), the data is automatically converted to
+``numpy.complex64`` after slicing:
 
 ::
 
-    >>> arc.sigmffile.get_global_field(sigmf.SigMFFile.DATATYPE_KEY)
+    >>> signal.get_global_field(sigmf.DATATYPE_KEY)
     'ci16_le'
 
-    >>> arc.sigmffile._memmap.dtype
-    dtype('int16')
-
-    >>> arc.sigmffile._return_type
-    '<c8'
-
-Another supported mode is the case where you might have an archive that *is not
-on disk* but instead is simply ``bytes`` in a python variable.
-
-Instead of needing to write this out to a temporary file before being able to
-read it, this can be done "in mid air" or "without touching the ground (disk)".
-
-::
-
-    >>> import sigmf, io
-    >>> sigmf_bytes = io.BytesIO(open('/src/LTE.sigmf', 'rb').read())
-    >>> arc = sigmf.SigMFArchiveReader(archive_buffer=sigmf_bytes)
-    >>> arc[:10]
-    array([-20.+11.j, -21. -6.j, -17.-20.j, -13.-52.j,   0.-75.j,  22.-58.j,
-            48.-44.j,  49.-60.j,  31.-56.j,  23.-47.j], dtype=complex64)
-
 ------------------------------
 Compressed SigMF Archives
 ------------------------------

docs/source/quickstart.rst

@@ -91,19 +91,19 @@ For full control over global fields, captures, and annotations:
     meta = SigMFFile(
         data_file="example.sigmf-data",  # extension is optional
         global_info={
-            SigMFFile.DATATYPE_KEY: get_data_type_str(data),  # in this case, "cf32_le"
-            SigMFFile.SAMPLE_RATE_KEY: 48000,
-            SigMFFile.AUTHOR_KEY: "jane.doe@domain.org",
-            SigMFFile.DESCRIPTION_KEY: "All zero complex float32 example file.",
+            sigmf.DATATYPE_KEY: get_data_type_str(data),  # in this case, "cf32_le"
+            sigmf.SAMPLE_RATE_KEY: 48000,
+            sigmf.AUTHOR_KEY: "jane.doe@domain.org",
+            sigmf.DESCRIPTION_KEY: "All zero complex float32 example file.",
         },
     )
 
     # create a capture key at time index 0
     meta.add_capture(
         0,
         metadata={
-            SigMFFile.FREQUENCY_KEY: 915000000,
-            SigMFFile.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
+            sigmf.FREQUENCY_KEY: 915000000,
+            sigmf.DATETIME_KEY: get_sigmf_iso8601_datetime_now(),
         },
     )
 
@@ -112,9 +112,9 @@ For full control over global fields, captures, and annotations:
         100,
         200,
         metadata={
-            SigMFFile.FLO_KEY: 914995000.0,
-            SigMFFile.FHI_KEY: 915005000.0,
-            SigMFFile.COMMENT_KEY: "example annotation",
+            sigmf.FREQ_LOWER_EDGE_KEY: 914995000.0,
+            sigmf.FREQ_UPPER_EDGE_KEY: 915005000.0,
+            sigmf.COMMENT_KEY: "example annotation",
         },
     )
 

sigmf/archive.py

@@ -75,36 +75,6 @@ def _get_archive_basename(path):
         return name[: -len(SIGMF_ARCHIVE_EXT)]
     return path.stem
 
-SIGMF_COMPRESSED_EXTS = {
-    # compression type -> unique compound extension
-    "gz": ".sigmf.gz",
-    "xz": ".sigmf.xz",
-    "zip": ".sigmf.zip",
-}
-
-# all recognized archive extensions (uncompressed + compressed)
-SIGMF_ARCHIVE_EXTS = {SIGMF_ARCHIVE_EXT} | set(SIGMF_COMPRESSED_EXTS.values())
-
-
-def _detect_compression(path):
-    """Detect compression type from a file path's extension(s).
-
-    Parameters
-    ----------
-    path : Path
-        Path to check.
-
-    Returns
-    -------
-    str or None
-        Compression type ("gz", "xz", "zip") or None for uncompressed.
-    """
-    name = str(path).lower()
-    for comp_type, ext in SIGMF_COMPRESSED_EXTS.items():
-        if name.endswith(ext):
-            return comp_type
-    return None
-
 
 def _get_archive_basename(path):
     """Get the archive base name (without any sigmf archive extension).
@@ -207,7 +177,6 @@ def __init__(self, sigmffile, name=None, fileobj=None, compression=None, overwri
         with open(meta_path, "w") as handle:
             self.sigmffile.dump(handle)
         if isinstance(self.sigmffile.data_buffer, io.BytesIO):
-            self.sigmffile.data_file = data_path
             with open(data_path, "wb") as handle:
                 handle.write(self.sigmffile.data_buffer.getbuffer())
         else:

sigmf/archivereader.py

@@ -116,6 +116,8 @@ def _read_tar_obj(self, tar_obj):
                     with tar_obj.extractfile(memb) as fid:
                         data_buffer = io.BytesIO(fid.read())
 
+        if json_contents is None:
+            raise SigMFFileError("No .sigmf-meta file found in archive!")
         if data_buffer is None:
             raise SigMFFileError("No .sigmf-data file found in archive!")
         return json_contents, data_buffer, data_size_bytes
@@ -151,6 +153,8 @@ def _read_zip_obj(self, zf):
                 data_size_bytes = len(raw)
                 data_buffer = io.BytesIO(raw)
 
+        if json_contents is None:
+            raise SigMFFileError("No .sigmf-meta file found in archive!")
         if data_buffer is None:
             raise SigMFFileError("No .sigmf-data file found in archive!")
         return json_contents, data_buffer, data_size_bytes
@@ -188,6 +192,8 @@ def _init_from_tar_memmap(self, path, skip_checksum, map_readonly, autoscale):
 
         tar_obj.close()
 
+        if json_contents is None:
+            raise SigMFFileError("No .sigmf-meta file found in archive!")
         if data_offset is None:
             raise SigMFFileError("No .sigmf-data file found in archive!")
 

sigmf/convert/blue.py

@@ -25,8 +25,8 @@
 import numpy as np
 from packaging.version import InvalidVersion, Version
 
-from ..error import SigMFConversionError
 from .. import keys
+from ..error import SigMFConversionError
 from ..sigmffile import SigMFFile, fromfile, get_sigmf_filenames
 from ..utils import SIGMF_DATETIME_ISO8601_FMT
 

sigmf/convert/signalhound.py

@@ -18,8 +18,7 @@
 import defusedxml.ElementTree as ET
 import numpy as np
 
-from .. import SigMFFile, fromfile
-from .. import keys
+from .. import SigMFFile, fromfile, keys
 from ..error import SigMFConversionError
 from ..sigmffile import get_sigmf_filenames
 from ..utils import SIGMF_DATETIME_ISO8601_FMT

sigmf/convert/wav.py

@@ -17,9 +17,8 @@
 import numpy as np
 
 from .. import SigMFFile
-from .. import keys
 from .. import __version__ as toolversion
-from .. import fromfile
+from .. import fromfile, keys
 from ..error import SigMFFileExistsError
 from ..sigmffile import get_sigmf_filenames
 from ..utils import SIGMF_DATETIME_ISO8601_FMT, get_data_type_str

sigmf/keys.py

@@ -138,6 +138,14 @@
 # all recognized archive extensions (uncompressed + compressed)
 SIGMF_ARCHIVE_EXTS = {SIGMF_ARCHIVE_EXT} | set(SIGMF_COMPRESSED_EXTS.values())
 
+# all SigMF file suffixes
+SIGMF_SUFFIXES = [
+    SIGMF_DATASET_EXT,
+    SIGMF_METADATA_EXT,
+    SIGMF_ARCHIVE_EXT,
+    SIGMF_COLLECTION_EXT,
+]
+
 # ---------------------------------------------------------------------------
 # deprecated alias map — used by _SigMFDeprecatingMeta in sigmffile.py
 # maps old_name -> (new_name, value)
@@ -210,4 +218,5 @@
     "SIGMF_COLLECTION_EXT",
     "SIGMF_COMPRESSED_EXTS",
     "SIGMF_ARCHIVE_EXTS",
+    "SIGMF_SUFFIXES",
 ]

sigmf/siggen.py

@@ -561,7 +561,7 @@ def create_full_signal_annotation(label: str) -> dict:
             annotations.append(phase_annotation)
 
         # sort annotations by sample_start to satisfy sigmf ordering requirement
-        annotations.sort(key=lambda a: a[SigMFFile.START_INDEX_KEY])
+        annotations.sort(key=lambda a: a[keys.SAMPLE_START_KEY])
 
         return annotations
 

sigmf/sigmffile.py

@@ -39,9 +39,9 @@
 
 
 class _DeprecatingKey:
-    '''Descriptor that emits DeprecationWarning when a field key constant is
+    """Descriptor that emits DeprecationWarning when a field key constant is
     accessed from the class or an instance, directing users to the sigmf module level.
-    Each attribute name only warns once per interpreter session.'''
+    Each attribute name only warns once per interpreter session."""
 
     _warned: set = set()
 
@@ -1368,15 +1368,15 @@ def fromarray(data, sample_rate, frequency=None, global_info=None):
 
     # build metadata
     info = {
-        SigMFFile.DATATYPE_KEY: get_data_type_str(data),
-        SigMFFile.SAMPLE_RATE_KEY: sample_rate,
+        keys.DATATYPE_KEY: get_data_type_str(data),
+        keys.SAMPLE_RATE_KEY: sample_rate,
     }
     if global_info is not None:
         info.update(global_info)
 
     capture_meta = None
     if frequency is not None:
-        capture_meta = {SigMFFile.FREQUENCY_KEY: frequency}
+        capture_meta = {keys.FREQUENCY_KEY: frequency}
 
     # create sigmffile object with in-memory buffer
     meta = SigMFFile(global_info=info)
@@ -1537,13 +1537,7 @@ def get_sigmf_filenames(filename):
     # If the path has a sigmf suffix, remove it. Otherwise do not remove the
     # suffix, because the filename might contain '.' characters which are part
     # of the filename rather than an extension.
-    sigmf_suffixes = [
-        SIGMF_DATASET_EXT,
-        SIGMF_METADATA_EXT,
-        SIGMF_ARCHIVE_EXT,
-        SIGMF_COLLECTION_EXT,
-    ]
-    if stem_path.suffix in sigmf_suffixes:
+    if stem_path.suffix in keys.SIGMF_SUFFIXES:
         with_suffix_path = stem_path
         stem_path = stem_path.with_suffix("")
     else: