X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=bindings%2Fpython%2Fsigrok%2Fcore%2Fclasses.i;h=75f20ea51df165f9f2d2e7992aa2b6ba27dc5635;hb=1b40fdb88108699cf9d912f3d7aadffb4dc04050;hp=374996d56f86c15aa9c4079e95381dd411b45b5d;hpb=abc7146d032d41af41e8bd20ea64554021e86656;p=libsigrok.git

diff --git a/bindings/python/sigrok/core/classes.i b/bindings/python/sigrok/core/classes.i
index 374996d5..75f20ea5 100644
--- a/bindings/python/sigrok/core/classes.i
+++ b/bindings/python/sigrok/core/classes.i
@@ -17,16 +17,42 @@
  * 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 libsigrokcxx 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>
+#include <numpy/arrayobject.h>
 
 PyObject *GLib;
 PyTypeObject *IOChannel;
 PyTypeObject *PollFD;
 
-#include "../../../../config.h"
+#include "config.h"
 
 #if PYGOBJECT_FLAGS_SIGNED
 typedef gint pyg_flags_type;
@@ -41,6 +67,7 @@ typedef guint pyg_flags_type;
     GLib = PyImport_ImportModule("gi.repository.GLib");
     IOChannel = (PyTypeObject *) PyObject_GetAttrString(GLib, "IOChannel");
     PollFD = (PyTypeObject *) PyObject_GetAttrString(GLib, "PollFD");
+    import_array();
 %}
 
 /* Map file objects to file descriptors. */
@@ -148,15 +175,29 @@ typedef guint pyg_flags_type;
         Py_XDECREF(arglist);
         Py_XDECREF(revents_obj);
 
-        if (PyErr_Occurred() || !PyBool_Check(result))
-            throw sigrok::Error(SR_ERR);
+        bool completed = !PyErr_Occurred();
+
+        if (!completed)
+            PyErr_Print();
 
-        bool retval = (result == Py_True);
+        bool valid_result = (completed && PyBool_Check(result));
+
+        if (completed && !valid_result)
+        {
+            PyErr_SetString(PyExc_TypeError,
+                "EventSource callback did not return a boolean");
+            PyErr_Print();
+        }
+
+        bool retval = (valid_result && result == Py_True);
 
         Py_XDECREF(result);
 
         PyGILState_Release(gstate);
 
+        if (!valid_result)
+            throw sigrok::Error(SR_ERR);
+
         return retval;
     };
 
@@ -187,9 +228,27 @@ typedef guint pyg_flags_type;
         Py_XDECREF(arglist);
         Py_XDECREF(log_obj);
         Py_XDECREF(string_obj);
+
+        bool completed = !PyErr_Occurred();
+
+        if (!completed)
+            PyErr_Print();
+
+        bool valid_result = (completed && result == Py_None);
+
         Py_XDECREF(result);
 
+        if (completed && !valid_result)
+        {
+            PyErr_SetString(PyExc_TypeError,
+                "Log callback did not return None");
+            PyErr_Print();
+        }
+
         PyGILState_Release(gstate);
+
+        if (!valid_result)
+            throw sigrok::Error(SR_ERR);
     };
 
     Py_XINCREF($input);
@@ -223,20 +282,81 @@ typedef guint pyg_flags_type;
         Py_XDECREF(arglist);
         Py_XDECREF(device_obj);
         Py_XDECREF(packet_obj);
+
+        bool completed = !PyErr_Occurred();
+
+        if (!completed)
+            PyErr_Print();
+
+        bool valid_result = (completed && result == Py_None);
+
         Py_XDECREF(result);
 
+        if (completed && !valid_result)
+        {
+            PyErr_SetString(PyExc_TypeError,
+                "Datafeed callback did not return None");
+            PyErr_Print();
+        }
+
         PyGILState_Release(gstate);
+
+        if (!valid_result)
+            throw sigrok::Error(SR_ERR);
     };
 
     Py_XINCREF($input);
 }
 
