X-Git-Url: http://git.kaliko.me/?p=python-musicpd.git;a=blobdiff_plain;f=musicpd.py;h=87bcaca0980b33b8e27a5e380b340bbec392ce85;hp=61ca97b645fb4e4a3341a333f41174b3015c7c9f;hb=refs%2Fheads%2Fmaster;hpb=0c16ca07e3ac85ab212c3444f9e5a71c4a96a406 diff --git a/musicpd.py b/musicpd.py index 61ca97b..e24b51d 100644 --- a/musicpd.py +++ b/musicpd.py @@ -1,26 +1,16 @@ -# python-musicpd: Python MPD client library -# Copyright (C) 2012-2021 kaliko -# Copyright (C) 2019 Naglis Jonaitis -# Copyright (C) 2019 Bart Van Loon -# Copyright (C) 2008-2010 J. Alexander Treuman -# -# 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 . - -# pylint: disable=missing-docstring +# -*- coding: utf-8 -*- +# SPDX-FileCopyrightText: 2012-2024 kaliko +# SPDX-FileCopyrightText: 2021 Wonko der Verständige +# SPDX-FileCopyrightText: 2019 Naglis Jonaitis +# SPDX-FileCopyrightText: 2019 Bart Van Loon +# SPDX-FileCopyrightText: 2008-2010 J. Alexander Treuman +# 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 @@ -28,13 +18,16 @@ HELLO_PREFIX = "OK MPD " ERROR_PREFIX = "ACK " SUCCESS = "OK" NEXT = "list_OK" -VERSION = '0.7.0' +#: Module version +VERSION = '0.9.0' #: Seconds before a connection attempt times out -#: (overriden by MPD_TIMEOUT env. var.) +#: (overriden by :envvar:`MPD_TIMEOUT` env. var.) CONNECTION_TIMEOUT = 30 -#: Socket timeout in second (Default is None for no timeout) +#: Socket timeout in second > 0 (Default is :py:obj:`None` for no timeout) SOCKET_TIMEOUT = None +log = logging.getLogger(__name__) + def iterator_wrapper(func): """Decorator handling iterate option""" @@ -56,59 +49,73 @@ 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: @@ -116,19 +123,20 @@ 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' @@ -139,22 +147,29 @@ class MPDClient: 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:: - .. warning:: Instance attribute host/port/pwd + 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`` - 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 + default port: + * use :envvar:`MPD_PORT` environment variable is set + * else use ``6600`` + + .. 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 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 MPS's password method 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 - will not be used as default value for the :py:meth:`password` method + 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 MPD's password command. """ def __init__(self): @@ -162,8 +177,12 @@ class MPDClient: #: Socket timeout value in seconds self._socket_timeout = SOCKET_TIMEOUT #: Current connection timeout value, defaults to - #: :py:attr:`musicpd.MPD_TIMEOUT` or env. var. ``MPD_TIMEOUT`` if provided + #: :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 @@ -296,47 +315,58 @@ class MPDClient: "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.getenv('MPD_PORT', '6600') - if os.getenv('MPD_HOST'): + _host = os.getenv('MPD_HOST', '') + if _host: # If password is set: MPD_HOST=pass@host - if '@' in os.getenv('MPD_HOST'): - mpd_host_env = os.getenv('MPD_HOST').split('@', 1) + 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 = os.getenv('MPD_HOST') + self.host = _host + log.debug('host detected in MPD_HOST: %s', self.host) else: # Is socket there 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 - self.mpd_timeout = os.getenv('MPD_TIMEOUT') - if self.mpd_timeout and self.mpd_timeout.isdigit(): - self.mpd_timeout = int(self.mpd_timeout) + 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 @@ -349,8 +379,8 @@ class MPDClient: 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): @@ -362,36 +392,31 @@ class MPDClient: 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: @@ -399,9 +424,10 @@ class MPDClient: 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): @@ -410,9 +436,9 @@ class MPDClient: parts = [command] for arg in args: if isinstance(arg, tuple): - parts.append('{0!s}'.format(Range(arg))) + parts.append(f'{Range(arg)!s}') else: - parts.append('"%s"' % escape(str(arg))) + parts.append(f'"{escape(str(arg))}"') if '\n' in ' '.join(parts): raise CommandError('new line found in the command!') self._write_line(" ".join(parts)) @@ -442,20 +468,20 @@ class MPDClient: 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): @@ -469,8 +495,7 @@ class MPDClient: 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 @@ -509,12 +534,12 @@ class MPDClient: 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 @@ -577,10 +602,11 @@ class MPDClient: try: obj['data'] = self._read_binary(amount) except IOError as err: - raise ConnectionError('Error reading binary content: %s' % err) - if len(obj['data']) != amount: # can we ever get there? + 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 @@ -597,11 +623,11 @@ class MPDClient: 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 @@ -612,15 +638,17 @@ class MPDClient: 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) + try: + sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + sock.settimeout(self.mpd_timeout) + sock.connect(path) + sock.settimeout(self.socket_timeout) + except socket.error as socket_err: + raise ConnectionError(socket_err) from socket_err return sock def _connect_tcp(self, host, port): @@ -629,31 +657,35 @@ class MPDClient: except AttributeError: flags = 0 err = None - for res in socket.getaddrinfo(host, port, socket.AF_UNSPEC, - socket.SOCK_STREAM, socket.IPPROTO_TCP, - flags): + try: + gai = socket.getaddrinfo(host, port, socket.AF_UNSPEC, + socket.SOCK_STREAM, socket.IPPROTO_TCP, + flags) + except socket.error as gaierr: + raise ConnectionError(gaierr) from gaierr + for res in gai: af, socktype, proto, _, sa = res sock = None try: + log.debug('opening socket %s', sa) sock = socket.socket(af, socktype, proto) sock.settimeout(self.mpd_timeout) sock.connect(sa) sock.settimeout(self.socket_timeout) return sock except socket.error as socket_err: + log.debug('opening socket %s failed: %s', sa, socket_err) err = socket_err if sock is not None: sock.close() if err is not None: - raise ConnectionError(str(err)) - else: - raise ConnectionError("getaddrinfo returns an empty list") + raise ConnectionError(err) + 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() @@ -661,29 +693,19 @@ class MPDClient: 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. + 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. - The underlying socket also honors MPD_TIMEOUT environment variable + The underlying socket also honors :envvar:`MPD_TIMEOUT` environment variable and defaults to :py:obj:`musicpd.CONNECTION_TIMEOUT` (connect command only). 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`. - - .. note:: Default host/port - - If host evaluate to :py:obj:`False` - * use ``MPD_HOST`` environment variable if set, extract password if present, - * else looks for an existing file in ``${XDG_RUNTIME_DIR:-/run/}/mpd/socket`` - * else set host to ``localhost`` - - If port evaluate to :py:obj:`False` - * if ``MPD_PORT`` environment variable is set, use it for port - * else use ``6600`` """ if not host: host = self.host @@ -696,8 +718,10 @@ class MPDClient: if self._sock is not None: raise ConnectionError("Already connected") 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") @@ -707,19 +731,30 @@ class MPDClient: 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.""" + Use :py:obj:`None` to disable socket timout. + + :setter: Set the socket timeout (integer > 0) + :type: int or None + """ return self._socket_timeout @socket_timeout.setter def socket_timeout(self, timeout): - self._socket_timeout = timeout + if timeout is not None: + if int(timeout) <= 0: + raise ValueError('socket_timeout expects a non zero positive integer') + self._socket_timeout = int(timeout) + else: + self._socket_timeout = timeout if getattr(self._sock, 'settimeout', False): self._sock.settimeout(self._socket_timeout) + def disconnect(self): """Closes the MPD connection. The client closes the actual socket, it does not use the @@ -735,6 +770,13 @@ class MPDClient: 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`. @@ -749,8 +791,7 @@ class MPDClient: 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 = []