python-mpv-jsonipc 1.2.3__tar.gz → 1.3.0__tar.gz

{python_mpv_jsonipc-1.2.3/python_mpv_jsonipc.egg-info → python_mpv_jsonipc-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mpv-jsonipc
-Version: 1.2.3
+Version: 1.3.0
 Summary: Python API to MPV using JSON IPC
 Author-email: Izzie Walton <izzie@iwalton.com>
 License-Expression: Apache-2.0

{python_mpv_jsonipc-1.2.3 → python_mpv_jsonipc-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-mpv-jsonipc"
-version = "1.2.3"
+version = "1.3.0"
 description = "Python API to MPV using JSON IPC"
 readme = "README.md"
 license = "Apache-2.0"

{python_mpv_jsonipc-1.2.3 → python_mpv_jsonipc-1.3.0/python_mpv_jsonipc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mpv-jsonipc
-Version: 1.2.3
+Version: 1.3.0
 Summary: Python API to MPV using JSON IPC
 Author-email: Izzie Walton <izzie@iwalton.com>
 License-Expression: Apache-2.0

python_mpv_jsonipc-1.3.0/python_mpv_jsonipc.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE.md
+README.md
+pyproject.toml
+python_mpv_jsonipc.py
+python_mpv_jsonipc.egg-info/PKG-INFO
+python_mpv_jsonipc.egg-info/SOURCES.txt
+python_mpv_jsonipc.egg-info/dependency_links.txt
+python_mpv_jsonipc.egg-info/top_level.txt
+tests/test_api_surface.py
+tests/test_arg_building.py
+tests/test_live_basic.py
+tests/test_live_events.py
+tests/test_live_failure.py
+tests/test_python_floor.py

{python_mpv_jsonipc-1.2.3 → python_mpv_jsonipc-1.3.0}/python_mpv_jsonipc.py

@@ -2,6 +2,7 @@ import threading
 import socket
 import json
 import os
+import re
 import time
 import subprocess
 import random
@@ -35,6 +36,79 @@ class MPVError(Exception):
     def __init__(self, *args, **kwargs):
         super(MPVError, self).__init__(*args, **kwargs)
 
+class MPVProcessError(MPVError):
+    """MPV would not start, with whatever MPV said about why.
+
+    A subclass so that every existing ``except MPVError`` keeps working
+    unchanged -- this library is depended on by projects that will never be
+    updated, and several of them catch only that.
+
+    *returncode* is MPV's exit status, if it got far enough to have one.
+    *bad_option* is the option MPV refused, when that could be determined.
+    *log_output* is what MPV wrote about the failure.
+    *retryable* is False when starting again cannot possibly work.
+    *argv* is the command line that was tried.
+    """
+    def __init__(self, message, returncode=None, bad_option=None,
+                 log_output=None, retryable=True, argv=None):
+        super(MPVProcessError, self).__init__(message)
+        self.returncode = returncode
+        self.bad_option = bad_option
+        self.log_output = log_output
+        self.retryable = retryable
+        self.argv = argv
+
+#: MPV's own wording when it is handed an option it does not have. Matching
+#: it is what turns "MPV exited" into "MPV has no --input-gamepad".
+_OPTION_ERROR = re.compile(r"Error parsing option ([^\s]+) \(option not found\)")
+
+def _diagnose_start_failure(argv, timeout=15):
+    """Ask MPV why it refused *argv*. Returns ``(bad_option, output)``.
+
+    Three details make this reliable, and each was measured rather than
+    reasoned about:
+
+    * **The message comes back on stdout, not stderr.** MPV writes its
+      terminal output to stdout; stderr is empty. Capturing the wrong stream
+      gets a confident, permanent "no idea why".
+    * **``--terminal=yes`` has to come first.** Options are parsed in order
+      and this library sets ``--terminal=no`` by default, so with the flags
+      left as they are MPV has already silenced itself by the time it reaches
+      the option it objects to. The library's own terminal flags are dropped
+      rather than fought with.
+    * **``--version`` goes last**, so a configuration that turns out to be
+      fine parses everything and then exits (~15ms) instead of starting up
+      and having to be killed. It exits before binding the IPC socket, so
+      this cannot disturb the real MPV that is about to start.
+
+    An earlier version of this read ``--log-file`` instead, on the theory
+    that Windows has no stderr to capture. That log is written
+    **unreliably**: MPV does not flush it before exiting, so it arrives
+    truncated at a random point -- measured at 6/8 and 7/8 runs containing
+    the error, cut off anywhere from 102 bytes in. A pipe has no such
+    problem, and is byte-identical across runs.
+
+    Every failure here is answered with ``(None, ...)``, which puts the
+    caller back on the path it took before this existed. Being unable to
+    explain a failed start must never turn into a second failure.
+    """
+    terminal_flags = ("--terminal=", "--input-terminal=")
+    argv = list(argv)
+    probe = ([argv[0], "--terminal=yes"]
+             + [a for a in argv[1:] if not a.startswith(terminal_flags)]
+             + ["--version"])
+    try:
+        completed = subprocess.run(probe,
+                                   stdout=subprocess.PIPE,
+                                   stderr=subprocess.STDOUT,
+                                   timeout=timeout)
+    except Exception:
+        log.debug("Could not run MPV to diagnose the failure.", exc_info=1)
+        return None, None
+    output = completed.stdout.decode("utf-8", "replace")
+    match = _OPTION_ERROR.search(output)
+    return (match.group(1) if match else None), output
+
 class WindowsSocket(threading.Thread):
     """
     Wraps a Windows named pipe in a high-level interface. (Internal)
@@ -198,6 +272,26 @@ class UnixSocket(threading.Thread):
         if self.quit_callback:
             self.quit_callback()
 
+def _ipc_endpoint_ready(ipc_socket):
+    """Return True once MPV's IPC endpoint is available.
+
+    On POSIX the endpoint is a filesystem socket, so ``os.path.exists`` works. On
+    Windows it is a *named pipe*, for which ``os.path.exists`` is always False — so we
+    probe it with ``WaitNamedPipe`` instead. Using ``os.path.exists`` on Windows made
+    the startup poll never detect the pipe, raising a spurious "MPV start timed out".
+    """
+    if os.name != 'nt':
+        return os.path.exists(ipc_socket)
+    try:
+        _winapi.WaitNamedPipe(ipc_socket, 0)
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError:
+        # Pipe exists but all instances are momentarily busy — it is present.
+        return True
+
+
 class MPVProcess:
     """
     Manages an MPV process, ensuring the socket or pipe is available. (Internal)
@@ -243,12 +337,13 @@ class MPVProcess:
 
         args.extend("--{0}={1}".format(v[0].replace("_", "-"), self._mpv_fmt(v[1]))
                     for v in arg_pairs)
+        self.argv = args
         self.process = subprocess.Popen(args)
         ipc_exists = False
         for _ in range(100): # Give MPV 10 seconds to start.
             time.sleep(0.1)
             self.process.poll()
-            if os.path.exists(ipc_socket):
+            if _ipc_endpoint_ready(ipc_socket):
                 ipc_exists = True
                 log.debug("Found MPV socket.")
                 break
@@ -257,11 +352,16 @@ class MPVProcess:
                 break
         else:
             self.process.terminate()
-            raise MPVError("MPV start timed out.")
+            raise MPVProcessError("MPV start timed out.", argv=args)
 
         if not ipc_exists or self.process.returncode is not None:
             self.process.terminate()
-            raise MPVError("MPV not started.")
+            # Message unchanged: it has been this string for years and is not
+            # ours to break. What is new is the argv riding along, which is
+            # what lets the caller ask MPV why.
+            raise MPVProcessError("MPV not started.",
+                                  returncode=self.process.returncode,
+                                  argv=args)
 
     def _set_default(self, prop_dict, key, value):
         if key not in prop_dict:
@@ -409,7 +509,8 @@ class MPV:
     list is used. Not all commands may actually work when this fallback is used.
     """
     def __init__(self, start_mpv=True, ipc_socket=None, mpv_location=None,
-                 log_handler=None, loglevel=None, quit_callback=None, start_retries=5, start_retry_delay_ms=1000, **kwargs):
+                 log_handler=None, loglevel=None, quit_callback=None, start_retries=5, start_retry_delay_ms=1000,
+                 diagnose_start_failures=True, **kwargs):
         """
         Create the interface to MPV and process instance.
 
@@ -419,6 +520,10 @@ class MPV:
         *log_handler(level, prefix, text)* is an optional handler for log events. (Default: Disabled)
         *loglevel* is the level for log messages. Levels are fatal, error, warn, info, v, debug, trace. (Default: Disabled)
         *quit_callback* is called when the socket connection to MPV dies.
+        *diagnose_start_failures* re-runs MPV once, on the first failed start, to find out
+        why it refused to start. If MPV names an option it does not have, MPVProcessError is
+        raised immediately with *bad_option* set instead of spending every retry on something
+        that cannot succeed. Set it to False for the pre-1.3 behaviour. (Default: True)
 
         All other arguments are forwarded to MPV as command-line arguments if *start_mpv* is used.
         """
@@ -440,16 +545,56 @@ class MPV:
 
         if start_mpv:
             # Attempt to start MPV multiple times.
+            last_error = None
+            diagnosed = False
+            log_output = None
             for i in range(start_retries):
                 try:
                     self.mpv_process = MPVProcess(ipc_socket, mpv_location, **kwargs)
                     break
-                except MPVError:
+                except MPVError as error:
+                    last_error = error
                     log.warning("MPV start failed.", exc_info=1)
+
+                    # Ask MPV why, once, on the first failure. An option MPV
+                    # does not have cannot start on the fifth attempt either,
+                    # and spending the whole retry budget on it produces the
+                    # least useful error this library has ever raised: a
+                    # timeout that names nothing. The probe costs one ~20ms
+                    # MPV run and only ever happens on a start that has
+                    # already failed.
+                    argv = getattr(error, "argv", None)
+                    if diagnose_start_failures and argv and not diagnosed:
+                        diagnosed = True
+                        bad_option, diagnosis = _diagnose_start_failure(argv)
+                        # Keep what MPV said even when it does not name an
+                        # option. Refusing to start over a missing DLL or an
+                        # unusable VO is the same predicament from the user's
+                        # side -- something they changed, and nothing to go
+                        # on -- and on Windows there is no console for them to
+                        # have seen it in. It rides out on .log_output below.
+                        log_output = diagnosis
+                        if bad_option is not None:
+                            raise MPVProcessError(
+                                "MPV rejected the option --{0}.".format(
+                                    bad_option),
+                                returncode=getattr(error, "returncode", None),
+                                bad_option=bad_option,
+                                log_output=log_output,
+                                retryable=False,
+                                argv=argv)
+
                     time.sleep(start_retry_delay_ms / 1000)
                     continue
             else:
-                raise MPVError("MPV process retry limit reached.")
+                # The message is unchanged on purpose. Downstream projects
+                # that will never be updated may be matching on it, and this
+                # is still the same situation it has always described.
+                raise MPVProcessError(
+                    "MPV process retry limit reached.",
+                    returncode=getattr(last_error, "returncode", None),
+                    log_output=log_output,
+                    argv=getattr(last_error, "argv", None))
 
         self.mpv_inter = MPVInter(ipc_socket, self._callback, self._quit_callback)
         self.properties = set(x.replace("-", "_") for x in self.command("get_property", "property-list"))

python_mpv_jsonipc-1.3.0/tests/test_api_surface.py

@@ -0,0 +1,136 @@
+"""The public surface, frozen.
+
+Roughly 78 repositories depend on this library, some unmaintained, and a name
+or keyword argument that quietly changes shape breaks them at *their* users'
+machines rather than here. Keyword names matter as much as the names
+themselves: callers pass `mpv_location=`, `quit_callback=`, `start_retries=`
+by keyword, so a rename is a break even when the parameter still exists.
+
+This is a snapshot, not a judgement. Nothing here says the surface is good --
+only that it is what shipped. Changing it deliberately means regenerating the
+golden file in the same commit, which is what makes the change visible in
+review instead of six months later in someone's issue tracker.
+
+    python3 tests/test_api_surface.py --update
+"""
+
+import inspect
+import json
+import os
+import sys
+import unittest
+
+from _harness import python_mpv_jsonipc
+
+GOLDEN = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                      "api_surface.json")
+
+
+def _signature(func):
+    try:
+        return str(inspect.signature(func))
+    except (TypeError, ValueError):  # pragma: no cover - C callables
+        return "(?)"
+
+
+def describe():
+    """The public surface as plain data, stable under dict ordering."""
+    module = python_mpv_jsonipc
+    surface = {"classes": {}, "functions": {}, "constants": {}}
+
+    for name in sorted(dir(module)):
+        if name.startswith("_"):
+            continue
+        value = getattr(module, name)
+        if inspect.isclass(value):
+            if value.__module__ != module.__name__:
+                continue  # imported, not ours
+            # Only what the class itself defines. `dir()` would drag in
+            # inherited stdlib members -- `Thread.start`, and for exceptions
+            # `with_traceback` and `add_note` -- whose introspectability
+            # varies by interpreter version: 3.13 reports
+            # `(self, object, /)` where 3.11 raises and we record `(?)`.
+            # That made the golden file disagree with itself across the
+            # Python matrix while nothing about this library had changed.
+            # Inheritance is still recorded, in `bases`.
+            methods = {}
+            for attr, member in sorted(vars(value).items()):
+                if attr.startswith("_") and attr != "__init__":
+                    continue
+                if callable(member):
+                    methods[attr] = _signature(member)
+            surface["classes"][name] = {
+                "bases": [b.__name__ for b in value.__bases__],
+                "methods": methods,
+            }
+        elif inspect.isfunction(value):
+            surface["functions"][name] = _signature(value)
+        elif isinstance(value, (int, float, str, bool, list, tuple)):
+            surface["constants"][name] = value
+
+    return surface
+
+
+class ApiSurfaceTest(unittest.TestCase):
+    def test_the_public_surface_matches_the_golden_file(self):
+        with open(GOLDEN) as handle:
+            expected = json.load(handle)
+        actual = describe()
+        self.assertEqual(
+            expected, actual,
+            "The public API changed. If that was deliberate, regenerate the "
+            "golden file with `python3 tests/test_api_surface.py --update` "
+            "in the same commit -- and consider whether downstream users who "
+            "never read the changelog will survive it.")
+
+    def test_the_names_downstream_actually_imports_are_present(self):
+        # Named individually as well as by snapshot, so a wholesale
+        # regeneration of the golden file cannot silently bless a removal.
+        for name in ("MPV", "MPVError", "MPVProcess", "MPVInter",
+                     "EventHandler", "UnixSocket"):
+            self.assertTrue(hasattr(python_mpv_jsonipc, name),
+                            "{0} disappeared from the public surface".format(name))
+
+    def test_mpv_error_stays_an_exception(self):
+        self.assertTrue(issubclass(python_mpv_jsonipc.MPVError, Exception))
+        # Downstream catches it and reads str(); both are contract.
+        self.assertEqual(str(python_mpv_jsonipc.MPVError("boom")), "boom")
+
+    def test_the_constructor_keywords_keep_their_names_and_defaults(self):
+        parameters = inspect.signature(python_mpv_jsonipc.MPV.__init__).parameters
+        self.assertEqual(parameters["start_mpv"].default, True)
+        self.assertEqual(parameters["ipc_socket"].default, None)
+        self.assertEqual(parameters["mpv_location"].default, None)
+        self.assertEqual(parameters["log_handler"].default, None)
+        self.assertEqual(parameters["loglevel"].default, None)
+        self.assertEqual(parameters["quit_callback"].default, None)
+        self.assertEqual(parameters["start_retries"].default, 5)
+        self.assertEqual(parameters["start_retry_delay_ms"].default, 1000)
+        self.assertEqual(parameters["kwargs"].kind,
+                         inspect.Parameter.VAR_KEYWORD)
+
+
+class FallbackCommandListTest(unittest.TestCase):
+    """Only reachable on very old mpv, and therefore never exercised by the
+    live tests -- which is exactly why it needs pinning here."""
+
+    def test_it_still_contains_what_a_client_needs_to_play_something(self):
+        commands = python_mpv_jsonipc.FALLBACK_COMMAND_LIST
+        for essential in ("loadfile", "quit", "seek", "stop", "set",
+                          "keybind", "script-message"):
+            self.assertIn(essential, commands)
+
+    def test_it_is_a_list_of_plain_strings(self):
+        self.assertIsInstance(python_mpv_jsonipc.FALLBACK_COMMAND_LIST, list)
+        for command in python_mpv_jsonipc.FALLBACK_COMMAND_LIST:
+            self.assertIsInstance(command, str)
+
+
+if __name__ == "__main__":
+    if "--update" in sys.argv:
+        with open(GOLDEN, "w") as handle:
+            json.dump(describe(), handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        print("wrote {0}".format(GOLDEN))
+        sys.exit(0)
+    unittest.main()

python_mpv_jsonipc-1.3.0/tests/test_arg_building.py

@@ -0,0 +1,125 @@
+"""How Python kwargs become mpv command-line arguments.
+
+Characterization, not aspiration: these assert what the library does today,
+including the parts that look accidental. The argv is the whole contract
+between this library and mpv, and downstream code passes options through it
+that neither this repo nor its author has ever seen -- so the mapping is
+pinned exactly, order included.
+
+No mpv runs here. ``Popen`` is captured and the endpoint poll is answered
+``True``, which is honest for a test that only ever reads back the argv; see
+``_harness`` for why nothing about lifecycle is tested this way.
+"""
+
+import os
+import unittest
+from unittest import mock
+
+from _harness import python_mpv_jsonipc
+
+
+class _FakeProcess:
+    returncode = None
+
+    def poll(self):
+        return None
+
+    def terminate(self):
+        pass
+
+
+def build_argv(ipc_socket="/tmp/testsocket", mpv_location="mpv", **kwargs):
+    """The argv ``MPVProcess`` would have spawned, without spawning it."""
+    with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen") as popen, \
+            mock.patch.object(python_mpv_jsonipc, "_ipc_endpoint_ready",
+                              return_value=True):
+        popen.return_value = _FakeProcess()
+        python_mpv_jsonipc.MPVProcess(ipc_socket, mpv_location, **kwargs)
+        return popen.call_args[0][0]
+
+
+class ArgumentTranslationTest(unittest.TestCase):
+    def test_the_binary_leads_and_defaults_follow_the_callers_options(self):
+        # Order is observable and therefore pinned. `_set_default` appends,
+        # so anything the caller did not pass arrives after what they did,
+        # in the order the defaults are applied.
+        self.assertEqual(build_argv(mpv_location="/usr/bin/mpv"), [
+            "/usr/bin/mpv",
+            "--idle=yes",
+            "--input-ipc-server=/tmp/testsocket",
+            "--input-terminal=no",
+            "--terminal=no",
+        ])
+
+    def test_underscores_become_dashes(self):
+        self.assertIn("--hwdec-codecs=all", build_argv(hwdec_codecs="all"))
+
+    def test_booleans_become_yes_and_no(self):
+        argv = build_argv(fullscreen=True, border=False)
+        self.assertIn("--fullscreen=yes", argv)
+        self.assertIn("--border=no", argv)
+
+    def test_numbers_are_not_booleans(self):
+        # 1 == True and 0 == False in Python, so an `==` comparison turns
+        # --video-scale-x=1 into --video-scale-x=yes, which mpv rejects.
+        # Fixed in 8ddcfec; pinned here because the bug is invisible until
+        # mpv refuses the option.
+        argv = build_argv(video_scale_x=1, volume=0)
+        self.assertIn("--video-scale-x=1", argv)
+        self.assertIn("--volume=0", argv)
+
+    def test_floats_and_strings_pass_through_as_written(self):
+        argv = build_argv(speed=1.5, title="a movie")
+        self.assertIn("--speed=1.5", argv)
+        self.assertIn("--title=a movie", argv)
+
+    def test_a_list_becomes_a_repeated_flag(self):
+        argv = build_argv(script=["a.lua", "b.lua"])
+        self.assertEqual([a for a in argv if a.startswith("--script=")],
+                         ["--script=a.lua", "--script=b.lua"])
+
+    def test_the_caller_can_override_every_default(self):
+        argv = build_argv(idle=False, terminal=True, input_terminal=True)
+        self.assertIn("--idle=no", argv)
+        self.assertIn("--terminal=yes", argv)
+        self.assertIn("--input-terminal=yes", argv)
+        self.assertEqual(len([a for a in argv if a.startswith("--idle=")]), 1)
+
+    def test_the_ipc_server_option_is_not_overridable_by_that_name(self):
+        # input_ipc_server is a default like any other, so a caller CAN
+        # replace it -- and then the library connects to the socket it was
+        # told about rather than the one mpv opens. Pinned as-is: it is a
+        # foot-gun, but changing it would change behaviour.
+        argv = build_argv(input_ipc_server="/tmp/elsewhere")
+        self.assertIn("--input-ipc-server=/tmp/elsewhere", argv)
+        self.assertNotIn("--input-ipc-server=/tmp/testsocket", argv)
+
+
+class SocketPathTest(unittest.TestCase):
+    @unittest.skipIf(os.name == "nt", "POSIX socket paths only")
+    def test_a_stale_socket_file_is_removed_before_starting(self):
+        import tempfile
+        path = os.path.join(tempfile.mkdtemp(), "stale.sock")
+        with open(path, "w") as handle:
+            handle.write("")
+        self.assertTrue(os.path.exists(path))
+        build_argv(ipc_socket=path)
+        self.assertFalse(os.path.exists(path))
+
+
+class MpvFmtTest(unittest.TestCase):
+    """`_mpv_fmt` in isolation, since it is where the bool/int trap lives."""
+
+    def setUp(self):
+        self.fmt = python_mpv_jsonipc.MPVProcess._mpv_fmt
+
+    def test_identity_comparison_keeps_numbers_intact(self):
+        self.assertEqual(self.fmt(None, True), "yes")
+        self.assertEqual(self.fmt(None, False), "no")
+        self.assertEqual(self.fmt(None, 1), 1)
+        self.assertEqual(self.fmt(None, 0), 0)
+        self.assertEqual(self.fmt(None, "yes"), "yes")
+
+
+if __name__ == "__main__":
+    unittest.main()

python_mpv_jsonipc-1.3.0/tests/test_live_basic.py

@@ -0,0 +1,189 @@
+"""Properties and commands against a real mpv.
+
+Everything here needs a live mpv on purpose. The dynamic attribute machinery
+is built from what mpv answers at construction time -- `property-list` and
+`command-list` -- so a stand-in that returns a convenient list would be
+testing the list, not the library.
+"""
+
+import unittest
+
+import os
+
+from _harness import (LiveMPVTest, MPV_BINARY,
+                      python_mpv_jsonipc)
+
+
+class ConstructionTest(LiveMPVTest):
+    def test_properties_are_discovered_and_underscored(self):
+        self.assertIn("pause", self.mpv.properties)
+        self.assertIn("playback_time", self.mpv.properties)   # playback-time
+        self.assertNotIn("playback-time", self.mpv.properties)
+
+    def test_commands_are_attached_as_methods(self):
+        for command in ("loadfile", "seek", "quit", "keybind"):
+            self.assertTrue(callable(getattr(self.mpv, command, None)),
+                            "{0} is not callable".format(command))
+
+    def test_json_ipc_only_commands_are_not_attached(self):
+        # These are not in mpv's `command-list` -- they exist only over the
+        # IPC transport -- so they never become methods. Callers reach them
+        # through `command()`, or through the wrappers that exist for the
+        # two that have one (`bind_property_observer`, `wait_for_property`).
+        # Worth pinning: it looks like an omission and is the actual design.
+        for command in ("observe_property", "unobserve_property",
+                        "get_property", "set_property",
+                        "request_log_messages", "client_name"):
+            self.assertFalse(callable(getattr(self.mpv, command, None)),
+                             "{0} unexpectedly became a method".format(command))
+
+    def test_a_command_that_collides_with_a_property_gets_a_cmd_suffix(self):
+        # `af` and `vf` are both, on every mpv this has been run against.
+        # Discovered rather than hard-coded so a change in mpv shows up as a
+        # skip, not a spurious failure.
+        collisions = [name for name in ("af", "vf")
+                      if name in self.mpv.properties]
+        if not collisions:
+            self.skipTest("this mpv has no command/property name collisions")
+        for name in collisions:
+            self.assertTrue(callable(getattr(self.mpv, name + "_cmd", None)))
+
+    def test_dir_lists_properties_alongside_real_attributes(self):
+        listing = dir(self.mpv)
+        self.assertIn("pause", listing)
+        self.assertIn("terminate", listing)
+
+
+class PropertyAccessTest(LiveMPVTest):
+    def test_a_property_round_trips_through_attribute_access(self):
+        self.mpv.pause = True
+        self.assertIs(self.mpv.pause, True)
+        self.mpv.pause = False
+        self.assertIs(self.mpv.pause, False)
+
+    def test_an_unavailable_property_reads_as_none_rather_than_raising(self):
+        # Nothing is loaded, so mpv answers "property unavailable". The
+        # library turns exactly that one error into None; downstream code
+        # leans on it heavily (`if mpv.width:`).
+        self.assertIsNone(self.mpv.width)
+
+    def test_an_unknown_property_raises_mpv_error(self):
+        with self.assertRaises(python_mpv_jsonipc.MPVError) as caught:
+            self.mpv.command("get_property", "no-such-property")
+        self.assertEqual(str(caught.exception), "property not found")
+
+    def test_an_unknown_attribute_is_a_normal_attribute_error(self):
+        # Not an MPVError: `properties` gates the property path, so anything
+        # else falls through to ordinary attribute lookup.
+        with self.assertRaises(AttributeError):
+            self.mpv.definitely_not_a_property
+
+    def test_setting_a_non_property_attribute_stays_local(self):
+        self.mpv.my_own_bookkeeping = 42
+        self.assertEqual(self.mpv.my_own_bookkeeping, 42)
+
+
+class CommandTest(LiveMPVTest):
+    def test_command_returns_the_data_field(self):
+        self.assertIsInstance(self.mpv.command("get_property", "mpv-version"),
+                              str)
+
+    def test_play_is_an_alias_for_loadfile(self):
+        seen = []
+        self.mpv.loadfile = lambda *args: seen.append(args)
+        self.mpv.play("av://lavfi:testsrc")
+        self.assertEqual(seen, [("av://lavfi:testsrc",)])
+
+
+class AttachToExistingMPVTest(unittest.TestCase):
+    """`start_mpv=False` -- attaching to an mpv somebody else started.
+
+    jellyfin-mpv-shim's `mpv_ext_start: false` runs this way, and it is the
+    path with the least coverage elsewhere: no `MPVProcess` is built, so
+    `_ipc_endpoint_ready` never runs and the transport's own connect retry is
+    the only thing that waits for the endpoint.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        if MPV_BINARY is None:
+            raise unittest.SkipTest("no mpv binary found")
+
+    def setUp(self):
+        import random
+        import subprocess
+        import time
+
+        name = "mpvtest{0}".format(random.randint(0, 2 ** 48))
+        # Windows wants a bare pipe name (the library prepends the
+        # \\.\pipe\ prefix); POSIX wants a filesystem path.
+        self.ipc_socket = name if os.name == "nt" else "/tmp/" + name
+
+        self.process = subprocess.Popen([
+            MPV_BINARY, "--idle=yes", "--config=no", "--vo=null", "--ao=null",
+            "--terminal=no", "--input-ipc-server=" + self.ipc_socket])
+        self.addCleanup(self._stop_mpv)
+
+        deadline = time.time() + 10
+        while time.time() < deadline:
+            if python_mpv_jsonipc._ipc_endpoint_ready(
+                    self.ipc_socket if os.name != "nt"
+                    else "\\\\.\\pipe\\" + self.ipc_socket):
+                break
+            time.sleep(0.1)
+        else:
+            self.fail("mpv never opened its IPC endpoint")
+
+    def _stop_mpv(self):
+        self.process.terminate()
+        self.process.wait(timeout=10)
+        if os.name != "nt" and os.path.exists(self.ipc_socket):
+            os.remove(self.ipc_socket)
+
+    def test_it_attaches_and_talks_to_the_running_mpv(self):
+        mpv = python_mpv_jsonipc.MPV(start_mpv=False,
+                                     ipc_socket=self.ipc_socket)
+        self.addCleanup(mpv.terminate)
+        self.assertIsInstance(mpv.command("get_property", "mpv-version"), str)
+        mpv.pause = True
+        self.assertIs(mpv.pause, True)
+
+    def test_terminate_leaves_the_process_it_did_not_start_alone(self):
+        # It never owned the process, so it must not kill it. A host that
+        # attaches to the user's own mpv would otherwise shut it down.
+        mpv = python_mpv_jsonipc.MPV(start_mpv=False,
+                                     ipc_socket=self.ipc_socket)
+        self.assertIsNone(mpv.mpv_process)
+        mpv.terminate()
+        self.assertIsNone(self.process.poll(),
+                          "terminate() killed an mpv it did not start")
+
+
+class TeardownTest(LiveMPVTest):
+    def test_terminate_is_safe_to_call_twice(self):
+        # __del__ calls terminate() too, so every user of this library
+        # terminates at least twice whether they meant to or not.
+        self.mpv.terminate()
+        self.mpv.terminate()
+
+    @unittest.skipIf(__import__("os").name == "nt", "POSIX socket files only")
+    def test_terminate_removes_the_socket_file_it_created(self):
+        # A long-running host that opens and closes many mpv instances would
+        # otherwise fill /tmp with dead sockets.
+        import glob
+        import os
+        socket_path = self.mpv.mpv_process.ipc_socket
+        self.assertTrue(os.path.exists(socket_path))
+        self.mpv.terminate()
+        self.assertFalse(os.path.exists(socket_path))
+
+    def test_commands_after_terminate_fail_fast_rather_than_hanging(self):
+        # The 120s command timeout would be a very long way to discover a
+        # closed socket. The transport raises instead.
+        self.mpv.terminate()
+        with self.assertRaises(BrokenPipeError):
+            self.mpv.command("get_property", "pause")
+
+
+if __name__ == "__main__":
+    unittest.main()

python_mpv_jsonipc-1.3.0/tests/test_live_events.py

@@ -0,0 +1,177 @@
+"""Observers, events, key bindings and log forwarding, against a real mpv.
+
+Every callback here is delivered on the `EventHandler` thread, so each test
+waits on a `threading.Event` with a bounded timeout rather than sleeping. A
+test that sleeps a fixed amount either wastes the time or fails on a loaded
+CI runner, and usually both.
+"""
+
+import threading
+import unittest
+
+from _harness import (LIVE_OPTIONS, LiveMPVTest, MPV_BINARY,
+                      python_mpv_jsonipc)
+
+TIMEOUT = 10
+
+
+def waiter():
+    """An event plus a recorder, for asserting on an async callback."""
+    seen = []
+    fired = threading.Event()
+
+    def record(*args):
+        seen.append(args)
+        fired.set()
+
+    return seen, fired, record
+
+
+class PropertyObserverTest(LiveMPVTest):
+    def test_observer_ids_start_at_one_and_increment(self):
+        first = self.mpv.bind_property_observer("pause", lambda *_: None)
+        second = self.mpv.bind_property_observer("volume", lambda *_: None)
+        self.assertEqual(first, 1)
+        self.assertEqual(second, 2)
+
+    def test_an_observer_is_called_with_the_name_and_value(self):
+        seen, fired, record = waiter()
+        self.mpv.bind_property_observer("pause", record)
+        # mpv sends the current value immediately on observe, before any
+        # change -- that first notification is what `wait_for_property`
+        # exists to skip.
+        self.assertTrue(fired.wait(TIMEOUT), "observer never fired")
+        self.assertEqual(seen[0][0], "pause")
+
+    def test_an_observer_sees_a_change(self):
+        seen, fired, record = waiter()
+        self.mpv.bind_property_observer("pause", record)
+        self.assertTrue(fired.wait(TIMEOUT))
+        fired.clear()
+        self.mpv.pause = True
+        self.assertTrue(fired.wait(TIMEOUT), "no notification for the change")
+        self.assertEqual(seen[-1], ("pause", True))
+
+    def test_unbinding_stops_the_callbacks_and_forgets_the_binding(self):
+        observer_id = self.mpv.bind_property_observer("pause", lambda *_: None)
+        self.assertIn(observer_id, self.mpv.property_bindings)
+        self.mpv.unbind_property_observer(observer_id)
+        self.assertNotIn(observer_id, self.mpv.property_bindings)
+
+    def test_property_observer_decorator_binds(self):
+        seen, fired, record = waiter()
+
+        @self.mpv.property_observer("pause")
+        def _handler(name, value):
+            record(name, value)
+
+        self.assertTrue(fired.wait(TIMEOUT))
+
+
+class WaitForPropertyTest(LiveMPVTest):
+    def test_it_returns_only_after_an_actual_change(self):
+        # The first notification is mpv reporting the current value. If
+        # wait_for_property honoured it, this would return before `pause`
+        # was ever set and the assertion below would be a coin flip.
+        done = threading.Event()
+
+        def wait():
+            self.mpv.wait_for_property("pause")
+            done.set()
+
+        thread = threading.Thread(target=wait, daemon=True)
+        thread.start()
+        self.assertFalse(done.wait(1.0),
+                         "returned on the initial value notification")
+        self.mpv.pause = True
+        self.assertTrue(done.wait(TIMEOUT), "never returned after the change")
+
+
+class EventTest(LiveMPVTest):
+    def test_on_event_receives_mpv_events(self):
+        seen, fired, record = waiter()
+        self.mpv.on_event("client-message")(record)
+        self.mpv.command("script-message", "hello")
+        self.assertTrue(fired.wait(TIMEOUT), "no client-message event")
+        self.assertEqual(seen[-1][0]["args"], ["hello"])
+
+    def test_event_callback_is_an_alias_of_on_event(self):
+        # Kept for python-mpv compatibility; downstream uses both spellings.
+        seen, fired, record = waiter()
+        self.mpv.event_callback("client-message")(record)
+        self.mpv.command("script-message", "via-alias")
+        self.assertTrue(fired.wait(TIMEOUT))
+
+    def test_bind_event_allows_several_callbacks_for_one_event(self):
+        first, fired_first, record_first = waiter()
+        second, fired_second, record_second = waiter()
+        self.mpv.bind_event("client-message", record_first)
+        self.mpv.bind_event("client-message", record_second)
+        self.mpv.command("script-message", "both")
+        self.assertTrue(fired_first.wait(TIMEOUT))
+        self.assertTrue(fired_second.wait(TIMEOUT))
+
+
+class KeyBindingTest(LiveMPVTest):
+    def test_a_bound_key_fires_its_callback(self):
+        # Round trips through mpv: keybind -> script-message custom-bind
+        # <id> -> client-message -> the callback registry.
+        seen, fired, record = waiter()
+        self.mpv.bind_key_press("a", record)
+        self.mpv.command("keypress", "a")
+        self.assertTrue(fired.wait(TIMEOUT), "key binding never fired")
+
+    def test_on_key_press_decorator_binds(self):
+        seen, fired, record = waiter()
+
+        @self.mpv.on_key_press("b")
+        def _handler():
+            record()
+
+        self.mpv.command("keypress", "b")
+        self.assertTrue(fired.wait(TIMEOUT))
+
+
+class LogHandlerTest(unittest.TestCase):
+    """The one existing opt-in output channel. Off unless BOTH log_handler
+    and loglevel are given -- pinned because the new startup-failure
+    diagnosis should follow this shape rather than invent another."""
+
+    def _mpv(self, **extra):
+        options = dict(LIVE_OPTIONS)
+        options.update(extra)
+        instance = python_mpv_jsonipc.MPV(mpv_location=MPV_BINARY, **options)
+        self.addCleanup(instance.terminate)
+        return instance
+
+    @classmethod
+    def setUpClass(cls):
+        if MPV_BINARY is None:
+            raise unittest.SkipTest("no mpv binary found")
+
+    def test_a_handler_with_a_level_receives_log_messages(self):
+        # `debug`, not `info`: an idle mpv says nothing at info or v once it
+        # has finished starting, and `request_log_messages` only forwards
+        # what is emitted after the request. Measured -- at info and v this
+        # test waits the full timeout and sees zero messages.
+        seen, fired, record = waiter()
+        mpv = self._mpv(log_handler=record, loglevel="debug")
+        mpv.command("script-message", "provoke-some-logging")
+        mpv.command("get_property", "mpv-version")
+        self.assertTrue(fired.wait(TIMEOUT), "no log messages arrived")
+        level, prefix, text = seen[0]
+        self.assertIsInstance(level, str)
+        self.assertIsInstance(prefix, str)
+        self.assertIsInstance(text, str)
+
+    def test_a_handler_without_a_level_is_ignored(self):
+        seen, fired, record = waiter()
+        mpv = self._mpv(log_handler=record)
+        mpv.command("script-message", "provoke-some-logging")
+        mpv.command("get_property", "mpv-version")
+        self.assertFalse(fired.wait(1.0),
+                         "log messages arrived without a loglevel")
+
+
+if __name__ == "__main__":
+    unittest.main()

python_mpv_jsonipc-1.3.0/tests/test_live_failure.py

@@ -0,0 +1,240 @@
+"""What happens when mpv will not start.
+
+**Most of this file exists to be changed.** The error handling here is due to
+be replaced with something that names the option mpv rejected and refuses to
+retry a start that cannot succeed. Pinning the current behaviour first is what
+makes that change reviewable: the diff will show precisely which observable
+things moved, rather than leaving it to be discovered by a downstream user on
+an unmaintained project.
+
+So: assert what it does, not what it should do. In particular the exact
+exception message and the retry count are load-bearing here only because
+somebody out there may be matching on them.
+"""
+
+import os
+import subprocess
+import time
+import unittest
+from unittest import mock
+
+from _harness import (LIVE_OPTIONS, MPV_BINARY, python_mpv_jsonipc,
+                      requires_mpv)
+
+
+@requires_mpv
+class BadOptionTest(unittest.TestCase):
+    """mpv exits immediately when handed an option it does not have. This is
+    the exact case the shim hits with a build-gated option such as
+    `--input-gamepad` on an mpv built without SDL2 gamepad support.
+
+    **These assertions were rewritten deliberately** when start-failure
+    diagnosis landed. What they said before is preserved in
+    `PreDiagnosisBehaviourTest` below, reachable with
+    `diagnose_start_failures=False`, because that is the behaviour downstream
+    projects have been living with.
+    """
+
+    def start_with_bad_option(self, **overrides):
+        options = dict(LIVE_OPTIONS)
+        options.update(dict(mpv_location=MPV_BINARY,
+                            start_retries=3,
+                            start_retry_delay_ms=50))
+        options.update(overrides)
+        options["definitely_not_an_mpv_option"] = "yes"
+        return python_mpv_jsonipc.MPV(**options)
+
+    def test_the_error_names_the_option_mpv_refused(self):
+        with self.assertRaises(python_mpv_jsonipc.MPVProcessError) as caught:
+            self.start_with_bad_option()
+        self.assertEqual(caught.exception.bad_option,
+                         "definitely-not-an-mpv-option")
+        self.assertIn("definitely-not-an-mpv-option", str(caught.exception))
+
+    def test_it_is_still_an_mpv_error(self):
+        # The compatibility promise. Downstream catches MPVError and nothing
+        # finer; a new type that escaped those handlers would be a break
+        # dressed up as an improvement.
+        with self.assertRaises(python_mpv_jsonipc.MPVError):
+            self.start_with_bad_option()
+
+    def test_it_carries_mpvs_exit_status_and_its_own_words(self):
+        with self.assertRaises(python_mpv_jsonipc.MPVProcessError) as caught:
+            self.start_with_bad_option()
+        self.assertEqual(caught.exception.returncode, 1)
+        self.assertIn("Error parsing option", caught.exception.log_output)
+        self.assertFalse(caught.exception.retryable)
+
+    def test_it_stops_instead_of_spending_every_retry(self):
+        # Exactly one real start attempt plus one diagnostic probe, and no
+        # second attempt. Counted by shape rather than by total, because the
+        # probe goes through Popen too (subprocess.run uses it), so a bare
+        # count of 2 would also be satisfied by two starts and no probe.
+        with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen",
+                               wraps=subprocess.Popen) as popen:
+            with self.assertRaises(python_mpv_jsonipc.MPVProcessError):
+                self.start_with_bad_option(start_retries=3)
+        argvs = [call.args[0] for call in popen.call_args_list]
+        starts = [a for a in argvs if "--version" not in a]
+        probes = [a for a in argvs if "--version" in a]
+        self.assertEqual(len(starts), 1, "MPV was started more than once")
+        self.assertEqual(len(probes), 1, "the diagnosis ran more than once")
+
+    def test_it_does_not_pay_the_retry_delay_it_cannot_use(self):
+        started = time.perf_counter()
+        with self.assertRaises(python_mpv_jsonipc.MPVProcessError):
+            self.start_with_bad_option(start_retries=3,
+                                       start_retry_delay_ms=3000)
+        self.assertLess(time.perf_counter() - started, 3.0)
+
+    def test_the_diagnosis_does_not_bind_the_ipc_socket(self):
+        # The probe re-runs MPV with the same --input-ipc-server. `--version`
+        # makes it exit before serving, but if that ever stopped being true
+        # the diagnosis would squat on the endpoint the real MPV is about to
+        # open -- turning a diagnosable failure into a mysterious one.
+        socket_path = "/tmp/diagnosis-probe-{0}".format(os.getpid())
+        if os.name == "nt":
+            self.skipTest("POSIX socket paths only")
+        with self.assertRaises(python_mpv_jsonipc.MPVProcessError):
+            self.start_with_bad_option(ipc_socket=socket_path)
+        self.assertFalse(os.path.exists(socket_path))
+
+    def test_mpvs_own_words_survive_even_when_no_option_is_named(self):
+        # Not every refusal is an option error -- a missing DLL or an
+        # unusable VO reads the same way to a user: something changed and
+        # there is nothing to go on. On Windows especially there is no
+        # console they could have seen it in. So whatever MPV said is
+        # attached even when the diagnosis cannot name an option.
+        with mock.patch.object(python_mpv_jsonipc, "_diagnose_start_failure",
+                               return_value=(None, "mpv: some other refusal")):
+            with self.assertRaises(python_mpv_jsonipc.MPVProcessError) as caught:
+                self.start_with_bad_option(start_retries=2)
+        self.assertEqual(str(caught.exception),
+                         "MPV process retry limit reached.")
+        self.assertEqual(caught.exception.log_output, "mpv: some other refusal")
+
+    def test_a_failure_it_cannot_explain_still_retries_and_reports_as_before(self):
+        # The diagnosis is not always conclusive -- mpv may have died for a
+        # reason it did not write down. That path must behave exactly as it
+        # always did, or an unexplained flake becomes a hard failure.
+        with mock.patch.object(python_mpv_jsonipc, "_diagnose_start_failure",
+                               return_value=(None, "nothing conclusive")):
+            with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen",
+                                   wraps=subprocess.Popen) as popen:
+                with self.assertRaises(python_mpv_jsonipc.MPVError) as caught:
+                    self.start_with_bad_option(start_retries=3)
+                self.assertEqual(str(caught.exception),
+                                 "MPV process retry limit reached.")
+                self.assertEqual(popen.call_count, 3)
+
+
+@requires_mpv
+class PreDiagnosisBehaviourTest(unittest.TestCase):
+    """`diagnose_start_failures=False` -- what every release before 1.3 did.
+
+    Kept as a supported escape hatch, and tested, because "you can turn the
+    new behaviour off" is worth nothing if nobody checks that the switch
+    still reaches the old code.
+    """
+
+    def start_with_bad_option(self, **overrides):
+        options = dict(LIVE_OPTIONS)
+        options.update(dict(mpv_location=MPV_BINARY,
+                            start_retries=3,
+                            start_retry_delay_ms=50,
+                            diagnose_start_failures=False))
+        options.update(overrides)
+        options["definitely_not_an_mpv_option"] = "yes"
+        return python_mpv_jsonipc.MPV(**options)
+
+    def test_it_raises_the_retry_limit_message_and_names_no_option(self):
+        with self.assertRaises(python_mpv_jsonipc.MPVError) as caught:
+            self.start_with_bad_option()
+        self.assertEqual(str(caught.exception),
+                         "MPV process retry limit reached.")
+        self.assertNotIn("definitely", str(caught.exception))
+
+    def test_every_retry_is_spent_on_a_start_that_cannot_succeed(self):
+        with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen",
+                               wraps=subprocess.Popen) as popen:
+            with self.assertRaises(python_mpv_jsonipc.MPVError):
+                self.start_with_bad_option(start_retries=3)
+            self.assertEqual(popen.call_count, 3)
+
+    def test_the_configured_delay_is_paid_after_every_failure(self):
+        started = time.perf_counter()
+        with self.assertRaises(python_mpv_jsonipc.MPVError):
+            self.start_with_bad_option(start_retries=3,
+                                       start_retry_delay_ms=300)
+        self.assertGreaterEqual(time.perf_counter() - started, 0.9)
+
+
+@requires_mpv
+class MissingBinaryTest(unittest.TestCase):
+    def test_a_missing_mpv_binary_is_not_retried_and_is_not_an_mpv_error(self):
+        # `except MPVError` in the retry loop does not catch this, so it
+        # escapes on the first attempt. jellyfin-mpv-shim depends on exactly
+        # this to tell "no mpv installed" from "mpv rejected an option".
+        with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen",
+                               wraps=subprocess.Popen) as popen:
+            with self.assertRaises(FileNotFoundError):
+                python_mpv_jsonipc.MPV(
+                    mpv_location=os.path.join(os.sep, "nonexistent", "mpv"),
+                    start_retries=5, start_retry_delay_ms=50, **LIVE_OPTIONS)
+            self.assertEqual(popen.call_count, 1)
+
+
+@requires_mpv
+class NoServerTest(unittest.TestCase):
+    def test_attaching_to_a_socket_nothing_is_listening_on_raises(self):
+        # start_mpv=False means "something else owns the process". If the
+        # endpoint is not there, the transport raises out of the constructor
+        # rather than waiting -- but *which* exception is a real divergence
+        # between the two transports, found by the Windows CI leg rather than
+        # by reading the code:
+        #
+        #   UnixSocket    -> socket.connect fails -> OSError, immediately.
+        #   WindowsSocket -> CreateFile fails -> five attempts a second apart
+        #                    -> MPVError("Cannot connect to pipe."), which is
+        #                    NOT an OSError.
+        #
+        # Pinned per platform rather than widened to `Exception`, because the
+        # difference is the thing worth knowing: code that catches OSError
+        # around this constructor works on Linux and not on Windows.
+        expected = (python_mpv_jsonipc.MPVError if os.name == "nt"
+                    else OSError)
+        with self.assertRaises(expected):
+            python_mpv_jsonipc.MPV(start_mpv=False,
+                                   ipc_socket="definitely-no-mpv-here"
+                                   if os.name == "nt"
+                                   else "/tmp/definitely-no-mpv-here")
+
+
+@requires_mpv
+class QuitCallbackTest(unittest.TestCase):
+    def test_it_fires_when_mpv_goes_away(self):
+        import threading
+        fired = threading.Event()
+        mpv = python_mpv_jsonipc.MPV(mpv_location=MPV_BINARY,
+                                     quit_callback=fired.set, **LIVE_OPTIONS)
+        self.addCleanup(lambda: None)
+        try:
+            mpv.command("quit")
+        except Exception:
+            pass  # the socket may die before the reply arrives
+        self.assertTrue(fired.wait(10), "quit_callback never fired")
+
+
+@requires_mpv
+class SuccessfulStartTest(unittest.TestCase):
+    def test_a_good_start_spawns_exactly_one_process(self):
+        with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen",
+                               wraps=subprocess.Popen) as popen:
+            mpv = python_mpv_jsonipc.MPV(mpv_location=MPV_BINARY,
+                                         **LIVE_OPTIONS)
+            self.addCleanup(mpv.terminate)
+            self.assertEqual(popen.call_count, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

python_mpv_jsonipc-1.3.0/tests/test_python_floor.py

@@ -0,0 +1,104 @@
+"""The module must stay parseable by the Python it claims to support.
+
+`pyproject.toml` says `requires-python = ">=3.6"`, and pip believes it: a
+stray f-string with `=`, a walrus, or `match` would install cleanly on an old
+interpreter and then fail at import, on a machine no CI here can reach.
+
+Raising the floor is itself a downstream break -- pip refuses to install on
+anything below it -- so the floor is treated as fixed and the syntax is what
+gets checked. The test reads the version from `pyproject.toml` rather than
+hard-coding it, so lowering or raising the claim moves the check with it.
+
+Only the shipped module is checked. The tests themselves are free to use
+whatever the CI interpreters provide.
+"""
+
+import ast
+import os
+import re
+import unittest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+MODULE = os.path.join(ROOT, "python_mpv_jsonipc.py")
+PYPROJECT = os.path.join(ROOT, "pyproject.toml")
+
+
+def declared_floor():
+    with open(PYPROJECT) as handle:
+        match = re.search(r'requires-python\s*=\s*"[><=~^]*\s*(\d+)\.(\d+)',
+                          handle.read())
+    if not match:
+        raise AssertionError("no requires-python in pyproject.toml")
+    return int(match.group(1)), int(match.group(2))
+
+
+#: Syntax that does not exist before the stated version, for probing whether
+#: this interpreter enforces `feature_version` at all.
+PROBES = (
+    ((3, 8), "if (n := 1): pass"),
+    ((3, 10), "match 1:\n    case 1: pass\n"),
+)
+
+
+def enforcement_probe(floor):
+    """A snippet newer than *floor*, or None if we have nothing newer."""
+    for version, source in PROBES:
+        if version > floor:
+            return source
+    return None
+
+
+def enforces_feature_version(floor):
+    """Whether `ast.parse` on THIS interpreter rejects newer syntax.
+
+    Not a version comparison: CPython's enforcement has been tightened over
+    time, and 3.9 accepts a walrus at `feature_version=(3, 6)` where 3.13
+    rejects it. Asking the interpreter is the only reliable form of the
+    question -- discovered when this file's own meta-test failed on the 3.9
+    CI leg and nowhere else.
+    """
+    source = enforcement_probe(floor)
+    if source is None:
+        return False
+    try:
+        ast.parse(source, feature_version=floor)
+    except SyntaxError:
+        return True
+    return False
+
+
+class PythonFloorTest(unittest.TestCase):
+    def test_the_module_parses_as_the_oldest_supported_python(self):
+        floor = declared_floor()
+        if not enforces_feature_version(floor):
+            # Honest skip rather than a pass that proves nothing. The guard
+            # only has teeth on interpreters that enforce feature_version,
+            # and the CI matrix includes several that do.
+            self.skipTest(
+                "this interpreter does not enforce feature_version={0}; "
+                "the check is meaningless here".format(floor))
+        with open(MODULE) as handle:
+            source = handle.read()
+        try:
+            ast.parse(source, filename=MODULE, feature_version=floor)
+        except SyntaxError as error:
+            self.fail(
+                "python_mpv_jsonipc.py uses syntax newer than the declared "
+                "floor {0}.{1}: {2} (line {3}). Either rewrite it or change "
+                "requires-python -- but note that raising the floor stops "
+                "pip installing for everyone below it.".format(
+                    floor[0], floor[1], error.msg, error.lineno))
+
+    def test_at_least_the_mechanism_is_exercised_somewhere(self):
+        # The check above passes trivially if `feature_version` is ignored,
+        # which is the shape of a test that cannot fail. This asserts the
+        # rejection really happens wherever it is claimed to.
+        floor = declared_floor()
+        if not enforces_feature_version(floor):
+            self.skipTest("no enforcement on this interpreter")
+        with self.assertRaises(SyntaxError):
+            ast.parse(enforcement_probe(floor), feature_version=floor)
+
+
+if __name__ == "__main__":
+    unittest.main()

python_mpv_jsonipc-1.2.3/python_mpv_jsonipc.egg-info/SOURCES.txt

@@ -1,8 +0,0 @@
-LICENSE.md
-README.md
-pyproject.toml
-python_mpv_jsonipc.py
-python_mpv_jsonipc.egg-info/PKG-INFO
-python_mpv_jsonipc.egg-info/SOURCES.txt
-python_mpv_jsonipc.egg-info/dependency_links.txt
-python_mpv_jsonipc.egg-info/top_level.txt