From 0ea4622fb7cf6c96571bb38b73d8eb493c29c8d8 Mon Sep 17 00:00:00 2001 From: jaseg Date: Sat, 18 Jul 2020 14:28:46 +0200 Subject: mpv.py: Add docstrings to new additions to API --- mpv.py | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/mpv.py b/mpv.py index a2950ce..87715b0 100644 --- a/mpv.py +++ b/mpv.py @@ -891,6 +891,8 @@ class MPV(object): @property def core_shutdown(self): + """Property indicating whether the core has been shut down. Possible causes for this are e.g. the `quit` command + or a user closing the mpv window.""" return self._core_shutdown def wait_until_paused(self): @@ -935,13 +937,26 @@ class MPV(object): self.unobserve_property(name, observer) def wait_for_event(self, *event_types, cond=lambda evt: True): + """Waits for the indicated event(s). If cond is given, waits until cond(event) is true. Raises a ShutdownError + if the core is shutdown while waiting. This also happens when 'shutdown' is in event_types. + """ with self.prepare_and_wait_for_event(*event_types, cond=cond): pass @contextmanager def prepare_and_wait_for_event(self, *event_types, cond=lambda evt: True): - """Waits for the indicated event(s). If cond is given, waits until cond(event) is true. Raises a ShutdownError - if the core is shutdown while waiting. This also happens when 'shutdown' is in event_types. + """Context manager that waits for the indicated event(s) like wait_for_event after running. If cond is given, + waits until cond(event) is true. Raises a ShutdownError if the core is shutdown while waiting. This also happens + when 'shutdown' is in event_types. + + Compared to wait_for_event this handles the case where a thread waits for an event it itself causes in a + thread-safe way. An example from the testsuite is: + + with self.m.prepare_and_wait_for_event('client_message'): + self.m.keypress(key) + + Using just wait_for_event it would be impossible to ensure the event is caught since it may already have been + handled in the interval between keypress(...) running and a subsequent wait_for_event(...) call. """ sema = threading.Semaphore(value=0) -- cgit