- 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
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 @@
.. 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 @@
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 @@
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.
- .. method:: flush():
+ .. versionchanged:: 2.5
+ Accepts an instance of :class:`bytes` when available (Python 2.6
+ and newer) and :class:`str` otherwiese.
+
+ .. 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 @@
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,112 +267,6 @@
Set software flow control state.
-.. class:: RawSerial
-
- 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`.
-
- This also means that readline is borrowed from the :mod:`io` module and
- lacks the ``eol`` parameter.
-
- .. versionadded:: 2.5
-
-
-.. class:: FileLike
-
- An abstract file like class. It is used as base class for :class:`Serial`.
-
- 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.
-
- 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)!
-
- .. method:: readline(size=None, eol='\n')
-
- :param size: Max number of bytes to read, ``None`` -> no limit.
- :param eol: The end of line character.
-
- Read a line which is terminated with end-of-line (eol) character
- ('\n' by default) or until timeout.
-
- .. 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 ``readlines`` - here for compatibility.
-
- .. method:: writelines(sequence)
-
- Write a list of strings to the port.
-
-
- The following three methods are overridden in :class:`Serial`.
-
- .. method:: flush()
-
- Flush of file like objects. It's a no-op in this class, may be overridden.
-
- .. method:: read()
-
- Raises NotImplementedError, needs to be overridden by subclass.
-
- .. method:: write(data)
-
- Raises NotImplementedError, needs to be overridden by subclass.
-
- The following functions are implemented for compatibility with other
- file-like objects, however serial ports are not seekable.
-
-
- .. method:: seek(pos, whence=0)
-
- :exception IOError: always, as method is not supported on serial port
-
- .. versionadded:: 2.5
-
- .. method:: tell()
-
- :exception IOError: always, as method is not supported on serial port
-
- .. versionadded:: 2.5
-
- .. method:: truncate(self, n=None):
-
- :exception IOError: always, as method is not supported on serial port
-
- .. versionadded:: 2.5
-
- .. method:: isatty()
-
- :exception IOError: always, as method is not supported on serial port
-
- .. versionadded:: 2.5
-
- To be able to use the file like object as iterator for e.g.
- ``for line in Serial(0): ...`` usage:
-
- .. method:: next()
-
- Return the next line by calling :meth:`readline`.
-
- .. method:: __iter__()
-
- Returns self.
-
-
.. class:: SerialBase
The following attributes are implemented as properties. They work with open
@@ -423,6 +336,130 @@
A tuple of supported stop bit settings.
+ .. method:: readline(size=None, eol='\\n')
+
+ :param size: Max number of bytes to read, ``None`` -> no limit.
+ :param eol: The end of line character.
+
+ Read a line which is terminated with end-of-line (*eol*) character
+ (``\\n`` by default) or until timeout.
+
+ .. 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:: writable()
+
+ :return: True
+ .. versionadded:: 2.5
+
+ .. method:: seekable()
+
+ :return: False
+ .. versionadded:: 2.5
+
+ .. method:: readinto(b)
+
+ :param b: bytearray or array instace
+ :return: Number of byte read
+
+ Read up to len(b) bytes into bytearray b and return the number of bytes read.
+
+ .. versionadded:: 2.5
+
+
+.. 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:: FileLike
+
+ An abstract file like class. It is used as base class for :class:`Serial`.
+
+ 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.
+
+ 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)!
+
+ .. method:: writelines(sequence)
+
+ Write a list of strings to the port.
+
+
+ The following three methods are overridden in :class:`Serial`.
+
+ .. method:: flush()
+
+ Flush of file like objects. It's a no-op in this class, may be overridden.
+
+ .. method:: read()
+
+ Raises NotImplementedError, needs to be overridden by subclass.
+
+ .. method:: write(data)
+
+ Raises NotImplementedError, needs to be overridden by subclass.
+
+ The following functions are implemented for compatibility with other
+ file-like objects, however serial ports are not seekable.
+
+
+ .. method:: seek(pos, whence=0)
+
+ :exception IOError: always, as method is not supported on serial port
+
+ .. versionadded:: 2.5
+
+ .. method:: tell()
+
+ :exception IOError: always, as method is not supported on serial port
+
+ .. versionadded:: 2.5
+
+ .. method:: truncate(self, n=None)
+
+ :exception IOError: always, as method is not supported on serial port
+
+ .. versionadded:: 2.5
+
+ .. method:: isatty()
+
+ :exception IOError: always, as method is not supported on serial port
+
+ .. versionadded:: 2.5
+
+ To be able to use the file like object as iterator for e.g.
+ ``for line in Serial(0): ...`` usage:
+
+ .. method:: next()
+
+ Return the next line by calling :meth:`readline`.
+
+ .. method:: __iter__()
+
+ Returns self.
+
Exceptions
@@ -432,6 +469,9 @@
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 @@
.. 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 @@
Others
-------
-Default control characters for software flow control.
+Default control characters for software flow control:
.. data:: XON
.. data:: XOFF
-Version
+Module version:
.. data:: VERSION