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

{python-musicpd-0.8.0 → python_musicpd-0.9.1}/CHANGES.txt

@@ -1,6 +1,27 @@
 python-musicpd Changes List
 ===========================
 
+Changes in 0.9.1
+----------------
+
+ * Add playlistlength command
+ * Add stickernames command
+ * Add searchcount command
+ * Improved documentation, add supported commands rtype
+
+Changes in 0.9.0
+----------------
+
+ * Use right SPDX identifier for license headers
+ * mpd_version attribute init to empty string instead of None
+ * Fixed send_noidle (introduced with e8daa719)
+ * Improved Range object to deal with window parameter
+ * Add logging
+ * Switch to pyproject.toml (setuptools build system)
+ * The connect sequence raises ConnectionError only on error,
+   previously getaddrinfo or unix socket connection error raised an OSError
+ * Improved documentation, add examples
+
 Changes in 0.8.0
 ----------------
 

python_musicpd-0.9.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGES.txt
+graft doc/source
+global-exclude *~ *.py[cod] *.so

python_musicpd-0.9.1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.1
+Name: python-musicpd
+Version: 0.9.1
+Summary: An MPD (Music Player Daemon) client library written in pure Python.
+Author-email: Kaliko Jack <kaliko@azylum.org>
+License:                    GNU LESSER GENERAL PUBLIC LICENSE
+                               Version 3, 29 June 2007
+        
+         Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+         Everyone is permitted to copy and distribute verbatim copies
+         of this license document, but changing it is not allowed.
+        
+        
+          This version of the GNU Lesser General Public License incorporates
+        the terms and conditions of version 3 of the GNU General Public
+        License, supplemented by the additional permissions listed below.
+        
+          0. Additional Definitions.
+        
+          As used herein, "this License" refers to version 3 of the GNU Lesser
+        General Public License, and the "GNU GPL" refers to version 3 of the GNU
+        General Public License.
+        
+          "The Library" refers to a covered work governed by this License,
+        other than an Application or a Combined Work as defined below.
+        
+          An "Application" is any work that makes use of an interface provided
+        by the Library, but which is not otherwise based on the Library.
+        Defining a subclass of a class defined by the Library is deemed a mode
+        of using an interface provided by the Library.
+        
+          A "Combined Work" is a work produced by combining or linking an
+        Application with the Library.  The particular version of the Library
+        with which the Combined Work was made is also called the "Linked
+        Version".
+        
+          The "Minimal Corresponding Source" for a Combined Work means the
+        Corresponding Source for the Combined Work, excluding any source code
+        for portions of the Combined Work that, considered in isolation, are
+        based on the Application, and not on the Linked Version.
+        
+          The "Corresponding Application Code" for a Combined Work means the
+        object code and/or source code for the Application, including any data
+        and utility programs needed for reproducing the Combined Work from the
+        Application, but excluding the System Libraries of the Combined Work.
+        
+          1. Exception to Section 3 of the GNU GPL.
+        
+          You may convey a covered work under sections 3 and 4 of this License
+        without being bound by section 3 of the GNU GPL.
+        
+          2. Conveying Modified Versions.
+        
+          If you modify a copy of the Library, and, in your modifications, a
+        facility refers to a function or data to be supplied by an Application
+        that uses the facility (other than as an argument passed when the
+        facility is invoked), then you may convey a copy of the modified
+        version:
+        
+           a) under this License, provided that you make a good faith effort to
+           ensure that, in the event an Application does not supply the
+           function or data, the facility still operates, and performs
+           whatever part of its purpose remains meaningful, or
+        
+           b) under the GNU GPL, with none of the additional permissions of
+           this License applicable to that copy.
+        
+          3. Object Code Incorporating Material from Library Header Files.
+        
+          The object code form of an Application may incorporate material from
+        a header file that is part of the Library.  You may convey such object
+        code under terms of your choice, provided that, if the incorporated
+        material is not limited to numerical parameters, data structure
+        layouts and accessors, or small macros, inline functions and templates
+        (ten or fewer lines in length), you do both of the following:
+        
+           a) Give prominent notice with each copy of the object code that the
+           Library is used in it and that the Library and its use are
+           covered by this License.
+        
+           b) Accompany the object code with a copy of the GNU GPL and this license
+           document.
+        
+          4. Combined Works.
+        
+          You may convey a Combined Work under terms of your choice that,
+        taken together, effectively do not restrict modification of the
+        portions of the Library contained in the Combined Work and reverse
+        engineering for debugging such modifications, if you also do each of
+        the following:
+        
+           a) Give prominent notice with each copy of the Combined Work that
+           the Library is used in it and that the Library and its use are
+           covered by this License.
+        
+           b) Accompany the Combined Work with a copy of the GNU GPL and this license
+           document.
+        
+           c) For a Combined Work that displays copyright notices during
+           execution, include the copyright notice for the Library among
+           these notices, as well as a reference directing the user to the
+           copies of the GNU GPL and this license document.
+        
+           d) Do one of the following:
+        
+               0) Convey the Minimal Corresponding Source under the terms of this
+               License, and the Corresponding Application Code in a form
+               suitable for, and under terms that permit, the user to
+               recombine or relink the Application with a modified version of
+               the Linked Version to produce a modified Combined Work, in the
+               manner specified by section 6 of the GNU GPL for conveying
+               Corresponding Source.
+        
+               1) Use a suitable shared library mechanism for linking with the
+               Library.  A suitable mechanism is one that (a) uses at run time
+               a copy of the Library already present on the user's computer
+               system, and (b) will operate properly with a modified version
+               of the Library that is interface-compatible with the Linked
+               Version.
+        
+           e) Provide Installation Information, but only if you would otherwise
+           be required to provide such information under section 6 of the
+           GNU GPL, and only to the extent that such information is
+           necessary to install and execute a modified version of the
+           Combined Work produced by recombining or relinking the
+           Application with a modified version of the Linked Version. (If
+           you use option 4d0, the Installation Information must accompany
+           the Minimal Corresponding Source and Corresponding Application
+           Code. If you use option 4d1, you must provide the Installation
+           Information in the manner specified by section 6 of the GNU GPL
+           for conveying Corresponding Source.)
+        
+          5. Combined Libraries.
+        
+          You may place library facilities that are a work based on the
+        Library side by side in a single library together with other library
+        facilities that are not Applications and are not covered by this
+        License, and convey such a combined library under terms of your
+        choice, if you do both of the following:
+        
+           a) Accompany the combined library with a copy of the same work based
+           on the Library, uncombined with any other library facilities,
+           conveyed under the terms of this License.
+        
+           b) Give prominent notice with the combined library that part of it
+           is a work based on the Library, and explaining where to find the
+           accompanying uncombined form of the same work.
+        
+          6. Revised Versions of the GNU Lesser General Public License.
+        
+          The Free Software Foundation may publish revised and/or new versions
+        of the GNU Lesser General Public License from time to time. Such new
+        versions will be similar in spirit to the present version, but may
+        differ in detail to address new problems or concerns.
+        
+          Each version is given a distinguishing version number. If the
+        Library as you received it specifies that a certain numbered version
+        of the GNU Lesser General Public License "or any later version"
+        applies to it, you have the option of following the terms and
+        conditions either of that published version or of any later version
+        published by the Free Software Foundation. If the Library as you
+        received it does not specify a version number of the GNU Lesser
+        General Public License, you may choose any version of the GNU Lesser
+        General Public License ever published by the Free Software Foundation.
+        
+          If the Library as you received it specifies that a proxy can decide
+        whether future versions of the GNU Lesser General Public License shall
+        apply, that proxy's public statement of acceptance of any version is
+        permanent authorization for you to choose that version for the
+        Library.
+        
+Project-URL: Homepage, https://kaliko.me/python-musicpd/
+Keywords: mpd,Music Player Daemon
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.6
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Provides-Extra: sphinx
+Requires-Dist: Sphinx>=5.3.0; extra == "sphinx"
+
+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.6+
+:Licence:       GNU LGPLv3

