rewrite docs & improve sigmf_convert entry point

Author: Teque5

docs/source/converters.rst

@@ -1,23 +1,23 @@
-=================
-Format Converters
-=================
+==========
+Converters
+==========
 
-The SigMF Python library includes converters to import data from various file formats into SigMF format.
+The SigMF Python library includes converters to import data from various RF recording formats into SigMF.
 Converters can create standard SigMF file pairs or Non-Conforming Datasets (NCDs) that reference the original files.
 
 Overview
 --------
 
-Converters are available for:
+Conversion is available for:
 
-* **BLUE files** - MIDAS Blue and Platinum BLUE RF recordings (``.cdif``)
+* **BLUE files** - MIDAS Blue and Platinum BLUE RF recordings (usually ``.cdif``)
 * **WAV files** - Audio recordings (``.wav``)
 
-All converters return a :class:`~sigmf.SigMFFile` object. Auto-detection is available through :func:`~sigmf.sigmffile.fromfile`.
+All converters return a :class:`~sigmf.SigMFFile` object with converted metadata.
 
 
-Auto-Detection
-~~~~~~~~~~~~~~
+Fromfile Auto-Detection
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The :func:`~sigmf.sigmffile.fromfile` function automatically detects file formats and creates Non-Conforming Datasets:
 
@@ -30,35 +30,66 @@ The :func:`~sigmf.sigmffile.fromfile` function automatically detects file format
     meta = sigmf.fromfile("recording.wav")   # WAV file
     meta = sigmf.fromfile("recording.sigmf")  # SigMF archive
 
-    samples = meta.read_samples()
+    all_samples = meta.read_samples()
+    sample_rate = meta.sample_rate
+
+
+Python API
+~~~~~~~~~~~
+
+For programmatic access, use the individual converter functions directly:
+
+.. code-block:: python
+
+    from sigmf.convert.wav import wav_to_sigmf
+    from sigmf.convert.blue import blue_to_sigmf
+
+    # convert WAV to SigMF archive
+    _ = wav_to_sigmf(wav_path="recording.wav", out_path="recording", create_archive=True)
+
+    # convert BLUE to SigMF pair and return metadata for new files
+    meta = blue_to_sigmf(blue_path="recording.cdif", out_path="recording")
 
 
 Command Line Usage
 ~~~~~~~~~~~~~~~~~~
 
-Converters can be used from the command line:
+Converters are accessed through a unified command-line interface that automatically detects file formats:
 
 .. code-block:: bash
 
-    sigmf_convert_blue recording.cdif
-    sigmf_convert_wav recording.wav
-
-or by using module execution:
+    # unified converter
+    sigmf_convert input_file output_file
 
-.. code-block:: bash
+    # examples
+    sigmf_convert recording.cdif recording.sigmf
+    sigmf_convert recording.wav recording.sigmf
 
-    python -m sigmf.convert.blue recording.cdif
-    python -m sigmf.convert.wav recording.wav
+The converter uses magic byte detection to automatically identify BLUE and WAV file formats.
+No need to remember format-specific commands!
 
 
 Output Options
 ~~~~~~~~~~~~~~
 
-Converters support multiple output modes:
+The unified converter supports multiple output modes:
+
+.. code-block:: bash
+
+    # standard conversion (creates out.sigmf-data and out.sigmf-meta files)
+    sigmf_convert in.wav out
 
-* **Standard conversion**: Creates ``.sigmf-data`` and ``.sigmf-meta`` files
-* **Archive mode**: Creates single ``.sigmf`` archive with ``--archive``
-* **Non-Conforming Dataset**: Creates metadata-only file referencing original data with ``--ncd``
+    # archive mode (creates single out.sigmf archive)
+    sigmf_convert in.wav out --archive
+
+    # non-conforming dataset (creates out.sigmf-meta only, references original file)
+    sigmf_convert in.wav out --ncd
+
+    # extra verbose output
+    sigmf_convert in.wav out -vv
+
+**Important**: When using ``--ncd``, the input and output files must be in the same directory.
+This ensures proper relative path references in the metadata.
 
 
 BLUE Converter
