- read/write now work with bytes when available on older Pythons that is equal to a str (implemented compatibility objects in serualutil)

- improve conversion result of 2to3
- remove RawSerial object again
- update docs

1 files changed, 158 insertions, 118 deletions

diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index f5fa01a..6b913a5 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -12,19 +12,25 @@ Classes
     .. method:: __init__(port=None, baudrate=9600, bytesize=EIGHTBITS, parity=PARITY_NONE, stopbits=STOPBITS_ONE, timeout=None, xonxoff=0, rtscts=0, interCharTimeout=None)
 
         :param port:
-            Device name or port number number or None.
+            Device name or port number number or :const:`None`.
 
         :param baudrate:
             Baud rate such as 9600 or 115200 etc.
 
         :param bytesize:
-            Number of data bits. Possible values: FIVEBITS, SIXBITS, SEVENBITS, EIGHTBITS
+            Number of data bits. Possible values:
+            :const:`FIVEBITS`, :const:`SIXBITS`, :const:`SEVENBITS`,
+            :const:`EIGHTBITS`
 
         :param parity:
-            Enable parity checking. Possible values: PARITY_NONE PARITY_EVEN PARITY_ODD PARITY_MARK PARITY_SPACE
+            Enable parity checking. Possible values:
+            :const:`PARITY_NONE` :const:`PARITY_EVEN` :const:`PARITY_ODD`
+            :const:`PARITY_MARK` :const:`PARITY_SPACE`
 
         :param stopbits:
-            Number of stop bits. Possible values: STOPBITS_ONE STOPBITS_ONE_POINT_FIVE STOPBITS_TWO
+            Number of stop bits. Possible values:
+            :const:`STOPBITS_ONE` :const:`STOPBITS_ONE_POINT_FIVE`
+            :const:`STOPBITS_TWO`
 
         :param timeout:
             Set a read timeout value.
@@ -36,23 +42,26 @@ Classes
             Enable hardware (RTS/CTS) flow control.
 
         :param interCharTimeout:
-            Inter-character timeout, None to disable.
+            Inter-character timeout, :const:`None` to disable (default).
 
         :exception ValueError:
-            Will be raised when parameter are out of range, e.g. baudrate, data bits.
+            Will be raised when parameter are out of range, e.g. baud rate, data bits.
 
         :exception SerialException:
             In case the device can not be found or can not be configured.
 
 
-        The port is immediately opened on object creation, when a ``port`` is
-        given. It is not opened when port is None.
+        The port is immediately opened on object creation, when a *port* is
+        given. It is not opened when *port* is :const:`None` and a successive call
+        to :meth:`open` will be needed.
+
+        Possible values for the parameter *port*:
 
         - Number: number of device, numbering starts at zero.
         - Device name: depending on operating system. e.g. ``/dev/ttyUSB0``
           on GNU/Linux or ``COM3`` on Windows.
 
-        Possible values for the parameter ``timeout``:
+        Possible values for the parameter *timeout*:
 
         - ``timeout = None``:  wait forever
         - ``timeout = 0``:     non-blocking mode (return immediately on read)
@@ -68,32 +77,41 @@ Classes
         Close port immediately.
 
 
-    The following methods may rise :exc:`ValueError` when applied to a closed port.
-
-    .. method:: inWaiting()
-
-        Return the number of chars in the receive buffer.
+    The following methods may raise :exc:`ValueError` when applied to a closed
+    port.
 
     .. method:: read(size=1)
 
         :param size: Number of bytes to read.
         :return: Bytes read from the port.
 
-        Read ``size`` bytes from the serial port. If a timeout is set it may
+        Read *size* bytes from the serial port. If a timeout is set it may
         return less characters as requested. With no timeout it will block
         until the requested number of bytes is read.
 
+        .. versionchanged:: 2.5
+            Returns an instance of :class:`bytes` when available (Python 2.6
+            and newer) and :class:`str` otherwiese.
+
     .. method:: write(data)
 
         :param data: Data to send.
-
+        :return: Number of bytes written.
         :exception SerialTimeoutException:
             In case a write timeout is configured for the port and the time is
             exceeded.
 
-        Write the string ``data`` to the port.
+        Write the string *data* to the port.
+
+        .. versionchanged:: 2.5
+            Accepts an instance of :class:`bytes` when available (Python 2.6
+            and newer) and :class:`str` otherwiese.
 
-    .. method:: flush():
+    .. method:: inWaiting()
+
+        Return the number of chars in the receive buffer.
+
+    .. method:: flush()
 
         Flush of file like objects. In this case, wait until all data is
         written.
@@ -188,7 +206,8 @@ Classes
         A list of valid stop bit widths for the device (Read Only).
 
 
-    New values can be assigned to the following attributes, the port will be reconfigured, even if it's opened at that time:
+    New values can be assigned to the following attributes, the port will be
+    reconfigured, even if it's opened at that time:
 
     .. attribute:: port
 
@@ -248,180 +267,198 @@ Classes
         Set software flow control state.
 
 
