X-Git-Url: http://git.kaliko.me/?a=blobdiff_plain;f=doc%2Fsource%2Fexplanations.rst;h=ecc0b9bf22bad4d6360eeb304ecb4625b1afb2db;hb=refs%2Fheads%2Fmain;hp=48724bfeb60c46b24f5f5dd653252a2fa2f50877;hpb=cdf2dd0c1021639a4aebae4eac44fbb09a224877;p=python-musicpdaio.git

diff --git a/doc/source/explanations.rst b/doc/source/explanations.rst
index 48724bf..ecc0b9b 100644
--- a/doc/source/explanations.rst
+++ b/doc/source/explanations.rst
@@ -3,13 +3,14 @@
 Explanations
 ============
 
-What is musicpdaio?
--------------------
-
  |  « Concurrency is about dealing with lots of things at once. »
  |  Concurrency is not Parallelism -- Rob Pike
 
-**musicpdaio** is the asyncio_ port of python-musicpd_.
+
+What is musicpdaio?
+-------------------
+
+**musicpdaio** is an asynchronous MPD (`Music Player Daemon`_) client library written in Python. It is the asyncio_ port of python-musicpd_.
 
 The goal of this project is to keep python-musicpd_ simplicity and provide
 asyncio_ support.
@@ -18,9 +19,9 @@ Should I use it?
 ----------------
 
  * If you need a plain MPD client to manage you MPD server, then stick with
-   no-ansynio module python-musicpd_
- * If you're building a interactive client, concurrent access to MPD or plugin
-   into another asyncio project then use musicpdaio.
+   non-asyncio module python-musicpd_
+ * If you're building an interactive client, concurrent access to MPD or need
+   to plug into another asyncio project then use musicpdaio.
 
 
 Using the client library
@@ -40,7 +41,7 @@ The MPD command protocol exchanges line-based text records. The client emits a
 command with optional arguments. In the example above the client sends a
 `setvol` command with the string argument `42`.
 
-MPD commands are exposed as :py:class:`mpdaio.MPDClient` methods. Methods
+MPD commands are exposed as |mpdaio.MPDClient| methods. Methods
 **arguments are python strings**. Some commands are composed of more than one word
 (ie "**tagtypes [disable|enable|all]**"), for these use a `snake case`_ style to
 access the method. Then **"tagtypes enable"** command is called with
@@ -52,31 +53,42 @@ strings. In the example above, an integer can be used as argument for the
 written to the socket. To avoid confusion use regular string instead of relying
 on object string representation.
 
-:py:class:`mpdaio.MPDClient` methods returns different kinds of objects
+|mpdaio.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`.
 
-Then :py:class:`mpdaio.MPDClient` **methods signatures** are not hard coded
+Then |mpdaio.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:`tutorial`.
 
-For a list of currently supported commands in this python module see
-:ref:`commands`.
-
 **musicpdaio** tries to come with sane defaults, then running
-:py:class:`mpdaio.MPDClient` with no explicit argument will try defaults values
-to connect to MPD. Cf. :ref:`reference` for more about defaults.
+|mpdaio.MPDClient| with no explicit argument will try default values
+to connect to MPD. Cf. :ref:`reference` for more about
+:ref:`defaults<default_settings>`.
+
+.. _socket_connections:
+.. index:: pair: connection pool; socket
 
+Socket connection
+-----------------
 
-.. _environment_variables:
+**musicpdaio** uses a connection pool internally to keep already opened socket
+and reuse it.
 
+When first instantiated |mpdaio.MPDClient| comes with an empty pool,
+when the first MPD command is called a connection is opened, saved and
+potentially reused later. In case a concurrent MPD command is called while the
+connection is still in use a new connection is made and kept in the pool.
+
+.. code-block:: python
 
-.. _snake case: https://en.wikipedia.org/wiki/Snake_case
-.. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/
-.. _asyncio: https://docs.python.org/3/library/asyncio.html
-.. _python-musicpd: https://kaliko.gitlab.io/python-musicpd
+   client = mpdaio.MPDClient()
+   client.connections    # Returns an empty list: []
+   client.version        # Returns empty string: ''
+   await client.ping()   # A connection is made and kept open
+   client.connections    # Returns a list; [Connection<example.org:6600>]
 
 .. vim: spell spelllang=en