Updated python wrapper: Fixes for python3 + documentation

xantares 09 wrote:
- Fixed examples with python3
- Added docstring documentation

Note: the read_chipid function fails from python3.

diff --git a/bindings/ftdi1.i b/bindings/ftdi1.i
index 952a383..d6fc05c 100644 (file)
--- a/bindings/ftdi1.i
+++ b/bindings/ftdi1.i
@@ -1,13 +1,14 @@
 /* File: ftdi1.i */
 
 %module(docstring="Python interface to libftdi1") ftdi1
+%feature("autodoc","1");
 
 %{
 #include "Python.h"
 
 inline PyObject* convertString( const char *v, Py_ssize_t len )
 #if PY_MAJOR_VERSION >= 3
-{ return PyUnicode_FromStringAndSize(v, len); }
+{ return PyBytes_FromStringAndSize(v, len); }
 #else
 { return PyString_FromStringAndSize(v, len); }
 #endif
@@ -27,6 +28,10 @@ inline PyObject* convertString( const char *v, Py_ssize_t len )
 %typemap(newfree) struct ftdi_context *ftdi "ftdi_free($1);";
 %delobject ftdi_free;
 
+%define ftdi_usb_find_all_docstring
+"usb_find_all(context, vendor, product) -> (return_code, devlist)"
+%enddef
+%feature("autodoc", ftdi_usb_find_all_docstring) ftdi_usb_find_all;
 %typemap(in,numinputs=0) SWIGTYPE** OUTPUT ($*ltype temp) %{ $1 = &temp; %}
 %typemap(argout) SWIGTYPE** OUTPUT %{ $result = SWIG_Python_AppendOutput($result, SWIG_NewPointerObj((void*)*$1,$*descriptor,0)); %}
 %apply SWIGTYPE** OUTPUT { struct ftdi_device_list **devlist };
@@ -34,6 +39,10 @@ inline PyObject* convertString( const char *v, Py_ssize_t len )
                           int vendor, int product);
 %clear struct ftdi_device_list **devlist;
 
+%define ftdi_usb_get_strings_docstring
+"usb_get_strings(context, device) -> (return_code, manufacturer, description, serial)"
+%enddef
+%feature("autodoc", ftdi_usb_get_strings_docstring) ftdi_usb_get_strings;
 %apply char *OUTPUT { char * manufacturer, char * description, char * serial };
 %cstring_bounded_output( char * manufacturer, 256 );
 %cstring_bounded_output( char * description, 256 );
@@ -46,6 +55,10 @@ inline PyObject* convertString( const char *v, Py_ssize_t len )
 %clear char * manufacturer, char * description, char * serial;
 %clear int mnf_len, int desc_len, int serial_len;
 
+%define ftdi_read_data_docstring
+"read_data(context) -> (return_code, buf)"
+%enddef
+%feature("autodoc", ftdi_read_data_docstring) ftdi_read_data;
 %typemap(in,numinputs=1) (unsigned char *buf, int size) %{ $2 = PyInt_AsLong($input);$1 = (unsigned char*)malloc($2*sizeof(char)); %}
 %typemap(argout) (unsigned char *buf, int size) %{ if(result<0) $2=0; $result = SWIG_Python_AppendOutput($result, convertString((char*)$1, $2)); free($1); %}
     int ftdi_read_data(struct ftdi_context *ftdi, unsigned char *buf, int size);
@@ -56,6 +69,10 @@ inline PyObject* convertString( const char *v, Py_ssize_t len )
     int ftdi_write_data_get_chunksize(struct ftdi_context *ftdi, unsigned int *chunksize);
 %clear unsigned int *chunksize;
 
+%define ftdi_read_pins_docstring
+"read_pins(context) -> (return_code, pins)"
+%enddef
+%feature("autodoc", ftdi_read_pins_docstring) ftdi_read_pins;
 %apply char *OUTPUT { unsigned char *pins };
     int ftdi_read_pins(struct ftdi_context *ftdi, unsigned char *pins);
 %clear unsigned char *pins;
@@ -77,10 +94,23 @@ inline PyObject* convertString( const char *v, Py_ssize_t len )
     int ftdi_get_eeprom_buf(struct ftdi_context *ftdi, unsigned char * buf, int size);
 %clear (unsigned char *buf, int size);
 
+%define ftdi_read_eeprom_location_docstring
+"read_eeprom_location(context, eeprom_addr) -> (return_code, eeprom_val)"
+%enddef
+%feature("autodoc", ftdi_read_eeprom_location_docstring) ftdi_read_eeprom_location;
 %apply short *OUTPUT { unsigned short *eeprom_val };
     int ftdi_read_eeprom_location (struct ftdi_context *ftdi, int eeprom_addr, unsigned short *eeprom_val);
 %clear unsigned short *eeprom_val;
 
