diff options
author | Chris Liechti <cliechti@gmx.net> | 2021-10-01 03:56:19 +0200 |
---|---|---|
committer | Chris Liechti <cliechti@gmx.net> | 2021-10-01 03:56:19 +0200 |
commit | aa68609f40d16a61f0ba65f4485419c0b04efcc0 (patch) | |
tree | 37098a800d92b3580fe3fb5b09c6ec6f8e1330b1 | |
parent | adf92098ae59774a1edce65924062872773f46b5 (diff) | |
download | pyserial-git-aa68609f40d16a61f0ba65f4485419c0b04efcc0.tar.gz |
docs: elaborate more on readline(s)
-rw-r--r-- | documentation/pyserial_api.rst | 6 | ||||
-rw-r--r-- | documentation/shortintro.rst | 17 |
2 files changed, 17 insertions, 6 deletions
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst index 2503ec5..fd15db5 100644 --- a/documentation/pyserial_api.rst +++ b/documentation/pyserial_api.rst @@ -486,11 +486,11 @@ Native ports .. method:: readline(size=-1) - Provided via :meth:`io.IOBase.readline` + Provided via :meth:`io.IOBase.readline` See also ref:`shortintro_readline`. .. method:: readlines(hint=-1) - Provided via :meth:`io.IOBase.readlines` + Provided via :meth:`io.IOBase.readlines`. See also ref:`shortintro_readline`. .. method:: writelines(lines) @@ -1188,7 +1188,7 @@ This module provides classes to simplify working with threads and protocols. .. attribute:: UNICODE_HANDLING = 'replace' - Unicode error handly policy. + Unicode error handling policy. .. method:: handle_packet(packet) diff --git a/documentation/shortintro.rst b/documentation/shortintro.rst index b9230e3..11b2ea0 100644 --- a/documentation/shortintro.rst +++ b/documentation/shortintro.rst @@ -53,13 +53,24 @@ Also supported with :ref:`context manager <context-manager>`:: ser.write(b'hello') +.. _shortintro_readline: + Readline ======== +:meth:`readline` reads up to one line, including the `\n` at the end. Be careful when using :meth:`readline`. Do specify a timeout when opening the serial port otherwise it could block forever if no newline character is -received. Also note that :meth:`readlines` only works with a timeout. -:meth:`readlines` depends on having a timeout and interprets that as EOF (end -of file). It raises an exception if the port is not opened correctly. +received. If the `\n` is missing in the return value, it returned on timeout. + +:meth:`readlines` tries to read "all" lines which is not well defined for a +serial port that is still open. Therefore :meth:`readlines` depends on having +a timeout on the port and interprets that as EOF (end of file). It raises an +exception if the port is not opened correctly. The returned list of lines do +not include the `\n`. + +Both functions call :meth:`read` to get their data and the serial port timeout +is acting on this function. Therefore the effective timeout, especially for +:meth:`readlines`, can be much larger. Do also have a look at the example files in the examples directory in the source distribution or online. |