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

{python_mpv_jsonipc-1.3.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.3.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,12 +8,105 @@ import subprocess
 import random
 import queue
 import logging
+from concurrent.futures import Future
 
 log = logging.getLogger('mpv-jsonipc')
 
 if os.name == "nt":
-    import _winapi
-    from multiprocessing.connection import PipeConnection
+    import ctypes
+    import ctypes.wintypes as _w
+
+    # The Windows transport calls kernel32 directly rather than going through
+    # ``_winapi`` and ``multiprocessing.connection.PipeConnection``. The second
+    # of those is a live bug, not tidiness:
+    #
+    #   PipeConnection says outright that "a connection should only be used by
+    #   a single thread", and this library used it from two -- a reader parked
+    #   in recv_bytes, and whoever called stop(). Its _close() cancels a
+    #   pending *send* before closing the handle, but has no equivalent for a
+    #   pending *read*, because _recv_bytes never stores its OVERLAPPED
+    #   anywhere reachable. So stop() closed the handle with an overlapped
+    #   read outstanding and a kernel-owned buffer still live, which is
+    #   undefined: the kernel may complete the I/O into memory Python is
+    #   tearing down. CPython 3.13+ allocates its thread primitives from the
+    #   parking lot, so that corruption now lands as an abort --
+    #   ``Fatal Python error: _PySemaphore_Wakeup: ReleaseSemaphore failed
+    #   (error: 6)`` -- seen in CI on both 3.13 and 3.14.
+    #
+    # Neither ``_winapi`` (private C extension) nor ``PipeConnection`` (absent
+    # from __all__, defined conditionally, an implementation detail of Pipe())
+    # carries a compatibility contract, so this also removes a dependency that
+    # breaks along the *Python* axis rather than ours. ctypes is stdlib and
+    # needs no PyInstaller hooks or bundled DLLs, which is the property the
+    # original _winapi choice was buying and that downstream projects such as
+    # SyncPlay and jellyfin-mpv-shim adopted this library for.
+    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+
+    _GENERIC_READ = 0x80000000
+    _GENERIC_WRITE = 0x40000000
+    _OPEN_EXISTING = 3
+    _FILE_FLAG_OVERLAPPED = 0x40000000
+    _INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
+    _INFINITE = 0xFFFFFFFF
+    _WAIT_OBJECT_0 = 0
+    _ERROR_FILE_NOT_FOUND = 2
+    _ERROR_PATH_NOT_FOUND = 3
+    _ERROR_BROKEN_PIPE = 109
+    # Also "the other end is gone", and reached when the peer disconnects
+    # rather than exits. Without them a normal disconnect logs an ERROR and a
+    # traceback. Measured on real Windows, including against the old
+    # PipeConnection build, which logged it too -- it only raised EOFError for
+    # 109 -- so this is an improvement on the previous behaviour rather than a
+    # regression being repaired. Real MPV exiting gives 109, which is why no
+    # CI leg ever showed it.
+    _ERROR_NO_DATA = 232
+    _ERROR_PIPE_NOT_CONNECTED = 233
+    _ERROR_MORE_DATA = 234
+    _ERROR_OPERATION_ABORTED = 995
+    _ERROR_IO_PENDING = 997
+
+    #: Every way the far end can be gone. All of them are a clean end of
+    #: stream, not an error to log.
+    _PEER_GONE = (_ERROR_BROKEN_PIPE, _ERROR_NO_DATA, _ERROR_PIPE_NOT_CONNECTED)
+
+    class _OVERLAPPED(ctypes.Structure):
+        _fields_ = [("Internal", ctypes.c_void_p),
+                    ("InternalHigh", ctypes.c_void_p),
+                    ("Offset", _w.DWORD),
+                    ("OffsetHigh", _w.DWORD),
+                    ("hEvent", _w.HANDLE)]
+
+    # Declared explicitly: without argtypes ctypes truncates pointers to int
+    # on 64-bit, which fails in ways that look like random handle errors.
+    _kernel32.CreateFileW.argtypes = [_w.LPCWSTR, _w.DWORD, _w.DWORD,
+                                      ctypes.c_void_p, _w.DWORD, _w.DWORD,
+                                      _w.HANDLE]
+    _kernel32.CreateFileW.restype = _w.HANDLE
+    _kernel32.CreateEventW.argtypes = [ctypes.c_void_p, _w.BOOL, _w.BOOL,
+                                       _w.LPCWSTR]
+    _kernel32.CreateEventW.restype = _w.HANDLE
+    _kernel32.SetEvent.argtypes = [_w.HANDLE]
+    _kernel32.SetEvent.restype = _w.BOOL
+    _kernel32.ResetEvent.argtypes = [_w.HANDLE]
+    _kernel32.ResetEvent.restype = _w.BOOL
+    _kernel32.ReadFile.argtypes = [_w.HANDLE, ctypes.c_void_p, _w.DWORD,
+                                   _w.LPDWORD, ctypes.c_void_p]
+    _kernel32.ReadFile.restype = _w.BOOL
+    _kernel32.WriteFile.argtypes = [_w.HANDLE, ctypes.c_void_p, _w.DWORD,
+                                    _w.LPDWORD, ctypes.c_void_p]
+    _kernel32.WriteFile.restype = _w.BOOL
+    _kernel32.GetOverlappedResult.argtypes = [_w.HANDLE, ctypes.c_void_p,
+                                              _w.LPDWORD, _w.BOOL]
+    _kernel32.GetOverlappedResult.restype = _w.BOOL
+    _kernel32.CancelIoEx.argtypes = [_w.HANDLE, ctypes.c_void_p]
+    _kernel32.CancelIoEx.restype = _w.BOOL
+    _kernel32.WaitForMultipleObjects.argtypes = [_w.DWORD, ctypes.c_void_p,
+                                                 _w.BOOL, _w.DWORD]
+    _kernel32.WaitForMultipleObjects.restype = _w.DWORD
+    _kernel32.CloseHandle.argtypes = [_w.HANDLE]
+    _kernel32.CloseHandle.restype = _w.BOOL
+    _kernel32.WaitNamedPipeW.argtypes = [_w.LPCWSTR, _w.DWORD]
+    _kernel32.WaitNamedPipeW.restype = _w.BOOL
 
 TIMEOUT = 120
 
@@ -123,62 +216,220 @@ class WindowsSocket(threading.Thread):
         *callback(json_data)* is the function for recieving events.
         *quit_callback* is called when the socket connection dies.
         """
+        # First, so Thread's own attributes are in place before ours rather
+        # than landing on top of them. Thread grew a `self._handle` of its own
+        # in 3.13, so the pipe handle is `_pipe`: named `_handle` and assigned
+        # before this call, Thread silently replaced it with a
+        # _thread._ThreadHandle and every read died in ctypes argument
+        # conversion. Anything added below needs a name Thread does not use.
+        threading.Thread.__init__(self)
+        self.daemon = True
+
         ipc_socket = "\\\\.\\pipe\\" + ipc_socket
         self.callback = callback
         self.quit_callback = quit_callback
         self._stopping = False
-
-        access = _winapi.GENERIC_READ | _winapi.GENERIC_WRITE
+        self._closed = False
+        # Every send is held under this lock, so holding it is proof that no
+        # write is in flight and the pipe is safe to close. The reader is the
+        # exception and must stay one -- see run().
+        self._io_lock = threading.RLock()
+        # Guards the handle *values* against being used after _close cleared
+        # them. Held only for the moment it takes to signal or close, never
+        # across a wait.
+        self._handle_lock = threading.RLock()
+
+        access = _GENERIC_READ | _GENERIC_WRITE
         limit = 5 # Connection may fail at first. Try 5 times.
         for _ in range(limit):
-            try:
-                pipe_handle = _winapi.CreateFile(
-                    ipc_socket, access, 0, _winapi.NULL, _winapi.OPEN_EXISTING,
-                    _winapi.FILE_FLAG_OVERLAPPED, _winapi.NULL
-                    )
+            # Still five attempts, and still load-bearing: _ipc_endpoint_ready
+            # does not run on the start_mpv=False attach path, and it answers
+            # True for a pipe whose instances are all busy, which CreateFile
+            # then refuses with ERROR_PIPE_BUSY.
+            handle = _kernel32.CreateFileW(
+                ipc_socket, access, 0, None, _OPEN_EXISTING,
+                _FILE_FLAG_OVERLAPPED, None)
+            if handle != _INVALID_HANDLE_VALUE:
                 break
-            except OSError:
-                time.sleep(1)
+            time.sleep(1)
         else:
+            # Deliberately not an OSError: downstream and the failure tests
+            # both pin that this is what the Windows attach path raises.
             raise MPVError("Cannot connect to pipe.")
-        self.socket = PipeConnection(pipe_handle)
+        self._pipe = handle
+
+        # Manual-reset, so a stop stays visible to the reader and to any send
+        # waiting alongside it rather than waking exactly one of them.
+        self._stop_event = _kernel32.CreateEventW(None, True, False, None)
+        self._read_event = _kernel32.CreateEventW(None, True, False, None)
+        self._write_event = _kernel32.CreateEventW(None, True, False, None)
+        if not all((self._stop_event, self._read_event, self._write_event)):
+            self._close()
+            raise MPVError("Cannot create pipe events.")
 
         if self.callback is None:
             self.callback = lambda data: None
 
-        threading.Thread.__init__(self)
-        self.daemon = True
+    def _transfer(self, func, event, buf, size):
+        """Run one overlapped operation, waiting for it or for *stop*.
+
+        Returns the bytes transferred, or None if the pipe ended or *stop* cut
+        the operation short.
+
+        The GetOverlappedResult(wait=True) below is the point of this whole
+        class. It does not return until the kernel has finished with *buf* and
+        the OVERLAPPED -- including when we cancelled it -- so neither is ever
+        released while an I/O could still write into it.
+        """
+        ov = _OVERLAPPED()
+        ov.hEvent = event
+        _kernel32.ResetEvent(event)
+        moved = _w.DWORD(0)
+
+        # The guarded region starts *before* the call, and assumes the
+        # operation may be outstanding until proven otherwise. An
+        # asynchronous exception -- a KeyboardInterrupt, which lands on the
+        # main thread, which is where send() runs -- can arrive between the
+        # call returning ERROR_IO_PENDING and any flag recording that, so a
+        # flag set after the call is wrong in exactly the direction that
+        # matters: it would let the frame, and its buffer, go while the kernel
+        # still owns them. Assuming the worst costs nothing when nothing was
+        # started, because a fresh OVERLAPPED has Internal = STATUS_SUCCESS
+        # and GetOverlappedResult then returns immediately (measured).
+        outstanding = True
+        try:
+            if func(self._pipe, buf, size, ctypes.byref(moved),
+                    ctypes.byref(ov)):
+                outstanding = False
+                return moved.value
+
+            err = ctypes.get_last_error()
+            if err != _ERROR_IO_PENDING:
+                outstanding = False
+                if err in _PEER_GONE:
+                    return None
+                if err == _ERROR_MORE_DATA:
+                    # A completed read that filled the buffer, not a failure.
+                    # The completion path below already treats it that way;
+                    # raising here would have desynchronised the two.
+                    return moved.value
+                raise ctypes.WinError(err)
+
+            handles = (_w.HANDLE * 2)(event, self._stop_event)
+            waitres = _kernel32.WaitForMultipleObjects(2, handles, False,
+                                                       _INFINITE)
+            if waitres != _WAIT_OBJECT_0:
+                # stop() wants us gone, or the wait itself failed. Either way
+                # we will not be consuming this operation. Read the wait's
+                # error *first*: CancelIoEx overwrites the thread's last error,
+                # so reading it afterwards reports the cancel's success and
+                # loses the real cause on the path hardest to reproduce.
+                waitfail = ctypes.get_last_error()
+                _kernel32.CancelIoEx(self._pipe, ctypes.byref(ov))
+                if waitres != _WAIT_OBJECT_0 + 1:
+                    raise ctypes.WinError(waitfail)
+        except BaseException:
+            if outstanding:
+                _kernel32.CancelIoEx(self._pipe, ctypes.byref(ov))
+            raise
+        finally:
+            # Cancelling only *asks*. This is the wait that makes it true.
+            if outstanding:
+                completed = _kernel32.GetOverlappedResult(
+                    self._pipe, ctypes.byref(ov), ctypes.byref(moved), True)
+                failure = 0 if completed else ctypes.get_last_error()
+
+        if not completed:
+            if failure in _PEER_GONE or failure == _ERROR_OPERATION_ABORTED:
+                return None
+            if failure != _ERROR_MORE_DATA:
+                raise ctypes.WinError(failure)
+        return moved.value
+
+    def _close(self):
+        """Close the handles, once, with no I/O outstanding."""
+        # _io_lock first: holding it means no send is mid-write. _handle_lock
+        # second, to exclude a concurrent stop() signalling an event we are
+        # about to close. Nothing ever takes these in the other order, and
+        # _handle_lock is never held across a wait, so stop() cannot block.
+        with self._io_lock, self._handle_lock:
+            if self._closed:
+                return
+            self._closed = True
+            for name in ("_pipe", "_stop_event", "_read_event",
+                         "_write_event"):
+                handle = getattr(self, name, None)
+                if handle:
+                    _kernel32.CloseHandle(handle)
+                # Cleared, not just closed: terminate() is routinely called
+                # twice, and a closed handle value can be reused by the OS.
+                setattr(self, name, None)
 
     def stop(self, join=True):
         """Terminate the thread."""
         self._stopping = True
-        if self.socket is not None:
-            try:
-                self.socket.close()
-            except OSError:
-                pass # Ignore socket close failure.
-        if join:
+        # Deliberately does NOT close the handle. Closing it from here with
+        # the reader's overlapped read still pending is the corruption this
+        # class was rewritten to remove; instead we wake the reader and let it
+        # close the handle it owns, once its read has provably finished.
+        with self._handle_lock:
+            if self._stop_event:
+                _kernel32.SetEvent(self._stop_event)
+        # Two ways join() raises, and both would skip the _close() below and
+        # leak all four handles. is_alive() is True for the calling thread, so
+        # it never prevented the self-join it looked like it prevented -- the
+        # reader reaches here whenever a user's quit_callback calls
+        # terminate(). And `ident is None` means start() was never called,
+        # where join() raises too.
+        if (join and self.ident is not None
+                and self is not threading.current_thread()):
             self.join()
+        if not self.is_alive():
+            # The reader has finished, or never ran. Either way nothing can
+            # have I/O outstanding, so the handle is ours to close.
+            self._close()
 
     def send(self, data):
         """Send *data* to the pipe, encoded as JSON."""
-        try:
-            self.socket.send_bytes(json.dumps(data).encode('utf-8') + b'\n')
-        except OSError as ex:
-            if len(ex.args) == 1 and ex.args[0] == "handle is closed":
+        blob = json.dumps(data).encode('utf-8') + b'\n'
+        with self._io_lock:
+            if self._closed:
                 raise BrokenPipeError("handle is closed")
-            raise ex
+            written = self._transfer(_kernel32.WriteFile, self._write_event,
+                                     blob, len(blob))
+        if written is None:
+            raise BrokenPipeError("handle is closed")
 
     def run(self):
         """Process pipe events. Do not run this directly. Use *start*."""
+        buf = ctypes.create_string_buffer(2048)
         data = b''
         try:
-            while True:
-                current_data = self.socket.recv_bytes(2048)
-                if current_data == b'':
+            while not self._stopping:
+                # The stop event is only observed when a read *pends*, and a
+                # read that completes synchronously returns before ever
+                # reaching the wait. A peer with data always available could
+                # therefore keep stop() waiting in join(). Not reproducible --
+                # 124k messages of flooding still let the reader park -- but
+                # the flag costs nothing and closes the argument.
+                #
+                # Emphatically NOT under _io_lock: this read is parked
+                # whenever MPV has nothing to say, which is almost always, and
+                # holding the lock across it would block every send. The lock
+                # exists to keep a send and the close apart; the reader needs
+                # no such guard because it closes the handle itself, in the
+                # finally below, only once its own read has returned.
+                nread = self._transfer(_kernel32.ReadFile, self._read_event,
+                                       buf, len(buf))
+                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 += current_data
+                data += buf.raw[:nread]
                 if data[-1] != 10:
                     continue
 
@@ -189,15 +440,14 @@ class WindowsSocket(threading.Thread):
                     json_data = json.loads(item)
                     self.callback(json_data)
                 data = b''
-        except EOFError:
-            if self.quit_callback:
-                self.quit_callback()
-        except Exception as ex:
+        except Exception:
             # Only log if not intentionally stopping
             if not self._stopping:
                 log.error("Pipe connection died.", exc_info=1)
-            if self.quit_callback:
-                self.quit_callback()
+        finally:
+            self._close()
+        if self.quit_callback:
+            self.quit_callback()
 
 class UnixSocket(threading.Thread):
     """
@@ -229,28 +479,41 @@ class UnixSocket(threading.Thread):
     def stop(self, join=True):
         """Terminate the thread."""
         self._stopping = True
-        if self.socket is not None:
+        # Bind once. Two threads reach here -- the caller's terminate() and
+        # the reader's quit_callback -> terminate(join=False) -- and making
+        # stop() wait for MPV widened that overlap, because the wait ends on
+        # the same MPV exit that wakes the reader. Re-reading self.socket
+        # after the None check let the loser call shutdown/close on None,
+        # which is an AttributeError and so is *not* caught below.
+        sock, self.socket = self.socket, None
+        if sock is not None:
             try:
-                self.socket.shutdown(socket.SHUT_WR)
-                self.socket.close()
-                self.socket = None
+                sock.shutdown(socket.SHUT_WR)
+                sock.close()
             except OSError:
                 pass # Ignore socket close failure.
-        if join:
+        # Not a bare `if join`: the reader reaches here whenever a user's
+        # quit_callback calls terminate(), and joining yourself raises -- which
+        # escaped run() and leaked the event handler. `ident is None` is the
+        # never-started case, where join() raises as well.
+        if (join and self.ident is not None
+                and self is not threading.current_thread()):
             self.join()
 
     def send(self, data):
         """Send *data* to the socket, encoded as JSON."""
-        if self.socket is None:
+        sock = self.socket # bind once; see stop()
+        if sock is None:
             raise BrokenPipeError("socket is closed")
-        self.socket.send(json.dumps(data).encode('utf-8') + b'\n')
+        sock.send(json.dumps(data).encode('utf-8') + b'\n')
 
     def run(self):
         """Process socket events. Do not run this directly. Use *start*."""
         data = b''
+        sock = self.socket # bind once; see stop()
         try:
             while True:
-                current_data = self.socket.recv(1024)
+                current_data = sock.recv(1024)
                 if current_data == b'':
                     break
 
@@ -282,26 +545,31 @@ def _ipc_endpoint_ready(ipc_socket):
     """
     if os.name != 'nt':
         return os.path.exists(ipc_socket)
-    try:
-        _winapi.WaitNamedPipe(ipc_socket, 0)
+    if _kernel32.WaitNamedPipeW(ipc_socket, 0):
         return True
-    except FileNotFoundError:
+    # Both codes, because the old _winapi version raised FileNotFoundError and
+    # CPython maps ERROR_PATH_NOT_FOUND to ENOENT as well. Treating 3 as
+    # "present but busy" would report a successful start and then burn
+    # WindowsSocket's five CreateFileW retries before failing with the wrong
+    # exception for the caller's retry loop.
+    if ctypes.get_last_error() in (_ERROR_FILE_NOT_FOUND, _ERROR_PATH_NOT_FOUND):
         return False
-    except OSError:
-        # Pipe exists but all instances are momentarily busy — it is present.
-        return True
+    # 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)
     """
-    def __init__(self, ipc_socket, mpv_location=None, **kwargs):
+    def __init__(self, ipc_socket, mpv_location=None, discard_output=False, **kwargs):
         """
         Create and start the MPV process. Will block until socket/pipe is available.
 
         *ipc_socket* is the path to the Unix/Linux socket or name of the Windows pipe.
         *mpv_location* is the path to mpv. If left unset it tries the one in the PATH.
+        *discard_output* sends MPV's stdout and stderr to devnull instead of inheriting
+        the caller's. (Default: False)
 
         All other arguments are forwarded to MPV as command-line arguments.
         """
@@ -338,7 +606,14 @@ 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)
+        # close_fds only covers fds above 2, so MPV inherits our stdout and
+        # stderr. It never writes to them under --terminal=no, which is why
+        # this is invisible until something waits for EOF on the other end of
+        # that pipe: an MPV that outlives us holds it open and that reader
+        # blocks forever. Opt-in rather than default because callers who do
+        # want MPV's output on their terminal have had it for years.
+        stdio = subprocess.DEVNULL if discard_output else None
+        self.process = subprocess.Popen(args, stdout=stdio, stderr=stdio)
         ipc_exists = False
         for _ in range(100): # Give MPV 10 seconds to start.
             time.sleep(0.1)
