Add more docstrings

[python-musicpdaio.git] / mpdaio / client.py

diff --git a/mpdaio/client.py b/mpdaio/client.py
index 48b37bdded25075def30db52f214d4d5db45c978..c37e0d6cc3946cb573104b23863519227c8d1a50 100644 (file)
--- a/mpdaio/client.py
+++ b/mpdaio/client.py
@@ -17,16 +17,38 @@ log = logging.getLogger(__name__)
 
 
 class MPDClient:
+    """:synopsis: Main class to instanciate building an MPD client.
 
-    def __init__(self, host: str | None = None, port: str | int | None = None, password: str | None = None):
+    :param host: MPD server IP|FQDN to connect to
+    :param port: MPD port to connect to
+    :param password: MPD password
+
+    **musicpdaio** tries to come with sane defaults, then running
+    |mpdaio.MPDClient| with no explicit argument will try default values
+    to connect to MPD. Cf. :ref:`reference` for more about
+    :ref:`defaults<default_settings>`.
+
+    The class is also exposed in mpdaio namespace.
+
+    >>> import mpdaio
+    >>> cli = mpdaio.MPDClient(host='example.org')
+    >>> print(await cli.currentsong())
+    >>> await cli.close()
+    """
+
+    def __init__(self, host: str | None = None,
+            port: str | int | None = None,
+            password: str | None = None):
+        #: Connection pool
         self._pool = ConnectionPool(max_connections=CONNECTION_MAX)
         self._get_envvars()
-        #: host used with the current connection (:py:obj:`str`)
+        #: Host used to make connections (:py:obj:`str`)
         self.host = host or self.server_discovery[0]
-        #: password detected in :envvar:`MPD_HOST` environment variable (:py:obj:`str`)
+        #: password used to connect (:py:obj:`str`)
         self.pwd = password or self.server_discovery[2]
         #: port used with the current connection (:py:obj:`int`, :py:obj:`str`)
         self.port = port or self.server_discovery[1]
+        #: connection timeout
         self.mpd_timeout = CONNECTION_TIMEOUT
         log.info('Using %s:%s to connect', self.host, self.port)
 
@@ -87,8 +109,9 @@ class MPDClient:
         return lambda *args: wrapper(command, args)
 
     @property
-    def version(self):
-        """MPD protocol version"""
+    def version(self) -> str:
+        """MPD protocol version
+        """
         host = (self.host, self.port)
         version = {_.version for _ in self.connections}
         if not version:
@@ -99,12 +122,13 @@ class MPDClient:
         return version.pop()
 
     @property
-    def connections(self):
-        """Open connections"""
+    def connections(self) -> list[Connection]:
+        """connections in the pool"""
         host = (self.host, self.port)
         return self._pool._connections.get(host, [])
 
-    async def close(self):
+    async def close(self) -> None:
+        """:synopsis: Close connections in the pool"""
         await self._pool.close()