python-musicpd 0.9.1__tar.gz → 0.9.3__tar.gz

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/CHANGES.txt

@@ -1,6 +1,22 @@
 python-musicpd Changes List
 ===========================
 
+Changes in 0.9.3
+----------------
+
+ * Add support for the list command grouping (Group marker)
+ * Fix deprecation in pyproject.toml
+ * Minimum python version raised to 3.11
+
+Changes in 0.9.2
+----------------
+
+ * Add missing build-backend in pyproject.toml
+ * Add protocol commands
+ * Add stickernamestypes and stickertypes commands
+ * Add searchplaylist command
+ * Fixed deprecation in pyproject.toml
+
 Changes in 0.9.1
 ----------------
 

python_musicpd-0.9.3/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: python-musicpd
+Version: 0.9.3
+Summary: An MPD (Music Player Daemon) client library written in pure Python.
+Author-email: Kaliko Jack <kaliko@azylum.org>
+Project-URL: Homepage, https://kaliko.me/python-musicpd/
+Keywords: mpd,Music Player Daemon
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Provides-Extra: sphinx
+Requires-Dist: Sphinx>=5.3.0; extra == "sphinx"
+Requires-Dist: sphinx-rtd-theme>=3.1.0; extra == "sphinx"
+Dynamic: license-file
+
+Music Player Daemon client module
+*********************************
+
+An MPD (Music Player Daemon) client library written in pure Python.
+
+----
+
+:Documentation: https://kaliko.gitlab.io/python-musicpd
+:MPD Protocol:  https://www.musicpd.org/doc/html/protocol.html
+:Code:          https://gitlab.com/kaliko/python-musicpd
+:Dependencies:  None
+:Compatibility: Python 3.11+
+:Licence:       GNU LGPLv3

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/README.rst

@@ -9,5 +9,5 @@ An MPD (Music Player Daemon) client library written in pure Python.
 :MPD Protocol:  https://www.musicpd.org/doc/html/protocol.html
 :Code:          https://gitlab.com/kaliko/python-musicpd
 :Dependencies:  None
-:Compatibility: Python 3.6+
+:Compatibility: Python 3.11+
 :Licence:       GNU LGPLv3

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/doc/source/_commands.rst

@@ -1,4 +1,4 @@
-Below the commands list last updated for v0.9.1.
+Below the commands list last updated for v0.9.2.
 
 Querying MPD’s status
 ^^^^^^^^^^^^^^^^^^^^^
@@ -79,6 +79,7 @@ Protocol documentation: `Stored playlists <https://mpd.readthedocs.io/en/latest/
 
 * **listplaylist** -> list
 * **listplaylistinfo** -> list[dict]
+* **searchplaylist** -> list[dict]
 * **listplaylists** -> dict
 * **load** -> None
 * **playlistadd** -> None
@@ -135,6 +136,8 @@ Protocol documentation: `Stickers <https://mpd.readthedocs.io/en/latest/protocol
 * **sticker list** -> list
 * **sticker find** -> list[dict]
 * **stickernames** -> list
+* **stickertypes** -> list
+* **stickernamestypes** -> list
 
 Connection settings
 ^^^^^^^^^^^^^^^^^^^
