-# python-musicpd: Python MPD client library
-# Copyright (C) 2012-2020 kaliko <kaliko@azylum.org>
-# Copyright (C) 2019 Naglis Jonaitis <naglis@mailbox.org>
-# Copyright (C) 2019 Bart Van Loon <bbb@bbbart.be>
-# Copyright (C) 2008-2010 J. Alexander Treuman <jat@spatialrift.net>
-#
-# python-musicpd is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# python-musicpd is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with python-musicpd. If not, see <http://www.gnu.org/licenses/>.
-
-# pylint: disable=missing-docstring
+# -*- coding: utf-8 -*-
+# SPDX-FileCopyrightText: 2012-2023 kaliko <kaliko@azylum.org>
+# SPDX-FileCopyrightText: 2021 Wonko der Verständige <wonko@hanstool.org>
+# SPDX-FileCopyrightText: 2019 Naglis Jonaitis <naglis@mailbox.org>
+# SPDX-FileCopyrightText: 2019 Bart Van Loon <bbb@bbbart.be>
+# SPDX-FileCopyrightText: 2008-2010 J. Alexander Treuman <jat@spatialrift.net>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+"""Python Music Player Daemon client library"""
-import socket
+
+import logging
import os
+import socket
from functools import wraps
ERROR_PREFIX = "ACK "
SUCCESS = "OK"
NEXT = "list_OK"
-VERSION = '0.5.0'
-#: seconds before a tcp connection attempt times out
-CONNECTION_TIMEOUT = 5
+#: Module version
+VERSION = '0.9.0b0'
+#: Seconds before a connection attempt times out
+#: (overriden by :envvar:`MPD_TIMEOUT` env. var.)
+CONNECTION_TIMEOUT = 30
+#: Socket timeout in second (Default is None for no timeout)
+SOCKET_TIMEOUT = None
+
+log = logging.getLogger(__name__)
def iterator_wrapper(func):
class MPDError(Exception):
- pass
+ """Main musicpd Exception"""
class ConnectionError(MPDError):
- pass
+ """Fatal Connection Error, cannot recover from it."""
class ProtocolError(MPDError):
- pass
+ """Fatal Protocol Error, cannot recover from it"""
class CommandError(MPDError):
- pass
+ """Malformed command, socket should be fine, can reuse it"""
class CommandListError(MPDError):
- pass
+ """"""
class PendingCommandError(MPDError):
- pass
+ """"""
class IteratingError(MPDError):
- pass
+ """"""
class Range:
def __init__(self, tpl):
self.tpl = tpl
+ self.lower = ''
+ self.upper = ''
self._check()
def __str__(self):
- if len(self.tpl) == 0:
- return ':'
- if len(self.tpl) == 1:
- return '{0}:'.format(self.tpl[0])
- return '{0[0]}:{0[1]}'.format(self.tpl)
+ return f'{self.lower}:{self.upper}'
def __repr__(self):
- return 'Range({0})'.format(self.tpl)
+ return f'Range({self.tpl})'
+
+ def _check_element(self, item):
+ if item is None or item == '':
+ return ''
+ try:
+ return str(int(item))
+ except (TypeError, ValueError) as err:
+ raise CommandError(f'Not an integer: "{item}"') from err
+ return item
def _check(self):
if not isinstance(self.tpl, tuple):
raise CommandError('Wrong type, provide a tuple')
- if len(self.tpl) not in [0, 1, 2]:
- raise CommandError('length not in [0, 1, 2]')
- for index in self.tpl:
- try:
- index = int(index)
- except (TypeError, ValueError):
- raise CommandError('Not a tuple of int')
+ if len(self.tpl) == 0:
+ return
+ if len(self.tpl) == 1:
+ self.lower = self._check_element(self.tpl[0])
+ return
+ if len(self.tpl) != 2:
+ raise CommandError('Range wrong size (0, 1 or 2 allowed)')
+ self.lower = self._check_element(self.tpl[0])
+ self.upper = self._check_element(self.tpl[1])
+ if self.lower == '' and self.upper != '':
+ raise CommandError(f'Integer expected to start the range: {self.tpl}')
+ if self.upper.isdigit() and self.lower.isdigit():
+ if int(self.lower) > int(self.upper):
+ raise CommandError(f'Wrong range: {self.lower} > {self.upper}')
class _NotConnected:
def __getattr__(self, attr):
return self._dummy
- def _dummy(*args):
+ def _dummy(self, *args):
raise ConnectionError("Not connected")
class MPDClient:
- """MPDClient instance will look for ``MPD_HOST``/``MPD_PORT``/``XDG_RUNTIME_DIR`` environment
- variables and set instance attribute ``host``, ``port`` and ``pwd``
- accordingly. Regarding ``MPD_HOST`` format to expose password refer
- MPD client manual :manpage:`mpc (1)`.
+ """MPDClient instance will look for :envvar:`MPD_HOST`/:envvar:`MPD_PORT`/:envvar:`XDG_RUNTIME_DIR` environment
+ variables and set instance attribute :py:attr:`host`, :py:attr:`port` and :py:obj:`pwd`
+ accordingly.
- Then :py:obj:`musicpd.MPDClient.connect` will use ``host`` and ``port`` as defaults if not provided as args.
+ Then :py:obj:`musicpd.MPDClient.connect` will use :py:obj:`host` and
+ :py:obj:`port` as defaults if not provided as args.
- Cf. :py:obj:`musicpd.MPDClient.connect` for details.
+ Regarding :envvar:`MPD_HOST` format to expose password refer this module
+ documentation or MPD client manual :manpage:`mpc (1)`.
>>> from os import environ
>>> environ['MPD_HOST'] = 'pass@mpdhost'
True
>>> cli.connect() # will use host/port as set in MPD_HOST/MPD_PORT
- :ivar str host: host used with the current connection
- :ivar str,int port: port used with the current connection
- :ivar str pwd: password detected in ``MPD_HOST`` environment variable
+ .. note::
+
+ 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:-/run/}/mpd/socket``
+ * else set host to ``localhost``
+
+ default port:
+ * use :envvar:`MPD_PORT` environment variable is set
+ * else use ``6600``
- .. warning:: Instance attribute host/port/pwd
+ .. warning:: **Instance attribute host/port/pwd**
- While :py:attr:`musicpd.MPDClient().host` and
- :py:attr:`musicpd.MPDClient().port` keep track of current connection
- host and port, :py:attr:`musicpd.MPDClient().pwd` is set once with
+ While :py:attr:`musicpd.MPDClient.host` and
+ :py:attr:`musicpd.MPDClient.port` keep track of current connection
+ host and port, :py:attr:`musicpd.MPDClient.pwd` is set once with
password extracted from environment variable.
- Calling :py:meth:`musicpd.MPDClient().password()` with a new password
- won't update :py:attr:`musicpd.MPDClient().pwd` value.
+ Calling :py:meth:`password` methode with a new password
+ won't update :py:attr:`musicpd.MPDClient.pwd` value.
- Moreover, :py:attr:`musicpd.MPDClient().pwd` is only an helper attribute
- exposing password extracted from ``MPD_HOST`` environment variable, it
+ Moreover, :py:attr:`musicpd.MPDClient.pwd` is only an helper attribute
+ exposing password extracted from :envvar:`MPD_HOST` environment variable, it
will not be used as default value for the :py:meth:`password` method
"""
def __init__(self):
self.iterate = False
+ #: Socket timeout value in seconds
+ self._socket_timeout = SOCKET_TIMEOUT
+ #: Current connection timeout value, defaults to
+ #: :py:obj:`CONNECTION_TIMEOUT` or env. var. ``MPD_TIMEOUT`` if provided
+ self.mpd_timeout = None
+ self.mpd_version = ''
+ """Protocol version as exposed by the server as a :py:obj:`str`
+
+ .. note:: This is the version of the protocol spoken, not the real version of the daemon."""
self._reset()
self._commands = {
# Status Commands
"random": self._fetch_nothing,
"repeat": self._fetch_nothing,
"setvol": self._fetch_nothing,
+ "getvol": self._fetch_object,
"single": self._fetch_nothing,
"replay_gain_mode": self._fetch_nothing,
"replay_gain_status": self._fetch_item,
"kill": None,
"password": self._fetch_nothing,
"ping": self._fetch_nothing,
+ "binarylimit": self._fetch_nothing,
"tagtypes": self._fetch_list,
"tagtypes disable": self._fetch_nothing,
"tagtypes enable": self._fetch_nothing,
"readmessages": self._fetch_messages,
"sendmessage": self._fetch_nothing,
}
+ #: host used with the current connection (:py:obj:`str`)
+ self.host = None
+ #: password detected in :envvar:`MPD_HOST` environment variable (:py:obj:`str`)
+ self.pwd = None
+ #: port used with the current connection (:py:obj:`int`, :py:obj:`str`)
+ self.port = None
self._get_envvars()
def _get_envvars(self):
"""
- Retrieve MPD env. var. to overrides "localhost:6600"
- Use MPD_HOST/MPD_PORT if set
- else use MPD_HOST=${XDG_RUNTIME_DIR:-/run/}/mpd/socket if file exists
+ Retrieve MPD env. var. to overrides default "localhost:6600"
"""
+ # Set some defaults
self.host = 'localhost'
- self.pwd = None
- self.port = os.environ.get('MPD_PORT', '6600')
- mpd_host_env = os.environ.get('MPD_HOST')
- if mpd_host_env:
- # If password is set:
- # mpd_host_env = ['pass', 'host'] because MPD_HOST=pass@host
- mpd_host_env = mpd_host_env.split('@')
- mpd_host_env.reverse()
- self.host = mpd_host_env[0]
- if len(mpd_host_env) > 1 and mpd_host_env[1]:
- self.pwd = mpd_host_env[1]
+ self.port = os.getenv('MPD_PORT', '6600')
+ _host = os.getenv('MPD_HOST', '')
+ if _host:
+ # If password is set: MPD_HOST=pass@host
+ if '@' in _host:
+ mpd_host_env = _host.split('@', 1)
+ if mpd_host_env[0]:
+ # A password is actually set
+ log.debug('password detected in MPD_HOST, set client pwd attribute')
+ self.pwd = mpd_host_env[0]
+ if mpd_host_env[1]:
+ self.host = mpd_host_env[1]
+ log.debug('host detected in MPD_HOST: %s', self.host)
+ elif mpd_host_env[1]:
+ # No password set but leading @ is an abstract socket
+ self.host = '@'+mpd_host_env[1]
+ log.debug('host detected in MPD_HOST: %s (abstract socket)', self.host)
+ else:
+ # MPD_HOST is a plain host
+ self.host = _host
+ log.debug('host detected in MPD_HOST: @%s', self.host)
else:
# Is socket there
- xdg_runtime_dir = os.environ.get('XDG_RUNTIME_DIR', '/run')
+ xdg_runtime_dir = os.getenv('XDG_RUNTIME_DIR', '/run')
rundir = os.path.join(xdg_runtime_dir, 'mpd/socket')
if os.path.exists(rundir):
self.host = rundir
+ log.debug('host detected in ${XDG_RUNTIME_DIR}/run: %s (unix socket)', self.host)
+ _mpd_timeout = os.getenv('MPD_TIMEOUT', '')
+ if _mpd_timeout.isdigit():
+ self.mpd_timeout = int(_mpd_timeout)
+ log.debug('timeout detected in MPD_TIMEOUT: %d', self.mpd_timeout)
+ else: # Use CONNECTION_TIMEOUT as default even if MPD_TIMEOUT carries gargage
+ self.mpd_timeout = CONNECTION_TIMEOUT
def __getattr__(self, attr):
if attr == 'send_noidle': # have send_noidle to cancel idle as well as noidle
- return self.noidle()
+ return self.noidle
if attr.startswith("send_"):
command = attr.replace("send_", "", 1)
wrapper = self._send
if command not in self._commands:
command = command.replace("_", " ")
if command not in self._commands:
- raise AttributeError("'%s' object has no attribute '%s'" %
- (self.__class__.__name__, attr))
+ cls = self.__class__.__name__
+ raise AttributeError(f"'{cls}' object has no attribute '{attr}'")
return lambda *args: wrapper(command, args)
def _send(self, command, args):
if retval is not None:
self._pending.append(command)
- def _fetch(self, command, args=None):
+ def _fetch(self, command, args=None): # pylint: disable=unused-argument
+ cmd_fmt = command.replace(" ", "_")
if self._command_list is not None:
- raise CommandListError("Cannot use fetch_%s in a command list" %
- command.replace(" ", "_"))
+ raise CommandListError(f"Cannot use fetch_{cmd_fmt} in a command list")
if self._iterating:
- raise IteratingError("Cannot use fetch_%s while iterating" %
- command.replace(" ", "_"))
+ raise IteratingError(f"Cannot use fetch_{cmd_fmt} while iterating")
if not self._pending:
raise PendingCommandError("No pending commands to fetch")
if self._pending[0] != command:
- raise PendingCommandError("'%s' is not the currently "
- "pending command" % command)
+ raise PendingCommandError(f"'{command}' is not the currently pending command")
del self._pending[0]
retval = self._commands[command]
if callable(retval):
return retval()
return retval
- def _execute(self, command, args):
+ def _execute(self, command, args): # pylint: disable=unused-argument
if self._iterating:
- raise IteratingError("Cannot execute '%s' while iterating" %
- command)
+ raise IteratingError(f"Cannot execute '{command}' while iterating")
if self._pending:
- raise PendingCommandError(
- "Cannot execute '%s' with pending commands" % command)
+ raise PendingCommandError(f"Cannot execute '{command}' with pending commands")
retval = self._commands[command]
if self._command_list is not None:
if not callable(retval):
- raise CommandListError(
- "'%s' not allowed in command list" % command)
+ raise CommandListError(f"'{command}' not allowed in command list")
self._write_command(command, args)
self._command_list.append(retval)
else:
if callable(retval):
return retval()
return retval
+ return None
def _write_line(self, line):
- self._wfile.write("%s\n" % line)
+ self._wfile.write(f"{line!s}\n")
self._wfile.flush()
def _write_command(self, command, args=None):
parts.append('{0!s}'.format(Range(arg)))
else:
parts.append('"%s"' % escape(str(arg)))
+ if '\n' in ' '.join(parts):
+ raise CommandError('new line found in the command!')
self._write_line(" ".join(parts))
def _read_binary(self, amount):
raise CommandError(error)
if self._command_list is not None:
if line == NEXT:
- return
+ return None
if line == SUCCESS:
- raise ProtocolError("Got unexpected '%s'" % SUCCESS)
+ raise ProtocolError(f"Got unexpected '{SUCCESS}'")
elif line == SUCCESS:
- return
+ return None
return line
def _read_pair(self, separator, binary=False):
line = self._read_line(binary=binary)
if line is None:
- return
+ return None
pair = line.split(separator, 1)
if len(pair) < 2:
- raise ProtocolError("Could not parse pair: '%s'" % line)
+ raise ProtocolError(f"Could not parse pair: '{line}'")
return pair
def _read_pairs(self, separator=": ", binary=False):
for key, value in self._read_pairs():
if key != seen:
if seen is not None:
- raise ProtocolError("Expected key '%s', got '%s'" %
- (seen, key))
+ raise ProtocolError(f"Expected key '{seen}', got '{key}'")
seen = key
yield value
def _fetch_nothing(self):
line = self._read_line()
if line is not None:
- raise ProtocolError("Got unexpected return value: '%s'" % line)
+ raise ProtocolError(f"Got unexpected return value: '{line}'")
def _fetch_item(self):
pairs = list(self._read_pairs())
if len(pairs) != 1:
- return
+ return None
return pairs[0][1]
@iterator_wrapper
try:
obj['data'] = self._read_binary(amount)
except IOError as err:
- raise ConnectionError('Error reading binary content: %s' % err)
- if len(obj['data']) != amount:
+ raise ConnectionError(f'Error reading binary content: {err}') from err
+ data_bytes = len(obj['data'])
+ if data_bytes != amount: # can we ever get there?
raise ConnectionError('Error reading binary content: '
- 'Expects %sB, got %s' % (amount, len(obj['data'])))
+ f'Expects {amount}B, got {data_bytes}')
# Fetches trailing new line
self._read_line(binary=True)
# Fetches SUCCESS code
raise ConnectionError("Connection lost while reading MPD hello")
line = line.rstrip("\n")
if not line.startswith(HELLO_PREFIX):
- raise ProtocolError("Got invalid MPD hello: '%s'" % line)
+ raise ProtocolError(f"Got invalid MPD hello: '{line}'")
self.mpd_version = line[len(HELLO_PREFIX):].strip()
def _reset(self):
- self.mpd_version = None
+ self.mpd_version = ''
self._iterating = False
self._pending = []
self._command_list = None
def _connect_unix(self, path):
if not hasattr(socket, "AF_UNIX"):
- raise ConnectionError(
- "Unix domain sockets not supported on this platform")
+ raise ConnectionError("Unix domain sockets not supported on this platform")
+ # abstract socket
+ if path.startswith('@'):
+ path = '\0'+path[1:]
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+ sock.settimeout(self.mpd_timeout)
sock.connect(path)
+ sock.settimeout(self.socket_timeout)
return sock
def _connect_tcp(self, host, port):
sock = None
try:
sock = socket.socket(af, socktype, proto)
- sock.settimeout(CONNECTION_TIMEOUT)
+ sock.settimeout(self.mpd_timeout)
sock.connect(sa)
- sock.settimeout(None)
+ sock.settimeout(self.socket_timeout)
return sock
except socket.error as socket_err:
err = socket_err
sock.close()
if err is not None:
raise ConnectionError(str(err))
- else:
- raise ConnectionError("getaddrinfo returns an empty list")
+ raise ConnectionError("getaddrinfo returns an empty list")
def noidle(self):
# noidle's special case
if not self._pending or self._pending[0] != 'idle':
- raise CommandError(
- 'cannot send noidle if send_idle was not called')
+ raise CommandError('cannot send noidle if send_idle was not called')
del self._pending[0]
self._write_command("noidle")
return self._fetch_list()
def connect(self, host=None, port=None):
"""Connects the MPD server
- :param str host: hostname, IP or FQDN (defaults to `localhost` or socket, see below for details)
- :param port: port number (defaults to 6600)
+ :param str host: hostname, IP or FQDN (defaults to *localhost* or socket)
+ :param port: port number (defaults to *6600*)
:type port: str or int
- The connect method honors MPD_HOST/MPD_PORT environment variables.
-
- .. note:: Default host/port
+ If host/port are :py:obj:`None` the socket uses :py:attr:`host`/:py:attr:`port`
+ attributes as defaults. Cf. :py:obj:`MPDClient` for the logic behind default host/port.
- If host evaluate to :py:obj:`False`
- * use ``MPD_HOST`` environment variable if set, extract password if present,
- * else looks for a existing file in ``${XDG_RUNTIME_DIR:-/run/}/mpd/socket``
- * else set host to ``localhost``
+ The underlying socket also honors :envvar:`MPD_TIMEOUT` environment variable
+ and defaults to :py:obj:`musicpd.CONNECTION_TIMEOUT` (connect command only).
- If port evaluate to :py:obj:`False`
- * if ``MPD_PORT`` environment variable is set, use it for port
- * else use ``6600``
+ If you want to have a timeout for each command once you got connected,
+ set its value in :py:obj:`MPDClient.socket_timeout` (in second) or at
+ module level in :py:obj:`musicpd.SOCKET_TIMEOUT`.
"""
if not host:
host = self.host
self.port = port
if self._sock is not None:
raise ConnectionError("Already connected")
- if host.startswith("/"):
+ if host[0] in ['/', '@']:
+ log.debug('Connecting unix socket %s', host)
self._sock = self._connect_unix(host)
else:
+ log.debug('Connecting tcp socket %s:%s (timeout: %ss)', host, port, self.mpd_timeout)
self._sock = self._connect_tcp(host, port)
self._rfile = self._sock.makefile("r", encoding='utf-8', errors='surrogateescape')
self._rbfile = self._sock.makefile("rb")
except:
self.disconnect()
raise
+ log.debug('Connected')
+
+ @property
+ def socket_timeout(self):
+ """Socket timeout in second (defaults to :py:obj:`SOCKET_TIMEOUT`).
+ Use None to disable socket timout."""
+ return self._socket_timeout
+
+ @socket_timeout.setter
+ def socket_timeout(self, timeout):
+ self._socket_timeout = timeout
+ if getattr(self._sock, 'settimeout', False):
+ self._sock.settimeout(self._socket_timeout)
def disconnect(self):
"""Closes the MPD connection.
self._sock.close()
self._reset()
+ def __enter__(self):
+ self.connect()
+ return self
+
+ def __exit__(self, exception_type, exception_value, exception_traceback):
+ self.disconnect()
+
def fileno(self):
+ """Return the socket’s file descriptor (a small integer).
+ This is useful with :py:obj:`select.select`.
+ """
if self._sock is None:
raise ConnectionError("Not connected")
return self._sock.fileno()
if self._iterating:
raise IteratingError("Cannot begin command list while iterating")
if self._pending:
- raise PendingCommandError("Cannot begin command list "
- "with pending commands")
+ raise PendingCommandError("Cannot begin command list with pending commands")
self._write_command("command_list_ok_begin")
self._command_list = []