@@ -351,11 +626,16 @@ class MPVProcess:
                 log.error("MPV failed with returncode {0}.".format(self.process.returncode))
                 break
         else:
-            self.process.terminate()
+            # stop(), not a bare terminate(): a failed start orphans MPV
+            # exactly like a failed teardown did, and MPV.__init__ retries
+            # this up to start_retries times -- so a machine where MPV wedges
+            # without opening its pipe used to leave five live processes,
+            # each still holding the caller's stdout.
+            self._stop_quietly()
             raise MPVProcessError("MPV start timed out.", argv=args)
 
         if not ipc_exists or self.process.returncode is not None:
-            self.process.terminate()
+            self._stop_quietly()
             # 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.
@@ -379,11 +659,72 @@ class MPVProcess:
         else:
             return data
 
-    def stop(self):
-        """Terminate the process."""
+    def _stop_quietly(self):
+        """stop(), for the paths that are already raising something better.
+
+        A failed unlink here would replace MPVProcessError -- and an OSError
+        escapes MPV.__init__'s ``except MPVError`` retry loop, so the caller
+        would lose both the retries and the argv and returncode that the
+        error carries.
+        """
+        try:
+            self.stop()
+        except OSError:
+            log.debug("Cleanup after a failed MPV start did not complete.",
+                      exc_info=1)
+
+    def stop(self, timeout=5):
+        """Terminate the process, and do not return while it may still be alive.
+
+        *timeout* is the seconds to wait for a polite exit before killing, and
+        again for the kill to land.
+        """
+        # terminate() only *asks*. Returning here while MPV is still running
+        # left the caller no supported way to wait for it -- and a caller that
+        # exits at that moment orphans an MPV still holding its stdout. Both
+        # waits are bounded so a wedged MPV cannot hang teardown.
         self.process.terminate()
