bindings/python/sigrok/core/classes.i

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2014 Martin Ling <martin-sigrok@earth.li>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 %define DOCSTRING
  21 "@mainpage API Reference
  22
  23 Introduction
  24 ------------
  25
  26 The pysigrok API provides an object-oriented Python interface to the
  27 functionality in libsigrok. It is built on top of the libsigrokcxx C++ API.
  28
  29 Getting started
  30 ---------------
  31
  32 Usage of the pysigrok API needs to begin with a call to Context.create().
  33 This will create the global libsigrok context and returns a Context object.
  34 Methods on this object provide access to the hardware drivers, input and output
  35 formats supported by the library, as well as means of creating other objects
  36 such as sessions and triggers.
  37
  38 Error handling
  39 --------------
  40
  41 When any libsigrok C API call returns an error, an Error exception is raised,
  42 which provides access to the error code and description."
  43 %enddef
  44
  45 %module(docstring=DOCSTRING) classes
  46
  47 %{
  48 #include "config.h"
  49
  50 #include <stdio.h>
  51 #include <pygobject.h>
  52 #define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION
  53 #include <numpy/arrayobject.h>
  54
  55 PyObject *PyGObject_lib;
  56 PyObject *GLib;
  57
  58 #if PYGOBJECT_FLAGS_SIGNED
  59 typedef gint pyg_flags_type;
  60 #else
  61 typedef guint pyg_flags_type;
  62 #endif
  63
  64 #if PY_VERSION_HEX >= 0x03000000
  65 #define string_check PyUnicode_Check
  66 #define string_from_python PyUnicode_AsUTF8
  67 #define string_to_python PyUnicode_FromString
  68 #else
  69 #define string_check PyString_Check
  70 #define string_from_python PyString_AsString
  71 #define string_to_python PyString_FromString
  72 #endif
  73
  74 %}
  75
  76 %init %{
  77     PyGObject_lib = pygobject_init(-1, -1, -1);
  78     if (!PyGObject_lib)
  79         fprintf(stderr, "pygobject initialization failed.\n");
  80     GLib = PyImport_ImportModule("gi.repository.GLib");
  81     /*
  82      * This check can't save us if the import fails, but at least it gives us
  83      * a starting point to trace the issue versus straight out crashing.
  84      */
  85     if (!GLib) {
  86         fprintf(stderr, "Import of gi.repository.GLib failed.\n");
  87 #if PY_VERSION_HEX >= 0x03000000
  88         return nullptr;
  89 #else
  90         return;
  91 #endif
  92     }
  93     import_array();
  94 %}
  95
  96 %include "../../../swig/templates.i"
  97
  98 /* Map file objects to file descriptors. */
  99 %typecheck(SWIG_TYPECHECK_POINTER) int fd {
 100     $1 = (PyObject_AsFileDescriptor($input) != -1);
 101 }
 102
 103 /* Map from Glib::Variant to native Python types. */
 104 %typemap(out) Glib::VariantBase {
 105     GValue *value = g_new0(GValue, 1);
 106     g_value_init(value, G_TYPE_VARIANT);
 107     g_value_set_variant(value, $1.gobj());
 108     PyObject *variant = pyg_value_as_pyobject(value, true);
 109     $result = PyObject_CallMethod(variant,
 110         const_cast<char *>("unpack"), nullptr);
 111     Py_XDECREF(variant);
 112     g_free(value);
 113 }
 114
 115 /* Use the same typemap above for Glib::VariantContainerBase */
 116 %apply Glib::VariantBase { Glib::VariantContainerBase }
 117
 118 /* Map from callable PyObject to LogCallbackFunction */
 119 %typecheck(SWIG_TYPECHECK_POINTER) sigrok::LogCallbackFunction {
 120     $1 = PyCallable_Check($input);
 121 }
 122
 123 %typemap(in) sigrok::LogCallbackFunction {
 124     if (!PyCallable_Check($input))
 125         SWIG_exception(SWIG_TypeError, "Expected a callable Python object");
 126
 127     $1 = [=] (const sigrok::LogLevel *loglevel, std::string message) {
 128         auto gstate = PyGILState_Ensure();
 129
 130         auto log_obj = SWIG_NewPointerObj(
 131                 SWIG_as_voidptr(loglevel), SWIGTYPE_p_sigrok__LogLevel, 0);
 132
 133         auto string_obj = string_to_python(message.c_str());
 134
 135         auto arglist = Py_BuildValue("(OO)", log_obj, string_obj);
 136
 137         auto result = PyEval_CallObject($input, arglist);
 138
 139         Py_XDECREF(arglist);
 140         Py_XDECREF(log_obj);
 141         Py_XDECREF(string_obj);
 142
 143         bool completed = !PyErr_Occurred();
 144
 145         if (!completed)
 146             PyErr_Print();
 147
 148         bool valid_result = (completed && result == Py_None);
 149
 150         Py_XDECREF(result);
 151
 152         if (completed && !valid_result)
 153         {
 154             PyErr_SetString(PyExc_TypeError,
 155                 "Log callback did not return None");
 156             PyErr_Print();
 157         }
 158
 159         PyGILState_Release(gstate);
 160
 161         if (!valid_result)
 162             throw sigrok::Error(SR_ERR);
 163     };
 164
 165     Py_XINCREF($input);
 166 }
 167
 168 /* Map from callable PyObject to SessionStoppedCallback */
 169 %typecheck(SWIG_TYPECHECK_POINTER) sigrok::SessionStoppedCallback {
 170     $1 = PyCallable_Check($input);
 171 }
 172
 173 %typemap(in) sigrok::SessionStoppedCallback {
 174     if (!PyCallable_Check($input))
 175         SWIG_exception(SWIG_TypeError, "Expected a callable Python object");
 176
 177     $1 = [=] () {
 178         const auto gstate = PyGILState_Ensure();
 179
 180         const auto result = PyEval_CallObject($input, nullptr);
 181         const bool completed = !PyErr_Occurred();
 182         const bool valid_result = (completed && result == Py_None);
 183
 184         if (completed && !valid_result) {
 185             PyErr_SetString(PyExc_TypeError,
 186                 "Session stop callback did not return None");
 187         }
 188         if (!valid_result)
 189             PyErr_Print();
 190
 191         Py_XDECREF(result);
 192         PyGILState_Release(gstate);
 193
 194         if (!valid_result)
 195             throw sigrok::Error(SR_ERR);
 196     };
 197
 198     Py_XINCREF($input);
 199 }
 200
 201 /* Map from callable PyObject to DatafeedCallbackFunction */
 202 %typecheck(SWIG_TYPECHECK_POINTER) sigrok::DatafeedCallbackFunction {
 203     $1 = PyCallable_Check($input);
 204 }
 205
 206 %typemap(in) sigrok::DatafeedCallbackFunction {
 207     if (!PyCallable_Check($input))
 208         SWIG_exception(SWIG_TypeError, "Expected a callable Python object");
 209
 210     $1 = [=] (std::shared_ptr<sigrok::Device> device,
 211             std::shared_ptr<sigrok::Packet> packet) {
 212         auto gstate = PyGILState_Ensure();
 213
 214         auto device_obj = SWIG_NewPointerObj(
 215             SWIG_as_voidptr(new std::shared_ptr<sigrok::Device>(device)),
 216             SWIGTYPE_p_std__shared_ptrT_sigrok__Device_t, SWIG_POINTER_OWN);
 217
 218         auto packet_obj = SWIG_NewPointerObj(
 219             SWIG_as_voidptr(new std::shared_ptr<sigrok::Packet>(packet)),
 220             SWIGTYPE_p_std__shared_ptrT_sigrok__Packet_t, SWIG_POINTER_OWN);
 221
 222         auto arglist = Py_BuildValue("(OO)", device_obj, packet_obj);
 223
 224         auto result = PyEval_CallObject($input, arglist);
 225
 226         Py_XDECREF(arglist);
 227         Py_XDECREF(device_obj);
 228         Py_XDECREF(packet_obj);
 229
 230         bool completed = !PyErr_Occurred();
 231
 232         if (!completed)
 233             PyErr_Print();
 234
 235         bool valid_result = (completed && result == Py_None);
 236
 237         Py_XDECREF(result);
 238
 239         if (completed && !valid_result)
 240         {
 241             PyErr_SetString(PyExc_TypeError,
 242                 "Datafeed callback did not return None");
 243             PyErr_Print();
 244         }
 245
 246         PyGILState_Release(gstate);
 247
 248         if (!valid_result)
 249             throw sigrok::Error(SR_ERR);
 250     };
 251
 252     Py_XINCREF($input);
 253 }
 254
 255 /* Cast PacketPayload pointers to correct subclass type. */
 256 %ignore sigrok::Packet::payload;
 257
 258 %extend sigrok::Packet
 259 {
 260     std::shared_ptr<sigrok::Header> _payload_header()
 261     {
 262         return dynamic_pointer_cast<sigrok::Header>($self->payload());
 263     }
 264     std::shared_ptr<sigrok::Meta> _payload_meta()
 265     {
 266         return dynamic_pointer_cast<sigrok::Meta>($self->payload());
 267     }
 268     std::shared_ptr<sigrok::Analog> _payload_analog()
 269     {
 270         return dynamic_pointer_cast<sigrok::Analog>($self->payload());
 271     }
 272     std::shared_ptr<sigrok::Logic> _payload_logic()
 273     {
 274         return dynamic_pointer_cast<sigrok::Logic>($self->payload());
 275     }
 276 }
 277
 278 %extend sigrok::Packet
 279 {
 280 %pythoncode
 281 {
 282     def _payload(self):
 283         if self.type == PacketType.HEADER:
 284             return self._payload_header()
 285         elif self.type == PacketType.META:
 286             return self._payload_meta()
 287         elif self.type == PacketType.LOGIC:
 288             return self._payload_logic()
 289         elif self.type == PacketType.ANALOG:
 290             return self._payload_analog()
 291         else:
 292             return None
 293
 294     payload = property(_payload)
 295 }
 296 }
 297
 298 %{
 299
 300 #include "libsigrokcxx/libsigrokcxx.hpp"
 301
 302 /* Convert from a Python dict to a std::map<std::string, std::string> */
 303 std::map<std::string, std::string> dict_to_map_string(PyObject *dict)
 304 {
 305     if (!PyDict_Check(dict))
 306         throw sigrok::Error(SR_ERR_ARG);
 307
 308     std::map<std::string, std::string> output;
 309
 310     PyObject *py_key, *py_value;
 311     Py_ssize_t pos = 0;
 312
 313     while (PyDict_Next(dict, &pos, &py_key, &py_value)) {
 314         if (!string_check(py_key))
 315             throw sigrok::Error(SR_ERR_ARG);
 316         if (!string_check(py_value))
 317             throw sigrok::Error(SR_ERR_ARG);
 318         auto key = string_from_python(py_key);
 319         auto value = string_from_python(py_value);
 320         output[key] = value;
 321     }
 322
 323     return output;
 324 }
 325
 326 /* Convert from a Python type to Glib::Variant, according to config key data type. */
 327 Glib::VariantBase python_to_variant_by_key(PyObject *input, const sigrok::ConfigKey *key)
 328 {
 329     enum sr_datatype type = (enum sr_datatype) key->data_type()->id();
 330
 331     if (type == SR_T_UINT64 && PyInt_Check(input))
 332         return Glib::Variant<guint64>::create(PyInt_AsLong(input));
 333     if (type == SR_T_UINT64 && PyLong_Check(input))
 334         return Glib::Variant<guint64>::create(PyLong_AsLong(input));
 335     else if (type == SR_T_STRING && string_check(input))
 336         return Glib::Variant<Glib::ustring>::create(string_from_python(input));
 337     else if (type == SR_T_BOOL && PyBool_Check(input))
 338         return Glib::Variant<bool>::create(input == Py_True);
 339     else if (type == SR_T_FLOAT && PyFloat_Check(input))
 340         return Glib::Variant<double>::create(PyFloat_AsDouble(input));
 341     else if (type == SR_T_INT32 && PyInt_Check(input))
 342         return Glib::Variant<gint32>::create(PyInt_AsLong(input));
 343     else
 344         throw sigrok::Error(SR_ERR_ARG);
 345 }
 346
 347 /* Convert from a Python type to Glib::Variant, according to Option data type. */
 348 Glib::VariantBase python_to_variant_by_option(PyObject *input,
 349     std::shared_ptr<sigrok::Option> option)
 350 {
 351     GVariantType *type = option->default_value().get_type().gobj();
 352
 353     if (type == G_VARIANT_TYPE_UINT64 && PyInt_Check(input))
 354         return Glib::Variant<guint64>::create(PyInt_AsLong(input));
 355     if (type == G_VARIANT_TYPE_UINT64 && PyLong_Check(input))
 356         return Glib::Variant<guint64>::create(PyLong_AsLong(input));
 357     else if (type == G_VARIANT_TYPE_STRING && string_check(input))
 358         return Glib::Variant<Glib::ustring>::create(string_from_python(input));
 359     else if (type == G_VARIANT_TYPE_BOOLEAN && PyBool_Check(input))
 360         return Glib::Variant<bool>::create(input == Py_True);
 361     else if (type == G_VARIANT_TYPE_DOUBLE && PyFloat_Check(input))
 362         return Glib::Variant<double>::create(PyFloat_AsDouble(input));
 363     else if (type == G_VARIANT_TYPE_INT32 && PyInt_Check(input))
 364         return Glib::Variant<gint32>::create(PyInt_AsLong(input));
 365     else
 366         throw sigrok::Error(SR_ERR_ARG);
 367 }
 368
 369 /* Convert from a Python dict to a std::map<std::string, std::string> */
 370 std::map<std::string, Glib::VariantBase> dict_to_map_options(PyObject *dict,
 371     std::map<std::string, std::shared_ptr<sigrok::Option> > options)
 372 {
 373     if (!PyDict_Check(dict))
 374         throw sigrok::Error(SR_ERR_ARG);
 375
 376     std::map<std::string, Glib::VariantBase> output;
 377
 378     PyObject *py_key, *py_value;
 379     Py_ssize_t pos = 0;
 380
 381     while (PyDict_Next(dict, &pos, &py_key, &py_value)) {
 382         if (!string_check(py_key))
 383             throw sigrok::Error(SR_ERR_ARG);
 384         auto key = string_from_python(py_key);
 385         auto value = python_to_variant_by_option(py_value, options[key]);
 386         output[key] = value;
 387     }
 388
 389     return output;
 390 }
 391
 392 %}
 393
 394 /* Ignore these methods, we will override them below. */
 395 %ignore sigrok::Analog::data;
 396 %ignore sigrok::Logic::data;
 397 %ignore sigrok::Driver::scan;
 398 %ignore sigrok::InputFormat::create_input;
 399 %ignore sigrok::OutputFormat::create_output;
 400
 401 %include "doc_start.i"
 402
 403 %define %attributevector(Class, Type, Name, Get)
 404 %rename(_ ## Get) sigrok::Class::Get;
 405 %extend sigrok::Class
 406 {
 407 %pythoncode
 408 {
 409   Name = property(_ ## Get)
 410 }
 411 }
 412 %enddef
 413
 414 %define %attributemap(Class, Type, Name, Get)
 415 %rename(_ ## Get) sigrok::Class::Get;
 416 %extend sigrok::Class
 417 {
 418 %pythoncode
 419 {
 420   Name = property(fget = lambda x: x._ ## Get().asdict(), doc=_ ## Get.__doc__)
 421 }
 422 }
 423 %enddef
 424
 425 %define %enumextras(Class)
 426 %extend sigrok::Class
 427 {
 428   long __hash__()
 429   {
 430     return (long) $self;
 431   }
 432
 433   std::string __str__()
 434   {
 435     return $self->name();
 436   }
 437
 438   std::string __repr__()
 439   {
 440     return "Class." + $self->name();
 441   }
 442
 443 %pythoncode
 444 {
 445   def __eq__(self, other):
 446     return (type(self) is type(other) and hash(self) == hash(other))
 447
 448   def __ne__(self, other):
 449     return (type(self) is not type(other) or hash(self) != hash(other))
 450 }
 451 }
 452 %enddef
 453
 454 %include "../../../swig/classes.i"
 455
 456 /* Support Driver.scan() with keyword arguments. */
 457 %extend sigrok::Driver
 458 {
 459     std::vector<std::shared_ptr<sigrok::HardwareDevice> > _scan_kwargs(PyObject *dict)
 460     {
 461         if (!PyDict_Check(dict))
 462             throw sigrok::Error(SR_ERR_ARG);
 463
 464         PyObject *py_key, *py_value;
 465         Py_ssize_t pos = 0;
 466         std::map<const sigrok::ConfigKey *, Glib::VariantBase> options;
 467
 468         while (PyDict_Next(dict, &pos, &py_key, &py_value))
 469         {
 470             if (!string_check(py_key))
 471                 throw sigrok::Error(SR_ERR_ARG);
 472             auto key = sigrok::ConfigKey::get_by_identifier(string_from_python(py_key));
 473             auto value = python_to_variant_by_key(py_value, key);
 474             options[key] = value;
 475         }
 476
 477         return $self->scan(options);
 478     }
 479 }
 480
 481 %pythoncode
 482 {
 483     def _Driver_scan(self, **kwargs):
 484         return self._scan_kwargs(kwargs)
 485
 486     Driver.scan = _Driver_scan
 487 }
 488
 489 /* Support InputFormat.create_input() with keyword arguments. */
 490 %extend sigrok::InputFormat
 491 {
 492     std::shared_ptr<sigrok::Input> _create_input_kwargs(PyObject *dict)
 493     {
 494         return $self->create_input(
 495             dict_to_map_options(dict, $self->options()));
 496     }
 497 }
 498
 499 %pythoncode
 500 {
 501     def _InputFormat_create_input(self, **kwargs):
 502         return self._create_input(kwargs)
 503
 504     InputFormat.create_input = _InputFormat_create_input
 505 }
 506
 507 /* Support OutputFormat.create_output() with keyword arguments. */
 508 %extend sigrok::OutputFormat
 509 {
 510     std::shared_ptr<sigrok::Output> _create_output_kwargs(
 511         std::shared_ptr<sigrok::Device> device, PyObject *dict)
 512     {
 513         return $self->create_output(device,
 514             dict_to_map_options(dict, $self->options()));
 515     }
 516 }
 517
 518 %pythoncode
 519 {
 520     def _OutputFormat_create_output(self, device, **kwargs):
 521         return self._create_output_kwargs(device, kwargs)
 522
 523     OutputFormat.create_output = _OutputFormat_create_output
 524 }
 525
 526 /* Support config_set() with Python input types. */
 527 %extend sigrok::Configurable
 528 {
 529     void config_set(const ConfigKey *key, PyObject *input)
 530     {
 531         $self->config_set(key, python_to_variant_by_key(input, key));
 532     }
 533 }
 534
 535 /* Return NumPy array from Analog::data(). */
 536 %extend sigrok::Analog
 537 {
 538     PyObject * _data()
 539     {
 540         int nd = 2;
 541         npy_intp dims[2];
 542         dims[0] = $self->channels().size();
 543         dims[1] = $self->num_samples();
 544         int typenum = NPY_FLOAT;
 545         void *data = $self->data_pointer();
 546         return PyArray_SimpleNewFromData(nd, dims, typenum, data);
 547     }
 548
 549 %pythoncode
 550 {
 551     data = property(_data)
 552 }
 553 }
 554
 555 /* Return NumPy array from Logic::data(). */
 556 %extend sigrok::Logic
 557 {
 558     PyObject * _data()
 559     {
 560         npy_intp dims[2];
 561         dims[0] = $self->data_length() / $self->unit_size();
 562         dims[1] = $self->unit_size();
 563         int typenum = NPY_UINT8;
 564         void *data = $self->data_pointer();
 565         return PyArray_SimpleNewFromData(2, dims, typenum, data);
 566     }
 567
 568 %pythoncode
 569 {
 570     data = property(_data)
 571 }
 572 }
 573
 574 /* Create logic packet from Python buffer. */
 575 %extend sigrok::Context
 576 {
 577     std::shared_ptr<Packet> _create_logic_packet_buf(PyObject *buf, unsigned int unit_size)
 578     {
 579         Py_buffer view;
 580         PyObject_GetBuffer(buf, &view, PyBUF_SIMPLE);
 581         return $self->create_logic_packet(view.buf, view.len, unit_size);
 582     }
 583 }
 584
 585 %pythoncode
 586 {
 587     def _Context_create_logic_packet(self, buf, unit_size):
 588         return self._create_logic_packet_buf(buf, unit_size)
 589
 590     Context.create_logic_packet = _Context_create_logic_packet
 591 }
 592
 593 %include "doc_end.i"