diff options
author | Chris Liechti <cliechti@gmx.net> | 2015-12-18 23:23:26 +0100 |
---|---|---|
committer | Chris Liechti <cliechti@gmx.net> | 2015-12-18 23:23:26 +0100 |
commit | 3e0dcc7e3cf84dc2e98e7e364127b995114dcb84 (patch) | |
tree | 3f24d2f5810f54d2027ea34ed693f9fe5165bfbe /documentation/pyserial_api.rst | |
parent | 9ad044afd3ba15749178adb27af2591f2bb1c054 (diff) | |
download | pyserial-git-3e0dcc7e3cf84dc2e98e7e364127b995114dcb84.tar.gz |
doc update
Diffstat (limited to 'documentation/pyserial_api.rst')
-rw-r--r-- | documentation/pyserial_api.rst | 42 |
1 files changed, 27 insertions, 15 deletions
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst index a3f2ae8..9063ef2 100644 --- a/documentation/pyserial_api.rst +++ b/documentation/pyserial_api.rst @@ -80,14 +80,20 @@ Native ports OSX >= Tiger, Windows). Though, even on these platforms some serial ports may reject non-standard values. - Possible values for the parameter *timeout*: + Possible values for the parameter *timeout* which controls the behavior + of :meth:`read`: - - ``timeout = None``: wait forever - - ``timeout = 0``: non-blocking mode (return immediately on read) + - ``timeout = None``: wait forever / until requested number of bytes + are received + - ``timeout = 0``: non-blocking mode, return immediately in any case, + returning zero or more, up to the requested number of bytes - ``timeout = x``: set timeout to ``x`` seconds (float allowed) + returns immediately when the requested number of bytes are available, + otherwise wait until the timeout expires and return all bytes that + were received until then. - Writes are blocking by default, unless *write_timeout* is set. For - possible values refer to the list for *timeout* above. + :meth:`write` is blocking by default, unless *write_timeout* is set. + For possible values refer to the list for *timeout* above. Note that enabling both flow control methods (*xonxoff* and *rtscts*) together may not be supported. It is common to use one of the methods @@ -101,6 +107,7 @@ Native ports .. versionchanged:: 2.5 *dsrdtr* now defaults to ``False`` (instead of *None*) + .. versionchanged:: 3.0 numbers as *port* argument are no longer supported .. method:: open() @@ -122,6 +129,7 @@ Native ports :param size: Number of bytes to read. :return: Bytes read from the port. + :rtype: bytes 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 @@ -135,6 +143,7 @@ Native ports :param data: Data to send. :return: Number of bytes written. + :rtype: int :exception SerialTimeoutException: In case a write timeout is configured for the port and the time is exceeded. @@ -143,7 +152,7 @@ Native ports (or compatible such as ``bytearray`` or ``memoryview``). Unicode strings must be encoded (e.g. ``'hello'.encode('utf-8'``). - .. versionchanged:: 2.5 + .. versionchanged:: 2.5 Accepts instances of :class:`bytes` and :class:`bytearray` when available (Python 2.6 and newer) and :class:`str` otherwise. @@ -365,7 +374,7 @@ Native ports :setter: Disable (``None``) or enable the RS485 settings :type: :class:`rs485.RS485Settings` or ``None`` :platform: Posix (Linux, limited set of hardware) - :platform: Windows (RTS on TX only possible) + :platform: Windows (only RTS on TX possible) Attribute to configure RS485 support. When set to an instance of :class:`rs485.RS485Settings` and supported by OS, RTS will be active @@ -380,9 +389,9 @@ Native ports .. attribute:: BAUDRATES - A list of valid baud rates. The list may be incomplete such that higher - baud rates may be supported by the device and that values in between the - standard baud rates are supported. (Read Only). + A list of valid baud rates. The list may be incomplete, such that higher + and/or intermediate baud rates may also be supported by the device + (Read Only). .. attribute:: BYTESIZES @@ -432,6 +441,7 @@ Native ports .. method:: get_settings() :return: a dictionary with current port settings. + :rtype: dict Get a dictionary with port settings. This is useful to backup the current settings so that a later point in time they can be restored @@ -440,18 +450,20 @@ Native ports Note that control lines (RTS/DTR) are part of the settings. .. versionadded:: 2.5 + .. versionchanged:: 3.0 renamed from ``getSettingsDict`` .. method:: apply_settings(d) - :param d: a dictionary with port settings. + :param dict d: a dictionary with port settings. Applies a dictionary that was created by :meth:`get_settings`. Only - changes are applied and when a key is missing it means that the setting - stays unchanged. + changes are applied and when a key is missing, it means that the + setting stays unchanged. Note that control lines (RTS/DTR) are not changed. .. versionadded:: 2.5 + .. versionchanged:: 3.0 renamed from ``applySettingsDict`` Platform specific methods. @@ -477,7 +489,7 @@ Native ports .. method:: set_input_flow_control(enable) :platform: Posix - :param enable: Set flow control state. + :param bool enable: Set flow control state. Manually control flow - when software flow control is enabled. @@ -490,7 +502,7 @@ Native ports :platform: Posix (HW and SW flow control) :platform: Windows (SW flow control only) - :param enable: Set flow control state. + :param bool enable: Set flow control state. Manually control flow of outgoing data - when hardware or software flow control is enabled. |