-        if os.name != 'nt' and os.path.exists(self.ipc_socket):
-            os.remove(self.ipc_socket)
+        try:
+            self.process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            log.warning("MPV ignored terminate for {0}s; killing it.".format(timeout))
+            self.process.kill()
+            try:
+                self.process.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                log.error("MPV survived kill; giving up on reaping it.")
+        if os.name != 'nt':
+            # try/except rather than exists()-then-remove, because two threads
+            # reach here: the caller's terminate(), and the reader's
+            # quit_callback -> terminate(join=False) when MPV's exit closes
+            # the socket. Waiting above made them *overlap by construction* --
+            # the wait ends when MPV dies, which is the same event that wakes
+            # the reader -- so the check-then-act window is reliably lost.
+            try:
+                os.remove(self.ipc_socket)
+            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:
     """
@@ -394,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
@@ -405,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):
         """
@@ -432,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
@@ -440,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)
@@ -452,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
 
@@ -479,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:
     """
@@ -510,7 +971,7 @@ class MPV:
     """
     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,
-                 diagnose_start_failures=True, **kwargs):
+                 diagnose_start_failures=True, discard_output=False, **kwargs):
         """
         Create the interface to MPV and process instance.
 
@@ -519,11 +980,16 @@ 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
         that cannot succeed. Set it to False for the pre-1.3 behaviour. (Default: True)
+        *discard_output* sends MPV's stdout and stderr to devnull instead of letting it
+        inherit the caller's. Set it if anything waits for EOF on your stdout, since an
+        MPV that outlives *terminate* would otherwise hold that pipe open. Note this is
+        not MPV's own --quiet, which is still forwarded as an MPV option. (Default: False)
 
         All other arguments are forwarded to MPV as command-line arguments if *start_mpv* is used.
         """
