- [x]readline[s] docs moved to FileLike
- mention to_bytes
- minor updates
diff --git a/pyserial/documentation/pyserial_api.rst b/pyserial/documentation/pyserial_api.rst
index f5b0926..2aefb5c 100644
--- a/pyserial/documentation/pyserial_api.rst
+++ b/pyserial/documentation/pyserial_api.rst
@@ -360,25 +360,6 @@
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.
@@ -512,6 +493,38 @@
Returns self.
+ .. 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.
+
+ Note that this function only returns on a timeout.
+
+ .. method:: xreadlines(sizehint=None)
+
+ Read lines, implemented as generator. Unlike *readlines* (that only
+ returns on a timeout) is this function yielding lines are they are
+ recevied.
+
+ .. deprecated:: 2.5
+ Use ``for line in s`` instead. This method is not available in
+ Python 2.6 and newer where the *io* library is available and
+ pySerial bases on *io*.
+
+ .. versionchanged:: 2.5
+ Implement as generator.
+
:rfc:`2217` Network ports
-------------------------
@@ -620,7 +633,7 @@
sent over the network.
The function returns a generator which can be used in ``for`` loops.
- It can be converted to bytes using ``serial.to_bytes``.
+ It can be converted to bytes using :func:`serial.to_bytes`.
.. method:: filter(data)
@@ -633,7 +646,7 @@
received from the network.
The function returns a generator which can be used in ``for`` loops.
- It can be converted to bytes using ``serial.to_bytes``.
+ It can be converted to bytes using :func:`serial.to_bytes`.
.. method:: check_modem_lines(force_notification=False)
@@ -749,18 +762,31 @@
.. versionadded:: 2.5
+.. function:: to_bytes(seqeucne)
+
+ :param sequence: String or list of integers
+
+ Convert a sequence to a bytes type. This is used to write code that is
+ compatible to Python 2.x and 3.x.
+
+ In Python versions prior 3.x bytes is a subclass of str. They convert
+ str([17]) to '[17]' instead of '\x11' so a simple bytes(sequence) doesn't
+ work for all versions of Python.
+
+ This function is used internally and in the unit tests.
+
+
.. _URLs:
URLs
----
-The class :class:`rfc2217.Serial` and the function :func:`serial_for_url`
-accept the following types URL:
+The function :func:`serial_for_url` accepts the following types of URLs:
- ``rfc2217://<host>:<port>[/<option>[/<option>]]``
- ``socket://<host>:<port>[/<option>[/<option>]]``
- ``loop://[<option>[/<option>]]``
-Device names are also supported:
+Device names are also supported, e.g.:
- ``/dev/ttyUSB0`` (Linux)
- ``COM3`` (Windows)
@@ -810,8 +836,9 @@
output on ``sys.stderr`` (if no logging was set up already).
``loop://``
- The least useful type. It simulates a loop back connection.
- ``RX<->TX`` ``RTS<->CTS`` ``DTR<->DSR``
+ The least useful type. It simulates a loop back connection
+ (``RX<->TX`` ``RTS<->CTS`` ``DTR<->DSR``). It could be used to test
+ applications or run the unit tests.
Supported options in the URL are:
