python-mpv-jsonipc 1.4.0__tar.gz → 1.5.0__tar.gz

{python_mpv_jsonipc-1.4.0/python_mpv_jsonipc.egg-info → python_mpv_jsonipc-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mpv-jsonipc
-Version: 1.4.0
+Version: 1.5.0
 Summary: Python API to MPV using JSON IPC
 Author-email: Izzie Walton <izzie@iwalton.com>
 License-Expression: Apache-2.0
@@ -55,6 +55,10 @@ mpv.volume = 20
 # You can also send commands.
 mpv.command_name(arg1, arg2)
 
+# Or send one without waiting for it. Returns a concurrent.futures.Future.
+mpv.command_async("sub-add", "https://example.com/slow.srt",
+                  callback=lambda error, result: print(error or "loaded"))
+
 # Bind to key press events with a decorator
 @mpv.on_key_press("space")
 def space_handler():

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0}/README.md

@@ -41,6 +41,10 @@ mpv.volume = 20
 # You can also send commands.
 mpv.command_name(arg1, arg2)
 
+# Or send one without waiting for it. Returns a concurrent.futures.Future.
+mpv.command_async("sub-add", "https://example.com/slow.srt",
+                  callback=lambda error, result: print(error or "loaded"))
+
 # Bind to key press events with a decorator
 @mpv.on_key_press("space")
 def space_handler():

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0}/pyproject.toml

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

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0/python_mpv_jsonipc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mpv-jsonipc
-Version: 1.4.0
+Version: 1.5.0
 Summary: Python API to MPV using JSON IPC
 Author-email: Izzie Walton <izzie@iwalton.com>
 License-Expression: Apache-2.0
@@ -55,6 +55,10 @@ mpv.volume = 20
 # You can also send commands.
 mpv.command_name(arg1, arg2)
 
+# Or send one without waiting for it. Returns a concurrent.futures.Future.
+mpv.command_async("sub-add", "https://example.com/slow.srt",
+                  callback=lambda error, result: print(error or "loaded"))
+
 # Bind to key press events with a decorator
 @mpv.on_key_press("space")
 def space_handler():

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0}/python_mpv_jsonipc.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ 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_async.py
 tests/test_live_basic.py
 tests/test_live_events.py
 tests/test_live_failure.py

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0}/python_mpv_jsonipc.py

@@ -8,6 +8,7 @@ import subprocess
 import random
 import queue
 import logging
+from concurrent.futures import Future
 
 log = logging.getLogger('mpv-jsonipc')
 
@@ -420,8 +421,13 @@ class WindowsSocket(threading.Thread):
                 # finally below, only once its own read has returned.
                 nread = self._transfer(_kernel32.ReadFile, self._read_event,
                                        buf, len(buf))
-                if not nread:
+                if nread is None:   # the peer is gone, or stop()
                     break
+                if nread == 0:
+                    # A zero-length message, not the end: mpv's pipe is
+                    # message-mode and it answers an async command with an
+                    # empty write. Treating it as EOF closed the connection.
+                    continue
 
                 data += buf.raw[:nread]
                 if data[-1] != 10:
@@ -699,6 +705,27 @@ class MPVProcess:
             except FileNotFoundError:
                 pass # The other thread got there first, which is all we wanted.
 
+#: Stands in a sync command's result slot when the connection closed first.
+_CLOSED = object()
+
+def _call_user(what, func, *args):
+    """Call user code from a thread this library owns, logging anything it
+    raises -- SystemExit included: a caller's bug must not end the reader,
+    the close sweep or the drain. Not for EventHandler.run, which a
+    BaseException still ends (see there)."""
+    try:
+        func(*args)
+    except BaseException:
+        log.error("%s raised.", what, exc_info=1)
+
+def _reply_outcome(data):
+    """``(error, result)`` for one IPC reply."""
+    if data["error"] == "success":
+        return None, data.get("data")
+    if data["error"] == "property unavailable":
+        return None, None
+    return MPVError(data["error"]), None
+
 class MPVInter:
     """
     Low-level interface to MPV. Does NOT manage an mpv process. (Internal)
@@ -708,6 +735,7 @@ class MPVInter:
 
         *ipc_socket* is the path to the Unix/Linux socket or name of the Windows pipe.
         *callback(event_name, data)* is the function for recieving events.
+        It runs on the reader thread; an exception from it is logged.
         *quit_callback* is called when the socket connection to MPV dies.
         """
         Socket = UnixSocket
@@ -719,25 +747,64 @@ class MPVInter:
         if self.callback is None:
             self.callback = lambda event, data: None
 
-        self.socket = Socket(ipc_socket, self.event_callback, self.quit_callback)
-        self.socket.start()
         self.command_id = 1
         self.rid_lock = threading.Lock()
         self.socket_lock = threading.Lock()
         self.cid_result = {}
         self.cid_wait = {}
+        # Before the reader starts: it can deliver a reply, or die, at once.
+        self.cid_async = {}
+        self.async_lock = threading.Lock()
+        self.closed = False
+
+        self.socket = Socket(ipc_socket, self.event_callback, self._on_quit)
+        self.socket.start()
 
     def stop(self, join=True):
         """Terminate the underlying connection."""
         self.socket.stop(join)
