python-mpv-jsonipc 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

{python_mpv_jsonipc-1.4.0.dist-info → python_mpv_jsonipc-1.5.0.dist-info}/METADATA

@@ -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.5.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+python_mpv_jsonipc.py,sha256=6xQ45aP3vLNxLy6OdyReB-MPnQvmOJ00CzzNQ13iGS4,61266
+python_mpv_jsonipc-1.5.0.dist-info/licenses/LICENSE.md,sha256=7GQBUOA3dNG1Jk-yaPOCncNnRVURCRMev23QpZ1ew-s,10495
+python_mpv_jsonipc-1.5.0.dist-info/METADATA,sha256=axbDuWhKzIPoR1rvoF-b-MXVJx78LqF2MzFK6CGbmP8,2489
+python_mpv_jsonipc-1.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_mpv_jsonipc-1.5.0.dist-info/top_level.txt,sha256=nGk4yjpVHKmIrL39XdGD2PhCeWF0oMjwey0nsNOd2TM,19
+python_mpv_jsonipc-1.5.0.dist-info/RECORD,,

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.dist-info/RECORD

@@ -1,6 +0,0 @@
-python_mpv_jsonipc.py,sha256=g5BxL4Bzljm4QnsXG5kOKGGfHuiKlpqQqKmd5atQ-nM,50502
-python_mpv_jsonipc-1.4.0.dist-info/licenses/LICENSE.md,sha256=7GQBUOA3dNG1Jk-yaPOCncNnRVURCRMev23QpZ1ew-s,10495
-python_mpv_jsonipc-1.4.0.dist-info/METADATA,sha256=-gKDmmYj96EQjMvcTwgj_1AnBouKSD9ENAr1r77sVXU,2277
-python_mpv_jsonipc-1.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_mpv_jsonipc-1.4.0.dist-info/top_level.txt,sha256=nGk4yjpVHKmIrL39XdGD2PhCeWF0oMjwey0nsNOd2TM,19
-python_mpv_jsonipc-1.4.0.dist-info/RECORD,,