X-Git-Url: http://git.kaliko.me/?a=blobdiff_plain;f=doc%2Fsource%2Fuse.rst;h=d8e46e7e7c216143d980d72bd4f3b3628c428683;hb=HEAD;hp=a213247adaf4c7004d207b5acbeb56ad964dc1fb;hpb=e645adfa14a04168a4d8a892e88569205f868c84;p=python-musicpd.git diff --git a/doc/source/use.rst b/doc/source/use.rst index a213247..88728ef 100644 --- a/doc/source/use.rst +++ b/doc/source/use.rst @@ -1,3 +1,6 @@ +.. SPDX-FileCopyrightText: 2018-2023 kaliko +.. SPDX-License-Identifier: LGPL-3.0-or-later + Using the client library ========================= @@ -13,16 +16,100 @@ The client library can be used as follows: # 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 protocol version - print(client.cmd('foo', 42)) # print result of the request "cmd foo 42" - # (nb. for actual command, see link to the protocol below) + print(client.mpd_version) # print the MPD protocol version + client.setvol('42') # sets the volume client.disconnect() # disconnect from the server -In the example above `cmd` in not an actual MPD command, for a list of -supported commands, their arguments (as MPD currently understands -them), and the functions used to parse their responses see :ref:`commands`. +The MPD command protocol exchanges line-based text records. The client emits a +command with optional arguments. In the example above the client sends a +`setvol` command with the string argument `42`. + +MPD commands are exposed as :py:class:`musicpd.MPDClient` methods. Methods +**arguments are python strings**. Some commands are composed of more than one word +(ie "**tagtypes [disable|enable|all]**"), for these use a `snake case`_ style to +access the method. Then **"tagtypes enable"** command is called with +**"tagtypes_enable"**. + +Remember MPD protocol is text based, then all MPD command arguments are UTF-8 +strings. In the example above, an integer can be used as argument for the +`setvol` command, but it is then evaluated as a string when the command is +written to the socket. To avoid confusion use regular string instead of relying +on object string representation. + +:py:class:`musicpd.MPDClient` methods returns different kinds of objects +depending on the command. Could be :py:obj:`None`, a single object as a +:py:obj:`str` or a :py:obj:`dict`, a list of :py:obj:`dict`. + +Then :py:class:`musicpd.MPDClient` **methods signatures** are not hard coded +within this module since the protocol is handled on the server side. Please +refer to the protocol and MPD commands in `MPD protocol documentation`_ to +learn how to call commands and what kind of arguments they expect. + +Some examples are provided for the most common cases, see :ref:`examples`. + +For a list of currently supported commands in this python module see +:ref:`commands`. + +.. _environment_variables: + +Environment variables +--------------------- + +:py:class:`musicpd.MPDClient` honors the following environment variables: + +.. envvar:: MPD_HOST + + MPD host (:abbr:`FQDN (fully qualified domain name)`, IP, socket path or abstract socket) and password. + + | To define a **password** set :envvar:`MPD_HOST` to "*password@host*" (password only "*password@*") + | For **abstract socket** use "@" as prefix : "*@socket*" and then with a password "*pass@@socket*" + | Regular **unix socket** are set with an absolute path: "*/run/mpd/socket*" + +.. envvar:: MPD_PORT + + MPD port, relevant for TCP socket only + +.. envvar:: MPD_TIMEOUT + + socket timeout when connecting to MPD and waiting for MPD’s response (in seconds) + +.. envvar:: XDG_RUNTIME_DIR + + path to look for potential socket + +.. _default_settings: + +Default settings +---------------- + +Default host: + * use :envvar:`MPD_HOST` environment variable if set, extract password if present, + * else use :envvar:`XDG_RUNTIME_DIR` to looks for an existing file in ``${XDG_RUNTIME_DIR}/mpd/socket``, :envvar:`XDG_RUNTIME_DIR` defaults to ``/run`` if not set. + * else set host to ``localhost`` + +Default port: + * use :envvar:`MPD_PORT` environment variable if set + * else use ``6600`` -See the `MPD protocol documentation`_ for more details. +Default timeout: + * use :envvar:`MPD_TIMEOUT` if set + * else use :py:obj:`musicpd.CONNECTION_TIMEOUT` + +Context manager +--------------- + +Calling MPDClient in a context manager :py:obj:`musicpd.MPDClient.connect` is +transparently called with :ref:`default setting` (use +:ref:`environment variables` to override defaults). +Leaving the context manager :py:obj:`musicpd.MPDClient.disconnect` is called. + +.. code-block:: python + + import os + os.environ['MPD_HOST'] = 'mpdhost' + with MPDClient() as c: + c.status() + c.next() Command lists ------------- @@ -40,21 +127,24 @@ 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 -A notable case is the `rangeid` command allowing an empty range specified -as a single colon as argument (i.e. sending just ":"): +A notable case is the *rangeid* command allowing an empty range specified +as a single colon as argument (i.e. sending just ``":"``): .. code-block:: python @@ -63,6 +153,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. +.. note:: Remember the use of a tuple is **optional**. Range can still be specified as a plain string ``"START:END"``. + Iterators ---------- @@ -79,7 +171,7 @@ Idle prefixed commands ---------------------- Each command have a *send\_* and a *fetch\_* 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 @@ -100,6 +192,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` with idle command. + Fetching binary content (cover art) ----------------------------------- @@ -124,7 +218,7 @@ Fetching album covers is possible with albumart, here is an example: >>> print('something went wrong', file=sys.stderr) >>> cli.disconnect() -A `CommandError` is raised if the album does not expose a cover. +A :py:obj:`musicpd.CommandError` is raised if the album does not expose a cover. You can also use `readpicture` command to fetch embedded picture: @@ -150,4 +244,89 @@ 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 +-------------- + +.. note:: + When the timeout is reached it raises a :py:obj:`socket.timeout` exception. An :py:obj:`OSError` subclass. + +A timeout is used for the initial MPD connection (``connect`` command), then +the socket is put in blocking mode with no timeout. Its value is set in +:py:obj:`musicpd.CONNECTION_TIMEOUT` at module level and +:py:obj:`musicpd.MPDClient.mpd_timeout` in MPDClient instances . However it +is possible to set socket timeout for all command setting +:py:obj:`musicpd.MPDClient.socket_timeout` attribute to a value in second. + +Having ``socket_timeout`` enabled can help to detect "half-open connection". +For instance loosing connectivity without the server explicitly closing the +connection (switching network interface ethernet/wifi, router down, etc…). + +**Nota bene**: with ``socket_timeout`` enabled each command sent to MPD might +timeout. A couple of seconds should be enough for commands to complete except +for the special case of ``idle`` command which by definition *“ waits until +there is a noteworthy change in one or more of MPD’s subsystems.”* (cf. `MPD +protocol documentation`_). + +Here is a solution to use ``idle`` command with ``socket_timeout``: + +.. code-block:: python + + import musicpd + import select + import socket + + cli = musicpd.MPDClient() + try: + cli.socket_timeout = 10 # seconds + select_timeout = 5 # second + cli.connect() + while True: + cli.send_idle() # use send_ API to avoid blocking on read + _read, _, _ = select.select([cli], [], [], select_timeout) + if _read: # tries to read response + ret = cli.fetch_idle() + print(', '.join(ret)) # Do something + else: # cancels idle + cli.noidle() + except socket.timeout as err: + print(f'{err} (timeout {cli.socket_timeout})') + except (OSError, musicpd.MPDError) as err: + print(f'{err!r}') + if cli._sock is not None: + cli.disconnect() + except KeyboardInterrupt: + pass + +Some explanations: + + * First launch a non blocking ``idle`` command. This call do not wait for a + response to avoid socket timeout waiting for an MPD event. + * ``select`` waits for something to read on the socket (the idle response + in this case), returns after ``select_timeout`` seconds anyway. + * In case there is something to read read it using ``fetch_idle`` + * Nothing to read, cancel idle with ``noidle`` + +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 too much time to answer, but MPD taking more than a +couple of seconds for these commands should never occur). + +.. _exceptions: + +Exceptions +---------- + +The :py:obj:`connect` method raises +:py:obj:`ConnectionError` only (an :py:obj:`MPDError` exception) but then, calling other MPD commands, the module can raise +:py:obj:`MPDError` or an :py:obj:`OSError` depending on the error and +where it occurs. + +Then using musicpd module both :py:obj:`musicpd.MPDError` and :py:obj:`OSError` +exceptions families are expected, see :ref:`examples` for a +way to deal with this. + .. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/ +.. _snake case: https://en.wikipedia.org/wiki/Snake_case +.. vim: spell spelllang=en