fromfile & fromarchive (#114)

* import fromfile & fromarchive into top level to simplify usage
* increment patch

Author: Teque5

docs/source/advanced.rst

@@ -99,7 +99,7 @@ Now lets add another SigMF Recording and associate them with a SigMF Collection:
 
 .. code-block:: python
 
-    from sigmf import SigMFCollection
+    from sigmf import SigMFFile, SigMFCollection
 
     data_ci16 = np.zeros(1024, dtype=np.complex64)
 
@@ -134,8 +134,8 @@ The SigMF Collection and its associated Recordings can now be loaded like this:
 
 .. code-block:: python
 
-    from sigmf import sigmffile
-    collection = sigmffile.fromfile('example_zeros')
+    import sigmf
+    collection = sigmf.fromfile('example_zeros')
     ci16_sigmffile = collection.get_SigMFFile(stream_name='example_ci16')
     cf32_sigmffile = collection.get_SigMFFile(stream_name='example_cf32')
 
@@ -194,4 +194,4 @@ read it, this can be done "in mid air" or "without touching the ground (disk)".
     >>> 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)
+            48.-44.j,  49.-60.j,  31.-56.j,  23.-47.j], dtype=complex64)

docs/source/quickstart.rst

@@ -23,7 +23,7 @@ Read a SigMF Recording
 .. code-block:: python
 
     import sigmf
-    handle = sigmf.sigmffile.fromfile("example.sigmf")
+    handle = sigmf.fromfile("example.sigmf")
     handle.read_samples() # returns all timeseries data
     handle.get_global_info() # returns 'global' dictionary
     handle.get_captures() # returns list of 'captures' dictionaries
@@ -79,4 +79,4 @@ Save a Numpy array as a SigMF Recording
     })
 
     # check for mistakes & write to disk
-    meta.tofile('example_cf32.sigmf-meta') # extension is optional
+    meta.tofile('example_cf32.sigmf-meta') # extension is optional

sigmf/__init__.py

@@ -5,11 +5,11 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 # version of this python module
-__version__ = "1.2.11"
+__version__ = "1.2.12"
 # matching version of the SigMF specification
 __specification__ = "1.2.5"
 
 from . import archive, archivereader, error, schema, sigmffile, utils, validate
 from .archive import SigMFArchive
 from .archivereader import SigMFArchiveReader
-from .sigmffile import SigMFCollection, SigMFFile
+from .sigmffile import SigMFCollection, SigMFFile, fromarchive, fromfile

tests/test_archivereader.py

@@ -86,7 +86,7 @@ def test_archiveread_data_file_unchanged(test_sigmffile):
     with NamedTemporaryFile(suffix=".sigmf") as temp_file:
         input_samples = test_sigmffile.read_samples()
         test_sigmffile.archive(temp_file.name)
-        arc = sigmf.sigmffile.fromfile(temp_file.name)
+        arc = sigmf.fromfile(temp_file.name)
         output_samples = arc.read_samples()
 
         assert np.array_equal(input_samples, output_samples)

tests/test_sigmffile.py

@@ -15,8 +15,8 @@
 
 import numpy as np
 
-from sigmf import error, sigmffile, utils
-from sigmf.sigmffile import SigMFFile
+import sigmf
+from sigmf import SigMFFile, error, utils
 
 from .testdata import *
 
@@ -38,9 +38,9 @@ def tearDown(self):
     def test_pathlib_handle(self):
         """ensure file can be a string or a pathlib object"""
         self.assertTrue(self.temp_path_data.exists())
-        obj_str = sigmffile.fromfile(str(self.temp_path_data))
+        obj_str = sigmf.fromfile(str(self.temp_path_data))
         obj_str.validate()
-        obj_pth = sigmffile.fromfile(self.temp_path_data)
+        obj_pth = sigmf.fromfile(self.temp_path_data)
         obj_pth.validate()
 
     def test_filenames_with_dots(self):
@@ -54,7 +54,7 @@ def test_filenames_with_dots(self):
             self.sigmf_object.tofile(temp_path_meta)
             files = [str(temp_path_data), temp_path_data, str(temp_path_meta), temp_path_meta]
             for filename in files:
-                obj = sigmffile.fromfile(filename)
+                obj = sigmf.fromfile(filename)
                 obj.validate()
 
     def test_iterator_basic(self):
@@ -245,7 +245,7 @@ def prepare(self, data: list, meta: dict, dtype: type) -> SigMFFile:
         np.array(data, dtype=dtype).tofile(self.temp_path_data)
         with open(self.temp_path_meta, "w") as handle:
             json.dump(meta, handle)
-        meta = sigmffile.fromfile(self.temp_path_meta, skip_checksum=True)
+        meta = sigmf.fromfile(self.temp_path_meta, skip_checksum=True)
         return meta
 
     def test_000(self) -> None:
@@ -367,7 +367,7 @@ def test_add_annotation():
 def test_fromarchive(test_sigmffile):
     with tempfile.NamedTemporaryFile(suffix=".sigmf") as temp_file:
         archive_path = test_sigmffile.archive(name=temp_file.name)
-        result = sigmffile.fromarchive(archive_path=archive_path)
+        result = sigmf.fromarchive(archive_path=archive_path)
         assert result._metadata == test_sigmffile._metadata == TEST_METADATA