Move the shm_fallback_reason to a more general performance_status property.

Author: jholveck

docs/source/examples/linux_xshm_backend.py

@@ -10,8 +10,6 @@
     screenshot = sct.grab(sct.monitors[1])
     print(f"Captured screenshot dimensions: {screenshot.size.width}x{screenshot.size.height}")
 
-    print(f"shm_status: {sct.shm_status.name}")
-    if sct.shm_fallback_reason:
-        print(f"Falling back to XGetImage because: {sct.shm_fallback_reason}")
-    else:
-        print("MIT-SHM capture active.")
+    print("Did MIT-SHM work:")
+    for message in sct.performance_status:
+        print(message)

src/mss/base.py

@@ -17,7 +17,6 @@
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
 
-    from mss.linux.xshmgetimage import ShmStatus
     from mss.models import Monitor, Monitors, Size
 
     # Prior to 3.11, Python didn't have the Self type.  typing_extensions does, but we don't want to depend on it.
@@ -74,7 +73,7 @@ class MSSImplementation(ABC):
     MSS object will hold a lock during these calls.
     """
 
-    __slots__ = ("with_cursor",)
+    __slots__ = ("performance_status", "with_cursor")
 
     with_cursor: bool
 
@@ -87,6 +86,10 @@ def __init__(self, /, *, with_cursor: bool = False) -> None:
         # Xlib is legacy, and just complicates things.
         self.with_cursor = with_cursor
 
+        # Any notes the backend needs to give the user for debugging purposes, like why it had to fall back to a
+        # slower implementation.
+        self.performance_status: list[str] = []
+
     @abstractmethod
     def cursor(self) -> ScreenShot | None:
         """Retrieve all cursor data. Pixels have to be RGB."""
@@ -169,15 +172,17 @@ class MSS:
 
     :param backend: Backend selector, for platforms with multiple backends.
     :param compression_level: PNG compression level.
-    :param with_cursor: Include the mouse cursor in screenshots (GNU/Linux only)
+    :param with_cursor: Include the mouse cursor in screenshots
+        (GNU/Linux only)
     :type display: bool, optional (default False)
     :param display: X11 display name (GNU/Linux only).
     :type display: bytes | str, optional (default :envvar:`$DISPLAY`)
     :param max_displays: Maximum number of displays to enumerate (macOS only).
     :type max_displays: int, optional (default 32)
 
     .. versionadded:: 8.0.0
-        ``compression_level``, ``display``, ``max_displays``, and ``with_cursor`` keyword arguments.
+        ``compression_level``, ``display``, ``max_displays``, and
+        ``with_cursor`` keyword arguments.
 
     .. versionadded:: 10.2.0
         ``backend`` keyword argument.
@@ -498,35 +503,23 @@ def _cfactory(
     # max_displays, should probably be removed in 11.0.  with_cursor
     # should probably be moved to MSS instead of MSSImplementation (as
     # noted there).
-    #
-    # The shm_status is mostly a debugging field, and probably should
-    # be replaced with something different.  Ideas include a log
-    # message, an exception if the user explicitly requested
-    # xshmgetimage, or a platform-independent message attribute (for
-    # instance, if Windows has to fall back to GDI).
 
     @property
-    def shm_status(self) -> ShmStatus:
-        """Whether we can use the MIT-SHM extensions for this connection.
+    def performance_status(self) -> list[str]:
+        """Implementation-specific notes that might affect performance.
 
-        Availability: GNU/Linux, when using the default XShmGetImage backend.
+        For instance, on GNU/Linux, when using the default XShmGetImage
+        backend, this will include a note if the MIT-SHM extension is
+        not usable.
 
-        This will not be ``AVAILABLE`` until at least one capture has succeeded.
-        It may be set to ``UNAVAILABLE`` sooner.
-
-        .. versionadded:: 10.2.0
-        """
-        return self._impl.shm_status  # type: ignore[attr-defined]
-
-    @property
-    def shm_fallback_reason(self) -> str | None:
-        """If MIT-SHM is unavailable, the reason why (for debugging purposes).
+        This may not be ready until one screenshot has been taken.
 
-        Availability: GNU/Linux, when using the default XShmGetImage backend.
+        This is meant only for debugging purposes; the contents are
+        subject to change at any time.
 
         .. versionadded:: 10.2.0
         """
-        return self._impl.shm_fallback_reason  # type: ignore[attr-defined]
+        return self._impl.performance_status
 
     @property
     def max_displays(self) -> int:

src/mss/linux/xshmgetimage.py

@@ -5,7 +5,7 @@
 
 This implementation prefers shared-memory captures for performance and will
 fall back to XGetImage when the MIT-SHM extension is unavailable or fails at
-runtime. The fallback reason is exposed via ``shm_fallback_reason`` to aid
+runtime. The fallback reason is exposed via ``performance_status`` to aid
 debugging.
 
 .. versionadded:: 10.2.0
@@ -61,8 +61,6 @@ def __init__(self, *, display: str | bytes | None = None, with_cursor: bool = Fa
         #: This will not be ``AVAILABLE`` until at least one capture has succeeded.
         #: It may be set to ``UNAVAILABLE`` sooner.
         self.shm_status: ShmStatus = self._setup_shm()
-        #: If MIT-SHM is unavailable, the reason why (for debugging purposes).
-        self.shm_fallback_reason: str | None = None
 
     def _shm_report_issue(self, msg: str, *args: Any) -> None:
         """Debugging hook for troubleshooting MIT-SHM issues.
@@ -73,7 +71,7 @@ def _shm_report_issue(self, msg: str, *args: Any) -> None:
         full_msg = msg
         if args:
             full_msg += " | " + ", ".join(str(arg) for arg in args)
-        self.shm_fallback_reason = full_msg
+        self.performance_status.append(full_msg)
 
     def _setup_shm(self) -> ShmStatus:  # noqa: PLR0911
         assert self.conn is not None  # noqa: S101
@@ -200,7 +198,9 @@ def grab(self, monitor: Monitor) -> bytearray:
         # The usual path is just the next few lines.
         try:
             rv = self._grab_xshmgetimage(monitor)
-            self.shm_status = ShmStatus.AVAILABLE
+            if self.shm_status != ShmStatus.AVAILABLE:
+                self.shm_status = ShmStatus.AVAILABLE
+                self.performance_status.append("MIT-SHM is working correctly.")
         except XProtoError as e:
             if self.shm_status != ShmStatus.UNKNOWN:
                 # We know XShmGetImage works, because it worked earlier.  Reraise the error.