X-Git-Url: http://git.kaliko.me/?a=blobdiff_plain;f=doc%2Fsource%2Fexplanations.rst;h=ecc0b9bf22bad4d6360eeb304ecb4625b1afb2db;hb=HEAD;hp=15155a0df07dd35d6ac35a541ecaa3cace63394e;hpb=a1bb332d045c1c375ad2fa331476ee95d964017c;p=python-musicpdaio.git diff --git a/doc/source/explanations.rst b/doc/source/explanations.rst index 15155a0..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. @@ -19,8 +20,8 @@ Should I use it? * If you need a plain MPD client to manage you MPD server, then stick with non-asyncio module python-musicpd_ - * If you're building an interactive client, concurrent access to MPD or plugin - into another asyncio project then use musicpdaio. + * 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,11 +53,11 @@ 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. @@ -64,7 +65,7 @@ learn how to call commands and what kind of arguments they expect. Some examples are provided for the most common cases, see :ref:`tutorial`. **musicpdaio** tries to come with sane defaults, then running -:py:class:`mpdaio.MPDClient` with no explicit argument will try default values +|mpdaio.MPDClient| with no explicit argument will try default values to connect to MPD. Cf. :ref:`reference` for more about :ref:`defaults`. @@ -77,7 +78,7 @@ Socket connection **musicpdaio** uses a connection pool internally to keep already opened socket and reuse it. -When first instantiated :py:class:`mpdaio.MPDClient` comes with an empty pool, +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. @@ -90,10 +91,4 @@ connection is still in use a new connection is made and kept in the pool. await client.ping() # A connection is made and kept open client.connections # Returns a list; [Connection] - -.. _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 - .. vim: spell spelllang=en