added non-blocking mode

fixed win32 version: no data is lost when a timeout occours
typos in the docs

7 files changed, 91 insertions, 47 deletions

diff --git a/pyserial/CHANGES.txt b/pyserial/CHANGES.txt
index f16ba57..9826c62 100644
--- a/pyserial/CHANGES.txt
+++ b/pyserial/CHANGES.txt
@@ -25,3 +25,9 @@ Version 1.12    18 Feb 2002
 Version 1.13    09 Apr 2002
     Added alternate way for enabling rtscts (CNEW_RTSCTS is tried too)
     If port opening fails, a SerialException is raised on all platforms
+
+Version 1.xx
+    added examples to archive
+    added non-blocking mode for timeout=0 (tnx Mat Martineau)
+    win32 does now return the remaining characters on timeout
+    
\ No newline at end of file
diff --git a/pyserial/MANIFEST b/pyserial/MANIFEST
index f139e1e..32217d2 100644
--- a/pyserial/MANIFEST
+++ b/pyserial/MANIFEST
@@ -7,3 +7,5 @@ serial\serialjava.py
 serial\serialposix.py
 serial\serialwin32.py
 serial\serialutil.py
+examples\miniterm.py
+examples\tcp_serial_redirect.py
diff --git a/pyserial/README.txt b/pyserial/README.txt
index 1717024..d3022a9 100644
--- a/pyserial/README.txt
+++ b/pyserial/README.txt
@@ -1,9 +1,9 @@
 pySerial
 --------
 This module capsulates the access for the serial port. It provides backends
