Fixed unused argument

[python-musicpdaio.git] / doc / source / explanations.rst

diff --git a/doc/source/explanations.rst b/doc/source/explanations.rst
index 48724bfeb60c46b24f5f5dd653252a2fa2f50877..ecc0b9bf22bad4d6360eeb304ecb4625b1afb2db 100644 (file)
--- a/doc/source/explanations.rst
+++ b/doc/source/explanations.rst
@@ -3,13 +3,14 @@
 Explanations
 ============
 
 Explanations
 ============
 

-What is musicpdaio?
--------------------
-

  |  « Concurrency is about dealing with lots of things at once. »
  |  Concurrency is not Parallelism -- Rob Pike
 
  |  « 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.
 
 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
 ----------------
 
  * 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
 
 
 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`.
 
 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
 **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.
 
 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`.
 
 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`.
 
 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
 **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
 
 .. vim: spell spelllang=en