+        # The reader's _on_quit usually gets here first. This one does not
+        # depend on it, so nothing is left pending once stop() returns.
+        self._fail_async()
+
+    def _on_quit(self):
+        self._fail_async()
+        if self.quit_callback:
+            self.quit_callback()
+
+    def _fail_async(self):
+        """Answer every pending command, async or not: nothing else ever will."""
+        with self.async_lock:
+            self.closed = True
+            pending, self.cid_async = self.cid_async, {}
+            for command_id, event in list(self.cid_wait.items()):
+                # setdefault: a reply that landed just before still wins.
+                self.cid_result.setdefault(command_id, _CLOSED)
+                event.set()
+        for on_reply in pending.values():
+            _call_user("command_async reply handler", on_reply,
+                       BrokenPipeError("MPV connection closed."), None)
 
     def event_callback(self, data):
         """Internal callback for recieving events from MPV."""
         if "request_id" in data:
-            self.cid_result[data["request_id"]] = data
-            self.cid_wait[data["request_id"]].set()
+            request_id = data["request_id"]
+            with self.async_lock:
+                on_reply = self.cid_async.pop(request_id, None)
+            if on_reply is not None:
+                _call_user("command_async reply handler", on_reply,
+                           *_reply_outcome(data))
+                return
+            # Not indexed: a reply nobody waits for (mpv answers id 0 to a
+            # request without one) would raise here, on the reader thread,
+            # and end the read loop as if the connection had died.
+            event = self.cid_wait.get(request_id)
+            if event is not None:
+                self.cid_result[request_id] = data
+                event.set()
         elif "event" in data:
-            self.callback(data["event"], data)
+            _call_user("MPVInter event callback", self.callback,
+                       data["event"], data)
 
     def command(self, command, *args):
         """
@@ -746,7 +813,8 @@ class MPVInter:
         *command* is the name of the MPV command
 
         All further arguments are forwarded to the MPV command.
-        Throws TimeoutError if timeout of 120 seconds is reached.
+        Throws TimeoutError if timeout of 120 seconds is reached, and
+        BrokenPipeError as soon as the connection closes before the reply.
         """
         self.rid_lock.acquire()
         command_id = self.command_id
@@ -754,7 +822,12 @@ class MPVInter:
         self.rid_lock.release()
 
         event = threading.Event()
-        self.cid_wait[command_id] = event
+        # Under the lock _fail_async takes, so a close either finds this
+        # waiter or is seen here first; neither way waits out TIMEOUT.
+        with self.async_lock:
+            if self.closed:
+                raise BrokenPipeError("MPV connection closed.")
+            self.cid_wait[command_id] = event
 
         command_list = [command]
         command_list.extend(args)
@@ -766,23 +839,59 @@ class MPVInter:
 
         has_event = event.wait(timeout=TIMEOUT)
         if has_event:
-            data = self.cid_result[command_id]
-            del self.cid_result[command_id]
+            data = self.cid_result.pop(command_id)
             del self.cid_wait[command_id]
-            if data["error"] != "success":
-                if data["error"] == "property unavailable":
-                    return None
-                raise MPVError(data["error"])
-            else:
-                return data.get("data")
+            if data is _CLOSED:
+                raise BrokenPipeError("MPV connection closed.")
+            error, result = _reply_outcome(data)
+            if error is not None:
+                raise error
+            return result
         else:
             raise TimeoutError("No response from MPV.")
 
+    def command_async(self, on_reply, command, *args):
+        """
+        Issue a command to MPV without waiting for it to finish.
+
+        *on_reply(error, result)* is called exactly once: with MPV's answer on
+        the transport's reader thread; with BrokenPipeError on the thread
+        that closes the connection, or on the calling thread if it is already
+        closed; or with the send's own error on the calling thread. An
+        exception from it is logged when the reader or the close calls it,
+        and raised to the caller otherwise. There is no timeout.
+        """
+        with self.rid_lock:
+            command_id = self.command_id
+            self.command_id += 1
+
+        with self.async_lock:
+            closed = self.closed
+            if not closed:
+                self.cid_async[command_id] = on_reply
+        if closed:
+            on_reply(BrokenPipeError("MPV connection closed."), None)
+            return
+
+        command_list = [command]
+        command_list.extend(args)
+        try:
+            with self.socket_lock:
+                self.socket.send({"command": command_list,
+                                  "request_id": command_id, "async": True})
+        except Exception as error:
+            with self.async_lock:
+                owned = self.cid_async.pop(command_id, None)
+            if owned is not None:   # else _fail_async has already answered
+                on_reply(error, None)
+
 class EventHandler(threading.Thread):
     """Event handling thread. (Internal)"""
     def __init__(self):
         """Create an instance of the thread."""
         self.queue = queue.Queue()
+        self.stopped = False
+        self.stop_lock = threading.Lock()
         threading.Thread.__init__(self)
         self.daemon = True
 
@@ -793,24 +902,62 @@ class EventHandler(threading.Thread):
         *func* is the function to call
 
         All further arguments are forwarded to *func*.
