X-Git-Url: http://git.kaliko.me/?a=blobdiff_plain;f=musicpd.py;h=ed2e01ee5f3b4b0d148d6bf07c5ae478e57536ae;hb=9e5f6e0992455bb7e640ee9c4b1169648278ddfc;hp=50c35dd33bdd80342f38b230f674e399a5445f13;hpb=7de98640722cf64c68d89d3e82067f8f9eb75a49;p=python-musicpd.git diff --git a/musicpd.py b/musicpd.py index 50c35dd..ed2e01e 100644 --- a/musicpd.py +++ b/musicpd.py @@ -1,10 +1,11 @@ +# -*- coding: utf-8 -*- # SPDX-FileCopyrightText: 2012-2023 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-musicpd: Python Music Player Daemon client library""" +"""Python Music Player Daemon client library""" import socket @@ -16,9 +17,10 @@ HELLO_PREFIX = "OK MPD " ERROR_PREFIX = "ACK " SUCCESS = "OK" NEXT = "list_OK" +#: Module version VERSION = '0.9.0b0' #: 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 = None @@ -44,59 +46,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) as err: - raise CommandError('Not a tuple of int') from err + 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: @@ -109,14 +125,15 @@ class _NotConnected: 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' @@ -127,21 +144,28 @@ 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 :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 """ @@ -288,21 +312,26 @@ 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 self.pwd = mpd_host_env[0] @@ -313,22 +342,22 @@ class MPDClient: self.host = '@'+mpd_host_env[1] else: # MPD_HOST is a plain host - self.host = os.getenv('MPD_HOST') + self.host = _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) + _mpd_timeout = os.getenv('MPD_TIMEOUT', '') + if _mpd_timeout.isdigit(): + self.mpd_timeout = int(_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 @@ -646,29 +675,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