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

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

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

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

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

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

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

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

@@ -11,4 +11,5 @@ tests/test_arg_building.py
 tests/test_live_basic.py
 tests/test_live_events.py
 tests/test_live_failure.py
+tests/test_live_teardown.py
 tests/test_python_floor.py

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

@@ -12,8 +12,100 @@ import logging
 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 +215,215 @@ 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 not nread:
                     break
 
-                data += current_data
+                data += buf.raw[:nread]
                 if data[-1] != 10:
                     continue
 
@@ -189,15 +434,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 +473,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 +539,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 +600,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 +620,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 +653,51 @@ 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.
 
 class MPVInter:
     """
@@ -510,7 +824,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.
 
@@ -524,6 +838,10 @@ class MPV:
         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 +868,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
@@ -782,6 +1101,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)

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

@@ -107,6 +107,38 @@ class SocketPathTest(unittest.TestCase):
         self.assertFalse(os.path.exists(path))
 
 
+class OutputRedirectionTest(unittest.TestCase):
+    """Which stdio ``Popen`` is asked for, which is not visible in the argv."""
+
+    def popen_call(self, **kwargs):
+        with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen") as popen, \
+                mock.patch.object(python_mpv_jsonipc, "_ipc_endpoint_ready",
+                                  return_value=True):
+            popen.return_value = _FakeProcess()
+            python_mpv_jsonipc.MPVProcess("/tmp/testsocket", "mpv", **kwargs)
+            return popen.call_args
+
+    def test_by_default_mpv_inherits_our_stdout_and_stderr(self):
+        # Characterization: None means inherit. See test_live_teardown for
+        # what that costs and why it is still the default.
+        kwargs = self.popen_call()[1]
+        self.assertIsNone(kwargs["stdout"])
+        self.assertIsNone(kwargs["stderr"])
+
+    def test_discard_output_sends_both_to_devnull(self):
+        kwargs = self.popen_call(discard_output=True)[1]
+        self.assertEqual(kwargs["stdout"], python_mpv_jsonipc.subprocess.DEVNULL)
+        self.assertEqual(kwargs["stderr"], python_mpv_jsonipc.subprocess.DEVNULL)
+
+    def test_discard_output_is_never_forwarded_to_mpv(self):
+        # It is a keyword of ours, not an mpv option -- unlike `quiet`, which
+        # mpv really has and which must keep being forwarded. That collision
+        # is why this keyword is not named `quiet`.
+        argv = self.popen_call(discard_output=True, quiet=True)[0][0]
+        self.assertIn("--quiet=yes", argv)
+        self.assertEqual([a for a in argv if "discard" in a], [])
+
+
 class MpvFmtTest(unittest.TestCase):
     """`_mpv_fmt` in isolation, since it is where the bool/int trap lives."""
 

python_mpv_jsonipc-1.4.0/tests/test_live_teardown.py

@@ -0,0 +1,300 @@
+"""What ``terminate()`` guarantees about the mpv process it started.
+
+Reported by jellyfin-mpv-shim, 2026-08-31: an integration leg printed its
+results, exited cleanly, and then its parent hung forever reading the leg's
+stdout. The orphan was an mpv with PPID 1 still holding the pipe the parent
+was blocked on -- ``/proc/<mpv>/fd/1`` named the exact inode.
+
+Two separate facts produced that, and they are tested separately here because
+only one of them was fixed:
+
+* ``stop()`` sent SIGTERM and returned without waiting, so ``terminate()``
+  could return while mpv was still running. That is now a wait with a kill
+  escalation, and it is what these tests pin.
+* mpv inherits the caller's stdout and stderr, because ``close_fds`` only
+  covers fds above 2. That is *unchanged by default* -- callers have had
+  mpv's output on their terminal for years -- and opt-out via
+  ``discard_output``. The default is pinned below as characterization, not
+  as approval.
+
+The intermittency is the tell: it is a race between mpv's SIGTERM handling
+and the caller exiting, so a run where the orphan does not appear proves
+nothing. These assert the postcondition instead of trying to lose the race.
+
+A third fact arrived with the fix rather than before it, which is why it is
+tested here too: making ``stop()`` wait turned a long-latent check-then-act
+race on the socket unlink into a reliable one, because the wait ends on the
+same MPV exit that wakes the reader into a second ``terminate()``. It was
+found by ``stress_teardown.py`` at ~50 cycles, not by this file -- a reminder
+that the cheap tests here cover postconditions, not interleavings.
+"""
+
+import os
+import tempfile
+import threading
+import time
+import unittest
+from unittest import mock
+
+from _harness import MPV_BINARY, LIVE_OPTIONS, python_mpv_jsonipc, requires_mpv
+
+#: The fd-inheritance assertions read /proc, so they are Linux-only. The
+#: waiting assertions above them are not, and run everywhere.
+has_proc = unittest.skipUnless(os.path.exists("/proc/self/fd"),
+                               "needs /proc to see the child's fds")
+
+
+def _skip_only_the_readiness_poll():
+    """Make MPVProcess's 0.1s poll free without touching any other sleep.
+
+    Patching ``time.sleep`` wholesale would also hit ``Popen.wait(timeout=)``,
+    which stop() calls from inside the same patched block -- turning a bounded
+    wait into a busy spin, and spinning every other sleeping thread with it.
+    """
+    real_sleep = python_mpv_jsonipc.time.sleep
+    return lambda seconds: None if seconds == 0.1 else real_sleep(seconds)
+
+
+def start_mpv(**extra):
+    options = dict(LIVE_OPTIONS)
+    options.update(extra)
+    return python_mpv_jsonipc.MPV(mpv_location=MPV_BINARY, **options)
+
+
+@requires_mpv
+class TerminateWaitsTest(unittest.TestCase):
+    def test_terminate_does_not_return_while_mpv_may_still_be_alive(self):
+        mpv = start_mpv()
+        process = mpv.mpv_process.process
+
+        mpv.terminate()
+
+        # returncode is only set by a wait(). Before the fix nothing ever
+        # called one, so this was None however long mpv had been dead --
+        # which is the whole complaint: the caller had no way to know.
+        self.assertIsNotNone(
+            process.returncode,
+            "terminate() returned without waiting for mpv; a caller that "
+            "exits here orphans an mpv still holding its stdout")
+
+    @unittest.skipIf(os.name == "nt", "POSIX socket files only")
+    def test_the_socket_removal_survives_losing_the_race(self):
+        # Two threads reach MPVProcess.stop(): the caller's terminate(), and
+        # the reader's quit_callback -> terminate(join=False), woken by the
+        # very MPV exit that stop() now waits for. So they overlap by
+        # construction, and the loser finds the socket already unlinked.
+        #
+        # The window itself cannot be hit on demand, but its outcome can:
+        # exists() answering True for a file that is gone is exactly what the
+        # loser sees. Check-then-act raises FileNotFoundError here.
+        mpv = start_mpv()
+        process = mpv.mpv_process
+        mpv.terminate()
+        self.assertFalse(os.path.exists(process.ipc_socket))
+
+        with mock.patch("os.path.exists", return_value=True):
+            process.stop()
+
+    @unittest.skipIf(os.name == "nt", "UnixSocket only")
+    def test_stopping_the_socket_survives_the_other_thread_finishing_first(self):
+        # Two threads reach UnixSocket.stop(): the caller's terminate() and
+        # the reader's quit_callback -> terminate(join=False). Making stop()
+        # wait for MPV widened that overlap, because the wait ends on the same
+        # MPV exit that wakes the reader.
+        #
+        # Racing it is unreliable -- 400 live cycles produced none -- so model
+        # the losing thread instead: the winner clears self.socket midway
+        # through ours. Re-reading the attribute then calls close() on None,
+        # an AttributeError, which `except OSError` does not catch.
+        class Winner:
+            def __init__(self, real, owner):
+                self._real, self._owner = real, owner
+
+            def shutdown(self, how):
+                self._owner.socket = None   # the other thread finishes here
+                return self._real.shutdown(how)
+
+            def close(self):
+                return self._real.close()
+
+        mpv = start_mpv()
+        self.addCleanup(mpv.terminate)
+        transport = mpv.mpv_inter.socket
+        transport.socket = Winner(transport.socket, transport)
+
+        transport.stop(join=False)
+
+    def test_a_failed_start_does_not_leave_mpv_running(self):
+        # The failure path orphaned MPV exactly as the success path did, and
+        # worse: MPV.__init__ retries construction up to start_retries times,
+        # so a machine where MPV wedges without opening its pipe left five
+        # live processes, each holding the caller's stdout.
+        #
+        # The endpoint poll is answered False so the start "times out" while
+        # MPV is genuinely running, and sleep is a no-op so that costs
+        # microseconds instead of the real ten seconds.
+        spawned = []
+        real_popen = python_mpv_jsonipc.subprocess.Popen
+
+        def record(*args, **kwargs):
+            process = real_popen(*args, **kwargs)
+            spawned.append(process)
+            return process
+
+        with mock.patch.object(python_mpv_jsonipc.subprocess, "Popen", record), \
+                mock.patch.object(python_mpv_jsonipc, "_ipc_endpoint_ready",
+                                  return_value=False), \
+                mock.patch.object(python_mpv_jsonipc.time, "sleep",
+                                  _skip_only_the_readiness_poll()):
+            with self.assertRaises(python_mpv_jsonipc.MPVProcessError):
+                python_mpv_jsonipc.MPVProcess(
+                    os.path.join(tempfile.mkdtemp(), "failed-start.sock"),
+                    MPV_BINARY, **LIVE_OPTIONS)
+
+        self.assertEqual(len(spawned), 1)
+        self.assertIsNotNone(
+            spawned[0].returncode,
+            "a start that failed left MPV running and unreaped")
+
+    def test_a_quit_callback_that_terminates_does_not_join_its_own_thread(self):
+        # quit_callback runs on the reader thread, and terminate() defaults to
+        # join=True -- so the reader was asked to join itself. RuntimeError
+        # escaped run(), which skipped the internal terminate(join=False)
+        # after it and leaked the event handler.
+        mpv = start_mpv()
+        escaped = []
+        original_hook = threading.excepthook
+        threading.excepthook = lambda args: escaped.append(
+            "{0}: {1}".format(args.exc_type.__name__, args.exc_value))
+        self.addCleanup(setattr, threading, "excepthook", original_hook)
+
+        mpv.quit_callback = mpv.terminate
+        mpv.mpv_process.process.kill()
+
+        deadline = time.time() + 5
+        while mpv.mpv_inter.socket.is_alive() and time.time() < deadline:
+            time.sleep(0.02)
+        time.sleep(0.2)
+
+        self.assertEqual(escaped, [])
+
+    def test_the_process_is_reaped_not_merely_signalled(self):
+        mpv = start_mpv()
+        process = mpv.mpv_process.process
+
+        mpv.terminate()
+
+        self.assertIsNotNone(process.poll())
+
+
+class StopWaitingTest(unittest.TestCase):
+    """No mpv here: a stub is the only way to hold SIGTERM open on demand."""
+
+    class _Stubborn:
+        """Ignores terminate(); only kill() gets through."""
+
+        def __init__(self):
+            self.killed = False
+            self.waits = []
+
+        def terminate(self):
+            pass
+
+        def kill(self):
+            self.killed = True
+
+        def wait(self, timeout=None):
+            self.waits.append(timeout)
+            if self.killed:
+                return -9
+            raise python_mpv_jsonipc.subprocess.TimeoutExpired("mpv", timeout)
+
+    def _process(self, socket_name="absent.sock"):
+        process = python_mpv_jsonipc.MPVProcess.__new__(
+            python_mpv_jsonipc.MPVProcess)
+        process.process = self._Stubborn()
+        process.ipc_socket = os.path.join(tempfile.mkdtemp(), socket_name)
+        return process
+
+    def test_a_timeout_waits_then_escalates_to_kill(self):
+        process = self._process()
+
+        process.stop(timeout=0)
+
+        self.assertTrue(process.process.killed)
+        self.assertEqual(process.process.waits, [0, 0])
+
+    @unittest.skipIf(os.name == "nt", "POSIX socket files only")
+    def test_an_unlink_failure_that_is_not_the_race_is_not_swallowed(self):
+        # Only FileNotFoundError means "the other thread got there first".
+        # Swallowing every OSError would hide a permission problem or a path
+        # that is not the socket we think it is.
+        process = self._process()
+        process.process.killed = True   # so the wait returns instead of escalating
+        with mock.patch("os.remove", side_effect=PermissionError("nope")):
+            with self.assertRaises(PermissionError):
+                process.stop(timeout=0)
+
+
+@requires_mpv
+class TerminateAlwaysTerminatesTest(unittest.TestCase):
+    def test_it_reaps_mpv_even_when_asked_not_to_join(self):
+        # `join` governs whether we join our *threads* -- _quit_callback
+        # passes False only because a thread cannot join itself. It is not a
+        # "do not block" flag: it is undocumented in both the docstring and
+        # docs.md, and every use of it reaches a Thread.join and nothing else.
+        # So it must not gate the process wait, or passing it hands back the
+        # orphaned MPV this file exists to prevent.
+        mpv = start_mpv()
+        process = mpv.mpv_process.process
+
+        mpv.terminate(join=False)
+
+        self.assertIsNotNone(
+            process.returncode,
+            "terminate(join=False) left MPV unreaped; join is about threads, "
+            "not about whether MPV actually dies")
+
+
+@requires_mpv
+@has_proc
+class InheritedOutputTest(unittest.TestCase):
+    def _child_stdio(self, mpv):
+        pid = mpv.mpv_process.process.pid
+        return (os.readlink("/proc/{0}/fd/1".format(pid)),
+                os.readlink("/proc/{0}/fd/2".format(pid)))
+
+    def test_mpv_inherits_the_callers_stdout_and_stderr_by_default(self):
+        # Characterization. This is the behaviour that let an orphaned mpv
+        # hold a test runner's pipe open, and it is still the default because
+        # changing it would silently take mpv's output away from every caller
+        # who currently sees it.
+        mpv = start_mpv()
+        self.addCleanup(mpv.terminate)
+        ours = (os.readlink("/proc/self/fd/1"), os.readlink("/proc/self/fd/2"))
+
+        self.assertEqual(self._child_stdio(mpv), ours)
+
+    def test_discard_output_keeps_mpv_off_the_callers_pipes(self):
+        mpv = start_mpv(discard_output=True)
+        self.addCleanup(mpv.terminate)
+
+        stdout, stderr = self._child_stdio(mpv)
+
+        self.assertEqual(stdout, os.devnull)
+        self.assertEqual(stderr, os.devnull)
+
+    def test_discard_output_is_not_passed_on_to_mpv(self):
+        # mpv has a real --quiet; it must keep working as an mpv option, which
+        # is why this keyword is not called that. If discard_output ever leaks
+        # into the argv, mpv rejects it and nothing starts at all.
+        mpv = start_mpv(discard_output=True, quiet=True)
+        self.addCleanup(mpv.terminate)
+
+        self.assertIn("--quiet=yes", mpv.mpv_process.argv)
+        self.assertEqual(
+            [a for a in mpv.mpv_process.argv if "discard" in a], [])
+
+
+if __name__ == "__main__":
+    unittest.main()