+/* Cast PacketPayload pointers to correct subclass type. */
+%ignore sigrok::Packet::payload;
+
+%extend sigrok::Packet
+{
+    std::shared_ptr<sigrok::Header> _payload_header()
+    {
+        return dynamic_pointer_cast<sigrok::Header>($self->payload());
+    }
+    std::shared_ptr<sigrok::Meta> _payload_meta()
+    {
+        return dynamic_pointer_cast<sigrok::Meta>($self->payload());
+    }
+    std::shared_ptr<sigrok::Analog> _payload_analog()
+    {
+        return dynamic_pointer_cast<sigrok::Analog>($self->payload());
+    }
+    std::shared_ptr<sigrok::Logic> _payload_logic()
+    {
+        return dynamic_pointer_cast<sigrok::Logic>($self->payload());
+    }
+}
+
+%extend sigrok::Packet
+{
+%pythoncode
+{
+    def _payload(self):
+        if self.type == PacketType.HEADER:
+            return self._payload_header()
+        elif self.type == PacketType.META:
+            return self._payload_meta()
+        elif self.type == PacketType.LOGIC:
+            return self._payload_logic()
+        elif self.type == PacketType.ANALOG:
+            return self._payload_analog()
+        else:
+            return None
+
+    payload = property(_payload)
+}
+}
+
 %{
 
-#include "libsigrok/libsigrok.hpp"
+#include "libsigrok/libsigrokcxx.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);
@@ -262,14 +382,14 @@ std::map<std::string, std::string> dict_to_map(PyObject *dict)
 /* Convert from a Python type to Glib::Variant, according to config key data type. */
 Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::ConfigKey *key)
 {
-    enum sr_datatype type = key->get_data_type()->get_id();
+    enum sr_datatype type = (enum sr_datatype) key->data_type()->id();
 
     if (type == SR_T_UINT64 && PyInt_Check(input))
         return Glib::Variant<guint64>::create(PyInt_AsLong(input));
     if (type == SR_T_UINT64 && PyLong_Check(input))
         return Glib::Variant<guint64>::create(PyLong_AsLong(input));
     else if (type == SR_T_STRING && PyString_Check(input))
-        return Glib::Variant<std::string>::create(PyString_AsString(input));
+        return Glib::Variant<Glib::ustring>::create(PyString_AsString(input));
     else if (type == SR_T_BOOL && PyBool_Check(input))
         return Glib::Variant<bool>::create(input == Py_True);
     else if (type == SR_T_FLOAT && PyFloat_Check(input))
@@ -280,13 +400,102 @@ 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->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<Glib::ustring>::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. */
+%ignore sigrok::Analog::data;
 %ignore sigrok::Driver::scan;
-%ignore sigrok::InputFormat::open_file;
+%ignore sigrok::InputFormat::create_input;
 %ignore sigrok::OutputFormat::create_output;
 
+%include "doc.i"
+
+%define %attributevector(Class, Type, Name, Get)
+%rename(_ ## Get) sigrok::Class::Get;
+%extend sigrok::Class
+{
+%pythoncode
+{
+  Name = property(_ ## Get)
+}
+}
+%enddef
+
+%define %attributemap(Class, Type, Name, Get)
+%rename(_ ## Get) sigrok::Class::Get;
+%extend sigrok::Class
+{
+%pythoncode
+{
+  Name = property(fget = lambda x: x._ ## Get().asdict(), doc=_ ## Get.__doc__)
+}
+}
+%enddef
+
+%define %enumextras(Class)
+%extend sigrok::Class
+{
+  long __hash__()
+  {
+    return (long) $self;
+  }
+
+%pythoncode
+{
+  def __eq__(self, other):
+    return (type(self) is type(other) and hash(self) == hash(other))
+
+  def __ne__(self, other):
+    return (type(self) is not type(other) or hash(self) != hash(other))
+}
+}
+%enddef
+
 %include "../../../swig/classes.i"
 
 /* Support Driver.scan() with keyword arguments. */
@@ -305,7 +514,7 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
         {
             if (!PyString_Check(py_key))
                 throw sigrok::Error(SR_ERR_ARG);
-            auto key = sigrok::ConfigKey::get(PyString_AsString(py_key));
+            auto key = sigrok::ConfigKey::get_by_identifier(PyString_AsString(py_key));
             auto value = python_to_variant_by_key(py_value, key);
             options[key] = value;
         }
@@ -322,21 +531,22 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
     Driver.scan = _Driver_scan
 }
 
-/* Support InputFormat.open_file() with keyword arguments. */
+/* Support InputFormat.create_input() with keyword arguments. */
 %extend sigrok::InputFormat
 {
-    std::shared_ptr<sigrok::InputFileDevice> _open_file_kwargs(std::string filename, PyObject *dict)
+    std::shared_ptr<sigrok::Input> _create_input_kwargs(PyObject *dict)
     {
-        return $self->open_file(filename, dict_to_map(dict));
+        return $self->create_input(
+            dict_to_map_options(dict, $self->options()));
     }
 }
 
 %pythoncode
 {
-    def _InputFormat_open_file(self, filename, **kwargs):
-        return self._open_file_kwargs(filename, kwargs)
+    def _InputFormat_create_input(self, **kwargs):
+        return self._create_input(kwargs)
 
-    InputFormat.open_file = _InputFormat_open_file
+    InputFormat.create_input = _InputFormat_create_input
 }
 
 /* Support OutputFormat.create_output() with keyword arguments. */
@@ -345,7 +555,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->options()));
     }
 }
 
@@ -365,3 +576,23 @@ Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::Config
         $self->config_set(key, python_to_variant_by_key(input, key));
     }
 }
+
+/* Return NumPy array from Analog::data(). */
+%extend sigrok::Analog
+{
+    PyObject * _data()
+    {
+        int nd = 2;
+        npy_intp dims[2];
+        dims[0] = $self->channels().size();
+        dims[1] = $self->num_samples();
+        int typenum = NPY_FLOAT;
+        void *data = $self->data_pointer();
+        return PyArray_SimpleNewFromData(nd, dims, typenum, data);
+    }
+
+%pythoncode
+{
+    data = property(_data)
+}
+}