@@ -149,6 +152,12 @@ Protocol documentation: `Connection settings <https://mpd.readthedocs.io/en/late
 * **tagtypes enable** -> None
 * **tagtypes clear** -> None
 * **tagtypes all** -> None
+* **protocol** -> list
+* **protocol disable** -> None
+* **protocol enable** -> None
+* **protocol clear** -> None
+* **protocol all** -> None
+* **protocol available** -> list
 
 Partition Commands
 ^^^^^^^^^^^^^^^^^^

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/doc/source/commands.txt

@@ -75,7 +75,7 @@ count              group <str>                              -> fetch_object
 getfingerprint     <str>                                    -> fetch_object
 find               <str> <str> [<str> <str>]...             -> fetch_songs
 findadd            <str> <str> [<str> <str>]                -> fetch_nothing
-list               <str> [<str> <str>]...[group <str>]...   -> fetch_list
+list               <str> [<str> <str>]...[<Group>]...       -> fetch_list
 listall            [<str>]                                  -> fetch_database
 listallinfo        [<str>]                                  -> fetch_database
 listfiles          <str>                                    -> fetch_database

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/doc/source/conf.py

@@ -1,5 +1,5 @@
 # coding: utf-8
-# SPDX-FileCopyrightText: 2018-2021  kaliko <kaliko@azylum.org>
+# SPDX-FileCopyrightText: 2018-2026  kaliko <kaliko@azylum.org>
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #
 # Python MPD Module documentation build configuration file, created by
@@ -57,9 +57,9 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Python MPD Module'
+project = 'Python MPD Module'
 from datetime import datetime
-copyright = u'2012-{}, {}'.format(datetime.now().year, __author__)
+copyright = '2012-{}, {}'.format(datetime.now().year, __author__)
 author = __author__
 
 # The version info for the project you're documenting, acts as replacement for
@@ -146,7 +146,7 @@ html_theme = 'classic'
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = u'Python MPD Module v0.0.1'
+# html_title = 'Python MPD Module v0.0.1'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -273,8 +273,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'PythonMPDModule.tex', u'Python MPD Module Documentation',
-     u'kaliko', 'manual'),
+    (master_doc, 'PythonMPDModule.tex', 'Python MPD Module Documentation',
+     'kaliko', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -315,7 +315,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'pythonmpdmodule', u'Python MPD Module Documentation',
+    (master_doc, 'pythonmpdmodule', 'Python MPD Module Documentation',
      [author], 1)
 ]
 
@@ -330,7 +330,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'PythonMPDModule', u'Python MPD Module Documentation',
+    (master_doc, 'PythonMPDModule', 'Python MPD Module Documentation',
      author, 'PythonMPDModule', 'One line description of project.',
      'Miscellaneous'),
 ]

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/doc/source/examples/musicpd.py

@@ -1,5 +1,4 @@
-# -*- coding: utf-8 -*-
-# SPDX-FileCopyrightText: 2012-2024  kaliko <kaliko@azylum.org>
+# SPDX-FileCopyrightText: 2012-2026  kaliko <kaliko@azylum.org>
 # SPDX-FileCopyrightText: 2021       Wonko der Verständige <wonko@hanstool.org>
 # SPDX-FileCopyrightText: 2019       Naglis Jonaitis <naglis@mailbox.org>
 # SPDX-FileCopyrightText: 2019       Bart Van Loon <bbb@bbbart.be>
@@ -11,7 +10,6 @@
 import logging
 import os
 import socket
-
 from functools import wraps
 
 HELLO_PREFIX = "OK MPD "
@@ -19,14 +17,14 @@ ERROR_PREFIX = "ACK "
 SUCCESS = "OK"
 NEXT = "list_OK"
 #: Module version
-VERSION = '0.9.1'
+VERSION = '0.9.3'
 #: Seconds before a connection attempt times out
 #: (overriden by :envvar:`MPD_TIMEOUT` env. var.)
 CONNECTION_TIMEOUT = 30
 #: Socket timeout in second > 0 (Default is :py:obj:`None` for no timeout)
 SOCKET_TIMEOUT = None
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 
 def iterator_wrapper(func):
@@ -40,8 +38,7 @@ def iterator_wrapper(func):
 
         def iterator(gen):
             try:
-                for item in gen:
-                    yield item
+                yield from gen
             finally:
                 instance._iterating = False
         return iterator(generator)
@@ -97,7 +94,6 @@ class Range:
             return str(int(item))
         except (TypeError, ValueError) as err:
             raise CommandError(f'Not an integer: "{item}"') from err
-        return item
 
     def _check(self):
         if not isinstance(self.tpl, tuple):
@@ -118,6 +114,22 @@ class Range:
                 raise CommandError(f'Wrong range: {self.lower} > {self.upper}')
 
 
+class Group:
+    """Mark a tag used with the ``group`` keyword of the :py:obj:`list` command.
+
+    >>> client.list('album', '(genre == "Punk")', musicpd.Group('artist'))
+    """
+
+    def __init__(self, tag):
+        self.tag = tag
+
+    def __str__(self):
+        return f'group {self.tag}'
+
+    def __repr__(self):
+        return f'Group({self.tag!r})'
+
+
 class _NotConnected:
 
     def __getattr__(self, attr):
@@ -184,6 +196,7 @@ class MPDClient:
 
         .. note:: This is the version of the protocol spoken, not the real version of the daemon."""
         self._reset()
+        # fmt: off
         self._commands = {
             # Querying MPD’s status # querying-mpd-s-status
             "clearerror":         self._fetch_nothing,
@@ -241,6 +254,7 @@ class MPDClient:
             # Stored playlists # stored-playlists
             "listplaylist":       self._fetch_list,
             "listplaylistinfo":   self._fetch_songs,
+            "searchplaylist":     self._fetch_songs,
             "listplaylists":      self._fetch_playlists,
             "load":               self._fetch_nothing,
             "playlistadd":        self._fetch_nothing,
@@ -282,6 +296,8 @@ class MPDClient:
             "sticker list":       self._fetch_list,
             "sticker find":       self._fetch_songs,
             "stickernames":       self._fetch_list,
+            "stickertypes":       self._fetch_list,
+            "stickernamestypes":  self._fetch_list,
             # Connection settings # connection-settings
             "close":              None,
             "kill":               None,
@@ -293,6 +309,12 @@ class MPDClient:
             "tagtypes enable":    self._fetch_nothing,
             "tagtypes clear":     self._fetch_nothing,
             "tagtypes all":       self._fetch_nothing,
+            "protocol":           self._fetch_list,
+            "protocol disable":   self._fetch_nothing,
+            "protocol enable":    self._fetch_nothing,
+            "protocol clear":     self._fetch_nothing,
+            "protocol all":       self._fetch_nothing,
+            "protocol available": self._fetch_list,
             # Partition Commands # partition-commands
             "partition":          self._fetch_nothing,
             "listpartitions":     self._fetch_list,
@@ -318,21 +340,19 @@ class MPDClient:
             "readmessages":       self._fetch_messages,
             "sendmessage":        self._fetch_nothing,
         }
+        # fmt: on
         #: host used with the current connection (:py:obj:`str`)
-        self.host = None
+        self.host = 'localhost'
         #: password detected in :envvar:`MPD_HOST` environment variable (:py:obj:`str`)
         self.pwd = None
         #: port used with the current connection (:py:obj:`int`, :py:obj:`str`)
-        self.port = None
+        self.port = os.getenv('MPD_PORT', '6600')
         self._get_envvars()
 
     def _get_envvars(self):
         """
         Retrieve MPD env. var. to overrides default "localhost:6600"
         """
-        # Set some defaults
-        self.host = 'localhost'
-        self.port = os.getenv('MPD_PORT', '6600')
         _host = os.getenv('MPD_HOST', '')
         if _host:
             # If password is set: MPD_HOST=pass@host
@@ -340,30 +360,30 @@ class MPDClient:
                 mpd_host_env = _host.split('@', 1)
                 if mpd_host_env[0]:
                     # A password is actually set
-                    log.debug('password detected in MPD_HOST, set client pwd attribute')
+                    logger.debug('password detected in MPD_HOST, set client pwd attribute')
                     self.pwd = mpd_host_env[0]
                     if mpd_host_env[1]:
                         self.host = mpd_host_env[1]
-                        log.debug('host detected in MPD_HOST: %s', self.host)
+                        logger.debug('host detected in MPD_HOST: %s', self.host)
                 elif mpd_host_env[1]:
                     # No password set but leading @ is an abstract socket
                     self.host = '@'+mpd_host_env[1]
-                    log.debug('host detected in MPD_HOST: %s (abstract socket)', self.host)
+                    logger.debug('host detected in MPD_HOST: %s (abstract socket)', self.host)
             else:
                 # MPD_HOST is a plain host
                 self.host = _host
-                log.debug('host detected in MPD_HOST: %s', self.host)
+                logger.debug('host detected in MPD_HOST: %s', self.host)
         else:
             # Is socket there
             xdg_runtime_dir = os.getenv('XDG_RUNTIME_DIR', '/run')
             rundir = os.path.join(xdg_runtime_dir, 'mpd/socket')
             if os.path.exists(rundir):
                 self.host = rundir
-                log.debug('host detected in ${XDG_RUNTIME_DIR}/run: %s (unix socket)', self.host)
+                logger.debug('host detected in ${XDG_RUNTIME_DIR}/run: %s (unix socket)', self.host)
         _mpd_timeout = os.getenv('MPD_TIMEOUT', '')
         if _mpd_timeout.isdigit():
             self.mpd_timeout = int(_mpd_timeout)
-            log.debug('timeout detected in MPD_TIMEOUT: %d', self.mpd_timeout)
+            logger.debug('timeout detected in MPD_TIMEOUT: %d', self.mpd_timeout)
         else:  # Use CONNECTION_TIMEOUT as default even if MPD_TIMEOUT carries gargage
             self.mpd_timeout = CONNECTION_TIMEOUT
 
@@ -388,8 +408,7 @@ class MPDClient:
 
     def _send(self, command, args):
         if self._command_list is not None:
-            raise CommandListError("Cannot use send_%s in a command list" %
-                                   command.replace(" ", "_"))
+            raise CommandListError("Cannot use send_{} in a command list".format(command.replace(" ", "_")))
         self._write_command(command, args)
         retval = self._commands[command]
         if retval is not None:
@@ -440,6 +459,8 @@ class MPDClient:
         for arg in args:
             if isinstance(arg, tuple):
                 parts.append(f'{Range(arg)!s}')
+            elif isinstance(arg, Group):
+                parts.append(f'group "{escape(str(arg.tag))}"')
             else:
                 parts.append(f'"{escape(str(arg))}"')
         if '\n' in ' '.join(parts):
@@ -494,13 +515,67 @@ class MPDClient:
             pair = self._read_pair(separator, binary=binary)
 
     def _read_list(self):
-        seen = None
-        for key, value in self._read_pairs():
-            if key != seen:
-                if seen is not None:
-                    raise ProtocolError(f"Expected key '{seen}', got '{key}'")
-                seen = key
-            yield value
+        """Read a ``list``-style response, flat or grouped.
+
+        Two response shapes are handled:
+
+        * **flat** — every line has the same key (e.g. ``Album: Foo`` then
+          ``Album: Bar``): values are yielded as a plain list.
+        * **grouped** — lines carry mixed keys, as returned by the ``list``
+          command with the ``group`` keyword. Group tags are only sent when
+          their value changes, so each row is rebuilt by propagating the
+          current group values.
+
+        For grouped responses, ``delimiters`` tracks the active tags in order
+        of appearance (the group hierarchy, ending with the listed tag). When
+        a key already present in the current row is seen, the row is yielded
+        and the ``while`` loop pops deeper tags from both the row and
+        ``delimiters`` until the changed key is reached, carrying the
+        shallower group values over to the next row.
+
+        Example::
+
+            Artist: Crass
+            Album: Stations
+            Album: Feeding
+            Artist: The Clash
+            Album: London Calling
+
+        yields::
+
+            [{'artist': 'Crass', 'album': 'Stations'},
+             {'artist': 'Crass', 'album': 'Feeding'},
+             {'artist': 'The Clash', 'album': 'London Calling'}]
+
+        .. note::
+            Grouping is detected from the response (mixed keys), not from the
+            command arguments, so plain and grouped ``list`` calls share the
+            same fetch method.
+        """
+        pairs = list(self._read_pairs())
+        if not pairs:
+            return
+        if len({key for key, _ in pairs}) == 1:
+            for _, value in pairs:
+                yield value
+            return
+        # Grouped list: group tags are only sent when their value changes,
+        # hence the dynamic delimiters handling.
+        delimiters = []
+        obj = {}
+        for key, value in pairs:
+            key = key.lower()
+            if key not in delimiters:
+                delimiters.append(key)
+            if obj and key in obj:
+                yield obj
+                obj = obj.copy()
+                while delimiters[-1] != key:
+                    obj.pop(delimiters[-1], None)
+                    delimiters.pop()
+            obj[key] = value
+        if obj:
+            yield obj
 
     def _read_playlist(self):
         for _, value in self._read_pairs(":"):
@@ -542,7 +617,7 @@ class MPDClient:
     def _fetch_item(self):
         pairs = list(self._read_pairs())
         if len(pairs) != 1:
-            return None
+            raise ProtocolError(f"Expected 1 pair, got {len(pairs)}")
         return pairs[0][1]
 
     @iterator_wrapper
@@ -604,7 +679,7 @@ class MPDClient:
         amount = int(obj['binary'])
         try:
             obj['data'] = self._read_binary(amount)
-        except IOError as err:
+        except OSError as err:
             raise ConnectionError(f'Error reading binary content: {err}') from err
         data_bytes = len(obj['data'])
         if data_bytes != amount:  # can we ever get there?
@@ -650,7 +725,7 @@ class MPDClient:
             sock.settimeout(self.mpd_timeout)
             sock.connect(path)
             sock.settimeout(self.socket_timeout)
-        except socket.error as socket_err:
+        except OSError as socket_err:
             raise ConnectionError(socket_err) from socket_err
         return sock
 
@@ -664,20 +739,20 @@ class MPDClient:
             gai = socket.getaddrinfo(host, port, socket.AF_UNSPEC,
                                      socket.SOCK_STREAM, socket.IPPROTO_TCP,
                                      flags)
-        except socket.error as gaierr:
+        except OSError as gaierr:
             raise ConnectionError(gaierr) from gaierr
         for res in gai:
             af, socktype, proto, _, sa = res
             sock = None
             try:
-                log.debug('opening socket %s', sa)
+                logger.debug('opening socket %s', sa)
                 sock = socket.socket(af, socktype, proto)
                 sock.settimeout(self.mpd_timeout)
                 sock.connect(sa)
                 sock.settimeout(self.socket_timeout)
                 return sock
-            except socket.error as socket_err:
-                log.debug('opening socket %s failed: %s', sa, socket_err)
+            except OSError as socket_err:
+                logger.debug('opening socket %s failed: %s', sa, socket_err)
                 err = socket_err
                 if sock is not None:
                     sock.close()
@@ -714,17 +789,17 @@ class MPDClient:
             host = self.host
         else:
             self.host = host
-        if not port:
+        if port is None:
             port = self.port
         else:
             self.port = port
         if self._sock is not None:
             raise ConnectionError("Already connected")
-        if host[0] in ['/', '@']:
-            log.debug('Connecting unix socket %s', host)
+        if host and host[0] in ['/', '@']:
+            logger.debug('Connecting unix socket %s', host)
             self._sock = self._connect_unix(host)
         else:
-            log.debug('Connecting tcp socket %s:%s (timeout: %ss)', host, port, self.mpd_timeout)
+            logger.debug('Connecting tcp socket %s:%s (timeout: %ss)', host, port, self.mpd_timeout)
             self._sock = self._connect_tcp(host, port)
         self._rfile = self._sock.makefile("r", encoding='utf-8', errors='surrogateescape')
         self._rbfile = self._sock.makefile("rb")
@@ -734,12 +809,12 @@ class MPDClient:
         except:
             self.disconnect()
             raise
-        log.debug('Connected')
+        logger.debug('Connected')
 
     @property
     def socket_timeout(self):
         """Socket timeout in second (defaults to :py:obj:`SOCKET_TIMEOUT`).
-        Use :py:obj:`None` to disable socket timout.
+        Use :py:obj:`None` to disable socket timeout.
 
         :setter: Set the socket timeout (integer > 0)
         :type: int or None

{python_musicpd-0.9.1 → python_musicpd-0.9.3}/doc/source/use.rst

@@ -157,6 +157,30 @@ Empty start in range (i.e. ":END") are not possible and will raise a CommandErro
 
 .. note:: Remember the use of a tuple is **optional**. Range can still be specified as a plain string ``"START:END"``.
 
+Grouping list results
+---------------------
+
+The ``list`` command supports the ``group`` keyword to group results by one or
+more tags (cf. `MPD protocol documentation`_). Use the :py:obj:`musicpd.Group`
+marker as argument to send the ``group`` keyword:
+
+.. code-block:: python
+
+    # list albums grouped by artist, filtered on genre
+    albums = client.list('album', '(genre == "Punk")', musicpd.Group('artist'))
+    # albums is a list of dicts, group values are propagated on each row:
+    # [{'artist': 'Ramones', 'album': 'Leave Home'},
+    #  {'artist': 'The Clash', 'album': 'The Clash'}, ...]
+
+The ``group`` keyword can be repeated to group by several tags:
+
+.. code-block:: python
+
+    client.list('album', musicpd.Group('date'), musicpd.Group('artist'))
+
+Without any :py:obj:`musicpd.Group` argument, ``list`` still returns a flat
+list of tag values.
+
 Iterators
 ----------