X-Git-Url: https://git.kaliko.me/?p=python-musicpd.git;a=blobdiff_plain;f=README.rst;h=61b305fec96b4ec1277c1bdd06ce4b266e5a0390;hp=a926514908ef9fe257a906815416c673f3f870c1;hb=86a40a9a5a668399c6ca07022b3c38251686ed1d;hpb=d28bd57ddc3465db4fcaa540fe7cb3de53f8be6b

diff --git a/README.rst b/README.rst
index a926514..61b305f 100644
--- a/README.rst
+++ b/README.rst
@@ -54,6 +54,25 @@ Command lists are also supported using `command_list_ok_begin()` and
     client.status()                      # insert the status command into the list
     results = client.command_list_end()  # results will be a list with the results
 
+Provide a 2-tuple as argument for command supporting ranges (cf. `MPD protocol documentation`_ for more details).
+Possible ranges are: "START:END", "START:" and ":" ::
+
+    # 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
+    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
+
+A notable case is the `rangeid` command allowing an empty range specified
+as a single colon as argument (i.e. sending just ":")::
+
+    # sending "rangeid :" to clear the range, play everything
+    client.rangeid(())  # send an empty tuple
+
+Empty start in range (i.e. ":END") are not possible and will raise a CommandError.
+
 
 Commands may also return iterators instead of lists if `iterate` is set to
 `True`::
@@ -62,6 +81,25 @@ Commands may also return iterators instead of lists if `iterate` is set to
     for song in client.playlistinfo():
         print song['file']
 
+Each command have a *send\_<CMD>* and a *fetch\_<CMD>* variant, which allows to
+send a MPD command and then fetch the result later.
+This is useful for the idle command::
+
+    >>> client.send_idle()
+    # do something else or use function like select()
+    # http://docs.python.org/howto/sockets.html#non-blocking-sockets
+    # ex. select([client], [], [])
+    >>> events = client.fetch_idle()
+
+    # more complex use for example, with glib/gobject:
+    >>> def callback(source, condition):
+    >>>    changes = client.fetch_idle()
+    >>>    print changes
+    >>>    return False  # removes the IO watcher
+
+    >>> client.send_idle()
+    >>> gobject.io_add_watch(client, gobject.IO_IN, callback)
+    >>> gobject.MainLoop().run()
 
 Contacting authors
 ------------------