{python-musicpd-0.8.0 → python_musicpd-0.9.1}/README.rst

@@ -1,5 +1,5 @@
-Python MusicPlayerDaemon client module
-***************************************
+Music Player Daemon client module
+*********************************
 
 An MPD (Music Player Daemon) client library written in pure Python.
 

python_musicpd-0.9.1/doc/source/_commands.rst

@@ -0,0 +1,195 @@
+Below the commands list last updated for v0.9.1.
+
+Querying MPD’s status
+^^^^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Querying MPD’s status <https://mpd.readthedocs.io/en/latest/protocol.html#querying-mpd-s-status>`_
+
+* **clearerror** -> None
+* **currentsong** -> dict
+* **idle** -> list
+* **status** -> dict
+* **stats** -> dict
+
+Playback Option
+^^^^^^^^^^^^^^^
+
+Protocol documentation: `Playback Option <https://mpd.readthedocs.io/en/latest/protocol.html#playback-options>`_
+
+* **consume** -> None
+* **crossfade** -> None
+* **mixrampdb** -> None
+* **mixrampdelay** -> None
+* **random** -> None
+* **repeat** -> None
+* **setvol** -> None
+* **getvol** -> dict
+* **single** -> None
+* **replay_gain_mode** -> None
+* **replay_gain_status** -> str
+* **volume** -> None
+
+Controlling playback
+^^^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Controlling playback <https://mpd.readthedocs.io/en/latest/protocol.html#controlling-playback>`_
+
+* **next** -> None
+* **pause** -> None
+* **play** -> None
+* **playid** -> None
+* **previous** -> None
+* **seek** -> None
+* **seekid** -> None
+* **seekcur** -> None
+* **stop** -> None
+
+The Queue
+^^^^^^^^^
+
+Protocol documentation: `The Queue <https://mpd.readthedocs.io/en/latest/protocol.html#the-queue>`_
+
+* **add** -> None
+* **addid** -> str
+* **clear** -> None
+* **delete** -> None
+* **deleteid** -> None
+* **move** -> None
+* **moveid** -> None
+* **playlist** -> list
+* **playlistfind** -> list[dict]
+* **playlistid** -> list[dict]
+* **playlistinfo** -> list[dict]
+* **playlistsearch** -> list[dict]
+* **plchanges** -> list[dict]
+* **plchangesposid** -> list[dict]
+* **prio** -> None
+* **prioid** -> None
+* **rangeid** -> None
+* **shuffle** -> None
+* **swap** -> None
+* **swapid** -> None
+* **addtagid** -> None
+* **cleartagid** -> None
+
+Stored playlists
+^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Stored playlists <https://mpd.readthedocs.io/en/latest/protocol.html#stored-playlists>`_
+
+* **listplaylist** -> list
+* **listplaylistinfo** -> list[dict]
+* **listplaylists** -> dict
+* **load** -> None
+* **playlistadd** -> None
+* **playlistclear** -> None
+* **playlistdelete** -> None
+* **playlistlength** -> dict
+* **playlistmove** -> None
+* **rename** -> None
+* **rm** -> None
+* **save** -> None
+
+The music database
+^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `The music database <https://mpd.readthedocs.io/en/latest/protocol.html#the-music-database>`_
+
+* **albumart** -> dict
+* **count** -> dict
+* **getfingerprint** -> dict
+* **find** -> list[dict]
+* **findadd** -> None
+* **list** -> list
+* **listall** -> list[dict]
+* **listallinfo** -> list[dict]
+* **listfiles** -> list[dict]
+* **lsinfo** -> list[dict]
+* **readcomments** -> dict
+* **readpicture** -> dict
+* **search** -> list[dict]
+* **searchadd** -> None
+* **searchaddpl** -> None
+* **searchcount** -> dict
+* **update** -> str
+* **rescan** -> str
+
+Mounts and neighbors
+^^^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Mounts and neighbors <https://mpd.readthedocs.io/en/latest/protocol.html#mounts-and-neighbors>`_
+
+* **mount** -> None
+* **unmount** -> None
+* **listmounts** -> list[dict]
+* **listneighbors** -> list[dict]
+
+Stickers
+^^^^^^^^
+
+Protocol documentation: `Stickers <https://mpd.readthedocs.io/en/latest/protocol.html#stickers>`_
+
+* **sticker get** -> str
+* **sticker set** -> None
+* **sticker delete** -> None
+* **sticker list** -> list
+* **sticker find** -> list[dict]
+* **stickernames** -> list
+
+Connection settings
+^^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Connection settings <https://mpd.readthedocs.io/en/latest/protocol.html#connection-settings>`_
+
+* **password** -> None
+* **ping** -> None
+* **binarylimit** -> None
+* **tagtypes** -> list
+* **tagtypes disable** -> None
+* **tagtypes enable** -> None
+* **tagtypes clear** -> None
+* **tagtypes all** -> None
+
+Partition Commands
+^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Partition Commands <https://mpd.readthedocs.io/en/latest/protocol.html#partition-commands>`_
+
+* **partition** -> None
+* **listpartitions** -> list
+* **newpartition** -> None
+* **delpartition** -> None
+* **moveoutput** -> None
+
+Audio output devices
+^^^^^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Audio output devices <https://mpd.readthedocs.io/en/latest/protocol.html#audio-output-devices>`_
+
+* **disableoutput** -> None
+* **enableoutput** -> None
+* **toggleoutput** -> None
+* **outputs** -> list[dict]
+* **outputset** -> None
+
+Reflection
+^^^^^^^^^^
+
+Protocol documentation: `Reflection <https://mpd.readthedocs.io/en/latest/protocol.html#reflection>`_
+
+* **config** -> dict
+* **commands** -> list
+* **notcommands** -> list
+* **urlhandlers** -> list
+* **decoders** -> list[dict]
+
+Client to Client
+^^^^^^^^^^^^^^^^
+
+Protocol documentation: `Client to Client <https://mpd.readthedocs.io/en/latest/protocol.html#client-to-client>`_
+
+* **subscribe** -> None
+* **unsubscribe** -> None
+* **channels** -> list
+* **readmessages** -> list[dict]
+* **sendmessage** -> None