+
+        Returns False, without queueing it, once the thread has stopped --
+        by stop(), or because a task raised SystemExit or the like.
         """
-        self.queue.put((func, args))
+        with self.stop_lock:
+            if self.stopped:
+                return False
+            self.queue.put((func, args))
+            return True
 
     def stop(self, join=True):
         """Terminate the thread."""
-        self.queue.put("quit")
-        self.join(join)
+        with self.stop_lock:
+            self.stopped = True
+            self.queue.put("quit")
+        # A callback that calls terminate() is on this thread. The guard is
+        # the transports' (see UnixSocket.stop); `join` stays the timeout.
+        if self.ident is not None and self is not threading.current_thread():
+            self.join(join)
 
     def run(self):
         """Process socket events. Do not run this directly. Use *start*."""
+        try:
+            while True:
+                event = self.queue.get()
+                if event == "quit":
+                    break
+                try:
+                    event[0](*event[1])
+                except Exception:
+                    log.error("EventHandler caught exception from %s.", event, exc_info=1)
+        except BaseException as ex:
+            log.warning("A callback raised %r, ending the event thread: "
+                        "property observers, key bindings and events will no "
+                        "longer be delivered; command_async callbacks now run "
+                        "on whichever thread delivers their outcome.", ex)
+            # Not _call_user, deliberately: a callback's SystemExit ends this
+            # thread, as it has since 2020.
+            raise
+        finally:
+            self._drain()
+
+    def _drain(self):
+        """A callback's SystemExit (or similar) ends this thread, as it always
+        has. Refuse work from here on, so put_task says so, and run what was
+        already queued: a command_async future may be waiting in it."""
+        with self.stop_lock:
+            self.stopped = True
         while True:
-            event = self.queue.get()
-            if event == "quit":
-                break
             try:
-                event[0](*event[1])
-            except Exception:
-                log.error("EventHandler caught exception from {0}.".format(event), exc_info=1)
+                event = self.queue.get_nowait()
+            except queue.Empty:
+                return
+            if event == "quit":
+                continue
+            _call_user("EventHandler task", event[0], *event[1])
 
 class MPV:
     """
@@ -833,7 +980,8 @@ class MPV:
         *mpv_location* is the location of MPV for *start_mpv*. (Default: Use MPV in PATH)
         *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.
+        *quit_callback* is called on the reader thread when the socket connection to MPV dies.
+        An exception from it is logged, and MPV is still terminated.
         *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
@@ -958,7 +1106,7 @@ class MPV:
         Internal handler for quit events.
         """
         if self.quit_callback:
-            self.quit_callback()
+            _call_user("quit_callback", self.quit_callback)
         self.terminate(join=False)
 
     def bind_event(self, name, callback):
@@ -1068,6 +1216,11 @@ class MPV:
         Waits for the value of a property to change.
 
         *name* is the name of the property.
+
+        Never call it from inside a callback here: the change is delivered on
+        the event thread, which the wait would be blocking, so it never ends.
+        It also never returns once a callback has ended the event thread,
+        since the change is then never delivered.
         """
         event = threading.Event()
         first_event = True
