94913d0f65caa052065a122070d9b48939e0d65a
[libsigrok.git] / 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 if ((type == SR_T_RATIONAL_VOLT) && PyTuple_Check(input) && (PyTuple_Size(input) == 2)) {
344         PyObject *numObj = PyTuple_GetItem(input, 0);
345         PyObject *denomObj = PyTuple_GetItem(input, 1);
346         if ((PyInt_Check(numObj) || PyLong_Check(numObj)) && (PyInt_Check(denomObj) || PyLong_Check(denomObj))) {
347           std::tuple<guint64, guint64> tpl = {PyInt_AsLong(numObj), PyInt_AsLong(denomObj)};
348           return Glib::Variant< std::tuple<guint64,guint64> >::Variant::create(tpl);
349         }
350     }
351     throw sigrok::Error(SR_ERR_ARG);
352 }
353
354 /* Convert from a Python type to Glib::Variant, according to Option data type. */
355 Glib::VariantBase python_to_variant_by_option(PyObject *input,
356     std::shared_ptr<sigrok::Option> option)
357 {
358     GVariantType *type = option->default_value().get_type().gobj();
359
360     if (type == G_VARIANT_TYPE_UINT64 && PyInt_Check(input))
361         return Glib::Variant<guint64>::create(PyInt_AsLong(input));
362     if (type == G_VARIANT_TYPE_UINT64 && PyLong_Check(input))
363         return Glib::Variant<guint64>::create(PyLong_AsLong(input));
364     else if (type == G_VARIANT_TYPE_STRING && string_check(input))
365         return Glib::Variant<Glib::ustring>::create(string_from_python(input));
366     else if (type == G_VARIANT_TYPE_BOOLEAN && PyBool_Check(input))
367         return Glib::Variant<bool>::create(input == Py_True);
368     else if (type == G_VARIANT_TYPE_DOUBLE && PyFloat_Check(input))
369         return Glib::Variant<double>::create(PyFloat_AsDouble(input));
370     else if (type == G_VARIANT_TYPE_INT32 && PyInt_Check(input))
371         return Glib::Variant<gint32>::create(PyInt_AsLong(input));
372     else
373         throw sigrok::Error(SR_ERR_ARG);
374 }
375
376 /* Convert from a Python dict to a std::map<std::string, std::string> */
377 std::map<std::string, Glib::VariantBase> dict_to_map_options(PyObject *dict,
378     std::map<std::string, std::shared_ptr<sigrok::Option> > options)
379 {
380     if (!PyDict_Check(dict))
381         throw sigrok::Error(SR_ERR_ARG);
382
383     std::map<std::string, Glib::VariantBase> output;
384
385     PyObject *py_key, *py_value;
386     Py_ssize_t pos = 0;
387
388     while (PyDict_Next(dict, &pos, &py_key, &py_value)) {
389         if (!string_check(py_key))
390             throw sigrok::Error(SR_ERR_ARG);
391         auto key = string_from_python(py_key);
392         auto value = python_to_variant_by_option(py_value, options[key]);
393         output[key] = value;
394     }
395
396     return output;
397 }
398
399 %}
400
401 /* Ignore these methods, we will override them below. */
402 %ignore sigrok::Analog::data;
403 %ignore sigrok::Logic::data;
404 %ignore sigrok::Driver::scan;
405 %ignore sigrok::InputFormat::create_input;
406 %ignore sigrok::OutputFormat::create_output;
407
408 %include "doc_start.i"
409
410 %define %attributevector(Class, Type, Name, Get)
411 %rename(_ ## Get) sigrok::Class::Get;
412 %extend sigrok::Class
413 {
414 %pythoncode
415 {
416   Name = property(_ ## Get)
417 }
418 }
419 %enddef
420
421 %define %attributemap(Class, Type, Name, Get)
422 %rename(_ ## Get) sigrok::Class::Get;
423 %extend sigrok::Class
424 {
425 %pythoncode
426 {
427   Name = property(fget = lambda x: x._ ## Get().asdict(), doc=_ ## Get.__doc__)
428 }
429 }
430 %enddef
431
432 %define %enumextras(Class)
433 %extend sigrok::Class
434 {
435   long __hash__()
436   {
437     return (long) $self;
438   }
439
440   std::string __str__()
441   {
442     return $self->name();
443   }
444
445   std::string __repr__()
446   {
447     return "Class." + $self->name();
448   }
449
450 %pythoncode
451 {
452   def __eq__(self, other):
453     return (type(self) is type(other) and hash(self) == hash(other))
454
455   def __ne__(self, other):
456     return (type(self) is not type(other) or hash(self) != hash(other))
457 }
458 }
459 %enddef
460
461 %include "../../../swig/classes.i"
462
463 /* Support Driver.scan() with keyword arguments. */
464 %extend sigrok::Driver
465 {
466     std::vector<std::shared_ptr<sigrok::HardwareDevice> > _scan_kwargs(PyObject *dict)
467     {
468         if (!PyDict_Check(dict))
469             throw sigrok::Error(SR_ERR_ARG);
470
471         PyObject *py_key, *py_value;
472         Py_ssize_t pos = 0;
473         std::map<const sigrok::ConfigKey *, Glib::VariantBase> options;
474
475         while (PyDict_Next(dict, &pos, &py_key, &py_value))
476         {
477             if (!string_check(py_key))
478                 throw sigrok::Error(SR_ERR_ARG);
479             auto key = sigrok::ConfigKey::get_by_identifier(string_from_python(py_key));
480             auto value = python_to_variant_by_key(py_value, key);
481             options[key] = value;
482         }
483
484         return $self->scan(options);
485     }
486 }
487
488 %pythoncode
489 {
490     def _Driver_scan(self, **kwargs):
491         return self._scan_kwargs(kwargs)
492
493     Driver.scan = _Driver_scan
494 }
495
496 /* Support InputFormat.create_input() with keyword arguments. */
497 %extend sigrok::InputFormat
498 {
499     std::shared_ptr<sigrok::Input> _create_input_kwargs(PyObject *dict)
500     {
501         return $self->create_input(
502             dict_to_map_options(dict, $self->options()));
503     }
504 }
505
506 %pythoncode
507 {
508     def _InputFormat_create_input(self, **kwargs):
509         return self._create_input(kwargs)
510
511     InputFormat.create_input = _InputFormat_create_input
512 }
513
514 /* Support OutputFormat.create_output() with keyword arguments. */
515 %extend sigrok::OutputFormat
516 {
517     std::shared_ptr<sigrok::Output> _create_output_kwargs(
518         std::shared_ptr<sigrok::Device> device, PyObject *dict)
519     {
520         return $self->create_output(device,
521             dict_to_map_options(dict, $self->options()));
522     }
523 }
524
525 %pythoncode
526 {
527     def _OutputFormat_create_output(self, device, **kwargs):
528         return self._create_output_kwargs(device, kwargs)
529
530     OutputFormat.create_output = _OutputFormat_create_output
531 }
532
533 /* Support config_set() with Python input types. */
534 %extend sigrok::Configurable
535 {
536     void config_set(const ConfigKey *key, PyObject *input)
537     {
538         $self->config_set(key, python_to_variant_by_key(input, key));
539     }
540 }
541
542 /* Return NumPy array from Analog::data(). */
543 %extend sigrok::Analog
544 {
545     PyObject * _data()
546     {
547         int nd = 2;
548         npy_intp dims[2];
549         dims[0] = $self->channels().size();
550         dims[1] = $self->num_samples();
551         int typenum = NPY_FLOAT;
552         void *data = $self->data_pointer();
553         return PyArray_SimpleNewFromData(nd, dims, typenum, data);
554     }
555
556 %pythoncode
557 {
558     data = property(_data)
559 }
560 }
561
562 /* Return NumPy array from Logic::data(). */
563 %extend sigrok::Logic
564 {
565     PyObject * _data()
566     {
567         npy_intp dims[2];
568         dims[0] = $self->data_length() / $self->unit_size();
569         dims[1] = $self->unit_size();
570         int typenum = NPY_UINT8;
571         void *data = $self->data_pointer();
572         return PyArray_SimpleNewFromData(2, dims, typenum, data);
573     }
574
575 %pythoncode
576 {
577     data = property(_data)
578 }
579 }
580
581 /* Create logic packet from Python buffer. */
582 %extend sigrok::Context
583 {
584     std::shared_ptr<Packet> _create_logic_packet_buf(PyObject *buf, unsigned int unit_size)
585     {
586         Py_buffer view;
587         PyObject_GetBuffer(buf, &view, PyBUF_SIMPLE);
588         return $self->create_logic_packet(view.buf, view.len, unit_size);
589     }
590 }
591
592 %pythoncode
593 {
594     def _Context_create_logic_packet(self, buf, unit_size):
595         return self._create_logic_packet_buf(buf, unit_size)
596
597     Context.create_logic_packet = _Context_create_logic_packet
598 }
599
600 %include "doc_end.i"