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    no-ansynio module python-musicpd_
  22  * If you're building a 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 For a list of currently supported commands in this python module see
  67 :ref:`commands`.
  68
  69 **musicpdaio** tries to come with sane defaults, then running
  70 :py:class:`mpdaio.MPDClient` with no explicit argument will try defaults values
  71 to connect to MPD. Cf. :ref:`reference` for more about defaults.
  72
  73
  74 .. _environment_variables:
  75
  76
  77 .. _snake case: https://en.wikipedia.org/wiki/Snake_case
  78 .. _MPD protocol documentation: http://www.musicpd.org/doc/protocol/
  79 .. _asyncio: https://docs.python.org/3/library/asyncio.html
  80 .. _python-musicpd: https://kaliko.gitlab.io/python-musicpd
  81
  82 .. vim: spell spelllang=en