[build] Fix flake due to suspected finalizer exceptions

Author: Breakthrough

.github/workflows/build.yml

@@ -33,6 +33,7 @@ jobs:
   build:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [macos-14, macos-latest, ubuntu-22.04, ubuntu-latest, windows-latest]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
@@ -64,9 +65,18 @@ jobs:
           git fetch --depth=1 https://github.com/Breakthrough/PySceneDetect.git refs/heads/resources:refs/remotes/origin/resources
           git checkout refs/remotes/origin/resources -- tests/resources/
 
+      # Instrumented while chasing a windows-latest flake where python exits 1 after a
+      # fully green pytest run with no output. `-X dev` makes shutdown-time warnings and
+      # finalizer errors loud; echoing the exit code separates python's own return value
+      # from anything the shell wrapper does to a crash code.
       - name: Unit Tests
+        shell: bash
         run: |
-          python -m pytest -vv
+          set +e
+          python -X dev -m pytest -vv
+          code=$?
+          echo "pytest exit code: $code"
+          exit $code
 
       - name: Smoke Test (Module)
         run: |

pyproject.toml

@@ -94,13 +94,6 @@ markers = [
 addopts = "-m 'not release'"
 filterwarnings = [
     "ignore:TODO.*Update caller to handle VFR:UserWarning",
-    # Promote unraisable (finalizer) and unhandled-thread exceptions to named test
-    # failures. A CI run on windows-latest once exited 1 with every test passing and
-    # no output - the failure mode pytest 9.1+ reports for unraisable exceptions
-    # collected at shutdown. These filters turn any recurrence into an attributable
-    # traceback instead of a bare exit code.
-    "error::pytest.PytestUnraisableExceptionWarning",
-    "error::pytest.PytestUnhandledThreadExceptionWarning",
 ]
 
 [tool.ruff]

scenedetect/backends/pyav.py

@@ -157,10 +157,19 @@ def __init__(
         self._duration_frames = self._get_duration()
 
     def __del__(self):
-        # `_container` is unset if `__init__` raised before `av.open()` succeeded.
-        container = getattr(self, "_container", None)
-        if container is not None:
-            container.close()
+        # Finalizers must never raise - an exception here becomes an unraisable error. During
+        # interpreter shutdown the underlying handles are reclaimed by the OS anyway.
+        try:
+            # Close the decode generator first to break its cycle with the container.
+            decoder = getattr(self, "_decoder", None)
+            if decoder is not None:
+                decoder.close()
+            # `_container` is unset if `__init__` raised before `av.open()` succeeded.
+            container = getattr(self, "_container", None)
+            if container is not None:
+                container.close()
+        except Exception:
+            pass
 
     #
     # VideoStream Methods/Properties

scenedetect/scene_manager.py

@@ -573,31 +573,37 @@ def detect_scenes(
         frame_im = None
 
         logger.info("Detecting scenes...")
-        while not self._stop.is_set():
-            next_frame, position = frame_queue.get()
-            if next_frame is None and position is None:
-                break
-            if next_frame is not None:
-                frame_im = next_frame
-            assert frame_im is not None
-            new_cuts = self._process_frame(position, frame_im, callback)
+        try:
+            while not self._stop.is_set():
+                next_frame, position = frame_queue.get()
+                if next_frame is None and position is None:
+                    break
+                if next_frame is not None:
+                    frame_im = next_frame
+                assert frame_im is not None
+                new_cuts = self._process_frame(position, frame_im, callback)
+                if progress_bar is not None:
+                    if new_cuts:
+                        progress_bar.set_description(
+                            PROGRESS_BAR_DESCRIPTION % len(self._cutting_list), refresh=False
+                        )
+                    progress_bar.update(1 + frame_skip)
+        finally:
             if progress_bar is not None:
-                if new_cuts:
-                    progress_bar.set_description(
-                        PROGRESS_BAR_DESCRIPTION % len(self._cutting_list), refresh=False
-                    )
-                progress_bar.update(1 + frame_skip)
-
-        if progress_bar is not None:
-            progress_bar.set_description(
-                PROGRESS_BAR_DESCRIPTION % len(self._cutting_list), refresh=True
-            )
-            progress_bar.close()
-        # Unblock any puts in the decode thread before joining. This can happen if the main
-        # processing thread stops before the decode thread.
-        while not frame_queue.empty():
-            frame_queue.get_nowait()
-        decode_thread.join()
+                progress_bar.set_description(
+                    PROGRESS_BAR_DESCRIPTION % len(self._cutting_list), refresh=True
+                )
+                progress_bar.close()
+            # The decode thread must never be abandoned, even if a detector or callback
+            # raises above: an orphaned daemon thread keeps the VideoStream alive until
+            # interpreter shutdown, where finalizing it (or killing the thread mid-decode)
+            # can crash process exit. Signal it to stop, then keep unblocking any pending
+            # puts until it exits.
+            self._stop.set()
+            while decode_thread.is_alive():
+                while not frame_queue.empty():
+                    frame_queue.get_nowait()
+                decode_thread.join(timeout=0.1)
 
         if self._exception_info is not None:
             exc = self._exception_info[1]

tests/conftest.py

@@ -159,3 +159,26 @@ def delayed_start_video() -> str:
     """Video with a nonzero stream start time (1.075s edit-list offset). Created from
     fades.mp4 via: ffmpeg -itsoffset 1.075 -i fades.mp4 -t 2 -c:v copy -an delayed_start.mp4"""
     return check_exists("tests/resources/delayed_start.mp4")
+
+
+def pytest_unconfigure(config):
+    """Diagnostic for a windows-latest CI flake (silent exit 1 after a green run):
+    report any non-main threads still alive at session end. Leaked threads keep
+    VideoStreams alive into interpreter shutdown, where native teardown can crash
+    the process exit code. tqdm's global monitor singleton is expected and ignored."""
+    import sys
+    import threading
+
+    leftover = [
+        t
+        for t in threading.enumerate()
+        if t is not threading.main_thread() and t.name != "tqdm_monitor"
+    ]
+    for thread in leftover:
+        frame = sys._current_frames().get(thread.ident) if thread.ident else None
+        location = f"{frame.f_code.co_filename}:{frame.f_lineno}" if frame else "unknown"
+        print(
+            f"WARNING: thread still alive at exit: {thread.name} "
+            f"(daemon={thread.daemon}) at {location}",
+            file=sys.stderr,
+        )