From 010d7a7061e172a0e75f4bacce601e3025372500 Mon Sep 17 00:00:00 2001
From: Kaliko Jack <kaliko@azylum.org>
Date: Sat, 18 Dec 2021 09:45:38 +0100
Subject: [PATCH] Document context manager

---
 CHANGES.txt        |  1 +
 doc/source/use.rst | 25 +++++++++++++++++++++++--
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index 8f2846e..b07388d 100644
--- 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 a071084..29b6e53 100644
--- 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
 -------------
 
-- 
2.39.5