adding README.txt
authorJ. Alexander Treuman <jat@spatialrift.net>
Wed, 27 Feb 2008 23:09:52 +0000 (18:09 -0500)
committerJ. Alexander Treuman <jat@spatialrift.net>
Wed, 27 Feb 2008 23:09:52 +0000 (18:09 -0500)
README.txt [new file with mode: 0644]

diff --git a/README.txt b/README.txt
new file mode 100644 (file)
index 0000000..3b3fa5f
--- /dev/null
@@ -0,0 +1,80 @@
+python-mpd
+==========
+
+Getting python-mpd
+------------------
+
+The latest release of python-mpd can be found at
+http://pypi.python.org/pypi/python-mpd/[].
+
+
+Getting the latest source code
+------------------------------
+
+If you would instead like to use the latest source code, you can grab a copy
+of the development version from git by running the command:
+
+  git clone http://git.thejat.be/python-mpd.git
+
+
+Installing from source
+----------------------
+
+To install python-mpd from source, simply run the command:
+
+  python setup.py install
+
+You can use the `--help` switch to `setup.py` for a complete list of commands
+and their options.  See the http://docs.python.org/inst/inst.html[Installing
+Python Modules] document for more details.
+
+
+Using the client library
+------------------------
+
+The client library can be used as follows:
+
+------------------------------------------------------------------------------
+client = mpd.MPDClient()           # create client object
+client.connect("localhost", 6600)  # connect to localhost:6600
+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
+client.disconnect()                # disconnect from the server
+------------------------------------------------------------------------------
+
+A list of supported commands, their arguments (as MPD currently understands
+them), and the functions used to parse their responses can be found in
+`doc/commands.txt`.  See
+http://mpd.wikia.com/wiki/MusicPlayerDaemonCommands[MusicPlayerDaemonCommands]
+on the http://mpd.wikia.com/[MPD Wiki] for more details.
+
+Command lists are also supported using `command_list_ok_begin()` and
+`command_list_end()`:
+
+------------------------------------------------------------------------------
+client.command_list_ok_begin()       # start a command list
+client.update()                      # insert the update command into the list
+client.status()                      # insert the status command into the list
+results = client.command_list_end()  # results will be a list with the results
+------------------------------------------------------------------------------
+
+Commands may also return iterators instead of lists if `iterate` is set to
+`True`:
+
+------------------------------------------------------------------------------
+client.iterate = True
+for song in client.listallinfo():
+    print song["file"]
+------------------------------------------------------------------------------
+
+Extra care must be taken to exhaust the iterator before executing *any* other
+commands.
+
+
+Contacting the author
+---------------------
+
+You can contact the author by emailing J. Alexander Treuman
+<mailto:jat@spatialrift.net[]>.  He can also be found idling in #mpd on
+irc.freenode.net as jat.