-for stadard Python running on Windows, Linux, BSD (possibly any POSIX
+for standard Python running on Windows, Linux, BSD (possibly any POSIX
 compilant system) and Jython. The module named "serial" automaticaly selects
-the appropriate backed.
+the appropriate backend.
 
 It is released under a free software license, see LICENSE.txt for more
 details.
@@ -15,12 +15,12 @@ Project Homepage: pyserial.sourceforge.net
 Features
 --------
 - same class based interface on all supported platforms
-- port numbering starts at zero, no need to know the port name in the user
-  program
-- port string can be specified if access through numbering is inappropriate
-- support for diffrent bytesizes, stopbits, parity and flow control
+- port numbering starts at zero, no need to know the platform dependant port
+  name in the user program
+- port name can be specified if access through numbering is inappropriate
+- support for different bytesizes, stopbits, parity and flow control
   with RTS/CTS and/or xon/xoff
-- working with or without receive timeout
+- working with or without receive timeout, blocking or non-blocking
 - file like API with "read" and "write" ("readline" etc. also supported)
 - The files in this package are 100% pure Python.
   They depend on non standard but common packages on Windows (win32all) and
@@ -56,14 +56,20 @@ Open port 0 at 9600,8,N,1, no timeout
 >>> ser.write("hello")      #write a string
 >>> ser.close()             #close port
 
-Open port at 19200,8,N,1, 1s timeout
+Open named port at 19200,8,N,1, 1s timeout
 >>> ser = serial.Serial('/dev/ttyS1', 19200, timeout=1)
 >>> x = ser.read()          #read one byte
 >>> s = ser.read(10)        #read up to ten bytes (timeout)
 >>> line = ser.readline()   #read a \n terminated line
 >>> ser.close()
 
-Be carfully when using "readline" do specify a timeout when
+Open second port at 38400,8,E,1, non blocking HW handshaking
+>>> ser = serial.Serial(1, 38400, timeout=0,
+...                     parity=serial.PARITY_EVEN, rtscts=1)
+>>> s = ser.read(100)       #read up to one hunded bytes
+...                         #or as much is in the buffer
+
+Be carefully when using "readline". Do specify a timeout when
 opening the serial port otherwise it could block forever if
 no newline character is received. Also note that "readlines" only
 works with a timeout. "readlines" depends on having a timeout
@@ -87,6 +93,28 @@ ser = serial.Serial(
     rtscts=0,               #enable RTS/CTS flow control
 )
 
+The port is immediatley opened on object creation. Options:
+timeout=None            # wait forever
+timeout=0               #non-blocking mode (return immediately on read)
+timeout=x               #set timeout to x seconds (float allowed)
+
+Serial object Methods
+---------------------
+close()                 #close port immediately
+setBaudrate(baudrate)   #change baudarte on an open port
+inWaiting()             #return the number of chars in the receive buffer
+read(size=1)            #read "size" characters
+write(s)                #write the string to the port
+flushInput()            #flush input buffer
+flushOutput()           #flush output buffer
+sendBreak()             #send break condition
+setRTS(level=1)         #set RTS line to specified logic level
+setDTR(level=1)         #set DTR line to specified logic level
+getCTS()                #return the state of the CTS line
+getDSR()                #return the state of the DSR line
+getRI()                 #return the state of the RI line
+getCD()                 #return the state of the CD line
+
 Constants
 ---------
 parity:
diff --git a/pyserial/serial/serialjava.py b/pyserial/serial/serialjava.py
index 9863de3..a0d48a6 100644
--- a/pyserial/serial/serialjava.py
+++ b/pyserial/serial/serialjava.py
@@ -8,7 +8,7 @@
 import sys, os, string, javax.comm
 import serialutil
 
-VERSION = string.split("$Revision: 1.5 $")[1]     #extract CVS version
+VERSION = string.split("$Revision: 1.6 $")[1]     #extract CVS version
 
 PARITY_NONE, PARITY_EVEN, PARITY_ODD, PARITY_MARK, PARITY_SPACE = (0,1,2,3,4)
 STOPBITS_ONE, STOPBITS_TWO, STOPBITS_ONE_HALVE = (1, 2, 3)
@@ -99,7 +99,7 @@ class Serial(serialutil.FileLike):
         self.sPort.setFlowControlMode(jflowin | jflowout)
         
         self.timeout = timeout
-        if timeout:
+        if timeout >= 0:
             self.sPort.enableReceiveTimeout(timeout*1000)
         else:
             self.sPort.disableReceiveTimeout()
@@ -127,15 +127,16 @@ class Serial(serialutil.FileLike):
 
     def read(self, size=1):
         if not self.sPort: raise portNotOpenError
-        res = ''
-        while len(res) < size:
-            x = self.instream.read()
-            if x == -1:
-                if self.timeout:
-                    break
-            else:
-                res = res + chr(x)
-        return res
+        read = ''
+        if size > 0:
+            while len(read) < size:
+                x = self.instream.read()
+                if x == -1:
+                    if self.timeout >= 0:
+                        break
+                else:
+                    read = read + chr(x)
+        return read
 
     def flushInput(self):
         if not self.sPort: raise portNotOpenError
diff --git a/pyserial/serial/serialposix.py b/pyserial/serial/serialposix.py
index cafc2f7..522221b 100644
--- a/pyserial/serial/serialposix.py
+++ b/pyserial/serial/serialposix.py
@@ -12,7 +12,7 @@
 import sys, os, fcntl, termios, struct, string, select
 import serialutil
 
-VERSION = string.split("$Revision: 1.9 $")[1]     #extract CVS version
+VERSION = string.split("$Revision: 1.10 $")[1]     #extract CVS version
 
 PARITY_NONE, PARITY_EVEN, PARITY_ODD = range(3)
 STOPBITS_ONE, STOPBITS_TWO = (1, 2)
@@ -302,16 +302,14 @@ class Serial(serialutil.FileLike):
         inp = None
         if size > 0:
             while len(read) < size:
-                if self.timeout:
-                    #print "\tread(): size",size, "have", len(read)    #debug
-                    ready,_,_ = select.select([self.fd],[],[], self.timeout)
-                    if not ready:
-                        break   #timeout
-                    inp = os.read(self.fd, size-len(read))
-                else:
-                    inp = os.read(self.fd, size-len(read))
-                if not inp and self.timeout: break  #early abort on timeout
-                read = read + inp
+                #print "\tread(): size",size, "have", len(read)    #debug
+                ready,_,_ = select.select([self.fd],[],[], self.timeout)
+                if not ready:
+                    break   #timeout
+                buf = os.read(self.fd, size-len(read))
+                read = read + buf
+                if self.timeout >= 0 and not buf:
+                    break  #early abort on timeout
         return read
 
     def flushInput(self):
diff --git a/pyserial/serial/serialutil.py b/pyserial/serial/serialutil.py
index 057cd74..a0c6f97 100644
--- a/pyserial/serial/serialutil.py
+++ b/pyserial/serial/serialutil.py
@@ -20,7 +20,7 @@ class FileLike:
     def write(self, s): raise NotImplementedError
 
     def readline(self, size=None):
-        """read a line which is terminated with '\\n' or until timeout"""
+        """read a line which is terminated with '\n' or until timeout"""
         line = ''
         while 1:
             c = self.read(1)
@@ -35,7 +35,7 @@ class FileLike:
         return line
 
     def readlines(self, sizehint=None):
-        """read alist of lines, until timeout
+        """read a list of lines, until timeout
         sizehint is ignored"""
         if self.timeout is None:
             raise ValueError, "Serial port MUST have enabled timeout for this function!"
@@ -44,14 +44,14 @@ class FileLike:
             line = self.readline()
             if line:
                 lines.append(line)
-                if line[-1] != '\n':
+                if line[-1] != '\n':    #was the line received with a timeout?
                     break
             else:
                 break
         return lines
 
     def xreadlines(self, sizehint=None):
-        """just call readlines - just here for compatibility"""
+        """just call readlines - here for compatibility"""
         return self.readlines()
 
     def writelines(self, sequence):
@@ -63,6 +63,6 @@ class FileLike:
         method is not available"""
         try:
             self.flushOutput()
-        except NameError:
+        except AttributeError:
             pass
 
diff --git a/pyserial/serial/serialwin32.py b/pyserial/serial/serialwin32.py
index 4a11980..19b6d37 100644
--- a/pyserial/serial/serialwin32.py
+++ b/pyserial/serial/serialwin32.py
@@ -11,7 +11,7 @@ import win32con   # constants.
 import sys, string
 import serialutil
 
-VERSION = string.split("$Revision: 1.6 $")[1]     #extract CVS version
+VERSION = string.split("$Revision: 1.7 $")[1]     #extract CVS version
 
 PARITY_NONE, PARITY_EVEN, PARITY_ODD = range(3)
 STOPBITS_ONE, STOPBITS_TWO = (1, 2)
@@ -65,12 +65,12 @@ class Serial(serialutil.FileLike):
         #(ReadIntervalTimeout,ReadTotalTimeoutMultiplier,
         # ReadTotalTimeoutConstant,WriteTotalTimeoutMultiplier,
         # WriteTotalTimeoutConstant)
-        if timeout:
-            timeouts = (timeout*1000, 0, timeout*1000, 0, 0)
+        if timeout is None:
+             timeouts = (0, 0, 0, 0, 0)
+        elif timeout == 0:
+            timeouts = (win32con.MAXDWORD, 0, 0, 0, 1000)
         else:
-            #timeouts = (win32con.MAXDWORD, 1, 0, 1, 0)
-            #timeouts = (win32con.MAXDWORD, 0, 0, 0, 1000)
-            timeouts = (0, 0, 0, 0, 0)
+            timeouts = (timeout*1000, 0, timeout*1000, 0, 0)
         win32file.SetCommTimeouts(self.hComPort, timeouts)
 
         #win32file.SetCommMask(self.hComPort, win32file.EV_RXCHAR | win32file.EV_TXEMPTY |
@@ -183,15 +183,24 @@ class Serial(serialutil.FileLike):
             while len(read) < size:
                 flags, comstat = win32file.ClearCommError( self.hComPort )
                 rc, buf = win32file.ReadFile(self.hComPort, size-len(read), self.overlapped)
-                if self.timeout:
+                print "x",  rc
+                if self.timeout > 0:
                     rc = win32event.WaitForSingleObject(self.overlapped.hEvent, self.timeout*1000)
-                    if rc == win32event.WAIT_TIMEOUT: break
-                    #TODO: if reading more than 1 byte data can be lost when a timeout occours!!!!
+                    n = win32file.GetOverlappedResult(self.hComPort, self.overlapped, 0)
+                    if rc == win32event.WAIT_TIMEOUT:
+                        print "n", n
+                        if n:
+                            togo = size-len(read)
+                            print n<togo and n or togo
+                            read = read + str(buf[:n])
+                        break
                 else:
                     win32event.WaitForSingleObject(self.overlapped.hEvent, win32event.INFINITE)
-                read = read + str(buf)
+                    n = win32file.GetOverlappedResult(self.hComPort, self.overlapped, 0)
+                read = read + str(buf[0:n])
+                if self.timeout == 0: break
         #print "read %r" % str(read)
-        return str(read)
+        return read
 
     def write(self, s):
         "write string to serial port"