{python-musicpd-0.8.0 → python_musicpd-0.9.1}/doc/source/commands.rst

@@ -1,5 +1,5 @@
-.. SPDX-FileCopyrightText: 2018-2021  kaliko <kaliko@azylum.org>
-.. SPDX-License-Identifier: GPL-3.0-or-later
+.. SPDX-FileCopyrightText: 2018-2024 kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
 
 .. _commands:
 
@@ -13,7 +13,4 @@ Get current available commands:
    import musicpd
    print(' '.join([cmd for cmd in musicpd.MPDClient()._commands.keys()]))
 
-
-List, last updated for v0.6.0:
-
-.. literalinclude:: commands.txt
+.. include:: _commands.rst

{python-musicpd-0.8.0 → python_musicpd-0.9.1}/doc/source/commands.txt

@@ -7,7 +7,7 @@ status                                     -> fetch_object
 stats                                      -> fetch_object
 
 == Playback Option Commands
-consume            <bool>                  -> fetch_nothing
+consume            <str>                   -> fetch_nothing
 crossfade          <int>                   -> fetch_nothing
 mixrampdb          <str>                   -> fetch_nothing
 mixrampdelay       <int>                   -> fetch_nothing
@@ -133,3 +133,10 @@ commands         -> fetch_list
 notcommands      -> fetch_list
 urlhandlers      -> fetch_list
 decoders         -> fetch_plugins