@@ -1126,6 +1279,80 @@ class MPV:
         """
         return self.mpv_inter.command(command, *args)
 
+    def command_async(self, command, *args, callback=None):
+        """
+        Send a command to MPV without waiting for it to finish, for one that
+        can take a long time (``sub-add`` of a slow URL). Unlike *command*,
+        it holds neither the caller nor the connection: other commands are
+        answered while it runs, and it has no timeout.
+
+        Returns a ``concurrent.futures.Future``. With no *callback* it holds
+        MPV's result or the error, as *command* would have returned or raised.
+        *callback(error, result)* is called first, with *error* None on
+        success, and the future then holds what it returns or raises.
+
+        The callback runs on the event thread, like every other callback
+        here. If an earlier callback ended that thread by raising SystemExit
+        or the like, a warning is logged, and property observers, key
+        bindings and events are no longer delivered at all; command_async
+        callbacks still run, on whichever thread delivers their outcome
+        instead -- the connection's reader while MPV is connected, or the
+        thread that closes the connection -- and a SystemExit from one there
+        is logged, not raised. With the event thread gone, a call made once
+        the connection has closed (by *terminate* or by MPV exiting), or
+        whose send fails, runs its callback on the calling thread before
+        command_async returns, and a SystemExit from it is raised to that
+        caller. A logging handler that raises SystemExit is not caught
+        anywhere: as in the standard library, it ends the thread that logged,
+        and in the close that leaves the futures after it unresolved.
+
+        The future resolves when MPV answers or, if the connection closes
+        first, with BrokenPipeError -- meaning no answer will come, not that
+        the command did not run. Until then it is pending: a command MPV is
+        still running has no timeout.
+
+        Never block on the future from inside a callback here (a property
+        observer, a key binding, an event, another command_async callback).
+        Those run on the event thread, the thread that would resolve it, so
+        the wait never ends. python-mpv behaves the same.
+
+        Once the event thread is gone, a callback must not block at all. On
+        the reader, a sync *command* waits out TIMEOUT with nothing else read
+        meanwhile, and a wait on a future never ends -- nor does a
+        *terminate* called from another thread. python-mpv fails here too:
+        once a callback's SystemExit stops its event loop, no callback or
+        future is delivered at all.
+
+        The future cannot be cancelled: MPV's IPC protocol cannot abort a
+        command. Needs MPV 0.33 or later; an older MPV ignores the request to
+        run in the background and runs the command as *command* does, blocking
+        every other command on the connection until it finishes.
+        """
+        future = Future()
+        future.set_running_or_notify_cancel()
+
+        def finish(error, result):
+            try:
+                if callback is not None:
+                    future.set_result(callback(error, result))
+                elif error is not None:
+                    future.set_exception(error)
+                else:
+                    future.set_result(result)
+            except BaseException as ex:
+                future.set_exception(ex)
+                if not isinstance(ex, Exception):
+                    raise   # which thread it reaches, and what happens: see the docstring
+                log.error("command_async callback for {0} raised.".format(
+                    command), exc_info=1)
+
+        def on_reply(error, result):
+            if not self.event_handler.put_task(finish, error, result):
+                finish(error, result)
+
+        self.mpv_inter.command_async(on_reply, command, *args)
+        return future
+
     def __getattr__(self, name):
         if name in self.properties:
             return self.command("get_property", name.replace("_", "-"))

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0}/tests/test_arg_building.py

@@ -98,8 +98,10 @@ class ArgumentTranslationTest(unittest.TestCase):
 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")
+        import shutil, tempfile
+        directory = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, directory, True)
+        path = os.path.join(directory, "stale.sock")
         with open(path, "w") as handle:
             handle.write("")
         self.assertTrue(os.path.exists(path))

python_mpv_jsonipc-1.5.0/tests/test_live_async.py

@@ -0,0 +1,550 @@
+"""``command_async`` against a real mpv.
+
+The case it exists for is a command that takes a long time and must not hold
+the caller or the pipe while it does: jellyfin-mpv-shim's ``sub-add`` of a
+subtitle the server extracts before it answers, which held a synchronous
+``command()`` for the full 120s ``TIMEOUT`` and then raised. A local HTTP
+server that answers late stands in for that server.
+
+The pipe half is the one a fake could not show: whether mpv answers *other*
+requests while one is running is mpv's behaviour, and it only does so for a
+request that carries ``"async": true``.
+"""
+
+import http.server
+import json
+import logging
+import os
+import shutil
+import socket
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from unittest import mock
+
+from _harness import LiveMPVTest, python_mpv_jsonipc
+
+SRT = b"1\n00:00:00,000 --> 00:10:00,000\nhello\n"
+
+
+class _LateServer:
+    """``/<seconds>/ok.srt`` answers with a subtitle after that long;
+    ``/<seconds>/missing.srt`` with a 404."""
+
+    def __init__(self):
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def do_GET(handler):
+                _, delay, name = handler.path.split("/")
+                time.sleep(float(delay))
+                if name == "ok.srt":
+                    handler.send_response(200)
+                    handler.send_header("Content-Length", str(len(SRT)))
+                    handler.end_headers()
+                    handler.wfile.write(SRT)
+                else:
+                    handler.send_response(404)
+                    handler.send_header("Content-Length", "0")
+                    handler.end_headers()
+
+            def log_message(handler, *args):
+                pass
+
+        self.server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.server.daemon_threads = True
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+
+    def url(self, delay, name="ok.srt"):
+        return "http://127.0.0.1:{0}/{1}/{2}".format(
+            self.server.server_address[1], delay, name)
+
+    def close(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+
+def _wait(predicate, timeout=10):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(0.05)
+    return False
+
+
+class _AsyncTest(LiveMPVTest):
+    def setUp(self):
+        super().setUp()
+        self.http = _LateServer()
+        self.addCleanup(self.http.close)
+        self.mpv.play("av://lavfi:testsrc")
+        self.assertTrue(_wait(lambda: self.mpv.time_pos is not None),
+                        "mpv never started playing")
+
+    def external_subs(self):
+        return [t for t in self.mpv.track_list or []
+                if t.get("type") == "sub" and t.get("external")]
+
+
+class CommandAsyncTest(_AsyncTest):
+    def test_it_returns_before_the_command_finishes(self):
+        started = time.monotonic()
+        future = self.mpv.command_async("sub-add", self.http.url(2), "select")
+        self.assertLess(time.monotonic() - started, 0.5)
+        self.assertFalse(future.done())
+
+        self.assertIsNone(future.result(timeout=15))
+        self.assertGreaterEqual(time.monotonic() - started, 2)
+        subs = self.external_subs()
+        self.assertEqual(len(subs), 1, subs)
+        self.assertTrue(subs[0].get("selected"), subs)
+
+    def test_other_requests_are_answered_while_it_runs(self):
+        # The difference "async" makes on the wire: without it mpv's IPC
+        # handler executes the command inline and reads nothing else from
+        # this client until it finishes, so this read would wait out the
+        # server's delay.
+        future = self.mpv.command_async("sub-add", self.http.url(5))
+        started = time.monotonic()
+        self.assertIsNotNone(self.mpv.pause)
+        self.assertLess(time.monotonic() - started, 1)
+        self.assertFalse(future.done())
+        future.result(timeout=15)
+
+    def test_a_failure_arrives_as_the_future_exception(self):
+        future = self.mpv.command_async(
+            "sub-add", self.http.url(0, "missing.srt"))
+        self.assertIsInstance(future.exception(timeout=15),
+                              python_mpv_jsonipc.MPVError)
+
+    def test_an_unavailable_property_is_none_as_it_is_for_command(self):
+        # testsrc has no audio, so mpv answers "property unavailable", which
+        # command() turns into None rather than raising.
+        self.assertIsNone(self.mpv.command("get_property", "audio-params"))
+        future = self.mpv.command_async("get_property", "audio-params")
+        self.assertIsNone(future.result(timeout=5))
+
+    def test_the_callback_sees_the_outcome_and_supplies_the_result(self):
+        seen = []
+
+        def callback(error, result):
+            seen.append((error, result, threading.current_thread()))
+            return "from the callback"
+
+        ok = self.mpv.command_async("get_property", "pause", callback=callback)
+        self.assertEqual(ok.result(timeout=5), "from the callback")
+        bad = self.mpv.command_async(
+            "sub-add", self.http.url(0, "missing.srt"), callback=callback)
+        self.assertEqual(bad.result(timeout=15), "from the callback")
+
+        (error, result, thread), (error2, result2, _) = seen
+        self.assertIsNone(error)
+        self.assertIs(result, False)
+        self.assertIsInstance(error2, python_mpv_jsonipc.MPVError)
+        self.assertIsNone(result2)
+        # Never the transport's reader: user code there stalls every reply.
+        self.assertIs(thread, self.mpv.event_handler)
+
+    def test_a_callback_that_raises_becomes_the_future_exception(self):
+        def callback(error, result):
+            raise ValueError("boom")
+
+        with self.assertLogs("mpv-jsonipc", "ERROR"):
+            future = self.mpv.command_async("get_property", "pause",
+                                            callback=callback)
+            self.assertIsInstance(future.exception(timeout=5), ValueError)
+
+    def test_it_cannot_be_cancelled(self):
+        # The IPC protocol has no way to abort a running command.
+        future = self.mpv.command_async("sub-add", self.http.url(2))
+        self.assertFalse(future.cancel())
+        future.result(timeout=15)
+
+    def test_loading_another_file_aborts_a_pending_sub_add(self):
+        # mpv's behaviour, pinned because the shim relies on it: a subtitle
+        # still loading when the next item starts must not land on that item.
+        future = self.mpv.command_async("sub-add", self.http.url(5), "select")
+        time.sleep(0.5)
+        self.mpv.play("av://lavfi:testsrc")
+        self.assertIsInstance(future.exception(timeout=15),
+                              python_mpv_jsonipc.MPVError)
+        self.assertTrue(_wait(lambda: self.mpv.time_pos is not None))
+        self.assertEqual(self.external_subs(), [])
+
+
+class TeardownTest(_AsyncTest):
+    """A closed connection resolves every future, and a callback that
+    raises, SystemExit included, strands none. One left pending forever is a
+    caller blocked on ``result()`` forever, which is worse than the timeout
+    this replaces."""
+
+    def test_terminate_fails_what_is_pending(self):
+        future = self.mpv.command_async("sub-add", self.http.url(30))
+        self.mpv.terminate()
+        self.assertIsInstance(future.exception(timeout=5), BrokenPipeError)
+
+    def test_mpv_dying_fails_what_is_pending(self):
+        future = self.mpv.command_async("sub-add", self.http.url(30))
+        self.mpv.mpv_process.process.kill()
+        self.assertIsInstance(future.exception(timeout=5), BrokenPipeError)
+
+    def test_after_terminate_it_fails_instead_of_hanging(self):
+        self.mpv.terminate()
+        future = self.mpv.command_async("get_property", "pause")
+        self.assertIsInstance(future.exception(timeout=5), BrokenPipeError)
+
+    def test_the_callback_still_runs_after_terminate(self):
+        seen = []
+        self.mpv.terminate()
+        self.mpv.command_async("get_property", "pause",
+                               callback=lambda e, r: seen.append(e))
+        self.assertTrue(_wait(lambda: seen, 5))
+        self.assertIsInstance(seen[0], BrokenPipeError)
+
+    def test_a_callback_can_terminate(self):
+        # The callback runs on the event thread, and terminate() stops that
+        # thread: it must not try to join itself.
+        future = self.mpv.command_async(
+            "get_property", "pause",
+            callback=lambda e, r: self.mpv.terminate())
+        self.assertIsNone(future.exception(timeout=10))
+        self.assertTrue(_wait(lambda: self.mpv.mpv_process.process.poll()
+                              is not None, 10), "mpv is still running")
+
+    def test_a_callback_that_exits_strands_nothing(self):
+        # A BaseException from a callback ends the event thread, as it always
+        # has; what was waiting behind it must still resolve, and so must
+        # what comes after.
+        def leave(error, result):
+            sys.exit(3)
+
+        first = self.mpv.command_async("get_property", "pause", callback=leave)
+        second = self.mpv.command_async("get_property", "pause")
+        self.assertIsInstance(first.exception(timeout=5), SystemExit)
+        self.assertIs(second.result(timeout=5), False)
+        self.assertTrue(_wait(lambda: not self.mpv.event_handler.is_alive(), 5))
+        self.assertIs(self.mpv.command_async("get_property", "pause")
+                      .result(timeout=5), False)
+
+    def test_a_callback_that_exits_on_the_reader_ends_nothing(self):
+        # Once a callback has ended the event thread, later callbacks run on
+        # the reader. One that exits there must not end the read loop too:
+        # replies still arrive, and mpv dying is still noticed.
+        def leave(error, result):
+            ran_on.append(threading.current_thread())
+            sys.exit(3)
+
+        ran_on = []
+        with self.assertLogs("mpv-jsonipc", "WARNING") as logs:
+            self.mpv.command_async("get_property", "pause",
+                                   callback=leave).exception(timeout=5)
+            self.assertTrue(
+                _wait(lambda: not self.mpv.event_handler.is_alive(), 5))
+            self.assertIsInstance(self.mpv.command_async(
+                "get_property", "pause", callback=leave).exception(timeout=5),
+                SystemExit)
+            # Logged after the future resolves, on the reader.
+            self.assertTrue(_wait(lambda: any(
+                r.levelname == "ERROR" for r in logs.records), 5))
+        self.assertIs(ran_on[1], self.mpv.mpv_inter.socket)
+        self.assertIn("WARNING", [r.levelname for r in logs.records])
+        with mock.patch.object(python_mpv_jsonipc, "TIMEOUT", 3):
+            self.assertIs(self.mpv.command("get_property", "pause"), False)
+        pending = self.mpv.command_async("sub-add", self.http.url(30))
+        self.mpv.mpv_process.process.kill()
+        self.assertIsInstance(pending.exception(timeout=5), BrokenPipeError)
+
+    def test_mpv_dying_fails_a_waiting_command_at_once(self):
+        # command() used to wait out TIMEOUT (120 s) for a reply that could
+        # no longer come, holding whatever lock its caller held.
+        outcome = []
+
+        def wait():
+            try:
+                self.mpv.command("sub-add", self.http.url(30))
+            except BaseException as error:
+                outcome.append(error)
+
+        waiter = threading.Thread(target=wait, daemon=True)
+        waiter.start()
+        time.sleep(0.5)
+        self.mpv.mpv_process.process.kill()
+        waiter.join(10)
+        self.assertFalse(waiter.is_alive(), "command() is still waiting")
+        self.assertIsInstance(outcome[0], BrokenPipeError)
+
+
+class ReplyRoutingTest(unittest.TestCase):
+    """The reader thread's side, without a pipe. An exception here escapes
+    the transport's read loop, which reports it as the connection dying."""
+
+    def setUp(self):
+        transport = mock.MagicMock()
+        patch = mock.patch.object(python_mpv_jsonipc, "UnixSocket", transport)
+        patch.start()
+        self.addCleanup(patch.stop)
+        mock.patch.object(python_mpv_jsonipc, "WindowsSocket",
+                          transport).start()
+        self.addCleanup(mock.patch.stopall)
+        self.inter = python_mpv_jsonipc.MPVInter("unused")
+        self.quits = []
+        self.inter.quit_callback = lambda: self.quits.append(True)
+
+    def player_whose_event_thread_is_gone(self):
+        """An MPV over the stub, in the state a callback's SystemExit leaves
+        it: put_task refuses, so callbacks run on whichever thread delivers
+        the reply."""
+        player = python_mpv_jsonipc.MPV.__new__(python_mpv_jsonipc.MPV)
+        handler = python_mpv_jsonipc.EventHandler()
+        handler.stop(join=False)
+        for name, value in [("properties", set()), ("mpv_process", None),
+                            ("mpv_inter", self.inter),
+                            ("event_handler", handler)]:
+            object.__setattr__(player, name, value)
+        return player
+
+    def request_id(self, n):
+        return self.inter.socket.send.call_args_list[n][0][0]["request_id"]
+
+    def test_a_reply_nobody_is_waiting_for_is_dropped(self):
+        # mpv answers a request that carried no request_id with id 0.
+        self.inter.event_callback({"request_id": 0, "error": "success"})
+        self.inter.event_callback({"request_id": 12345, "error": "success"})
+
+    def test_an_async_reply_is_delivered_once(self):
+        seen = []
+        self.inter.command_async(lambda e, r: seen.append((e, r)),
+                                 "get_property", "pause")
+        sent = self.inter.socket.send.call_args[0][0]
+        self.assertIs(sent["async"], True)
+        reply = {"request_id": sent["request_id"], "error": "success",
+                 "data": True}
+        self.inter.event_callback(reply)
+        self.inter.event_callback(reply)
+        self.inter.stop()
+        self.assertEqual(seen, [(None, True)])
+
+    def test_a_raising_on_reply_loses_nothing_else_on_close(self):
+        seen, quits = [], []
+        self.inter.quit_callback = lambda: quits.append(True)
+
+        def bad(error, result):
+            raise ValueError("a caller's bug")
+
+        self.inter.command_async(bad, "get_property", "pause")
+        self.inter.command_async(lambda e, r: seen.append(e),
+                                 "get_property", "pause")
+        with self.assertLogs("mpv-jsonipc", "ERROR"):
+            self.inter._on_quit()
+        self.assertEqual(len(seen), 1)
+        self.assertIsInstance(seen[0], BrokenPipeError)
+        self.assertEqual(quits, [True])
+
+    def test_a_raising_on_reply_does_not_end_the_read_loop(self):
+        def bad(error, result):
+            raise ValueError("a caller's bug")
+
+        self.inter.command_async(bad, "get_property", "pause")
+        sent = self.inter.socket.send.call_args[0][0]
+        with self.assertLogs("mpv-jsonipc", "ERROR"):
+            self.inter.event_callback({"request_id": sent["request_id"],
+                                       "error": "success", "data": True})
+
+    def test_an_exiting_callback_on_the_reader_is_logged(self):
+        player = self.player_whose_event_thread_is_gone()
+        first = player.command_async("get_property", "pause",
+                                     callback=lambda e, r: sys.exit(3))
+        second = player.command_async("get_property", "pause")
+        try:
+            with self.assertLogs("mpv-jsonipc", "ERROR"):
+                self.inter.event_callback({"request_id": self.request_id(0),
+                                           "error": "success", "data": False})
+        except SystemExit:
+            self.fail("SystemExit escaped event_callback, ending the reader")
+        self.assertIsInstance(first.exception(0), SystemExit)
+        self.inter._on_quit()
+        self.assertIsInstance(second.exception(0), BrokenPipeError)
+        self.assertEqual(self.quits, [True])
+
+    def test_an_exiting_callback_does_not_cut_the_close_short(self):
+        player = self.player_whose_event_thread_is_gone()
+        first = player.command_async("get_property", "pause",
+                                     callback=lambda e, r: sys.exit(3))
+        rest = [player.command_async("get_property", "pause")
+                for _ in range(2)]
+        try:
+            with self.assertLogs("mpv-jsonipc", "ERROR"):
+                self.inter._on_quit()
+        except SystemExit:
+            self.fail("SystemExit escaped the close sweep")
+        self.assertIsInstance(first.exception(0), SystemExit)
+        for future in rest:
+            self.assertIsInstance(future.exception(0), BrokenPipeError)
+        self.assertEqual(self.quits, [True])
+
+    def test_terminate_logs_an_exiting_callback_instead_of_raising_it(self):
+        # The callback runs on terminate()'s caller here, but it is the
+        # library's close doing the calling: the rest must still resolve.
+        player = self.player_whose_event_thread_is_gone()
+        first = player.command_async("get_property", "pause",
+                                     callback=lambda e, r: sys.exit(3))
+        second = player.command_async("get_property", "pause")
+        try:
+            with self.assertLogs("mpv-jsonipc", "ERROR"):
+                player.terminate()
+        except SystemExit:
+            self.fail("SystemExit raised out of terminate()")
+        self.assertIsInstance(first.exception(0), SystemExit)
+        self.assertIsInstance(second.exception(0), BrokenPipeError)
+
+    def test_a_raising_event_callback_is_logged(self):
+        def bad(event, data):
+            raise ValueError("a caller's bug")
+
+        self.inter.callback = bad
+        try:
+            with self.assertLogs("mpv-jsonipc", "ERROR"):
+                self.inter.event_callback({"event": "pause"})
+        except ValueError:
+            self.fail("the event callback's exception escaped event_callback")
+
+    def test_a_command_after_the_reader_died_fails_at_once(self):
+        # The reader's quit sweeps before anything stops the socket, so a
+        # send can still "succeed" into a dead connection in between.
+        self.inter._on_quit()
+        with mock.patch.object(python_mpv_jsonipc, "TIMEOUT", 2):
+            with self.assertRaises(BrokenPipeError):
+                self.inter.command("get_property", "pause")
+
+    def test_a_send_that_fails_is_reported_to_the_callback(self):
+        seen = []
+        self.inter.socket.send.side_effect = BrokenPipeError("gone")
+        self.inter.command_async(lambda e, r: seen.append(e), "stop")
+        self.assertEqual(len(seen), 1)
+        self.assertIsInstance(seen[0], BrokenPipeError)
+
+
+
+@unittest.skipIf(os.name == "nt", "the reader there is a named pipe")
+class RealReaderTest(unittest.TestCase):
+    """The stub above cannot show whether the read loop goes on afterwards;
+    a real UnixSocket reader against a fake mpv can."""
+
+    def test_an_exiting_event_callback_does_not_end_the_read_loop(self):
+        directory = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, directory, True)
+        path = os.path.join(directory, "mpv.sock")
+        server = socket.socket(socket.AF_UNIX)
+        server.bind(path)
+        server.listen(1)
+        self.addCleanup(server.close)
+        accepted = []
+        threading.Thread(target=lambda: accepted.append(server.accept()[0]),
+                         daemon=True).start()
+
+        def leave(event, data):
+            raise SystemExit(3)
+
+        inter = python_mpv_jsonipc.MPVInter(path, callback=leave)
+        self.addCleanup(inter.stop)
+        self.assertTrue(_wait(lambda: accepted, 5))
+        peer = accepted[0]
+        self.addCleanup(peer.close)
+        seen = []
+        inter.command_async(lambda e, r: seen.append(r),
+                            "get_property", "pause")
+        request = json.loads(peer.recv(4096).split(b"\n")[0])
+        with self.assertLogs("mpv-jsonipc", "ERROR"):
+            peer.sendall(b'{"event": "pause"}\n')
+            peer.sendall(json.dumps({"request_id": request["request_id"],
+                                     "error": "success", "data": 7})
+                         .encode() + b"\n")
+            self.assertTrue(_wait(lambda: seen, 3),
+                            "the reply after the event was never read")
+        self.assertEqual(seen, [7])
+        self.assertTrue(inter.socket.is_alive())
+
+
+class _BadRepr:
+    """A task's object whose repr raises: logging it must not cost the
+    tasks queued after it."""
+
+    def __repr__(self):
+        raise ValueError("bad repr")
+
+    def method(self):
+        pass
+
+    def raises(self):
+        raise RuntimeError("a caller's bug")
+
+
+class EventThreadTest(unittest.TestCase):
+    def records(self):
+        seen = []
+        handler = logging.Handler()
+        handler.emit = seen.append
+        logger = logging.getLogger("mpv-jsonipc")
+        logger.addHandler(handler)
+        self.addCleanup(logger.removeHandler, handler)
+        return seen
+
+    def test_a_callback_ending_the_thread_warns_once(self):
+        seen = self.records()
+        handler = python_mpv_jsonipc.EventHandler()
+        handler.start()
+        handler.put_task(sys.exit, 3)
+        handler.join(5)
+        self.assertFalse(handler.is_alive())
+        warnings = [r for r in seen if r.levelno == logging.WARNING]
+        self.assertEqual(len(warnings), 1, [r.getMessage() for r in seen])
+
+    def test_an_ordinary_stop_does_not_warn(self):
+        seen = self.records()
+        handler = python_mpv_jsonipc.EventHandler()
+        handler.start()
+        handler.stop(5)
+        self.assertEqual([r for r in seen if r.levelno >= logging.WARNING], [])
+
+    def test_a_task_whose_repr_raises_strands_nothing_behind_it(self):
+        seen = []
+        handler = python_mpv_jsonipc.EventHandler()
+        handler.put_task(sys.exit, 3)
+        handler.put_task(_BadRepr().method)
+        handler.put_task(seen.append, "after")
+        self.records()
+        handler.start()
+        handler.join(5)
+        self.assertEqual(seen, ["after"])
+
+    def test_a_raising_task_whose_repr_raises_does_not_end_the_thread(self):
+        seen = self.records()
+        handler = python_mpv_jsonipc.EventHandler()
+        handler.start()
+        self.addCleanup(handler.stop, 5)
+        handler.put_task(_BadRepr().raises)
+        self.assertTrue(_wait(lambda: seen, 5))
+        time.sleep(0.1)
+        self.assertTrue(handler.is_alive(), "the event thread ended")
+        self.assertEqual([r.levelno for r in seen], [logging.ERROR])
+
+    def test_what_was_queued_behind_an_exit_still_runs(self):
+        # The first exit ends run(); the rest goes to _drain, which must
+        # survive the second and still pass the third its arguments.
+        seen = []
+        handler = python_mpv_jsonipc.EventHandler()
+        handler.put_task(sys.exit, 3)
+        handler.put_task(sys.exit, 4)
+        handler.put_task(seen.append, "after")
+        with self.assertLogs("mpv-jsonipc", "ERROR") as logs:
+            handler.start()
+            handler.join(5)
+        self.assertFalse(handler.is_alive())
+        self.assertEqual(seen, ["after"])
+        self.assertTrue(any(r.exc_info and r.exc_info[0] is SystemExit
+                            for r in logs.records))
+
+
+if __name__ == "__main__":
+    unittest.main()

