get & set global fields via properties

* created new get/set dynamic interface for global fields
* fixed bug where (data_doi, meta_doi) was incorrectly (data-doi, meta_doi)
* increment API version
* Thanks to @gregparkes for base implementation
* add documentation
* add tests

Author: Teque5

.gitignore

@@ -22,3 +22,6 @@ htmlcov/*
 # docs related
 docs/_build/
 docs/source/_autosummary/
+
+# dev related
+.vscode/

docs/source/quickstart.rst

@@ -24,11 +24,14 @@ Read a SigMF Recording
 
     import sigmf
     handle = sigmf.fromfile("example.sigmf")
-    handle.read_samples() # returns all timeseries data
+    # reading data
+    handle.read_samples() # read all timeseries data
+    handle[10:50] # read memory slice of samples 10 through 50
+    # accessing metadata
+    handle.sample_rate # get sample rate attribute
     handle.get_global_info() # returns 'global' dictionary
     handle.get_captures() # returns list of 'captures' dictionaries
     handle.get_annotations() # returns list of all annotations
-    handle[10:50] # return memory slice of samples 10 through 50
 
 -----------------------------------
 Verify SigMF Integrity & Compliance
@@ -80,3 +83,47 @@ Save a Numpy array as a SigMF Recording
 
     # check for mistakes & write to disk
     meta.tofile('example_cf32.sigmf-meta') # extension is optional
+
+----------------------------------
+Attribute Access for Global Fields
+----------------------------------
+
+SigMF-Python provides convenient attribute-style access for core global metadata fields,
+allowing you to read and write metadata using simple dot notation alongside the traditional
+method-based approach.
+
+.. code-block:: python
+
+    import numpy as np
+    from sigmf import SigMFFile
+
+    # create a new recording
+    meta = SigMFFile()
+
+    # set global metadata using attributes
+    meta.sample_rate = 48000
+    meta.author = 'jane.doe@domain.org'
+    meta.datatype = 'cf32_le'
+    meta.description = 'Example recording with attribute access'
+    meta.license = 'MIT'
+    meta.recorder = 'hackrf_one'
+
+    # read global metadata using attributes
+    print(f"Sample rate: {meta.sample_rate}")
+    print(f"Author: {meta.author}")
+    print(f"License: {meta.license}")
+
+    # method-based approach
+    meta.set_global_field(SigMFFile.HW_KEY, 'SDR Hardware v1.2')
+    hw_info = meta.get_global_field(SigMFFile.HW_KEY)
+    print(f"Hardware: {hw_info}")
+
+    # attribute and method access are equivalent
+    meta.set_global_field(SigMFFile.RECORDER_KEY, 'usrp_b210')
+    print(f"Recorder via attribute: {meta.recorder}")  # prints: usrp_b210
+
+.. note::
+
+   Only core **global** fields support attribute access. Capture and annotation
+   fields must still be accessed using the traditional ``add_capture()`` and
+   ``add_annotation()`` methods.

sigmf/__init__.py

@@ -5,7 +5,7 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 # version of this python module
-__version__ = "1.2.13"
+__version__ = "1.3.0"
 # matching version of the SigMF specification
 __specification__ = "1.2.5"
 

sigmf/sigmffile.py

@@ -126,8 +126,8 @@ class SigMFFile(SigMFMetafile):
     COMMENT_KEY = "core:comment"
     DESCRIPTION_KEY = "core:description"
     AUTHOR_KEY = "core:author"
-    META_DOI_KEY = "core:meta-doi"
-    DATA_DOI_KEY = "core:data-doi"
+    META_DOI_KEY = "core:meta_doi"
+    DATA_DOI_KEY = "core:data_doi"
     GENERATOR_KEY = "core:generator"
     LABEL_KEY = "core:label"
     RECORDER_KEY = "core:recorder"
@@ -147,14 +147,38 @@ class SigMFFile(SigMFMetafile):
     CAPTURE_KEY = "captures"
     ANNOTATION_KEY = "annotations"
     VALID_GLOBAL_KEYS = [
-        AUTHOR_KEY, COLLECTION_KEY, DATASET_KEY, DATATYPE_KEY, DATA_DOI_KEY, DESCRIPTION_KEY, EXTENSIONS_KEY,
-        GEOLOCATION_KEY, HASH_KEY, HW_KEY, LICENSE_KEY, META_DOI_KEY, METADATA_ONLY_KEY, NUM_CHANNELS_KEY, RECORDER_KEY,
-        SAMPLE_RATE_KEY, START_OFFSET_KEY, TRAILING_BYTES_KEY, VERSION_KEY
+        AUTHOR_KEY,
+        COLLECTION_KEY,
+        DATASET_KEY,
+        DATATYPE_KEY,
+        DATA_DOI_KEY,
+        DESCRIPTION_KEY,
+        EXTENSIONS_KEY,
+        GEOLOCATION_KEY,
+        HASH_KEY,
+        HW_KEY,
+        LICENSE_KEY,
+        META_DOI_KEY,
+        METADATA_ONLY_KEY,
+        NUM_CHANNELS_KEY,
+        RECORDER_KEY,
+        SAMPLE_RATE_KEY,
+        START_OFFSET_KEY,
+        TRAILING_BYTES_KEY,
+        VERSION_KEY,
     ]
     VALID_CAPTURE_KEYS = [DATETIME_KEY, FREQUENCY_KEY, HEADER_BYTES_KEY, GLOBAL_INDEX_KEY, START_INDEX_KEY]
     VALID_ANNOTATION_KEYS = [
-        COMMENT_KEY, FHI_KEY, FLO_KEY, GENERATOR_KEY, LABEL_KEY, LAT_KEY, LENGTH_INDEX_KEY, LON_KEY, START_INDEX_KEY,
-        UUID_KEY
+        COMMENT_KEY,
+        FHI_KEY,
+        FLO_KEY,
+        GENERATOR_KEY,
+        LABEL_KEY,
+        LAT_KEY,
+        LENGTH_INDEX_KEY,
+        LON_KEY,
+        START_INDEX_KEY,
+        UUID_KEY,
     ]
     VALID_KEYS = {GLOBAL_KEY: VALID_GLOBAL_KEYS, CAPTURE_KEY: VALID_CAPTURE_KEYS, ANNOTATION_KEY: VALID_ANNOTATION_KEYS}
 
@@ -201,6 +225,75 @@ def __eq__(self, other):
             return self._metadata == other._metadata
         return False
 
+    def __getattr__(self, name):
+        """
+        Enable dynamic attribute access for core global metadata fields.
+
+        Allows convenient access to core metadata fields using attribute notation:
+        - `sigmf_file.sample_rate` returns `sigmf_file._metadata["global"]["core:sample_rate"]
+        - `sigmf_file.author` returns `sigmf_file._metadata["global"]["core:author"]
+
+        Parameters
+        ----------
+        name : str
+            Attribute name corresponding to a core field (without "core:" prefix).
+
+        Returns
+        -------
+        value
+            The value of the core field from global metadata, or None if not set.
+
+        Raises
+        ------
+        SigMFAccessError
+            If the attribute name doesn't correspond to a valid core global field.
+        """
+        # iterate through valid global keys to find matching core field
+        for key in self.VALID_GLOBAL_KEYS:
+            if key.startswith("core:") and key[5:] == name:
+                field_value = self.get_global_field(key)
+                if field_value is None:
+                    raise SigMFAccessError(f"Core field '{key}' does not exist in global metadata")
+                return field_value
+
+        # if we get here, the attribute doesn't correspond to a core field
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+
+    def __setattr__(self, name, value):
+        """
+        Enable dynamic attribute setting for core global metadata fields.
+
+        Allows convenient setting of core metadata fields using attribute notation:
+        - `sigmf_file.sample_rate = 1000000` sets `sigmf_file._metadata["global"]["core:sample_rate"]
+        - `sigmf_file.author = "jane.doe@domain.org"` sets `sigmf_file._metadata["global"]["core:author"]
+
+        Parameters
+        ----------
+        name : str
+            Attribute name. If it corresponds to a core field (without "core:" prefix),
+            the value will be set in global metadata. Otherwise, normal attribute setting occurs.
+        value
+            The value to set for the field.
+        """
+        # handle regular instance attributes, existing properties, or during initialization
+        if (
+            name.startswith("_")
+            or hasattr(type(self), name)
+            or not hasattr(self, "_metadata")
+            or self._metadata is None
+        ):
+            super().__setattr__(name, value)
+            return
+
+        # check if this corresponds to a core global field
+        for key in self.VALID_GLOBAL_KEYS:
+            if key.startswith("core:") and key[5:] == name:
+                self.set_global_field(key, value)
+                return
+
+        # fall back to normal attribute setting for non-core attributes
+        super().__setattr__(name, value)
+
     def __next__(self):
         """get next batch of samples"""
         if self.iter_position < len(self):
@@ -782,7 +875,9 @@ class SigMFCollection(SigMFMetafile):
     ]
     VALID_KEYS = {COLLECTION_KEY: VALID_COLLECTION_KEYS}
 
-    def __init__(self, metafiles: list = None, metadata: dict = None, base_path=None, skip_checksums: bool = False) -> None:
+    def __init__(
+        self, metafiles: list = None, metadata: dict = None, base_path=None, skip_checksums: bool = False
+    ) -> None:
         """
         Create a SigMF Collection object.
 
@@ -1060,6 +1155,7 @@ def fromarchive(archive_path, dir=None, skip_checksum=False):
     access SigMF archives without extracting them.
     """
     from .archivereader import SigMFArchiveReader
+
     return SigMFArchiveReader(archive_path, skip_checksum=skip_checksum).sigmffile
 
 
@@ -1133,8 +1229,10 @@ def get_sigmf_filenames(filename):
     # 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,
+        SIGMF_DATASET_EXT,
+        SIGMF_METADATA_EXT,
+        SIGMF_ARCHIVE_EXT,
+        SIGMF_COLLECTION_EXT,
     ]
     if stem_path.suffix in sigmf_suffixes:
         with_suffix_path = stem_path

tests/test_attributes.py

@@ -0,0 +1,94 @@
+"""Tests for dynamic attribute access functionality."""
+
+import copy
+import unittest
+
+import numpy as np
+
+from sigmf import SigMFFile
+from sigmf.error import SigMFAccessError
+
+from .testdata import TEST_METADATA
+
+SOME_LICENSE = "CC0-1.0"
+SOME_RECORDER = "HackRF Pro"
+SOME_DOI = "10.1000/182"
+
+
+class TestDynamicAttributeAccess(unittest.TestCase):
+    """Test dynamic attribute access for core global metadata fields."""
+
+    def setUp(self):
+        """create test sigmf file with some initial metadata"""
+        self.meta = SigMFFile(copy.deepcopy(TEST_METADATA))
+
+    def test_getter_existing_fields(self):
+        """test attribute getters for existing core fields"""
+        # test common core fields
+        # self.assertEqual(self.meta.sample_rate, self.meta.get_global_field(SigMFFile.SAMPLE_RATE_KEY))
+        # self.assertEqual(self.meta.author, self.meta.get_global_field(SigMFFile.AUTHOR_KEY))
+        self.assertEqual(self.meta.datatype, self.meta.get_global_field(SigMFFile.DATATYPE_KEY))
+        self.assertEqual(self.meta.sha512, self.meta.get_global_field(SigMFFile.HASH_KEY))
+        # self.assertEqual(self.meta.description, self.meta.get_global_field(SigMFFile.DESCRIPTION_KEY))
+
+    def test_getter_missing_core_fields(self):
+        """test that getter raises SigMFAccessError for missing core fields"""
+        with self.assertRaises(SigMFAccessError) as context:
+            _ = self.meta.license
+        self.assertIn(SigMFFile.LICENSE_KEY, str(context.exception))
+
+    def test_getter_nonexistent_attribute(self):
+        """test that getter raises AttributeError for non-core attributes"""
+        with self.assertRaises(AttributeError) as context:
+            _ = self.meta.nonexistent_field
+        self.assertIn("nonexistent_field", str(context.exception))
+
+    def test_setter_new_fields(self):
+        """test that attribute setters work for new core fields"""
+        # set various core global fields using attribute notation
+        self.meta.license = SOME_LICENSE
+        self.meta.meta_doi = SOME_DOI
+        self.meta.recorder = SOME_RECORDER
+
+        # verify they were set correctly
+        self.assertEqual(self.meta.license, SOME_LICENSE)
+        self.assertEqual(self.meta.meta_doi, SOME_DOI)
+        self.assertEqual(self.meta.recorder, SOME_RECORDER)
+
+    def test_setter_overwrite_fields(self):
+        """test that attribute setters can overwrite existing fields"""
+        self.meta.sha512 = "effec7"
+        self.assertEqual(self.meta.sha512, "effec7")
+
+    def test_setter_noncore_attributes(self):
+        """test that setter works for non-core object attributes"""
+        # set a regular attribute
+        self.meta.custom_attribute = "test value"
+
+        # verify it was set as a regular attribute
+        self.assertEqual(self.meta.custom_attribute, "test value")
+
+        # verify it doesn't appear in metadata
+        self.assertNotIn("custom_attribute", self.meta.get_global_info())
+
+    def test_method_vs_attribute_equivalence(self):
+        """test that method-based and attribute-based access are equivalent"""
+        # set via method, access via attribute
+        self.meta.set_global_field(SigMFFile.LICENSE_KEY, SOME_LICENSE)
+        self.assertEqual(self.meta.license, SOME_LICENSE)
+
+        # set via attribute, access via method
+        self.meta.recorder = SOME_RECORDER
+        self.assertEqual(self.meta.get_global_field(SigMFFile.RECORDER_KEY), SOME_RECORDER)
+
+    def test_private_attributes_unaffected(self):
+        """test that private attributes work normally"""
+        # private attributes should not trigger dynamic behavior
+        self.meta._test_private = "private_value"
+        self.assertEqual(self.meta._test_private, "private_value")
+
+    def test_existing_properties_unaffected(self):
+        """test that existing class properties work normally"""
+        # test that existing properties like data_file still work
+        self.meta.data_file = None  # this should work normally
+        self.assertIsNone(self.meta.data_file)