Improved Range object to deal with window parameter

[python-musicpd.git] / doc / source / use.rst

diff --git a/doc/source/use.rst b/doc/source/use.rst
index 29b6e53e1cfbcea9c2f824437e25801af6caadd2..213491ed7d29b39097c90ba8d4bb300cd73bad31 100644 (file)
--- a/doc/source/use.rst
+++ b/doc/source/use.rst
@@ -1,3 +1,6 @@
+.. SPDX-FileCopyrightText: 2018-2023  kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
+
 Using the client library
 =========================
 
@@ -83,15 +86,18 @@ Command lists are also supported using `command_list_ok_begin()` and
 Ranges
 ------
 
-Provide a 2-tuple as argument for command supporting ranges (cf. `MPD protocol documentation`_ for more details).
-Possible ranges are: "START:END", "START:" and ":" :
+Some commands (e.g. delete) allow specifying a range in the form `"START:END"` (cf. `MPD protocol documentation`_ for more details).
+
+Possible ranges are: `"START:END"`, `"START:"` and `":"` :
+
+Instead of giving the plain string as `"START:END"`, you **can** provide a :py:obj:`tuple` as `(START,END)`. The module is then ensuring the format is correct and raises an :py:obj:`musicpd.CommandError` exception otherwise. Empty start or end can be specified as en empty string `''` or :py:obj:`None`.
 
 .. code-block:: python
 
     # An intelligent clear
     # clears played track in the queue, currentsong included
     pos = client.currentsong().get('pos', 0)
-    # the 2-tuple range object accepts str, no need to convert to int
+    # the range object accepts str, no need to convert to int
     client.delete((0, pos))
     # missing end interpreted as highest value possible, pay attention still need a tuple.
     client.delete((pos,))  # purge queue from current to the end
@@ -106,6 +112,8 @@ as a single colon as argument (i.e. sending just ":"):
 
 Empty start in range (i.e. ":END") are not possible and will raise a CommandError.
 
+Remember the of the tuple is optional, range can still be specified as single string `START:END`. In case of malformed range a CommandError is still raised.
+
 Iterators
 ----------
 
@@ -122,7 +130,7 @@ Idle prefixed commands
 ----------------------
 
 Each command have a *send\_<CMD>* and a *fetch\_<CMD>* variant, which allows to
-send a MPD command and then fetch the result later.
+send a MPD command and then fetch the result later (non-blocking call).
 This is useful for the idle command:
 
 .. code-block:: python
@@ -143,6 +151,8 @@ This is useful for the idle command:
     >>> gobject.io_add_watch(client, gobject.IO_IN, callback)
     >>> gobject.MainLoop().run()
 
+See also use of :ref:`socket timeout<socket_timeout>` with idle command.
+
 Fetching binary content (cover art)
 -----------------------------------
 
@@ -193,6 +203,8 @@ You can also use `readpicture` command to fetch embedded picture:
 
 Refer to `MPD protocol documentation`_ for the meaning of `binary`, `size` and `data`.
 
+.. _socket_timeout:
+
 Socket timeout
 --------------
 
@@ -257,7 +269,7 @@ Some explanations:
 
 All three commands in the while loop (send_idle, fetch_idle, noidle) are not
 triggering a socket timeout unless the connection is actually lost (actually it
-could also be that MPD took to much time to answer, but MPD taking more than a
+could also be that MPD took too much time to answer, but MPD taking more than a
 couple of seconds for these commands should never occur).