-.. class:: RawSerial
+.. class:: SerialBase
 
-    This class is only present when run with Python 2.6 and newer that prides
-    the module :mod:`io`. It shares the same interface with :class:`Serial`
-    with the difference that :meth:`read` and :meth:`write` work with
-    :class:`bytes`and :class:`bytearrays`.
+    The following attributes are implemented as properties. They work with open
+    and closed ports.
 
-    This also means that readline is borrowed from the :mod:`io` module and
-    lacks the ``eol`` parameter.
+    .. attribute:: port
 
-    .. versionadded:: 2.5
+        Read or write port. When the port is already open, it will be closed
+        and reopened with the new setting.
 
+    .. attribute:: baudrate
 
-.. class:: FileLike
+        Read or write current baud rate setting.
 
-    An abstract file like class. It is used as base class for :class:`Serial`.
+    .. attribute:: bytesize
 
-    This class implements readline and readlines based on read and
-    writelines based on write.
-    This class is used to provide the above functions for to Serial
-    port objects.
+        Read or write current data byte size setting.
 
-    Note that when the serial port was opened with no timeout that
-    readline blocks until it sees a newline (or the specified size is
-    reached) and that readlines would never return and therefore
-    refuses to work (it raises an exception in this case)!
+    .. attribute:: parity
 
-    .. method:: readline(size=None, eol='\n')
+        Read or write current parity setting.
 
-        :param size: Max number of  bytes to read, ``None`` -> no limit.
-        :param eol: The end of line character.
+    .. attribute:: stopbits
 
-        Read a line which is terminated with end-of-line (eol) character
-        ('\n' by default) or until timeout.
+        Read or write current stop bit width setting.
 
-    .. method:: readlines(sizehint=None, eol='\n')
+    .. attribute:: timeout
 
-        :param size: Ignored parameter.
-        :param eol: The end of line character.
+        Read or write current read timeout setting.
 
-        Read a list of lines, until timeout. ``sizehint`` is ignored and only
-        present for API compatibility with built-in File objects.
+    .. attribute:: writeTimeout
 
-    .. method:: xreadlines(sizehint=None)
+        Read or write current write timeout setting.
 
-        Just calls ``readlines`` - here for compatibility.
+    .. attribute:: xonxoff
 
-    .. method:: writelines(sequence)
+        Read or write current software flow control rate setting.
 
-        Write a list of strings to the port.
+    .. attribute:: rtscts
 
+        Read or write current hardware flow control setting.
 
-    The following three methods are overridden in :class:`Serial`.
+    .. attribute:: dsrdtr
 
-    .. method:: flush()
+        Read or write current hardware flow control setting.
 
-        Flush of file like objects. It's a no-op in this class, may be overridden.
+    .. attribute:: interCharTimeout
 
-    .. method:: read()
+        Read or write current inter character timeout setting.
 
-        Raises NotImplementedError, needs to be overridden by subclass.
+    The following constants are also provided:
 
-    .. method:: write(data)
+    .. attribute:: BAUDRATES
 
-        Raises NotImplementedError, needs to be overridden by subclass.
+        A tuple of standard baud rate values. The actual device may support more
+        or less...
 
-    The following functions are implemented for compatibility with other
-    file-like objects, however serial ports are not seekable.
+    .. attribute:: BYTESIZES
 
+        A tuple of supported byte size values.
 
-    .. method:: seek(pos, whence=0)
+    .. attribute:: PARITIES
 
-        :exception IOError: always, as method is not supported on serial port
+        A tuple of supported parity settings.
 
-        .. versionadded:: 2.5
+    .. attribute:: STOPBITS
 
-    .. method:: tell()
+        A tuple of supported stop bit settings.
 
-        :exception IOError: always, as method is not supported on serial port
+    .. method:: readline(size=None, eol='\\n')
 
-        .. versionadded:: 2.5
+        :param size: Max number of bytes to read, ``None`` -> no limit.
+        :param eol: The end of line character.
 
-    .. method:: truncate(self, n=None):
+        Read a line which is terminated with end-of-line (*eol*) character
+        (``\\n`` by default) or until timeout.
 
-        :exception IOError: always, as method is not supported on serial port
+    .. method:: readlines(sizehint=None, eol='\\n')
+
+        :param size: Ignored parameter.
+        :param eol: The end of line character.
+
+        Read a list of lines, until timeout. *sizehint* is ignored and only
+        present for API compatibility with built-in File objects.
+
+    .. method:: xreadlines(sizehint=None)
 
+        Just calls :meth:`readlines` - here for compatibility.
+
+    For compatibility with the :mod:`io` library are the following methods.
+
+    .. method:: readable()
+
+        :return: True
         .. versionadded:: 2.5
 
-    .. method:: isatty()
+    .. method:: writable()
 
-        :exception IOError: always, as method is not supported on serial port
+        :return: True
+        .. versionadded:: 2.5
 
+    .. method:: seekable()
+
+        :return: False
         .. versionadded:: 2.5
 
