From e4003597f43ccb041f81827b56c082cf5554098d Mon Sep 17 00:00:00 2001 From: Kaliko Jack Date: Sun, 3 Feb 2019 14:29:23 +0100 Subject: [PATCH] Update documentation --- doc/source/commands.rst | 16 +++++++++++++ doc/{ => source}/commands.txt | 45 ++++++++++++++++++++--------------- doc/source/index.rst | 3 ++- doc/source/use.rst | 37 ++++++++++++++++++---------- 4 files changed, 68 insertions(+), 33 deletions(-) create mode 100644 doc/source/commands.rst rename doc/{ => source}/commands.txt (78%) diff --git a/doc/source/commands.rst b/doc/source/commands.rst new file mode 100644 index 0000000..c11e5aa --- /dev/null +++ b/doc/source/commands.rst @@ -0,0 +1,16 @@ +.. _commands: + +Available commands +================== + +Get current available commands: + +.. code-block:: python + + import musicpd + print(' '.join([cmd for cmd in musicpd.MPDClient()._commands.keys()])) + + +List, last updated for v0.4.4: + +.. literalinclude:: commands.txt diff --git a/doc/commands.txt b/doc/source/commands.txt similarity index 78% rename from doc/commands.txt rename to doc/source/commands.txt index 10134a1..f471bb0 100644 --- a/doc/commands.txt +++ b/doc/source/commands.txt @@ -27,9 +27,10 @@ playid [] -> fetch_nothing previous -> fetch_nothing seek -> fetch_nothing seekid -> fetch_nothing +seekcur -> fetch_nothing stop -> fetch_nothing -== Playlist Commands +== Queue Commands add -> fetch_nothing addid [] -> fetch_item clear -> fetch_nothing @@ -44,9 +45,9 @@ playlistinfo [|] -> fetch_songs playlistsearch -> fetch_songs plchanges -> fetch_songs plchangesposid -> fetch_changes -prio | -> self._fetch_nothing, -prioid -> self._fetch_nothing, -rangeid -> self._fetch_nothing, +prio | -> fetch_nothing, +prioid -> fetch_nothing, +rangeid -> fetch_nothing, shuffle [] -> fetch_nothing swap -> fetch_nothing swapid -> fetch_nothing @@ -67,6 +68,7 @@ rm -> fetch_nothing save -> fetch_nothing == Database Commands +albumart -> fetch_object count -> fetch_object count group -> fetch_object find [ ]... -> fetch_songs @@ -74,8 +76,9 @@ findadd [ ] -> fetch_nothing list [ ]...[group ]... -> fetch_list listall [] -> fetch_database listallinfo [] -> fetch_database +listfiles -> fetch_database lsinfo [] -> fetch_database -readcomments -> fetch_object +readcomments [] -> fetch_object search [ ]... -> fetch_song searchadd [ ]... -> fetch_nothing searchaddpl [ ]... -> fetch_nothing @@ -83,11 +86,10 @@ update [] -> fetch_item rescan [] -> fetch_item == Mounts and neighbors == - -mount -> self._fetch_nothing -unmount -> self._fetch_nothing -listmounts -> self._fetch_mounts -listneighbors -> self._fetch_neighbors +mount -> fetch_nothing +unmount -> fetch_nothing +listmounts -> fetch_mounts +listneighbors -> fetch_neighbors == Sticker Commands sticker get -> fetch_item @@ -97,10 +99,15 @@ sticker list -> fetch_list sticker find -> fetch_songs == Connection Commands -close -> None -kill -> None -password -> fetch_nothing -ping -> fetch_nothing +close -> None +kill -> None +password -> fetch_nothing +ping -> fetch_nothing +tagtypes -> fetch_list +tagtypes disable: []... -> fetch_nothing +tagtypes enable: []... -> fetch_nothing +tagtypes clear: -> fetch_nothing +tagtypes all: -> fetch_nothing == Partition Commands partition -> fetch_nothing @@ -108,15 +115,15 @@ listpartitions -> fetch_list newpartition -> fetch_nothing == Audio Output Commands -disableoutput -> fetch_nothing -enableoutput -> fetch_nothing -toggleoutput -> fetch_nothing -outputs -> fetch_outputs +disableoutput -> fetch_nothing +enableoutput -> fetch_nothing +toggleoutput -> fetch_nothing +outputs -> fetch_outputs +outputset -> fetch_nothing == Reflection Commands config -> fetch_object commands -> fetch_list notcommands -> fetch_list -tagtypes -> fetch_list urlhandlers -> fetch_list decoders -> fetch_plugins diff --git a/doc/source/index.rst b/doc/source/index.rst index fdfeb70..d552f00 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -66,6 +66,7 @@ Contents use.rst doc.rst + commands.rst contribute.rst @@ -73,8 +74,8 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` +.. * :ref:`modindex` .. vim: spell spelllang=en diff --git a/doc/source/use.rst b/doc/source/use.rst index fdc1317..d8e46e7 100644 --- a/doc/source/use.rst +++ b/doc/source/use.rst @@ -1,25 +1,28 @@ Using the client library ========================= -The client library can be used as follows:: +The client library can be used as follows: + +.. code-block:: python client = musicpd.MPDClient() # create client object 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 + print(client.mpd_version) # print the mpd protocol version + print(client.cmd('one', 2)) # print result of the command "cmd one 2" 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 the `MPD protocol documentation`_ for more -details. +For a list of supported commands, their arguments (as MPD currently understands +them), and the functions used to parse their responses see :ref:`commands`. + +See the `MPD protocol documentation`_ for more details. Command lists are also supported using `command_list_ok_begin()` and -`command_list_end()` :: +`command_list_end()` : + +.. code-block:: python client.command_list_ok_begin() # start a command list client.update() # insert the update command into the list @@ -27,7 +30,9 @@ Command lists are also supported using `command_list_ok_begin()` and 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 ":" :: +Possible ranges are: "START:END", "START:" and ":" : + +.. code-block:: python # An intelligent clear # clears played track in the queue, currentsong included @@ -38,7 +43,9 @@ Possible ranges are: "START:END", "START:" and ":" :: 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 ":"):: +as a single colon as argument (i.e. sending just ":"): + +.. code-block:: python # sending "rangeid :" to clear the range, play everything client.rangeid(()) # send an empty tuple @@ -47,7 +54,9 @@ Empty start in range (i.e. ":END") are not possible and will raise a CommandErro Commands may also return iterators instead of lists if `iterate` is set to -`True`:: +`True`: + +.. code-block:: python client.iterate = True for song in client.playlistinfo(): @@ -55,7 +64,9 @@ Commands may also return iterators instead of lists if `iterate` is set to Each command have a *send\_* and a *fetch\_* variant, which allows to send a MPD command and then fetch the result later. -This is useful for the idle command:: +This is useful for the idle command: + +.. code-block:: python >>> client.send_idle() # do something else or use function like select() -- 2.39.2