+%define ftdi_read_eeprom_docstring
+"read_eeprom(context) -> (return_code, eeprom)"
+%enddef
+%feature("autodoc", ftdi_read_eeprom_docstring) ftdi_read_eeprom;
+
+%define ftdi_read_chipid_docstring
+"read_pins(context) -> (return_code, chipid)"
+%enddef
+%feature("autodoc", ftdi_read_chipid_docstring) ftdi_read_chipid;
 %apply int *OUTPUT { unsigned int *chipid };
     int ftdi_read_chipid(struct ftdi_context *ftdi, unsigned int *chipid);
 %clear unsigned int *chipid;

diff --git a/examples/python/complete.py b/examples/python/complete.py
index 3a765c8..239188c 100644 (file)
--- a/examples/python/complete.py
+++ b/examples/python/complete.py
@@ -9,6 +9,7 @@ of the swig generated python wrapper
 You need to build and install the wrapper first"""
 
 import os
+import sys
 import ftdi1 as ftdi
 import time
 
@@ -18,8 +19,11 @@ if ftdic == 0:
     print( 'new failed: %d', ret )
     os._exit( 1 )
 
-# list all devices
-ret, devlist = ftdi.usb_find_all( ftdic, 0x0403, 0x6001 )
+# try to list ftdi devices 0x6010 or 0x6001
+ret, devlist = ftdi.usb_find_all( ftdic, 0x0403, 0x6010 )
+if ret <= 0:
+    ret, devlist = ftdi.usb_find_all( ftdic, 0x0403, 0x6001)
+
 if ret < 0:
     print( 'ftdi_usb_find_all failed: %d (%s)' % ( ret, ftdi.get_error_string( ftdic ) ) )
     os._exit( 1 )
@@ -59,20 +63,22 @@ for i in range( 8 ):
     ftdi.write_data( ftdic, chr(val), 1 )
     time.sleep ( 1 )
 ftdi.disable_bitbang( ftdic )
-print( '\n' )
+print( '' )
 
 
 # read pins
-ret, pins = ftdi.read_pins( ftdic )
-print( 'pins:\n' )
-if ( ret == 0 ):
-    print( '%02x' % ord( pins[0] ) )
-print( '\n' )
-
+# FIXME: read_pins fails with python3, so I disabled it for now
+# tested on ubuntu 12.04 ( python3.2.3 / swig 2.0.4 )
+if (sys.version_info[0]<3):
+    ret, pins = ftdi.read_pins( ftdic )
+    if ( ret == 0 ):
+        print( 'pins: %02x' % ord( pins[0] ) )
+              
 
 # read chip id
 ret, chipid = ftdi.read_chipid( ftdic )
-print( 'FDTI chip id: %X\n' % chipid )
+if (ret==0):
+    print( 'chip id: %X\n' % chipid )
 
 
 # read eeprom
@@ -81,19 +87,27 @@ ret, eeprom_val = ftdi.read_eeprom_location( ftdic, eeprom_addr )
 if (ret==0):
     print( 'eeprom @ %d: 0x%04x\n' % ( eeprom_addr, eeprom_val ) )
 
-print( 'complete eeprom:' )
+print( 'eeprom:' )
 ret = ftdi.read_eeprom( ftdic )
 size = 128
 ret, eeprom = ftdi.get_eeprom_buf ( ftdic, size )
 if ( ret == 0 ):
     for i in range( size ):
-        print( '%02x' % ord( eeprom[i] ) )
+        if isinstance(eeprom[i], str):
+            octet = ord( eeprom[i] ) # python2
+        else:
+            octet = eeprom[i] # python3
+        sys.stdout.write( '%02x ' % octet )
         if ( i % 8 == 7 ):
-            print( '\n' )
+            print( '' )
+print( '' )
 
+            
 # close usb
 ret = ftdi.usb_close( ftdic )
 if ret < 0:
     print( 'unable to close ftdi device: %d (%s)' % ( ret, ftdi.get_error_string( ftdic ) ) )
     os._exit( 1 )
+    
+print ('device closed')    
 ftdi.free( ftdic )

diff --git a/examples/python/simple.py b/examples/python/simple.py
index 82ef6bb..9298c24 100644 (file)
--- a/examples/python/simple.py
+++ b/examples/python/simple.py
@@ -20,7 +20,12 @@ def main():
                (version_info.major, version_info.minor, version_info.micro,
                version_info.version_str, version_info.snapshot_str))
 
-    print("ftdi.usb_open(): %d" % ftdi.usb_open(context, 0x0403, 0x6010))
+    # try to open an ftdi 0x6010 or 0x6001
+    ret = ftdi.usb_open(context, 0x0403, 0x6010)
+    if ret < 0:
+        ret = ftdi.usb_open(context, 0x0403, 0x6001)
+        
+    print("ftdi.usb_open(): %d" % ret)
     print("ftdi.set_baudrate(): %d" % ftdi.set_baudrate(context, 9600))
 
     ftdi.free(context)