-    To be able to use the file like object as iterator for e.g. 
-    ``for line in Serial(0): ...`` usage:
+    .. method:: readinto(b)
 
-    .. method:: next()
+        :param b: bytearray or array instace
+        :return: Number of byte read
 
-        Return the next line by calling :meth:`readline`.
+        Read up to len(b) bytes into bytearray b and return the number of bytes read.
 
-    .. method:: __iter__()
+        .. versionadded:: 2.5
 
-        Returns self.
+ 
+.. note::
 
+    For systems that provide the :mod:`io` library (Python 2.6 and newer), the
+    class :class:`Serial` will derrive from :class:`io.RawIOBase`. For all
+    others from :class:`FileLike`.
 
-.. class:: SerialBase
+.. class:: FileLike
 
-    The following attributes are implemented as properties. They work with open
-    and closed ports.
+    An abstract file like class. It is used as base class for :class:`Serial`.
 
-    .. attribute:: port
+    This class implements :meth:`readline` and :meth:`readlines` based on read
+    and :meth:`writelines` based on write.  This class is used to provide the
+    above functions for to Serial port objects.
 
-        Read or write port. When the port is already open, it will be closed
-        and reopened with the new setting.
+    Note that when the serial port was opened with no timeout that
+    :meth:`readline` blocks until it sees a newline (or the specified size is
+    reached) and that :meth:`readlines` would never return and therefore
+    refuses to work (it raises an exception in this case)!
 
-    .. attribute:: baudrate
+    .. method:: writelines(sequence)
 
-        Read or write current baud rate setting.
+        Write a list of strings to the port.
 
-    .. attribute:: bytesize
 
-        Read or write current data byte size setting.
+    The following three methods are overridden in :class:`Serial`.
 
-    .. attribute:: parity
+    .. method:: flush()
 
-        Read or write current parity setting.
+        Flush of file like objects. It's a no-op in this class, may be overridden.
 
-    .. attribute:: stopbits
+    .. method:: read()
 
-        Read or write current stop bit width setting.
+        Raises NotImplementedError, needs to be overridden by subclass.
 
-    .. attribute:: timeout
+    .. method:: write(data)
 
-        Read or write current read timeout setting.
+        Raises NotImplementedError, needs to be overridden by subclass.
 
-    .. attribute:: writeTimeout
+    The following functions are implemented for compatibility with other
+    file-like objects, however serial ports are not seekable.
 
-        Read or write current write timeout setting.
 
-    .. attribute:: xonxoff
+    .. method:: seek(pos, whence=0)
 
-        Read or write current software flow control rate setting.
+        :exception IOError: always, as method is not supported on serial port
 
-    .. attribute:: rtscts
+        .. versionadded:: 2.5
 
-        Read or write current hardware flow control setting.
+    .. method:: tell()
 
-    .. attribute:: dsrdtr
+        :exception IOError: always, as method is not supported on serial port
 
-        Read or write current hardware flow control setting.
+        .. versionadded:: 2.5
 
-    .. attribute:: interCharTimeout
+    .. method:: truncate(self, n=None)
 
-        Read or write current inter character timeout setting.
+        :exception IOError: always, as method is not supported on serial port
 
-    The following constants are also provided:
+        .. versionadded:: 2.5
 
-    .. attribute:: BAUDRATES
+    .. method:: isatty()
 
-        A tuple of standard baud rate values. The actual device may support more
-        or less...
+        :exception IOError: always, as method is not supported on serial port
 
-    .. attribute:: BYTESIZES
+        .. versionadded:: 2.5
 
-        A tuple of supported byte size values.
+    To be able to use the file like object as iterator for e.g. 
+    ``for line in Serial(0): ...`` usage:
 
-    .. attribute:: PARITIES
+    .. method:: next()
 
-        A tuple of supported parity settings.
+        Return the next line by calling :meth:`readline`.
 
-    .. attribute:: STOPBITS
+    .. method:: __iter__()
 
-        A tuple of supported stop bit settings.
+        Returns self.
 
 
 
@@ -432,6 +469,9 @@ Exceptions
 
     Base class for serial port exceptions.
 
+    .. versionchanged:: 2.5
+        Now derrives from :exc:`IOError` instead of :exc:`Exception`
+
 .. exception:: SerialTimeoutException
 
     Exception that is raised on write timeouts.
@@ -448,14 +488,14 @@ Parity
 .. data:: PARITY_MARK
 .. data:: PARITY_SPACE
 
-Stopbits
---------
+Stop bits
+---------
 .. data:: STOPBITS_ONE
 .. data:: STOPBITS_ONE_POINT_FIVE
 .. data:: STOPBITS_TWO
 
-Bytesize
---------
+Byte size
+---------
 .. data:: FIVEBITS
 .. data:: SIXBITS
 .. data:: SEVENBITS
@@ -463,12 +503,12 @@ Bytesize
 
 Others
 -------
-Default control characters for software flow control.
+Default control characters for software flow control:
 
 .. data:: XON
 .. data:: XOFF
 
-Version
+Module version:
 
 .. data:: VERSION