# musicpd namespace

Python Music Player Daemon client library

musicpd.VERSION = '0.9.2'

  Module version

musicpd.CONNECTION_TIMEOUT = 30

  Seconds before a connection attempt times out (overriden by `MPD_TIMEOUT` env. var.)

musicpd.SOCKET_TIMEOUT = None

  Socket timeout in second > 0 (Default is `None` for no timeout)

musicpd.iterator_wrapper(func)

  Decorator handling iterate option

exception musicpd.MPDError

  Main musicpd Exception

exception musicpd.ConnectionError

  Fatal Connection Error, cannot recover from it.

exception musicpd.ProtocolError

  Fatal Protocol Error, cannot recover from it

exception musicpd.CommandError

  Malformed command, socket should be fine, can reuse it

class musicpd.MPDClient

  MPDClient instance will look for `MPD_HOST`/`MPD_PORT`/`XDG_RUNTIME_DIR` environment variables and set instance attribute `host`, `port` and `pwd` accordingly.

  Then `musicpd.MPDClient.connect` will use `host` and `port` as defaults if not provided as args.

  Regarding `MPD_HOST` format to expose password refer this module documentation or MPD client manual mpc (1).

      >>> from os import environ
      >>> environ['MPD_HOST'] = 'pass@mpdhost'
      >>> cli = musicpd.MPDClient()
      >>> cli.pwd == environ['MPD_HOST'].split('@')[0]
      True
      >>> cli.host == environ['MPD_HOST'].split('@')[1]
      True
      >>> cli.connect() # will use host/port as set in MPD_HOST/MPD_PORT

  Note

  default host:

    - use `MPD_HOST` environment variable if set, extract password if present,

    - else use `XDG_RUNTIME_DIR` to looks for an existing file in `${XDG_RUNTIME_DIR:-/run/}/mpd/socket`

    - else set host to `localhost`

  default port:

    - use `MPD_PORT` environment variable is set

    - else use `6600`

  Warning

  Instance attribute host/port/pwd

  While `musicpd.MPDClient.host` and `musicpd.MPDClient.port` keep track of current connection host and port, `musicpd.MPDClient.pwd` is set once with password extracted from environment variable. Calling MPS’s password method with a new password won’t update `musicpd.MPDClient.pwd` value.

  Moreover, `musicpd.MPDClient.pwd` is only an helper attribute exposing password extracted from `MPD_HOST` environment variable, it will not be used as default value for the MPD’s password command.

  mpd_timeout

    Current connection timeout value, defaults to `CONNECTION_TIMEOUT` or env. var. `MPD_TIMEOUT` if provided

  mpd_version

    Protocol version as exposed by the server as a `str`

    Note

    This is the version of the protocol spoken, not the real version of the daemon.

  host

    host used with the current connection (`str`)

  pwd

    password detected in `MPD_HOST` environment variable (`str`)

  port

    port used with the current connection (`int`, `str`)

  connect(host=None, port=None)

    Connects the MPD server

    Parameters:

      - host (str) – hostname, IP or FQDN (defaults to localhost or socket)

      - port (str or int) – port number (defaults to 6600)

    If host/port are `None` the socket uses `host`/`port` attributes as defaults. Cf. `MPDClient` for the logic behind default host/port.

    The underlying socket also honors `MPD_TIMEOUT` environment variable and defaults to `musicpd.CONNECTION_TIMEOUT` (connect command only).

    If you want to have a timeout for each command once you got connected, set its value in `MPDClient.socket_timeout` (in second) or at module level in `musicpd.SOCKET_TIMEOUT`.

  property socket_timeout

    Socket timeout in second (defaults to `SOCKET_TIMEOUT`). Use `None` to disable socket timout.

    Setter:

      Set the socket timeout (integer > 0)

    Type:

      int or None

  disconnect()

    Closes the MPD connection. The client closes the actual socket, it does not use the ‘close’ request from MPD protocol (as suggested in documentation).

  fileno()

    Return the socket’s file descriptor (a small integer). This is useful with `select.select`.