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

{python-musicpd-0.8.0 → python-musicpd-0.9.0}/CHANGES.txt

@@ -1,6 +1,19 @@
 python-musicpd Changes List
 ===========================
 
+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.0/MANIFEST.in

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

python-musicpd-0.9.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.1
+Name: python-musicpd
+Version: 0.9.0
+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.0}/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.8.0 → python-musicpd-0.9.0}/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-2023 kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
 
 .. _commands:
 
@@ -13,7 +13,6 @@ Get current available commands:
    import musicpd
    print(' '.join([cmd for cmd in musicpd.MPDClient()._commands.keys()]))
 
-
-List, last updated for v0.6.0:
+List, last updated for v0.8.0:
 
 .. literalinclude:: commands.txt

{python-musicpd-0.8.0 → python-musicpd-0.9.0}/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.0}/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.0}/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.0/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.0/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.0/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.0/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()

python-musicpd-0.9.0/doc/source/examples/exceptions.py

@@ -0,0 +1,59 @@
+"""client class dealing with all Exceptions
+"""
+import logging
+
+import musicpd
+
+
+# Wrap Exception decorator
+def wrapext(func):
+    """Decorator to wrap errors in musicpd.MPDError"""
+    errors=(OSError, TimeoutError)
+    into = musicpd.MPDError
+    def w_func(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except errors as err:
+            strerr = str(err)
+            if hasattr(err, 'strerror'):
+                if err.strerror:
+                    strerr = err.strerror
+            raise into(strerr) from err
+    return w_func
+
+
+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)-10s %(message)s')
+        self.log = logging.getLogger(__name__)
+        super().__init__()
+
+    @wrapext
+    def __getattr__(self, cmd):
+        """Wrapper around MPDClient calls for abstract overriding"""
+        self.log.debug('cmd: %s', cmd)
+        return super().__getattr__(cmd)
+
+
+if __name__ == '__main__':
+    cli = MyClient()
+    # You can overrides host here or in init
+    #cli.host = 'example.org'
+    # Connect MPD server
+    try:
+        cli.connect()
+        cli.currentsong()
+        cli.stats()
+    except musicpd.MPDError as error:
+        cli.log.fatal(error)
+    finally:
+        cli.log.info('Disconnecting')
+        try:
+            # Tries to close the socket anyway
+            cli.disconnect()
+        except OSError:
+            pass

python-musicpd-0.9.0/doc/source/examples/findadd.py

@@ -0,0 +1,8 @@
+import musicpd
+
+# Using a context manager
+# (use env var if you need to override default host)
+with musicpd.MPDClient() as client:
+    client.clear()
+    client.findadd("(artist == 'Monkey3')")
+    client.play()

python-musicpd-0.9.0/doc/source/examples/playback.py

@@ -0,0 +1,7 @@
+import musicpd
+
+# Using a context manager
+# (use env var if you need to override default host)
+with musicpd.MPDClient() as client:
+    client.play()
+    client.setvol('80')

python-musicpd-0.9.0/doc/source/examples.rst

@@ -0,0 +1,57 @@
+.. SPDX-FileCopyrightText: 2018-2023 kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
+
+.. _examples:
+
+Examples
+========
+
+Plain examples
+--------------
+
+Connect, if playing, get currently playing track, the next one:
+
+.. literalinclude:: examples/connect.py
+   :language: python
+   :linenos:
+
+Connect a specific password protected host:
+
+.. literalinclude:: examples/connect_host.py
+   :language: python
+   :linenos:
+
+Start playing current queue and set the volume:
+
+.. literalinclude:: examples/playback.py
+   :language: python
+   :linenos:
+
+Clear the queue, search artist, queue what's found and play:
+
+.. literalinclude:: examples/findadd.py
+   :language: python
+   :linenos:
+
+Object Oriented example
+-----------------------
+
+A plain client monitoring changes on MPD.
+
+.. literalinclude:: examples/client.py
+   :language: python
+   :linenos:
+
+.. _exceptions_example:
+
+Dealing with Exceptions
+-----------------------
+
+Musicpd module will raise it's own :py:obj:`MPDError<musicpd.MPDError>`
+exceptions **and** python :py:obj:`OSError`. Then you can wrap
+:py:obj:`OSError` in :py:obj:`MPDError<musicpd.MPDError>` exceptions to have to deal
+with a single type of exceptions in your code:
+
+.. literalinclude:: examples/exceptions.py
+   :language: python
+   :linenos:

{python-musicpd-0.8.0 → python-musicpd-0.9.0}/doc/source/index.rst

@@ -1,5 +1,5 @@
-.. SPDX-FileCopyrightText: 2018-2021  kaliko <kaliko@azylum.org>
-.. SPDX-License-Identifier: GPL-3.0-or-later
+.. SPDX-FileCopyrightText: 2018-2023  kaliko <kaliko@azylum.org>
+.. SPDX-License-Identifier: LGPL-3.0-or-later
 
 .. include:: ../../README.rst
 
@@ -20,7 +20,7 @@ Installation
 
 
 Library overview
-----------------
+================
 Here is a snippet allowing to list the last modified artists in the media library:
 
 .. code:: python3
@@ -46,7 +46,7 @@ Here is a snippet allowing to list the last modified artists in the media librar
 
 
 Build documentation
---------------------
+===================
 
 .. code:: bash
 
@@ -55,9 +55,7 @@ Build documentation
     # Installs sphinx if needed
     python3 -m venv venv && . ./venv/bin/activate
     pip install sphinx
-    # And build
-    python3 setup.py build_sphinx
-    # Or call sphinx
+    # Call sphinx
     sphinx-build -d ./doc/build/doctrees doc/source -b html ./doc/build/html
 
 
@@ -67,9 +65,11 @@ Contents
 .. toctree::
    :maxdepth: 2
 
+   self
    use.rst
    doc.rst
    commands.rst
+   examples.rst
    contribute.rst