+
+== Client to Client
+subscribe      <str>       -> self._fetch_nothing,
+unsubscribe    <str>       -> self._fetch_nothing,
+channels                   -> self._fetch_list,
+readmessages               -> self._fetch_messages,
+sendmessage    <str> <str> -> self._fetch_nothing,

{python-musicpd-0.8.0 → python_musicpd-0.9.1}/doc/source/conf.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 # SPDX-FileCopyrightText: 2018-2021  kaliko <kaliko@azylum.org>
-# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #
 # Python MPD Module documentation build configuration file, created by
 # sphinx-quickstart on Mon Mar 12 14:37:32 2018.
@@ -76,7 +76,7 @@ release = VERSION
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+#language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -438,7 +438,7 @@ epub_exclude_files = ['search.html']
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 # autodoc config
 autodoc_member_order = 'bysource'

{python-musicpd-0.8.0 → python_musicpd-0.9.1}/doc/source/contribute.rst

@@ -1,5 +1,5 @@
 .. SPDX-FileCopyrightText: 2018-2021  kaliko <kaliko@azylum.org>
-.. SPDX-License-Identifier: GPL-3.0-or-later
+.. SPDX-License-Identifier: LGPL-3.0-or-later
 
 Contributing
 =============

python_musicpd-0.9.1/doc/source/doc.rst

@@ -0,0 +1,12 @@
+.. SPDX-FileCopyrightText: 2018-2023 kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
+
+musicpd namespace
+=================
+
+.. automodule:: musicpd
+   :members:
+   :no-undoc-members:
+
+
+.. vim: spell spelllang=en

python_musicpd-0.9.1/doc/source/examples/client.py

