[Python] PySide2/Qt Application Locks Up on macOS After QToolBar Operations in Event Loop

I'm experiencing a mysterious lockup issue with a PySide2 application on macOS (works fine on Windows/Linux). The application locks up consistently after a specific sequence of operations, but only after all Python code completes and control returns to Qt's event loop.

The Problem:

• The application works on Windows and Linux
• On macOS, it locks up after making moves in a chess tactics trainer
• The lockup happens after all Python functions complete
• Debugging shows all operations complete successfully, then the app becomes unresponsive

What I've Tried:

1. Suppressed QPainter errors using qInstallMessageHandler()
2. Skipped all refresh operations (QWidget.update(), processEvents())
3. Prevented toolbar clearing and rebuilding
4. Added extensive debugging - all functions complete normally

Debug Output (macOS only):

DEBUG: add_move start - toolbar should be visible
DEBUG: after game.add_move
DEBUG: after check_boards_setposition
DEBUG: after put_arrow_sc
DEBUG: after beep_extended
DEBUG: after pgn_refresh
DEBUG: skipping refresh on macOS to prevent toolbar corruption
DEBUG: refresh skipped on macOS
DEBUG: on macOS - skipping all end-of-line processing to prevent lockup
DEBUG: skipping play_next_move on macOS after correct move to prevent lockup


[App becomes unresponsive here - no crash, just frozen]

Simplified Code Pattern:


class ManagerEntPos:
def player_has_moved(self, from_sq, to_sq, promotion=""):
# Validate move, update game state
move = self.check_human_move(from_sq, to_sq, promotion)
self.add_move(move, True)

# This condition triggers the lockup sequence
if self.game_obj and self.pos_obj >= len(self.game_obj):
# Line completed - this triggers lockup on macOS
self.linea_terminada_opciones() # Even when skipped, lockup occurs

self.play_next_move() # Even when skipped, lockup occurs
return True # Function completes, then Qt event loop hangs

def add_move(self, move, si_nuestra):
self.game.add_move(move)
self.put_arrow_sc(move.from_sq, move.to_sq) # Disabled on macOS
self.pgn_refresh(self.game.last_position.is_white)
self.refresh() # Disabled on macOS


Observations:

• The lockup happens only when a tactical line is completed (correct move sequence)
• Wrong moves don't cause lockups
• All Python code executes successfully before the hang
• Even when skipping problematic functions entirely, the lockup still occurs
• Qt message handler successfully suppresses QPainter errors, but lockup persists

Environment:

• macOS 14.6.0 (Darwin 24.6.0)
• PySide2 5.15.x
• Python 3.x
• QGraphicsView-based chess board with QToolBar

What could cause Qt's event loop to hang on macOS after Python functions complete successfully? Is there a known macOS-specific Qt issue with QToolBar operations or QGraphicsView updates that could cause this behavior?

Continue reading...