Commits

Ben Bass  committed 3fc1e67

api changes: interface->interface_select; buffer_size->chunk_size

  • Participants
  • Parent commits a8d1757

Comments (0)

Files changed (6)

 =================
 
 0.11.0
+ * API change:
+   * Device() parameter 'interface' has been renamed to 'interface_select',
+     as it wasn't clear what this meant. Symbolic constants 'INTERFACE_ANY',
+     'INTERFACE_A'/B/C/D are provided in the pylibftdi package namespace.
+   * Device() parameter 'buffer_size' has been renamed to 'chunk_size'
+     because there isn't any buffering going on, so it was potentially
+     misleading.
  * In progress...
 0.10.3
  * lots more documentation, cleaned up, on readthedocs. Still in progress though.

File doc/how_to.rst

 -----------------------
 
 Tests aren't included in the distutils distribution, so clone the
-repository and run from there::
+repository and run from there. pylibftdi supports Python 2.6/2.7 as well
+as Python 3.2+, so these tests can be run for each Python version::
 
     $ hg clone http://bitbucket.org/codedstructure/pylibftdi
     <various output stuff>
     $ cd pylibftdi
-    $ python -m unittest discover
+    $ python2.7 -m unittest discover
     ................
     ----------------------------------------------------------------------
-    Ran 16 tests in 0.025s
+    Ran 16 tests in 0.011s
+
+    OK
+    $ python3.3 -m unittest discover
+    ................
+    ----------------------------------------------------------------------
+    Ran 16 tests in 0.015s
 
     OK
     $
 of them, it is isolated from the other interfaces.
 
 To select which interface to use when opening a connection to a specific
-interface on a multiple-interface device, use the ``interface`` parameter
-of the Device (or BitBangDevice) class constructor.
-The value should be one of the following values:
+interface on a multiple-interface device, use the ``interface_select``
+parameter of the Device (or BitBangDevice) class constructor.
+The value should be one of the following values. Symbolic constants are
+provided in the pylibftdi namespace.
 
-    =================== =============
-    ``interface`` value Meaning
-    ------------------- -------------
-    0                   Any interface
-    1                   INTERFACE A
-    2                   INTERFACE B
-    3                   INTERFACE C
-    4                   INTERFACE D
-    =================== =============
+    ==================== =============
+    ``interface_select`` Meaning
+    -------------------- -------------
+    INTERFACE_ANY (0)    Any interface
+    INTERFACE_A (1)      INTERFACE A
+    INTERFACE_B (2)      INTERFACE B
+    INTERFACE_C (3)      INTERFACE C
+    INTERFACE_D (4)      INTERFACE D
+    ==================== =============
 
 You should be able to open multiple ``Device``\s with different
-``interface`` settings.
+``interface_select`` settings.
 *Thanks to Daniel Forer for testing multiple device support.*

File pylibftdi/__init__.py

 FLUSH_BOTH = driver.FLUSH_BOTH
 FLUSH_INPUT = driver.FLUSH_INPUT
 FLUSH_OUTPUT = driver.FLUSH_OUTPUT
+
+# Use these for interface_select on multiple-interface devices
+INTERFACE_ANY = 0
+INTERFACE_A = 1
+INTERFACE_B = 2
+INTERFACE_C = 3
+INTERFACE_D = 4

File pylibftdi/bitbang.py

                  lazy_open=False,
                  sync=True,
                  bitbang_mode=BITMODE_BITBANG,
-                 interface=None):
+                 interface_select=None):
         # initialise the super-class, but don't open yet. We really want
         # two-part initialisation here - set up all the instance variables
         # here in the super class, then open it after having set more
         super(BitBangDevice, self).__init__(device_id=device_id,
                                             mode='b',
                                             lazy_open=True,
-                                            interface=interface)
+                                            interface_select=interface_select)
         self.direction = direction
         self.sync = sync
         self.bitbang_mode = bitbang_mode

File pylibftdi/driver.py

 
 class Device(object):
     """
-    Device([device_id[, mode [, encoding [, lazy_open]]]) -> Device instance
+    Represents a connection to a single FTDI device
+    """
 
