9 | « Concurrency is about dealing with lots of things at once. »
10 | Concurrency is not Parallelism -- Rob Pike
12 **musicpdaio** is the asyncio_ port of python-musicpd_.
14 The goal of this project is to keep python-musicpd_ simplicity and provide
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.
26 Using the client library
27 -------------------------
29 The client library can be used as follows:
31 .. code-block:: python
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
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`.
43 MPD commands are exposed as |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"**.
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.
55 |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`.
59 Then |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.
64 Some examples are provided for the most common cases, see :ref:`tutorial`.
66 **musicpdaio** tries to come with sane defaults, then running
67 |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>`.
71 .. _socket_connections:
72 .. index:: pair: connection pool; socket
77 **musicpdaio** uses a connection pool internally to keep already opened socket
80 When first instantiated |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.
85 .. code-block:: python
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>]
93 .. vim: spell spelllang=en