python-musicpd Changes List
===========================
-Changes in 0.6.1
+Changes in 0.7.0
----------------
+* Add socket timeout (disabled by default)
+* MPD_TIMEOUT is set for both tcp and unix sockets
* Raises an exception if command contains '\n'
-
Changes in 0.6.0
----------------
.. autodata:: musicpd.CONNECTION_TIMEOUT
+.. autodata:: musicpd.SOCKET_TIMEOUT
+
.. autoclass:: musicpd.MPDClient
:members:
| 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
+ * ``MPD_TIMEOUT`` timeout for connecting to MPD and waiting for MPD’s response in seconds
* ``XDG_RUNTIME_DIR`` path to look for potential socket: ``${XDG_RUNTIME_DIR}/mpd/socket``
Defaults settings
Refer to `MPD protocol documentation`_ for the meaning of `binary`, `size` and `data`.
+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 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 to 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/
ERROR_PREFIX = "ACK "
SUCCESS = "OK"
NEXT = "list_OK"
-VERSION = '0.6.1'
-#: seconds before a tcp connection attempt times out (overriden by MPD_TIMEOUT env. var.)
+VERSION = '0.7.0'
+#: Seconds before a connection attempt times out
+#: (overriden by MPD_TIMEOUT env. var.)
CONNECTION_TIMEOUT = 30
-
+#: Socket timeout in second (Default is None for no timeout)
+SOCKET_TIMEOUT = None
def iterator_wrapper(func):
def __init__(self):
self.iterate = False
+ #: 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
+ self.mpd_timeout = None
self._reset()
self._commands = {
# Status Commands
self.mpd_timeout = os.getenv('MPD_TIMEOUT')
if self.mpd_timeout and self.mpd_timeout.isdigit():
self.mpd_timeout = int(self.mpd_timeout)
- else: # Use 30s default even is MPD_TIMEOUT carries gargage
+ else: # Use CONNECTION_TIMEOUT as default even if MPD_TIMEOUT carries gargage
self.mpd_timeout = CONNECTION_TIMEOUT
def __getattr__(self, attr):
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 = socket.socket(af, socktype, proto)
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
The connect method honors MPD_HOST/MPD_PORT environment variables.
- The underlying tcp socket also honors MPD_TIMEOUT environment variable
- and defaults to :py:obj:`musicpd.CONNECTION_TIMEOUT`.
+ The underlying socket also honors 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 a existing file in ``${XDG_RUNTIME_DIR:-/run/}/mpd/socket``
+ * 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`
self.disconnect()
raise
+ @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.
The client closes the actual socket, it does not use the
home / dev / repositories / python-musicpd.git / commitdiff