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

{python_mpv_jsonipc-1.2.2.dist-info → python_mpv_jsonipc-1.3.0.dist-info}/METADATA

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

python_mpv_jsonipc-1.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+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,,

{python_mpv_jsonipc-1.2.2.dist-info → python_mpv_jsonipc-1.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_mpv_jsonipc.py

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

python_mpv_jsonipc-1.2.2.dist-info/RECORD

@@ -1,6 +0,0 @@
-python_mpv_jsonipc.py,sha256=McfALK21Mp48Ekpg8wszSnHlSExtlrpsrw90i9syvng,24041
-python_mpv_jsonipc-1.2.2.dist-info/licenses/LICENSE.md,sha256=7GQBUOA3dNG1Jk-yaPOCncNnRVURCRMev23QpZ1ew-s,10495
-python_mpv_jsonipc-1.2.2.dist-info/METADATA,sha256=AjVHMMb5-bKwYuf89xM3J9jLRPX17v-iXkMvuft8AF0,2277
-python_mpv_jsonipc-1.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_mpv_jsonipc-1.2.2.dist-info/top_level.txt,sha256=nGk4yjpVHKmIrL39XdGD2PhCeWF0oMjwey0nsNOd2TM,19
-python_mpv_jsonipc-1.2.2.dist-info/RECORD,,