@@ -73,19 +104,22 @@ The BLUE converter handles CDIF (.cdif) recordings while placing BLUE header inf
 
 .. autofunction:: sigmf.convert.blue.blue_to_sigmf
 
+Examples
+~~~~~~~~
+
 .. code-block:: python
 
     from sigmf.convert.blue import blue_to_sigmf
 
     # standard conversion
     meta = blue_to_sigmf(blue_path="recording.cdif", out_path="recording")
 
-    # create NCD automatically (metadata-only, references original file)
+    # create NCD automatically (metadata-only, references original file) but don't save any output file
     meta = blue_to_sigmf(blue_path="recording.cdif")
 
     # access standard SigMF data & metadata
     all_samples = meta.read_samples()
-    sample_rate_hz = meta.sample_rate
+    sample_rate = meta.sample_rate
 
     # access BLUE-specific metadata
     blue_type = meta.get_global_field("blue:fixed")["type"]  # e.g., 1000
@@ -99,6 +133,9 @@ Converts WAV audio recordings to SigMF format.
 
 .. autofunction:: sigmf.convert.wav.wav_to_sigmf
 
+Examples
+~~~~~~~~
+
 .. code-block:: python
 
     from sigmf.convert.wav import wav_to_sigmf

pyproject.toml

@@ -33,7 +33,7 @@ dependencies = [
 
     [project.scripts]
     sigmf_validate = "sigmf.validate:main"
-    sigmf_convert = "sigmf.convert:main"
+    sigmf_convert = "sigmf.convert.__main__:main"
     [project.optional-dependencies]
     test = [
         "pylint",

sigmf/convert/__init__.py

@@ -1,75 +0,0 @@
-# Copyright: Multiple Authors
-#
-# This file is part of sigmf-python. https://github.com/sigmf/sigmf-python
-#
-# SPDX-License-Identifier: LGPL-3.0-or-later
-
-"""Unified converter for non-SigMF file formats"""
-
-import argparse
-import logging
-from pathlib import Path
-
-from .. import __version__ as toolversion
-from ..error import SigMFConversionError
-from ..utils import get_magic_bytes
-
-
-def main() -> None:
-    """
-    Unified entry-point for SigMF conversion of non-SigMF files.
-    """
-    parser = argparse.ArgumentParser(description="Convert non-SigMF files to SigMF format")
-    parser.add_argument("input", type=str, help="Input file path")
-    parser.add_argument("output", type=str, help="Output SigMF path (no extension)")
-    parser.add_argument("-v", "--verbose", action="count", default=0)
-    parser.add_argument(
-        "-a", "--archive", action="store_true", help="Save as SigMF archive instead of separate meta/data files."
-    )
-    parser.add_argument(
-        "--ncd", action="store_true", help="Process as Non-Conforming Dataset and write .sigmf-meta only."
-    )
-    parser.add_argument("--version", action="version", version=f"%(prog)s v{toolversion}")
-    args = parser.parse_args()
-
-    level_lut = {
-        0: logging.WARNING,
-        1: logging.INFO,
-        2: logging.DEBUG,
-    }
-    logging.basicConfig(level=level_lut[min(args.verbose, 2)])
-
-    input_path = Path(args.input)
-    output_path = Path(args.output)
-
-    # validate that ncd files are in same directory as input
-    if args.ncd and input_path.parent.resolve() != output_path.parent.resolve():
-        raise SigMFConversionError(
-            f"NCD files must be in the same directory as input file. "
-            f"Input: {input_path.parent.resolve()}, Output: {output_path.parent.resolve()}"
-        )
-
-    # detect file type using magic bytes (same logic as fromfile())
-    magic_bytes = get_magic_bytes(input_path, count=4, offset=0)
-
-    if magic_bytes == b"RIFF":
-        # WAV file
-        from .wav import wav_to_sigmf
-
-        _ = wav_to_sigmf(wav_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
-
-    elif magic_bytes == b"BLUE":
-        # BLUE file
-        from .blue import blue_to_sigmf
-
-        _ = blue_to_sigmf(blue_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
-
-    else:
-        raise SigMFConversionError(
-            f"Unsupported file format. Magic bytes: {magic_bytes}. "
-            f"Supported formats for conversion are WAV and BLUE/Platinum."
-        )
-
-
-if __name__ == "__main__":
-    main()

sigmf/convert/__main__.py

@@ -0,0 +1,81 @@
+# Copyright: Multiple Authors
+#
+# This file is part of sigmf-python. https://github.com/sigmf/sigmf-python
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Unified converter for non-SigMF file formats"""
+
+import argparse
+import logging
+import textwrap
+from pathlib import Path
+
+from .. import __version__ as toolversion
+from ..error import SigMFConversionError
+from ..utils import get_magic_bytes
+from .blue import blue_to_sigmf
+from .wav import wav_to_sigmf
+
+
+def main() -> None:
+    """
+    Unified entry-point for SigMF conversion of non-SigMF recordings.
+
+    This command-line interface converts various non-SigMF file formats into SigMF-compliant datasets.
+    It currently supports WAV and BLUE/Platinum file formats.
+    The converter detects the file type based on magic bytes and invokes the appropriate conversion function.
+
+    By default it will output a SigMF pair (.sigmf-meta and .sigmf-data).
+    """
+    parser = argparse.ArgumentParser(
+        description=textwrap.dedent(main.__doc__),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("input", type=str, help="Input recording path")
+    parser.add_argument("output", type=str, help="Output SigMF path (no extension)")
+    parser.add_argument("-v", "--verbose", action="count", default=0, help="Increase verbosity level")
+    parser.add_argument("-a", "--archive", action="store_true", help="Output .sigmf archive only")
+    parser.add_argument(
+        "--ncd", action="store_true", help="Output .sigmf-meta only and process as a Non-Conforming Dataset (NCD)"
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s v{toolversion}")
+    args = parser.parse_args()
+
+    level_lut = {
+        0: logging.WARNING,
+        1: logging.INFO,
+        2: logging.DEBUG,
+    }
+    logging.basicConfig(level=level_lut[min(args.verbose, 2)])
+
+    input_path = Path(args.input)
+    output_path = Path(args.output)
+
+    # validate that ncd files are in same directory as input
+    if args.ncd and input_path.parent.resolve() != output_path.parent.resolve():
+        raise SigMFConversionError(
+            f"NCD files must be in the same directory as input file. "
+            f"Input: {input_path.parent.resolve()}, Output: {output_path.parent.resolve()}"
+        )
+
+    # detect file type using magic bytes (same logic as fromfile())
+    magic_bytes = get_magic_bytes(input_path, count=4, offset=0)
+
+    if magic_bytes == b"RIFF":
+        # WAV file
+        _ = wav_to_sigmf(wav_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
+
+    elif magic_bytes == b"BLUE":
+        # BLUE file
+        _ = blue_to_sigmf(blue_path=input_path, out_path=output_path, create_archive=args.archive, create_ncd=args.ncd)
+
+    else:
+        raise SigMFConversionError(
+            f"Unsupported file format. Magic bytes: {magic_bytes}. "
+            f"Supported formats for conversion are WAV and BLUE/Platinum."
+        )
+
+
+if __name__ == "__main__":
+    main()

sigmf/convert/blue.py

@@ -24,11 +24,9 @@
 import numpy as np
 from packaging.version import InvalidVersion, Version
 
-from .. import SigMFFile
 from .. import __version__ as toolversion
-from .. import fromfile
 from ..error import SigMFConversionError
-from ..sigmffile import get_sigmf_filenames
+from ..sigmffile import SigMFFile, fromfile, get_sigmf_filenames
 from ..utils import SIGMF_DATETIME_ISO8601_FMT
 
 log = logging.getLogger()