Merge branch 'master' into ymodem

Author: tesch1

.drone.yml

@@ -0,0 +1,7 @@
+pipeline:
+  build:
+    image: maze/drone-python
+    commands:
+      - apt-get -qq install lrzsz
+      - pip install -r requirements-testing.txt
+      - tox

README.rst

@@ -18,12 +18,14 @@ Usage
 Create a function to get and put character data (to a serial line for
 example)::
 
+    >>> import serial
     >>> from xmodem import XMODEM
+    >>> ser = serial.Serial('/dev/ttyUSB0', timeout=0) # or whatever port you need
     >>> def getc(size, timeout=1):
-    ...     return data or None
+    ...     return ser.read(size) or None
     ...
     >>> def putc(data, timeout=1):
-    ...     return size or None
+    ...     return ser.write(data)  # note that this ignores the timeout
     ...
     >>> modem = XMODEM(getc, putc)
 
@@ -49,8 +51,12 @@ For more information, take a look at the documentation_.
 Changes
 =======
 
-0.4.5:
+0.4.6:
   * enhancement: added YMODEM ``send()`` capability.
+0.4.5:
+  * bugfix: Remove bogus `assert False` code in ``recv()`` that resulted in
+    `AssertionError` introduced in version 0.4.0 commit-id `9b03fc20`, `PR #29
+    <https://github.com/tehmaze/xmodem/pull/29>`_.
 0.4.4:
   * bugfix: Large file transfers in ``send()`` were more likely to fail for
     small values of ``retry``: This value should be the maximum failures per

setup.py

@@ -7,7 +7,7 @@
 
 setup(
     name='xmodem',
-    version='0.4.5',
+    version='0.4.6',
     author='Wijnand Modderman, Jeff Quast, Kris Hardy, Michael Tesch',
     author_email='[email protected]',
     description=('XMODEM/YMODEM protocol implementation.'),

xmodem/__init__.py

@@ -135,21 +135,32 @@
 
 class XMODEM(object):
     '''
-    XMODEM Protocol handler, expects an object to read from and an object to
-    write to.
+    XMODEM Protocol handler, expects two callables which encapsulate the read
+        and write operations on the underlying stream.
 
+    Example functions for reading and writing to a serial line:
+
+    >>> import serial
+    >>> from xmodem import XMODEM
+    >>> ser = serial.Serial('/dev/ttyUSB0', timeout=0) # or whatever you need
     >>> def getc(size, timeout=1):
-    ...     return data or None
+    ...     return ser.read(size) or None
     ...
     >>> def putc(data, timeout=1):
-    ...     return size or None
+    ...     return ser.write(data) or None
     ...
     >>> modem = XMODEM(getc, putc)
 
 
-    :param getc: Function to retrieve bytes from a stream
+    :param getc: Function to retrieve bytes from a stream. The function takes
+        the number of bytes to read from the stream and a timeout in seconds as
+        parameters. It must return the bytes which were read, or ``None`` if a
+        timeout occured.
     :type getc: callable
-    :param putc: Function to transmit bytes to a stream
+    :param putc: Function to transmit bytes to a stream. The function takes the
+        bytes to be written and a timeout in seconds as parameters. It must
+        return the number of bytes written to the stream, or ``None`` in case of
+        a timeout.
     :type putc: callable
     :param mode: XMODEM protocol mode
     :type mode: string
@@ -204,6 +215,11 @@ def __init__(self, getc, putc, mode='xmodem', pad=b'\x1a'):
     def abort(self, count=2, timeout=60):
         '''
         Send an abort sequence using CAN bytes.
+
+        :param count: how many abort characters to send
+        :type count: int
+        :param timeout: timeout in seconds
+        :type timeout: int
         '''
         for _ in range(count):
             self.putc(CAN, timeout)
@@ -430,6 +446,22 @@ def recv(self, stream, crc_mode=1, retry=16, timeout=60, delay=1, quiet=0):
 
         Returns the number of bytes received on success or ``None`` in case of
         failure.
+
+        :param stream: The stream object to write data to.
+        :type stream: stream (file, etc.)
+        :param crc_mode: XMODEM CRC mode
+        :type crc_mode: int
+        :param retry: The maximum number of times to try to resend a failed
+                      packet before failing.
+        :type retry: int
+        :param timeout: The number of seconds to wait for a response before
+                        timing out.
+        :type timeout: int
+        :param delay: The number of seconds to wait between resend attempts
+        :type delay: int
+        :param quiet: If ``True``, write transfer information to stderr.
+        :type quiet: bool
+
         '''
 
         # initiate protocol
@@ -581,7 +613,6 @@ def recv(self, stream, crc_mode=1, retry=16, timeout=60, delay=1, quiet=0):
                 data = self.getc(1, timeout=1)
                 if data is None:
                     break
-                assert False, data
             self.putc(NAK)
             # get next start-of-header byte
             char = self.getc(1, timeout)