@@ -550,7 +1016,8 @@ class MPV:
             log_output = None
             for i in range(start_retries):
                 try:
-                    self.mpv_process = MPVProcess(ipc_socket, mpv_location, **kwargs)
+                    self.mpv_process = MPVProcess(ipc_socket, mpv_location,
+                                                  discard_output=discard_output, **kwargs)
                     break
                 except MPVError as error:
                     last_error = error
@@ -639,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):
@@ -749,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
@@ -782,6 +1254,14 @@ class MPV:
     def terminate(self, join=True):
         """Terminate the connection to MPV and process (if *start_mpv* is used)."""
         if self.mpv_process:
+            # Unconditionally, regardless of *join*. That flag only ever
+            # reaches our own threads -- and imperfectly: the transports join
+            # properly, while EventHandler.stop passes it as Thread.join's
+            # *timeout*, so join=True waits at most a second there and does
+            # not confirm the thread exited. Either way it says nothing about
+            # MPV, and _quit_callback passes False only because a thread
+            # cannot join itself. Letting it skip this wait would hand the
+            # orphaned-MPV bug back to anyone who passed it.
             self.mpv_process.stop()
         if self.mpv_inter:
             self.mpv_inter.stop(join)
@@ -799,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.3.0.dist-info/RECORD

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