- add more methods for file-like compatibility
- provide RawSerial when io library is present (not yet finished)
-> changes internal class hierarchy
-> renamed internal read/write -> _read/_write (FileLike resp. RawSerialBase provides read/write)
-> add test_rawio.py
- _write returns number of byte written
- set minimal python version to 2.3 due to basestring
- add "name" attribute
- documentation updates (new io stuff and VERSION, device())
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index f5d5791..f5fa01a 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -56,7 +56,7 @@
- ``timeout = None``: wait forever
- ``timeout = 0``: non-blocking mode (return immediately on read)
- - ``timeout = x``: set timeout to x seconds (float allowed)
+ - ``timeout = x``: set timeout to ``x`` seconds (float allowed)
.. method:: open()
@@ -67,9 +67,8 @@
Close port immediately.
- .. method:: setBaudrate(baudrate)
- Change baud rate on an open port.
+ The following methods may rise :exc:`ValueError` when applied to a closed port.
.. method:: inWaiting()
@@ -159,11 +158,17 @@
Read-only attributes:
- .. attribute:: portstr
+ .. attribute:: name
Device name. This is always the device name even if the
port was opened by a number. (Read Only).
+ .. versionadded:: 2.5
+
+ .. attribute:: portstr
+
+ :deprecated: use :attr:`name` instead
+
.. attribute:: BAUDRATES
A list of valid baud rates. The list may be incomplete such that higher
@@ -243,6 +248,19 @@
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`.
@@ -296,6 +314,33 @@
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:
@@ -422,3 +467,24 @@
.. data:: XON
.. data:: XOFF
+
+Version
+
+.. data:: VERSION
+
+ A string indicating the pySerial version, such as ``2.5``.
+
+Functions:
+
+.. function:: device(number)
+
+ :param number: Port number.
+ :return: String containing device name.
+ :deprecated: Use device names directly.
+
+ Convert a port number to a platform dependent device name. Unfortunately
+ this does not work well for all platforms; e.g. some may miss USB-Serial
+ converters and enumerate only internal serial ports.
+
+ The conversion may be made off-line, that is, there is no guarantee that
+ the returned device name really exists on the system.