{python_mpv_jsonipc-1.4.0 → python_mpv_jsonipc-1.5.0}/tests/test_live_teardown.py

@@ -30,6 +30,7 @@ that the cheap tests here cover postconditions, not interleavings.
 """
 
 import os
+import shutil
 import tempfile
 import threading
 import time
@@ -141,6 +142,8 @@ class TerminateWaitsTest(unittest.TestCase):
             spawned.append(process)
             return process
 
+        directory = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, directory, True)
         with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen", record), \
                 mock.patch.object(python_mpv_jsonipc, "_ipc_endpoint_ready",
                                   return_value=False), \
@@ -148,7 +151,7 @@ class TerminateWaitsTest(unittest.TestCase):
                                   _skip_only_the_readiness_poll()):
             with self.assertRaises(python_mpv_jsonipc.MPVProcessError):
                 python_mpv_jsonipc.MPVProcess(
-                    os.path.join(tempfile.mkdtemp(), "failed-start.sock"),
+                    os.path.join(directory, "failed-start.sock"),
                     MPV_BINARY, **LIVE_OPTIONS)
 
         self.assertEqual(len(spawned), 1)
@@ -178,6 +181,25 @@ class TerminateWaitsTest(unittest.TestCase):
 
         self.assertEqual(escaped, [])
 
+    def test_a_raising_quit_callback_still_terminates(self):
+        # A raise there used to skip the terminate(join=False) after it,
+        # leaving the event thread running with MPV gone.
+        mpv = start_mpv()
+        self.addCleanup(mpv.terminate)
+
+        def bad():
+            raise ValueError("a caller's bug")
+
+        mpv.quit_callback = bad
+        with self.assertLogs("mpv-jsonipc", "ERROR"):
+            mpv.mpv_process.process.kill()
+            deadline = time.time() + 5
+            while mpv.event_handler.is_alive() and time.time() < deadline:
+                time.sleep(0.02)
+            self.assertFalse(
+                mpv.event_handler.is_alive(),
+                "terminate never ran: the event thread is still alive")
+
     def test_the_process_is_reaped_not_merely_signalled(self):
         mpv = start_mpv()
         process = mpv.mpv_process.process
@@ -213,7 +235,9 @@ class StopWaitingTest(unittest.TestCase):
         process = python_mpv_jsonipc.MPVProcess.__new__(
             python_mpv_jsonipc.MPVProcess)
         process.process = self._Stubborn()
-        process.ipc_socket = os.path.join(tempfile.mkdtemp(), socket_name)
+        directory = tempfile.mkdtemp()
+        self.addCleanup(shutil.rmtree, directory, True)
+        process.ipc_socket = os.path.join(directory, socket_name)
         return process
 
     def test_a_timeout_waits_then_escalates_to_kill(self):