improve docstrings, remove duplicative test, add test for fromarchive…

… with collection

sigmf/archivereader.py

@@ -25,6 +25,11 @@ class can be used to iterate through multiple SigMFFiles in the archive.
 
       path    -- path to archive file to access. If file does not exist,
                  or if `path` doesn't end in .sigmf, SigMFFileError is raised.
+
+    self.sigmffiles will contain the SigMFFile(s) (metadata/data) found in the
+    archive.
+
+    self.collection will contain the SigMFCollection if found in the archive.
     """
     def __init__(self, path=None, skip_checksum=False, map_readonly=True, archive_buffer=None):
         self.path = path

sigmf/sigmffile.py

@@ -1037,6 +1037,11 @@ def fromarchive(archive_path, dir=None):
 
     The `dir` parameter is no longer used as this function has been changed to
     access SigMF archives without extracting them.
+
+    If the archive contains a single recording, a single SigMFFile object will
+    be returned. If the archive contains multiple recordings a list of
+    SigMFFile objects will be returned. If the archive contains a collection,
+    a tuple (SigMFFile(s), SigMFCollection) will be returned.
     """
     from .archivereader import SigMFArchiveReader
     reader = SigMFArchiveReader(archive_path)
@@ -1068,8 +1073,8 @@ def fromfile(filename, skip_checksum=False):
 
     Returns
     -------
-    object
-        SigMFFile object with dataset & metadata or a SigMFCollection depending on the type of file
+    SigMFFile object(s) with dataset & metadata and/or a SigMFCollection
+    depending on the type of file or contents of archive.
     '''
     fns = get_sigmf_filenames(filename)
     meta_fn = fns['meta_fn']

tests/test_archive.py

@@ -118,17 +118,6 @@ def test_tarfile_names_and_extensions(test_sigmffile):
         assert file2_ext in file_extensions
 
 
-def test_sf_fromarchive_multirec(test_sigmffile, test_alternate_sigmffile):
-    """`SigMFFile.fromarchive` should return list of SigMFFiles."""
-    with tempfile.NamedTemporaryFile(delete=True) as tf:
-        # Create a multi-recording archive
-        input_sigmffiles = [test_sigmffile, test_alternate_sigmffile]
-        arch = SigMFArchive(input_sigmffiles, path=tf.name)
-        output_sigmf_files = sigmffile.fromarchive(archive_path=arch.path)
-        assert len(output_sigmf_files) == 2
-        assert input_sigmffiles == output_sigmf_files
-
-
 def test_multirec_archive_into_fileobj(test_sigmffile,
                                        test_alternate_sigmffile):
     with tempfile.NamedTemporaryFile() as t:

tests/test_sigmffile.py

@@ -148,6 +148,21 @@ def test_fromarchive_multi_recording(test_sigmffile,
         assert list_of_sigmffiles[2] == test_alternate_sigmffile_2
 
 
+def test_fromarchive_multirec_with_collection(test_sigmffile,
+                                              test_alternate_sigmffile):
+    with tempfile.NamedTemporaryFile(delete=True) as tf:
+        # Create a multi-recording archive with collection
+        in_sigmffiles = [test_sigmffile, test_alternate_sigmffile]
+        in_collection = SigMFCollection(in_sigmffiles)
+        arch = SigMFArchive(in_sigmffiles,
+                            collection=in_collection,
+                            path=tf.name)
+        out_sigmffiles, out_collection = fromarchive(archive_path=arch.path)
+        assert len(out_sigmffiles) == 2
+        assert in_sigmffiles == out_sigmffiles
+        assert in_collection == out_collection
+
+
 def test_add_multiple_captures_and_annotations():
     sigf = SigMFFile(name="test")
     for idx in range(3):
@@ -397,4 +412,4 @@ def test_collection_set_sigmffiles(test_sigmffile,
             assert input_sigmf in output_sigmf_files_by_index
     finally:
         if os.path.exists(third_sigmf_meta_filename):
-            os.remove(third_sigmf_meta_filename)
+            os.remove(third_sigmf_meta_filename)