doc/source/explanations.rst

   1 .. _explanations:
   2
   3 Explanations
   4 ============
   5
   6  |  « Concurrency is about dealing with lots of things at once. »
   7  |  Concurrency is not Parallelism -- Rob Pike
   8
   9
  10 What is musicpdaio?
  11 -------------------
  12
  13 **musicpdaio** is an asynchronous MPD (`Music Player Daemon`_) client library written in Python. It is the asyncio_ port of python-musicpd_.
  14
  15 The goal of this project is to keep python-musicpd_ simplicity and provide
  16 asyncio_ support.
  17
  18 Should I use it?
  19 ----------------
  20
  21  * If you need a plain MPD client to manage you MPD server, then stick with
  22    non-asyncio module python-musicpd_
  23  * If you're building an interactive client, concurrent access to MPD or need
  24    to plug into another asyncio project then use musicpdaio.
  25
  26
  27 Using the client library
  28 -------------------------
  29
  30 The client library can be used as follows:
  31
  32 .. code-block:: python
  33
  34     client = mpdaio.MPDClient()       # create client object
  35     await client.ping()               # test the connection, using default host/port, cf. Reference
  36     print(client.version)             # print the MPD protocol version
  37     await client.setvol('42')         # sets the volume
  38     await client.close()              # disconnect from the server
  39
  40 The MPD command protocol exchanges line-based text records. The client emits a
  41 command with optional arguments. In the example above the client sends a
  42 `setvol` command with the string argument `42`.
  43
  44 MPD commands are exposed as |mpdaio.MPDClient| methods. Methods
  45 **arguments are python strings**. Some commands are composed of more than one word
  46 (ie "**tagtypes [disable|enable|all]**"), for these use a `snake case`_ style to
  47 access the method. Then **"tagtypes enable"** command is called with
  48 **"tagtypes_enable"**.
  49
  50 Remember MPD protocol is text based, then all MPD command arguments are UTF-8
  51 strings. In the example above, an integer can be used as argument for the
  52 `setvol` command, but it is then evaluated as a string when the command is
  53 written to the socket. To avoid confusion use regular string instead of relying
  54 on object string representation.
  55
  56 |mpdaio.MPDClient| methods returns different kinds of objects
  57 depending on the command. Could be :py:obj:`None`, a single object as a
  58 :py:obj:`str` or a :py:obj:`dict`, a list of :py:obj:`dict`.
  59
  60 Then |mpdaio.MPDClient| **methods signatures** are not hard coded
  61 within this module since the protocol is handled on the server side. Please
  62 refer to the protocol and MPD commands in `MPD protocol documentation`_ to
  63 learn how to call commands and what kind of arguments they expect.
  64
  65 Some examples are provided for the most common cases, see :ref:`tutorial`.
  66
  67 **musicpdaio** tries to come with sane defaults, then running
  68 |mpdaio.MPDClient| with no explicit argument will try default values
  69 to connect to MPD. Cf. :ref:`reference` for more about
  70 :ref:`defaults<default_settings>`.
  71
  72 .. _socket_connections:
  73 .. index:: pair: connection pool; socket
  74
  75 Socket connection
  76 -----------------
  77
  78 **musicpdaio** uses a connection pool internally to keep already opened socket
  79 and reuse it.
  80
  81 When first instantiated |mpdaio.MPDClient| comes with an empty pool,
  82 when the first MPD command is called a connection is opened, saved and
  83 potentially reused later. In case a concurrent MPD command is called while the
  84 connection is still in use a new connection is made and kept in the pool.
  85
  86 .. code-block:: python
  87
  88    client = mpdaio.MPDClient()
  89    client.connections    # Returns an empty list: []
  90    client.version        # Returns empty string: ''
  91    await client.ping()   # A connection is made and kept open
  92    client.connections    # Returns a list; [Connection<example.org:6600>]
  93
  94 .. vim: spell spelllang=en