Add suport for environment variables MPD_HOST/MPD_PORT/XDG_RUNTIME_DIR

[python-musicpd.git] / README.rst

diff --git a/README.rst b/README.rst
index 2bd88dce0ac714c31bee7c2fbfd5befcbaec3732..95e6ff5b19fb653a57aa7636aa44bcaf145233dd 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -35,7 +35,10 @@ Using the client library
 The client library can be used as follows::
 
     client = musicpd.MPDClient()       # create client object
-    client.connect('localhost', 6600)  # connect to localhost:6600
+    client.connect()                   # use MPD_HOST/MPD_PORT if set else
+                                       #   test ${XDG_RUNTIME_DIR}/mpd/socket for existence
+                                       #   fallback to localhost:6600
+                                       # `connect` support host/port argument as well
     print client.mpd_version           # print the mpd version
     print client.cmd('one', 2)         # print result of the command "cmd one 2"
     client.close()                     # send the close command
@@ -54,6 +57,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`::