doc/source/explanations.rst

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