@@ -0,0 +1,94 @@
+"""Plain client class
+"""
+import logging
+import select
+import sys
+
+import musicpd
+
+
+class MyClient(musicpd.MPDClient):
+    """Plain client inheriting from MPDClient"""
+
+    def __init__(self):
+        # Set logging to debug level
+        logging.basicConfig(level=logging.DEBUG,
+                            format='%(levelname)-8s %(module)-8s %(message)s')
+        self.log = logging.getLogger(__name__)
+        super().__init__()
+        # Set host/port/password after init to overrides defaults
+        # self.host = 'example.org'
+        # self.port = 4242
+        # self.pwd = 'secret'
+
+    def connect(self):
+        """Overriding explicitly MPDClient.connect()"""
+        try:
+            super().connect(host=self.host, port=self.port)
+            if hasattr(self, 'pwd') and self.pwd:
+                self.password(self.pwd)
+        except musicpd.ConnectionError as err:
+            # Catch socket error
+            self.log.error('Failed to connect: %s', err)
+            sys.exit(42)
+
+    def _wait_for_changes(self, callback):
+        select_timeout = 10  # second
+        while True:
+            self.send_idle()  # use send_ API to avoid blocking on read
+            _read, _, _ = select.select([self], [], [], select_timeout)
+            if _read:  # tries to read response
+                ret = self.fetch_idle()
+                # do something
+                callback(ret)
+            else:  # cancels idle
+                self.noidle()
+
+    def callback(self, *args):
+        """Method launch on MPD event, cf. monitor method"""
+        self.log.info('%s', args)
+
+    def monitor(self):
+        """Continuously monitor MPD activity.
+        Launch callback method on event.
+        """
+        try:
+            self._wait_for_changes(self.callback)
+        except (OSError, musicpd.MPDError) as err:
+            self.log.error('%s: Something went wrong: %s',
+                           type(err).__name__, err)
+
+if __name__ == '__main__':
+    cli = MyClient()
+    # You can overrides host here or in init
+    #cli.host = 'example.org'
+    # Connect MPD server
+    try:
+        cli.connect()
+    except musicpd.ConnectionError as err:
+        cli.log.error(err)
+
+    # Monitor MPD changes, blocking/timeout idle approach
+    try:
+        cli.socket_timeout =  20 # seconds
+        ret = cli.idle()
+        cli.log.info('Leaving idle, got: %s', ret)
+    except TimeoutError as err:
+        cli.log.info('Nothing occured the last %ss', cli.socket_timeout)
+
+    # Reset connection
+    try:
+        cli.socket_timeout = None
+        cli.disconnect()
+        cli.connect()
+    except musicpd.ConnectionError as err:
+        cli.log.error(err)
+
+    # Monitor MPD changes, non blocking idle approach
+    try:
+        cli.monitor()
+    except KeyboardInterrupt as err:
+        cli.log.info(type(err).__name__)
+        cli.send_noidle()
+        cli.disconnect()
+

python_musicpd-0.9.1/doc/source/examples/connect.py

@@ -0,0 +1,29 @@
+import logging
+
+import musicpd
+
+# Set logging to debug level
+# it should log messages showing where defaults come from
+logging.basicConfig(level=logging.DEBUG, format='%(levelname)-8s %(message)s')
+log = logging.getLogger()
+
+client = musicpd.MPDClient()
+# use MPD_HOST/MPD_PORT env var if set else
+# test ${XDG_RUNTIME_DIR}/mpd/socket for existence
+# fallback to localhost:6600
+# connect support host/port argument as well
+client.connect()
+
+status = client.status()
+if status.get('state') == 'play':
+    current_song_id = status.get('songid')
+    current_song = client.playlistid(current_song_id)[0]
+    log.info(f'Playing   : {current_song.get("file")}')
+    next_song_id = status.get('nextsongid', None)
+    if next_song_id:
+        next_song = client.playlistid(next_song_id)[0]
+        log.info(f'Next song : {next_song.get("file")}')
+else:
+    log.info('Not playing')
+
+client.disconnect()

python_musicpd-0.9.1/doc/source/examples/connect_host.py

@@ -0,0 +1,17 @@
+import sys
+import logging
+
+import musicpd
+
+# Set logging to debug level
+logging.basicConfig(level=logging.DEBUG, format='%(levelname)-8s %(message)s')
+
+client = musicpd.MPDClient()
+try:
+    client.connect(host='example.lan')
+    client.password('secret')
+    client.status()
+except musicpd.MPDError as err:
+    print(f'An error occured: {err}')
+finally:
+    client.disconnect()