-# SPDX-FileCopyrightText: 2012-2023 kaliko <kaliko@azylum.org>
+# -*- coding: utf-8 -*-
+# SPDX-FileCopyrightText: 2012-2024 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-musicpd: Python Music Player Daemon client library"""
+"""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.9.0b0'
+#: Module version
+VERSION = '0.9.0b2'
#: 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"""
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:
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``
- .. warning:: Instance attribute host/port/pwd
+ default port:
+ * use :envvar:`MPD_PORT` environment variable is set
+ * else use ``6600``
- 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
+ .. 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 :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
"""
"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')
_host = os.getenv('MPD_HOST', '')
if _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.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
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))
# 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):
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))
+ raise ConnectionError(err)
raise ConnectionError("getaddrinfo returns an empty list")
def noidle(self):
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
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")
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
+ :type: int or None (integer > 0)
+ """
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