python: Separating exposed Python data structures

- Separating exposed Python data structures into logical sections
- Exposes all of the multi_usrp API
- Adds a layer of Python for documentation and adding helper methods
- Adds improvements and fixes to the MultiUSRP object
- Includes additional exposed data structures (like time_spec_t, etc.)
- Add code to release the Python GIL during long C++ calls

3 files changed, 38 insertions, 55 deletions

diff --git a/host/examples/python/CMakeLists.txt b/host/examples/python/CMakeLists.txt
index 628bf10a2..4b75f57bd 100644
--- a/host/examples/python/CMakeLists.txt
+++ b/host/examples/python/CMakeLists.txt
@@ -1,23 +1,12 @@
 #
-# Copyright 2010-2012,2015 Ettus Research LLC
+# Copyright 2017-2018 Ettus Research, a National Instruments Company
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# SPDX-License-Identifier: GPL-3.0-or-later
 #
 
 SET(python_examples
-    pyuhd_rx_to_file.py
-    pyuhd_tx_waveforms.py
+    rx_to_file.py
+    tx_waveforms.py
 )
 
-UHD_INSTALL(PROGRAMS ${python_examples} DESTINATION ${PKG_LIB_DIR}/examples COMPONENT examples)
+UHD_INSTALL(PROGRAMS ${python_examples} DESTINATION ${PKG_LIB_DIR}/examples/python COMPONENT examples)
diff --git a/host/examples/python/pyuhd_rx_to_file.py b/host/examples/python/rx_to_file.py
index 0b4956b33..7017a08c2 100755
--- a/host/examples/python/pyuhd_rx_to_file.py
+++ b/host/examples/python/rx_to_file.py
@@ -1,27 +1,20 @@
-#! /usr/bin/env python
+#!/usr/bin/env python
 #
-# Copyright 2017 Ettus Research LLC
+# Copyright 2017-2018 Ettus Research, a National Instruments Company
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# SPDX-License-Identifier: GPL-3.0-or-later
 #
+"""
+RX samples to file using Python API
+"""
 
-
+import argparse
 import numpy as np
 import uhd
-import argparse
+
 
 def parse_args():
+    """Parse the command line arguments"""
     parser = argparse.ArgumentParser()
     parser.add_argument("-a", "--args", default="", type=str)
     parser.add_argument("-o", "--output-file", type=str, required=True)
@@ -30,17 +23,24 @@ def parse_args():
     parser.add_argument("-d", "--duration", default=5.0, type=float)
     parser.add_argument("-c", "--channels", default=0, nargs="+", type=int)
     parser.add_argument("-g", "--gain", type=int, default=10)
+    parser.add_argument("-n", "--numpy", default=False, action="store_true",
+                        help="Save output file in NumPy format (default: No)")
     return parser.parse_args()
 
+
 def main():
+    """RX samples and write to file"""
     args = parse_args()
-    usrp = uhd.multi_usrp(args.args)
+    usrp = uhd.usrp.MultiUSRP(args.args)
     num_samps = int(np.ceil(args.duration*args.rate))
     if not isinstance(args.channels, list):
         args.channels = [args.channels]
     samps = usrp.recv_num_samps(num_samps, args.freq, args.rate, args.channels, args.gain)
-    with open(args.output_file, 'wb') as f:
-        np.save(f, samps, allow_pickle=False, fix_imports=False)
+    with open(args.output_file, 'wb') as out_file:
+        if args.numpy:
+            np.save(out_file, samps, allow_pickle=False, fix_imports=False)
+        else:
+            samps.tofile(out_file)
 
 if __name__ == "__main__":
     main()
diff --git a/host/examples/python/pyuhd_tx_waveforms.py b/host/examples/python/tx_waveforms.py
index d7d431f44..6db50fa2b 100755
--- a/host/examples/python/pyuhd_tx_waveforms.py
+++ b/host/examples/python/tx_waveforms.py
@@ -1,35 +1,28 @@
-#! /usr/bin/env python
+#!/usr/bin/env python
 #
-# Copyright 2017 Ettus Research LLC
+# Copyright 2017-2018 Ettus Research, a National Instruments Company
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# SPDX-License-Identifier: GPL-3.0-or-later
 #
+"""
+Generate and TX samples using a set of waveforms, and waveform characteristics
+"""
 
+import argparse
 import numpy as np
 import uhd
-import argparse
-
 
 waveforms = {
     "sine": lambda n, tone_offset, rate: np.exp(n * 2j * np.pi * tone_offset / rate),
     "square": lambda n, tone_offset, rate: np.sign(waveforms["sine"](n, tone_offset, rate)),
     "const": lambda n, tone_offset, rate: 1 + 1j,
-    "ramp": lambda n, tone_offset, rate: 2*(n*(tone_offset/rate) - np.floor(float(0.5 + n*(tone_offset/rate))))
+    "ramp": lambda n, tone_offset, rate:
+            2*(n*(tone_offset/rate) - np.floor(float(0.5 + n*(tone_offset/rate))))
 }
 
 
 def parse_args():
+    """Parse the command line arguments"""
     parser = argparse.ArgumentParser()
     parser.add_argument("-a", "--args", default="", type=str)
     parser.add_argument(
@@ -45,15 +38,16 @@ def parse_args():
 
 
 def main():
+    """TX samples based on input arguments"""
     args = parse_args()
-    usrp = uhd.multi_usrp(args.args)
+    usrp = uhd.usrp.MultiUSRP(args.args)
     if not isinstance(args.channels, list):
         args.channels = [args.channels]
     data = np.array(
-        map(lambda n: args.wave_ampl * waveforms[args.waveform](n, args.wave_freq, args.rate),
+        list(map(lambda n: args.wave_ampl * waveforms[args.waveform](n, args.wave_freq, args.rate),
             np.arange(
                 int(10 * np.floor(args.rate / args.wave_freq)),
-                dtype=np.complex64)),
+                dtype=np.complex64))),
         dtype=np.complex64)  # One period
 
     usrp.send_waveform(data, args.duration, args.freq, args.rate,