-    represents a single FTDI device accessible via the libftdi driver.
-    Supports a basic file-like interface (open/close/read/write, context
-    manager support).
-
-    device_id - an optional serial number of the device to open.
-      if omitted, this refers to the first device found, which is
-      convenient if only one device is attached, but otherwise
-      fairly useless.
-
-    mode - either 'b' (binary) or 't' (text). This primarily affects
-      Python 3 calls to read() and write(), which will accept/return
-      unicode strings which will be encoded/decoded according to the given...
-
-    encoding - the codec name to be used for text operations.
-
-    lazy_open - if True, then the device will not be opened immediately - the
-      user must perform an explicit open() call prior to other operations.
-    """
     def __init__(self, device_id=None, mode="b",
                  encoding="latin1", lazy_open=False,
-                 buffer_size=0, interface=None):
+                 chunk_size=0, interface_select=None):
+        """
+        Device([device_id[, mode, [OPTIONS ...]]) -> Device instance
+
+        represents a single FTDI device accessible via the libftdi driver.
+        Supports a basic file-like interface (open/close/read/write, context
+        manager support).
+
+        device_id - an optional serial number of the device to open.
+            if omitted, this refers to the first device found, which is
+            convenient if only one device is attached, but otherwise
+            fairly useless.
+
+        mode - either 'b' (binary) or 't' (text). This primarily affects
+            Python 3 calls to read() and write(), which will accept/return
+            unicode strings which will be encoded/decoded according to the given...
+
+        encoding - the codec name to be used for text operations.
+
+        lazy_open - if True, then the device will not be opened immediately -
+            the user must perform an explicit open() call prior to other
+            operations.
+
+        chunk_size - if non-zero, split read and write operations into chunks
+            of this size. With large or slow accesses, interruptions (i.e.
+            KeyboardInterrupt) may not happen in a timely fashion.
+
+        interface_select - select interface to use on multi-interface devices
+        """
         self._opened = False
         self.driver = Driver()
         self.fdll = self.driver.fdll
         self._baudrate = 9600
         # defining softspace allows us to 'print' to this device
         self.softspace = 0
-        # buffer_size (if not 0) chunks the reads and writes
+        # chunk_size (if not 0) chunks the reads and writes
         # to allow interruption
-        self.buffer_size = buffer_size
+        self.chunk_size = chunk_size
         # interface can be set for devices which have multiple interface
         # ports (e.g. FT4232, FT2232)
-        self.interface = interface
+        self.interface_select = interface_select
         # lazy_open tells us not to open immediately.
         if not lazy_open:
             self.open()
             del self.ctx
             raise FtdiError(msg)
 
-        if self.interface is not None:
-            self.fdll.ftdi_set_interface(byref(self.ctx), self.interface)
+        if self.interface_select is not None:
+            self.fdll.ftdi_set_interface(byref(self.ctx),
+                self.interface_select)
 
         # Try to open the device.  If this fails, reset things to how
         # they were, but we can't use self.close as that assumes things
             raise FtdiError("read() on closed Device")
 
         # read the data
-        if self.buffer_size != 0:
+        if self.chunk_size != 0:
             remaining = length
             byte_data_list = []
             while remaining > 0:
-                rx_bytes = self._read(min(remaining, self.buffer_size))
+                rx_bytes = self._read(min(remaining, self.chunk_size))
                 if not rx_bytes:
                     break
                 byte_data_list.append(rx_bytes)
             byte_data = data.encode(self.encoding)
 
         # actually write it
-        if self.buffer_size != 0:
+        if self.chunk_size != 0:
             remaining = len(byte_data)
             written = 0
             while remaining > 0:
                 start = written
-                length = min(remaining, self.buffer_size)
+                length = min(remaining, self.chunk_size)
                 result = self._write(byte_data[start: start + length])
                 if result == -1:
                     written == result
     def __enter__(self):
         """
         support for context manager.
+
         Note the device is opened and closed automatically
         when used in a with statement, and the device object
         itself is returned:

File tests/test_driver.py

         # check that opening a specific interface does that
 
     def testOpenInterface(self):
-        self.assertCalls(lambda: Device(interface=1), 'ftdi_set_interface')
+        self.assertCalls(lambda: Device(interface_select=1),
+                         'ftdi_set_interface')
         # check that opening a specific interface does that
         self.assertNotCalls(lambda: Device(), 'ftdi_set_interface')
 
             self.assertEqual(line, lines[idx])
 
     def testBuffer(self):
-        d = LoopDevice(mode='t', buffer_size=3)
+        d = LoopDevice(mode='t', chunk_size=3)
         d.write('Hello')
         d.write(' World\n')
         d.write('Bye')