X-Git-Url: http://git.kaliko.me/?p=python-musicpd.git;a=blobdiff_plain;f=musicpd.py;h=89d38e4d5c5d6c77e36d18b8f066c6300cb55f43;hp=10b15cbabec174e42ea22a151ca4ffe4100b4b65;hb=4b44d5f37ad29e54c356f7dcc97194eaabcecc03;hpb=1fb65355de64ef044d0a7b3736a21bed6a6ae290

diff --git a/musicpd.py b/musicpd.py
index 10b15cb..89d38e4 100644
--- a/musicpd.py
+++ b/musicpd.py
@@ -104,6 +104,24 @@ class _NotConnected:
         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.
+
+    Then :py:obj:`musicpd.MPDClient.connect` will use ``host`` and ``port`` as defaults if not provided as args.
+
+    Cf. :py:obj:`musicpd.MPDClient.connect` for details.
+
+    >>> from os inport environ
+    >>> environ['MPD_HOST'] = 'pass@mpdhost'
+    >>> cli = musicpd.MPDClient()
+    >>> cli.pwd == environ['MPD_HOST'].split('@')[0]
+    True
+    >>> cli.host == environ['MPD_HOST'].split('@')[1]
+    True
+    >>> # cli.connect() will use host/port as set in MPD_HOST/MPD_PORT
+    """
+
     def __init__(self):
         self.iterate = False
         self._reset()
@@ -230,7 +248,7 @@ class MPDClient:
             else use MPD_HOST=${XDG_RUNTIME_DIR:-/run/}/mpd/socket if file exists
         """
         self.host = 'localhost'
-        self.password = None
+        self.pwd = None
         self.port = os.environ.get('MPD_PORT', '6600')
         mpd_host_env = os.environ.get('MPD_HOST')
         if mpd_host_env:
@@ -240,7 +258,7 @@ class MPDClient:
             mpd_host_env.reverse()
             self.host = mpd_host_env[0]
             if len(mpd_host_env) > 1 and mpd_host_env[1]:
-                self.password = mpd_host_env[1]
+                self.pwd = mpd_host_env[1]
         else:
             # Is socket there
             xdg_runtime_dir = os.environ.get('XDG_RUNTIME_DIR', '/run')
@@ -523,6 +541,24 @@ class MPDClient:
         return self._fetch_list()
 
     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 str port: port number (defaults to 6600)
+
+        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,
+           * 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
+           * else use ``6600``
+        """
         if not host:
             host = self.host
         if not port:
@@ -542,6 +578,10 @@ class MPDClient:
             raise
 
     def disconnect(self):
+        """Closes the MPD connection.
+        The client closes the actual socket, it does not use the
+        'close' request from MPD protocol (as suggested in documentation).
+        """
         if hasattr(self._rfile, 'close'):
             self._rfile.close()
         if hasattr(self._wfile, 'close'):