Improved documentation

[python-musicpd.git] / musicpd.py

diff --git a/musicpd.py b/musicpd.py
index ae12e1da501235b81f03846927054617795de51f..8c5bfc32c155e7cd1b8179ecdca217185239f591 100644 (file)
--- a/musicpd.py
+++ b/musicpd.py
@@ -1,7 +1,8 @@
 # python-musicpd: Python MPD client library
-# Copyright (C) 2008-2010  J. Alexander Treuman <jat@spatialrift.net>
-# Copyright (C) 2012-2019  Kaliko Jack <kaliko@azylum.org>
+# Copyright (C) 2012-2019  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
@@ -28,7 +29,9 @@ HELLO_PREFIX = "OK MPD "
 ERROR_PREFIX = "ACK "
 SUCCESS = "OK"
 NEXT = "list_OK"
-VERSION = '0.4.4'
+VERSION = '0.4.5'
+#: seconds before a tcp connection attempt times out
+CONNECTION_TIMEOUT = 5
 
 
 def iterator_wrapper(func):
@@ -116,10 +119,10 @@ 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.
+    accordingly. Regarding ``MPD_HOST`` format to expose password refer
+    MPD client manual :manpage:`mpc (1)`.
 
     Then :py:obj:`musicpd.MPDClient.connect` will use ``host`` and ``port`` as defaults if not provided as args.
 
@@ -132,7 +135,24 @@ class MPDClient:
     True
     >>> cli.host == environ['MPD_HOST'].split('@')[1]
     True
-    >>> # cli.connect() will use host/port as set in MPD_HOST/MPD_PORT
+    >>> 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
+
+    .. 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.
+
+      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
     """
 
     def __init__(self):
@@ -204,7 +224,7 @@ class MPDClient:
             "rm":                 self._fetch_nothing,
             "save":               self._fetch_nothing,
             # Database Commands
-            #"albumart":           self._fetch_object,
+            "albumart":           self._fetch_composite,
             "count":              self._fetch_object,
             "find":               self._fetch_songs,
             "findadd":            self._fetch_nothing,
@@ -502,6 +522,17 @@ class MPDClient:
     def _fetch_neighbors(self):
         return self._fetch_objects(["neighbor"])
 
+    def _fetch_composite(self):
+        obj = {}
+        for key, value in self._read_pairs():
+            key = key.lower()
+            obj[key] = value
+            if key == 'binary':
+                break
+        by = self._read_line()
+        obj['data'] = by.encode(errors='surrogateescape')
+        return obj
+
     @iterator_wrapper
     def _fetch_command_list(self):
         return self._read_command_list()
@@ -545,7 +576,9 @@ class MPDClient:
             sock = None
             try:
                 sock = socket.socket(af, socktype, proto)
+                sock.settimeout(CONNECTION_TIMEOUT)
                 sock.connect(sa)
+                sock.settimeout(None)
                 return sock
             except socket.error as socket_err:
                 err = socket_err
@@ -569,32 +602,37 @@ class MPDClient:
         """Connects the MPD server
 
         :param str host: hostname, IP or FQDN (defaults to `localhost` or socket, see below for details)
-        :param str port: port number (defaults to 6600)
+        :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 evaluate to :py:obj:`False`
-           * use ``MPD_HOST`` env. var. if set, extract password if present,
+           * 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``
 
           If port evaluate to :py:obj:`False`
-           * if ``MPD_PORT`` env. var. is set, use it for port
+           * if ``MPD_PORT`` environment variable is set, use it for port
            * else use ``6600``
         """
         if not host:
             host = self.host
+        else:
+            self.host = host
         if not port:
             port = self.port
+        else:
+            self.port = port
         if self._sock is not None:
             raise ConnectionError("Already connected")
         if host.startswith("/"):
             self._sock = self._connect_unix(host)
         else:
             self._sock = self._connect_tcp(host, port)
-        self._rfile = self._sock.makefile("r", encoding='utf-8')
+        self._rfile = self._sock.makefile("r", encoding='utf-8', errors='surrogateescape')
         self._wfile = self._sock.makefile("w", encoding='utf-8')
         try:
             self._hello()