Makefile.am: Fix out-of-tree build for Python bindings

[libsigrok.git] / bindings / python / sigrok / core / classes.i

diff --git a/bindings/python/sigrok/core/classes.i b/bindings/python/sigrok/core/classes.i
index f8620abe993ba7af380ba531cbbe8177cb3e44de..015011ea8e1aa729fa5c249129dc1371d1976b4c 100644 (file)
--- a/bindings/python/sigrok/core/classes.i
+++ b/bindings/python/sigrok/core/classes.i
@@ -17,7 +17,32 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-%module classes
+%define DOCSTRING
+"@mainpage API Reference
+
+Introduction
+------------
+
+The pysigrok API provides an object-oriented Python interface to the
+functionality in libsigrok. It is built on top of the sigrok++ C++ API.
+
+Getting started
+---------------
+
+Usage of the pysigrok API needs to begin with a call to Context.create().
+This will create the global libsigrok context and returns a Context object.
+Methods on this object provide access to the hardware drivers, input and output
+formats supported by the library, as well as means of creating other objects
+such as sessions and triggers.
+
+Error handling
+--------------
+
+When any libsigrok C API call returns an error, an Error exception is raised,
+which provides access to the error code and description."
+%enddef
+
+%module(docstring=DOCSTRING) classes
 
 %{
 #include <pygobject.h>
@@ -26,6 +51,14 @@ PyObject *GLib;
 PyTypeObject *IOChannel;
 PyTypeObject *PollFD;
 
+#include "config.h"
+
+#if PYGOBJECT_FLAGS_SIGNED
+typedef gint pyg_flags_type;
+#else
+typedef guint pyg_flags_type;
+#endif
+
 %}
 
 %init %{
@@ -64,7 +97,7 @@ PyTypeObject *PollFD;
 
 /* Map from Glib::IOCondition to GLib.IOCondition. */
 %typecheck(SWIG_TYPECHECK_POINTER) Glib::IOCondition {
-    gint flags;
+    pyg_flags_type flags;
     $1 = pygobject_check($input, &PyGFlags_Type) &&
          (pyg_flags_get_value(G_TYPE_IO_CONDITION, $input, &flags) != -1);
 }
@@ -72,7 +105,7 @@ PyTypeObject *PollFD;
 %typemap(in) Glib::IOCondition {
     if (!pygobject_check($input, &PyGFlags_Type))
         SWIG_exception(SWIG_TypeError, "Expected GLib.IOCondition value");
-    gint flags;
+    pyg_flags_type flags;
     if (pyg_flags_get_value(G_TYPE_IO_CONDITION, $input, &flags) == -1)
         SWIG_exception(SWIG_TypeError, "Not a valid Glib.IOCondition value");
     $1 = (Glib::IOCondition) flags;
@@ -97,7 +130,7 @@ PyTypeObject *PollFD;
         SWIG_exception(SWIG_TypeError, "Expected GLib.PollFD");
     PyObject *fd_obj = PyObject_GetAttrString($input, "fd");
     PyObject *events_obj = PyObject_GetAttrString($input, "events");
-    gint flags;
+    pyg_flags_type flags;
     pyg_flags_get_value(G_TYPE_IO_CONDITION, events_obj, &flags);
     int fd = PyInt_AsLong(fd_obj);
     Glib::IOCondition events = (Glib::IOCondition) flags;
@@ -228,7 +261,7 @@ PyTypeObject *PollFD;
 #include "libsigrok/libsigrok.hpp"
 
 /* Convert from a Python dict to a std::map<std::string, std::string> */
-std::map<std::string, std::string> dict_to_map(PyObject *dict)
+std::map<std::string, std::string> dict_to_map_string(PyObject *dict)
 {
     if (!PyDict_Check(dict))
         throw sigrok::Error(SR_ERR_ARG);
@@ -272,6 +305,51 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
         throw sigrok::Error(SR_ERR_ARG);
 }
 
+/* Convert from a Python type to Glib::Variant, according to Option data type. */
+Glib::VariantBase python_to_variant_by_option(PyObject *input,
+    std::shared_ptr<sigrok::Option> option)
+{
+    GVariantType *type = option->get_default_value().get_type().gobj();
+
+    if (type == G_VARIANT_TYPE_UINT64 && PyInt_Check(input))
+        return Glib::Variant<guint64>::create(PyInt_AsLong(input));
+    if (type == G_VARIANT_TYPE_UINT64 && PyLong_Check(input))
+        return Glib::Variant<guint64>::create(PyLong_AsLong(input));
+    else if (type == G_VARIANT_TYPE_STRING && PyString_Check(input))
+        return Glib::Variant<std::string>::create(PyString_AsString(input));
+    else if (type == G_VARIANT_TYPE_BOOLEAN && PyBool_Check(input))
+        return Glib::Variant<bool>::create(input == Py_True);
+    else if (type == G_VARIANT_TYPE_DOUBLE && PyFloat_Check(input))
+        return Glib::Variant<double>::create(PyFloat_AsDouble(input));
+    else if (type == G_VARIANT_TYPE_INT32 && PyInt_Check(input))
+        return Glib::Variant<gint32>::create(PyInt_AsLong(input));
+    else
+        throw sigrok::Error(SR_ERR_ARG);
+}
+
+/* Convert from a Python dict to a std::map<std::string, std::string> */
+std::map<std::string, Glib::VariantBase> dict_to_map_options(PyObject *dict,
+    std::map<std::string, std::shared_ptr<sigrok::Option> > options)
+{
+    if (!PyDict_Check(dict))
+        throw sigrok::Error(SR_ERR_ARG);
+
+    std::map<std::string, Glib::VariantBase> output;
+
+    PyObject *py_key, *py_value;
+    Py_ssize_t pos = 0;
+
+    while (PyDict_Next(dict, &pos, &py_key, &py_value)) {
+        if (!PyString_Check(py_key))
+            throw sigrok::Error(SR_ERR_ARG);
+        auto key = PyString_AsString(py_key);
+        auto value = python_to_variant_by_option(py_value, options[key]);
+        output[key] = value;
+    }
+
+    return output;
+}
+
 %}
 
 /* Ignore these methods, we will override them below. */
@@ -279,6 +357,8 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
 %ignore sigrok::InputFormat::open_file;
 %ignore sigrok::OutputFormat::create_output;
 
+%include "doc.i"
+
 %include "../../../swig/classes.i"
 
 /* Support Driver.scan() with keyword arguments. */
@@ -319,7 +399,7 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
 {
     std::shared_ptr<sigrok::InputFileDevice> _open_file_kwargs(std::string filename, PyObject *dict)
     {
-        return $self->open_file(filename, dict_to_map(dict));
+        return $self->open_file(filename, dict_to_map_string(dict));
     }
 }
 
@@ -337,7 +417,8 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
     std::shared_ptr<sigrok::Output> _create_output_kwargs(
         std::shared_ptr<sigrok::Device> device, PyObject *dict)
     {
-        return $self->create_output(device, dict_to_map(dict));
+        return $self->create_output(device,
+            dict_to_map_options(dict, $self->get_options()));
     }
 }