Ben Bass avatar Ben Bass committed 5772ef2

general tidy-ups

Comments (0)

Files changed (4)

 pylibftdi changes
 =================
 
-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.11.0pre
+~~~~~~~~~
+
+* API changes
+    * 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.
+    * new 'latch' property on BitBangDevices reflects current state of output
+      latch, for better defined behaviour on read-modify-write operations on
+      mixed-direction ports.
+* fixed the bit_server example; run as
+      python -m pylibftdi.examples.bit_server
+
+* docstring clean-ups
+* BitBangDevice now reads device pin state on startup, so read/rmw operations
+  across process runs now work as expected; for example previously running::
+
+      >>> from pylibftdi import BitBangDevice
+      >>> d = BitBangDevice()
+      >>> d.port = 1
+      >>> ^D
+
+      # restart interpreter
+
+      >>> from pylibftdi import BitBangDevice
+      >>> d = BitBangDevice()
+      >>> d.port |= 2
+
+  would have cleared D0, but now keeps it high (so d.port == 3)
+* TODO: more docstring tidy-up, tests for latch, doc updates
+
 0.10.3
- * lots more documentation, cleaned up, on readthedocs. Still in progress though.
- * Experimental support for multi-device interfaces ``Device(interface=1)``
+~~~~~~
+* lots more documentation, cleaned up, on readthedocs. Still in progress though.
+* Experimental support for multi-device interfaces ``Device(interface=1)``
+
 0.10.2
+~~~~~~
  * include examples subpackage
  * ensure examples work under Python3
  * 'python -m pylibftdi.examples.led_flash' should now work and pulse D0
+
 0.10.1
+~~~~~~
  * maintenance build to fix installation issues
  * USB_VID_LIST/USB_PID_LIST exposed directly as pylibftdi attributes
+
 0.10
- * support for FT232H via iteration over lists USB_VID_LIST/USB_PID_LIST in driver.py (FT232H uses different PID)
- * support for 'buffering' - i.e. chunking reads and writes to allow interruption (i.e. KeyboardInterrupt) in what could otherwise be a very long uninterruptable extension code call.
+~~~~
+ * support for FT232H via iteration over lists USB_VID_LIST/USB_PID_LIST in
+   driver.py (FT232H uses different PID)
+ * support for 'buffering' - i.e. chunking reads and writes to allow
+   interruption (i.e. KeyboardInterrupt) in what could otherwise be a very long
+   uninterruptable extension code call.
  * reset device to serial mode on open() (previously could be left in bitbang mode)
  * moved docs -> /doc
  * moved pylibftdi/tests -> /tests - makes python -m unittest discover etc work better
  * removed legacy support for Driver() to acting as a Device()
- * API for Bus class now requires .device rather than .driver (this still needs improving at some point)
+ * API for Bus class now requires .device rather than .driver (this still needs
+   improving at some point)
+
 0.9
+~~~
  * improved and extended tests
  * made a start on some Sphinx-based documentation
  * fixed long-standing issue with input from a BitBangDevice
    - magic_candle.py - example of using input and output together
    - pin_read.py - read and match values on device pins
  * All of this needs some tidying, but it fixes some key issues and has been unreleased too long.
+
 0.8.1
+~~~~~
  * fix issue with bitbang following API changes in 0.8
  * add tests for bitbang mode
  * refactor tests; fix text-based tests in Python3
  * slight refactor Device() to improve testability (_read and _write methods)
+
 0.8
+~~~
  * added some unit tests
  * API changes:
-   - when opening a device with a device_id parameter, this will now check
-     against both serial number and (if that fails), the device description.
-     Opening by device type (under the same proviso that an arbitrary device
-     will be selected if multiple matching devices are attached as when no
-     device_id is given) is frequently easier than matching by serial number.
-   - added flush(), flush_input() and flush_output() operations. This is
-     modelled after the pySerial API providing separate flush operations, and
-     gets the Device API closer to that of files.
-   - increased file-API compatibility, with line-oriented methods and iteration
+    * when opening a device with a device_id parameter, this will now check
+      against both serial number and (if that fails), the device description.
+      Opening by device type (under the same proviso that an arbitrary device
+      will be selected if multiple matching devices are attached as when no
+      device_id is given) is frequently easier than matching by serial number.
+    * added flush(), flush_input() and flush_output() operations. This is
+      modelled after the pySerial API providing separate flush operations, and
+      gets the Device API closer to that of files.
+    * increased file-API compatibility, with line-oriented methods and iteration
+
 0.7
+~~~
  * support multiple attached devices
  * API changes:
-   - separation between driver and device. Generally, now use Device() /
-     BitBangDevice() rather than Driver / BitBangDriver(), though older code
-     _should_ still work via some shims (though with Deprecation warnings).
-   - first parameter in Device() and BitBangDevice() is a device ID - the serial
-     number string of the target device.
-   - open() is generally no longer required on Devices. This is to more closely
-     model the file() API.
+    * separation between driver and device. Generally, now use Device() /
+      BitBangDevice() rather than Driver / BitBangDriver(), though older code
+      _should_ still work via some shims (though with Deprecation warnings).
+    * first parameter in Device() and BitBangDevice() is a device ID - the serial
+      number string of the target device.
+    * open() is generally no longer required on Devices. This is to more closely
+      model the file() API.
+
 0.6
+~~~
  * same source now works on both Python2.6+ and Python3.
+
 0.5
+~~~
  * fix various bugs found by pyflakes
  * improve module organisation, while providing interface compatibility
+
 0.4.1
+~~~~~
  * fix release issue
+
 0.4
+~~~
  * fixed embarrassing bug which caused things not to work on Linux 
    (is now find_library('ftdi') instead of find_library('libftdi'))
  * lots of error checking, new FtdiError exception. Before it just
    to change the API, and if I thought it was get_error_string
    multiple times when I wrote the error checking code, it probably
    should be the more natural thing.
+
 0.3
+~~~
  * added some examples
  * new Bus class in pylibftdi (though it probably belongs somewhere else)
  * first release on PyPI
+
 0.2
+~~~
  * fixed various bugs
  * added ftdi_fn and set_baudrate functions in Driver class
  * changed interface in BitBangDriver to direction/port properties
    rather than overriding the read/write functions, which are therefore
    still available as in the Driver class.
+
 0.1
+~~~
  * first release. Tested with libftdi 0.18 on Mac OS X 10.6 and Linux
-  (stock EEEPC 701 Xandros Linux, Ubuntu 10.04)
+   (stock EEEPC 701 Xandros Linux, Ubuntu 10.04)

pylibftdi/driver.py

         read(length) -> bytes/string of up to `length` bytes.
 
         read upto `length` bytes from the FTDI device
-        return type depends on self.mode - if 'b' return
-        raw bytes, else decode according to self.encoding
+        :param length: maximum number of bytes to read
+        :return: value read from device
+        :rtype: bytes if self.mode is 'b', else decode with self.encoding
         """
         if not self._opened:
             raise FtdiError("read() on closed Device")
     def _write(self, byte_data):
         """
         actually do the low level writing
+        :param byte_data: data to be written
+        :type byte_data: bytes
+        :return: number of bytes written
         """
         buf = create_string_buffer(byte_data)
         written = self.fdll.ftdi_write_data(byref(self.ctx),
         write(data) -> count of bytes actually written
 
         write given `data` string to the FTDI device
-        returns count of bytes written, which may be less than `len(data)`
+
+        :param data: string to be written
+        :type data: string or bytes
+        :return: count of bytes written, which may be less than `len(data)`
         """
         if not self._opened:
-            raise FtdiError("read() on closed Device")
+            raise FtdiError("write() on closed Device")
 
         try:
             byte_data = bytes(data)
         self.flush(FLUSH_OUTPUT)
 
     def get_error_string(self):
-        "return error string from libftdi driver"
+        """
+        :return: error string from libftdi driver
+        """
         return self.fdll.ftdi_get_error_string(byref(self.ctx))
 
     @property
         """
         readline() for file-like compatibility.
 
+        :param size: maximum amount of data to read looking for a line
+        :return: a line of text, or size bytes if no line-ending found
+
         This only works for mode='t' on Python3
         """
         lsl = len(os.linesep)
 #!/usr/bin/python
 
-from distutils.core import setup
+try:
+    # this is primarily to support the 'develop' target
+    # if setuptools/distribute are installed
+    from setuptools import setup
+except ImportError:
+    from distutils.core import setup
 
 setup(
     name="pylibftdi",

tests/test_driver.py

 """
 
 from tests.test_common import (LoopDevice, Device, CallCheckMixin, unittest)
+from pylibftdi import FtdiError
 
 # and now some test cases...
 
             self.assertCalls(dev.flush_output, 'ftdi_usb_purge_tx_buffer')
             self.assertCalls(dev.flush, 'ftdi_usb_purge_buffers')
 
+    def testClose(self):
+        d = Device()
+        d.close()
+        self.assertRaises(FtdiError, d.write, 'hello')
+        d = Device()
+        d.close()
+        self.assertRaises(FtdiError, d.read, 1)
+
 
 class LoopbackTest(unittest.TestCase):
     """
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.