+.. SPDX-FileCopyrightText: 2018-2023 kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
+
Using the client library
=========================
# 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`.
+
+For more about the protocol and MPD commands see the `MPD protocol
+documentation`_.
-See the `MPD protocol documentation`_ for more details.
+For a list of currently supported commands in this python module see
+:ref:`commands`.
+
+.. _environment_variables:
Environment variables
---------------------
-The client honors the following 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 looks for an existing file in :envvar:`${XDG_RUNTIME_DIR:-/run/}/mpd/socket`
+ * else set host to ``localhost``
- * ``MPD_HOST`` MPD host (:abbr:`FQDN (fully qualified domain name)`, socket path or abstract socket) and password.
+Default port:
+ * use :envvar:`MPD_PORT` environment variable is set
+ * else use ``6600``
- | To define a password set 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`"
- * ``MPD_PORT`` MPD port, relevant for TCP socket only, ie with :abbr:`FQDN (fully qualified domain name)` defined host
- * ``MPD_TIMEOUT`` timeout for connecting to MPD and for waiting for MPD’s response in seconds
- * ``XDG_RUNTIME_DIR`` path to look for potential socket: ``${XDG_RUNTIME_DIR}/mpd/socket``
+Default timeout:
+ * use :envvar:`MPD_TIMEOUT` is set
+ * else use :py:obj:`musicpd.CONNECTION_TIMEOUT`
-Defaults settings
------------------
+Context manager
+---------------
- * If ``MPD_HOST`` is not set, then look for a socket in ``${XDG_RUNTIME_DIR}/mpd/socket``
- * If there is no socket use ``localhost``
- * If ``MPD_PORT`` is not set, then use ``6600``
- * If ``MPD_TIMEOUT`` is not set, then uses :py:obj:`musicpd.CONNECTION_TIMEOUT`
+Calling MPDClient in a context manager :py:obj:`musicpd.MPDClient.connect` is
+transparently called with :ref:`default setting<default_settings>` (use
+:ref:`environment variables<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
-------------
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
Empty start in range (i.e. ":END") are not possible and will raise a CommandError.
+Remember the of the tuple is optional, range can still be specified as single string ``"START:END"``.
+
Iterators
----------
----------------------
Each command have a *send\_<CMD>* and a *fetch\_<CMD>* 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
>>> gobject.io_add_watch(client, gobject.IO_IN, callback)
>>> gobject.MainLoop().run()
+See also use of :ref:`socket timeout<socket_timeout>` with idle command.
+
Fetching binary content (cover art)
-----------------------------------
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).
+
+
.. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/
+.. _snake case: https://en.wikipedia.org/wiki/Snake_case
+.. vim: spell spelllang=en
home / dev / repositories / python-musicpd.git / blobdiff