written to the socket. To avoid confusion use regular string instead of relying
on object string representation.
-:py:class:`musicpd.MPDClient` methods returns different kinds of objects depending on the command. Could be :py:obj:`None`, a single object as a :py:obj:`str` or a :py:obj:`dict`, a list of :py:obj:`dict`.
+:py:class:`musicpd.MPDClient` methods returns different kinds of objects
+depending on the command. Could be :py:obj:`None`, a single object as a
+:py:obj:`str` or a :py:obj:`dict`, a list of :py:obj:`dict`.
-For more about the protocol and MPD commands see the `MPD protocol
-documentation`_.
+Then :py:class:`musicpd.MPDClient` **methods signatures** are not hard coded
+within this module since the protocol is handled on the server side. Please
+refer to the protocol and MPD commands in `MPD protocol documentation`_ to
+learn how to call commands and what kind of arguments they expect.
+
+Some examples are provided for the most common cases, see :ref:`examples`.
For a list of currently supported commands in this python module see
:ref:`commands`.
Default host:
* use :envvar:`MPD_HOST` environment variable if set, extract password if present,
- * else looks for an existing file in :envvar:`${XDG_RUNTIME_DIR:-/run/}/mpd/socket`
+ * else use :envvar:`XDG_RUNTIME_DIR` to looks for an existing file in ``${XDG_RUNTIME_DIR}/mpd/socket``, :envvar:`XDG_RUNTIME_DIR` defaults to ``/run`` if not set.
* else set host to ``localhost``
Default port:
- * use :envvar:`MPD_PORT` environment variable is set
+ * use :envvar:`MPD_PORT` environment variable if set
* else use ``6600``
Default timeout:
- * use :envvar:`MPD_TIMEOUT` is set
+ * use :envvar:`MPD_TIMEOUT` if set
* else use :py:obj:`musicpd.CONNECTION_TIMEOUT`
Context manager
>>> print('something went wrong', file=sys.stderr)
>>> cli.disconnect()
-A `CommandError` is raised if the album does not expose a cover.
+A :py:obj:`musicpd.CommandError` is raised if the album does not expose a cover.
You can also use `readpicture` command to fetch embedded picture:
could also be that MPD took too much time to answer, but MPD taking more than a
couple of seconds for these commands should never occur).
+.. _exceptions:
+
+Exceptions
+----------
+
+The :py:obj:`connect<musicpd.MPDClient.connect>` method raises
+:py:obj:`ConnectionError<musicpd.ConnectionError>` only (an :py:obj:`MPDError<musicpd.MPDError>` exception) but then, calling other MPD commands, the module can raise
+:py:obj:`MPDError<musicpd.MPDError>` or an :py:obj:`OSError` depending on the error and
+where it occurs.
+
+Then using musicpd module both :py:obj:`musicpd.MPDError` and :py:obj:`OSError`
+exceptions families are expected, see :ref:`examples<exceptions_example>` for a
+way to deal with this.
.. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/
.. _snake case: https://en.wikipedia.org/wiki/Snake_case