From aa68609f40d16a61f0ba65f4485419c0b04efcc0 Mon Sep 17 00:00:00 2001 From: Chris Liechti Date: Fri, 1 Oct 2021 03:56:19 +0200 Subject: docs: elaborate more on readline(s) --- documentation/pyserial_api.rst | 6 +++--- 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 `:: 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. -- cgit v1.2.1