Document context manager

diff --git a/CHANGES.txt b/CHANGES.txt
index 8f2846e12c3d51cdde036a80992f61a90fa630ca..b07388df71b70c960ad284e3a8d7d4bffed06dba 100644 (file)
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -5,6 +5,7 @@ Changes in 0.8.0
 ----------------
 
 * Need python 3.6 minimum (modernize code)
+* Add context management for MPDClient instance (Thanks Wonko der Verständige)
 
 Changes in 0.7.0
 ----------------

diff --git a/doc/source/use.rst b/doc/source/use.rst
index a071084fb1650c8095634d9ecafb3bf23196ca19..29b6e53e1cfbcea9c2f824437e25801af6caadd2 100644 (file)
--- a/doc/source/use.rst
+++ b/doc/source/use.rst
@@ -24,6 +24,8 @@ them), and the functions used to parse their responses see :ref:`commands`.
 
 See the `MPD protocol documentation`_ for more details.
 
+.. _environment_variables:
+
 Environment variables
 ---------------------
 
@@ -38,14 +40,33 @@ The client honors the following environment variables:
   * ``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
------------------
+.. _default_settings:
+
+Default settings
+----------------
 
   * If ``MPD_HOST`` is not set, then look for a socket in ``${XDG_RUNTIME_DIR}/mpd/socket``
   * If there is no socket use ``localhost``
   * If ``MPD_PORT`` is not set, then use ``6600``
   * If ``MPD_TIMEOUT`` is not set, then uses :py:obj:`musicpd.CONNECTION_TIMEOUT`
 
+
+Context manager
+---------------
+
+Calling MPDClient in a context manager :py:obj:`musicpd.MPDClient.connect` is
+transparently called with :ref:`default setting<default_settings>` (use
+:ref:`environment variables<environment_variables>` to override defaults).
+Leaving the context manager :py:obj:`musicpd.MPDClient.disconnect` is called.
+
+.. code-block:: python
+
+    import os
+    os.environ['MPD_HOST'] = 'mpdhost'
+    with MPDClient() as c:
+        c.status()
+        c.next()
+
 Command lists
 -------------