[Discuss-gnuradio] [UHD] Python API

[Martin Braun]

Hi all,

after a while of testing and gathering feedback, we have merged the UHD
Python API into master branch. In general, we are happy with its state,
but that doesn't mean it's perfect and complete.

First off, there's at least one known issue with the Python API: It does
not build on Windows. We will work on fixing this issue, but from what
we know it might require specific versions of Python and Boost.Python to
work.

The other major item is that it's not all that well documented. However,
the Python API matches the C++ API closely (albeit with some additions,
some more Pythonic structures, and PEP8-compliant object names). For
now, I recommend reading the examples in host/examples/python/*.py as a
reference. We will also start using Python more and more for testing
utilities, and merge those into the UHD repository as a reference.

We received a lot of valuable feedback from the community, which we very
much appreciated, and have fed back into the development of the API. One
of the concerns was *streaming performance*, and we're happy to say that
we can get pretty decent performance, almost matching the C++
performance (tested with our own benchmark_rate.py utility), even in
full-duplex and multi-channel situations (thanks to various users
pointing us the right way with respect to releasing the GIL!). Getting
high performance in Python is still hard, though. If you wanted to write
a continuous streaming application with high performance, you'd need to
maintain a buffer pool and rotate buffers; in benchmark_rate.py we get
away with a single buffer that we re-use. However, this is obviously
something that Python developers will be aware of, and if you need
highest performance, the Python API is probably not what you want anyway.

To enable the Python API, you need Boost.Python installed, and compile
UHD with the -DENABLE_PYTHON_API=ON switch.
Both Python2 and Python3 are supported, although we've found that CMake
isn't always cooperative in finding the correct libraries when using
Python3. Because the two versions of Python are so fundamentally
different, you need to specify -DENABLE_PYTHON3 if you want to use Py3k.
Boost.Python is also not currently packaged for a range of
distributions, so we assume that if you want Boost.Python + Python3 you
are familiar with more advanced settings.

We think the Python API will enable a range of new applications for
simple tasks, since it's very easy to grab a range of samples and then
do some basic DSP using SciPy and NumPy, plot them using Matplotlib, or
pass it to one of million of other Python libraries out there. Consider
the length of this file:
https://github.com/EttusResearch/uhddev/blob/master/host/examples/python/rx_to_file.py
...we think it's pretty short for what it does.

For continuous streaming and Python, we still recommend using GNU Radio.
gr-uhd also has a (different) Python API that is tied into GNU Radio,
and it is possible to write blocks in GNU Radio, but you won't have to
futz with buffers as mentioned above, and you still have access to all
the blocks written in C++.

Cheers all!

Martin