Update the docs

Also, before marking XShmGetImage as unavailable if the first grab()
fails, also test to see if the fallback XGetImage also fails (such as
if the user gave an out-of-bounds rect).  In that case, just reraise
the exception and try XShmGetImage again with the next grab().

Author: jholveck

CHANGELOG.md

@@ -5,7 +5,8 @@ See Git checking messages for full history.
 ## 10.1.1.dev0 (2025-xx-xx)
 - Linux: check the server for Xrandr support version (#417)
 - Linux: improve typing and error messages for X libraries (#418)
-- Linux: add a new XCB backend for better thread safety, error-checking, and future development (#425)
+- Linux: introduce an XCB-powered backend stack with a factory in ``mss.linux`` while keeping the Xlib code as a fallback (#425)
+- Linux: add the XShmGetImage backend with automatic XGetImage fallback and explicit status reporting (#431)
 - :heart: contributors: @jholveck
 
 ## 10.1.0 (2025-08-16)

CHANGES.md

@@ -1,5 +1,19 @@
 # Technical Changes
 
+## 10.1.1 (2025-xx-xx)
+
+### linux/__init__.py
+- Added an ``mss()`` factory to select between the different GNU/Linux backends.
+
+### linux/xlib.py
+- Moved the legacy Xlib backend into the ``mss.linux.xlib`` module to be used as a fallback implementation.
+
+### linux/xgetimage.py
+- Added an XCB-based backend that mirrors XGetImage semantics.
+
+### linux/xshmgetimage.py
+- Added an XCB backend powered by XShmGetImage with ``shm_status`` and ``shm_fallback_reason`` attributes for diagnostics.
+
 ## 10.1.0 (2025-08-16)
 
 ### darwin.py

docs/source/api.rst

@@ -33,6 +33,36 @@ GNU/Linux
 
 .. module:: mss.linux
 
+Factory function to return the appropriate backend implementation.
+
+.. function:: mss(backend="default", **kwargs)
+
+    :keyword str backend: Backend name ("default", "xlib", "xgetimage", or "xshmgetimage").
+    :keyword display: Display name (e.g., ":0.0") for the X server.  Default is taken from the :envvar:`DISPLAY` environment variable.
+    :type display: str or None
+    :param kwargs: Additional arguments passed to the backend MSS class.
+    :rtype: :class:`mss.base.MSSBase`
+    :return: Backend-specific MSS instance.
+
+    Factory returning a proper MSS class instance for GNU/Linux.
+    The backend parameter selects the implementation:
+
+    - "default" or "xlib": Traditional Xlib-based backend (default)
+    - "xgetimage": XCB-based backend using XGetImage
+    - "xshmgetimage": XCB-based backend using XShmGetImage (falls back to XGetImage if unavailable)
+
+.. function:: MSS(*args, **kwargs)
+
+    Alias for :func:`mss` for backward compatibility.
+
+
+Xlib Backend
+^^^^^^^^^^^^
+
+.. module:: mss.linux.xlib
+
+Traditional Xlib-based backend (default).
+
 .. attribute:: CFUNCTIONS
 
     .. versionadded:: 6.1.0
@@ -79,6 +109,55 @@ GNU/Linux
 
         .. versionadded:: 8.0.0
 
+
+XGetImage Backend
+^^^^^^^^^^^^^^^^^
+
+.. module:: mss.linux.xgetimage
+
+XCB-based backend using XGetImage protocol.
+
+.. class:: MSS
+
+    XCB implementation using XGetImage for screenshot capture.
+
+
+XShmGetImage Backend
+^^^^^^^^^^^^^^^^^^^^
+
+.. module:: mss.linux.xshmgetimage
+
+XCB-based backend using XShmGetImage protocol with shared memory.
+
+.. class:: ShmStatus
+
+    Enum describing the availability of the X11 MIT-SHM extension used by the backend.
+
+    .. attribute:: UNKNOWN
+
+        Initial state before any capture confirms availability or failure.
+
+    .. attribute:: AVAILABLE
+
+        Shared-memory capture works and will continue to be used.
+
+    .. attribute:: UNAVAILABLE
+
+        Shared-memory capture failed; MSS will use XGetImage.
+
+.. class:: MSS
+
+    XCB implementation using XShmGetImage for screenshot capture.
+    Falls back to XGetImage if shared memory extension is unavailable.
+
+    .. attribute:: shm_status
+
+        Current shared-memory availability, using :class:`mss.linux.xshmgetimage.ShmStatus`.
+
+    .. attribute:: shm_fallback_reason
+
+        Optional string describing why the backend fell back to XGetImage when MIT-SHM is unavailable.
+
 Windows
 -------
 

docs/source/developers.rst

@@ -50,3 +50,12 @@ To build the documentation, simply type::
 
     $ python -m pip install -e '.[docs]'
     $ sphinx-build -d docs docs/source docs_out --color -W -bhtml
+
+
+XCB Code Generator
+==================
+
+The GNU/Linux XCB backends rely on generated ctypes bindings.  If you need to
+add new XCB requests or types, do **not** edit ``src/mss/linux/xcbgen.py`` by
+hand.  Instead, follow the workflow described in ``src/xcbproto/README.md``,
+which explains how to update ``gen_xcb_to_py.py`` and regenerate the bindings.

docs/source/examples.rst

@@ -103,6 +103,15 @@ You can handle data using a custom class:
 
 .. versionadded:: 3.1.0
 
+GNU/Linux XShm backend
+----------------------
+
+Select the XShmGetImage backend explicitly and inspect whether it is active or
+falling back to XGetImage::
+
+.. literalinclude:: examples/linux_xshm_backend.py
+    :lines: 7-
+
 PIL
 ===
 

docs/source/examples/linux_xshm_backend.py

@@ -0,0 +1,17 @@
+"""This is part of the MSS Python's module.
+Source: https://github.com/BoboTiG/python-mss.
+
+Select the XShmGetImage backend explicitly and inspect its status.
+"""
+
+from mss.linux.xshmgetimage import MSS as mss
+
+with mss() as sct:
+    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.")

docs/source/usage.rst

@@ -5,7 +5,7 @@ Usage
 Import
 ======
 
-So MSS can be used as simply as::
+MSS can be used as simply as::
 
     from mss import mss
 
@@ -20,6 +20,11 @@ Or import the good one based on your operating system::
     # Microsoft Windows
     from mss.windows import MSS as mss
 
+On GNU/Linux you can also import a specific backend (see :ref:`backends`)
+directly when you need a particular implementation, for example::
+
+    from mss.linux.xshmgetimage import MSS as mss
+
 
 Instance
 ========
@@ -49,19 +54,57 @@ This is a much better usage, memory efficient::
 Also, it is a good thing to save the MSS instance inside an attribute of your class and calling it when needed.
 
 
+.. _backends:
+
+Backends
+--------
+
+Some platforms have multiple ways to take screenshots.  In MSS, these are known as *backends*.  The :py:func:`mss` functions will normally autodetect which one is appropriate for your situation, but you can override this if you want.  For instance, you may know that your specific situation requires a particular backend.
+
+If you want to choose a particular backend, you can use the :py::`backend` keyword to :py:func:`mss`:::
+
+    with mss(backend="xgetimage") as sct:
+        ...
+
+Instead, you can also directly import the backend you want to use:::
+
+    from mss.linux.xgetimage import MSS as mss
+
+Currently, only the GNU/Linux implementation has multiple backends.  These are described in their own section below.
+
+
 GNU/Linux
 ---------
 
-On GNU/Linux, you can specify which display to use (useful for distant screenshots via SSH)::
+Display
+^^^^^^^
+
+On GNU/Linux, the default display is taken from the :envvar:`DISPLAY` environment variable.  You can instead specify which display to use (useful for distant screenshots via SSH) using the :keyword:`display` keyword::
 
     with mss(display=":0.0") as sct:
-        # ...
+        ...
 
 A more specific example (only valid on GNU/Linux):
 
 .. literalinclude:: examples/linux_display_keyword.py
     :lines: 9-
 
+Backends
+^^^^^^^^
+
+The GNU/Linux implementation has multiple backends (see :ref:`backends`), or ways it can take screenshots.  The :py:func:`mss.mss` and :py:func:`mss.linux.mss` functions will normally autodetect which one is appropriate, but you can override this if you want.
+
+There are three available backends.
+
+:py:mod:`xlib` (default)
+    The legacy backend, based on :c:func:`XGetImage`.  This backend is not being improved anymore.  It is only provided in case the newer backends don't work for some reason.
+
+:py:mod:`xgetimage`
+    A highly-compatible, but slow, backend, based on :c:func:`xcb_get_image`.  This backend is the slowest of the new backends, but works in all situations.  You can use this if you know that :py:mod:`xshmgetimage` won't work.
+
+:py:mod:`xshmgetimage`
+    The fastest backend, based on :c:func:`xcb_shm_get_image`.  This backend is the fastest, about three times faster than :py:mod:`xgetimage`.  However, it doesn't work for remote screenshots, such as over SSH.  If you use it with a remote display, then it will automatically switch to :py:mod:`xgetimage` instead.  It's always safe to use this backend.
+
 
 Command Line
 ============

pyproject.toml

@@ -179,6 +179,7 @@ ignore = [
 "docs/source/*" = [
   "ERA001",   # commented code
   "INP001",   # file `xxx` is part of an implicit namespace package
+  "N811",     # importing constant (MSS) as non-constant (mss)
 ]
 "src/tests/*" = [
   "FBT001",   # boolean-typed positional argument in function definition
@@ -191,4 +192,4 @@ ignore = [
 ]
 
 [tool.ruff.per-file-target-version]
-"src/xcbproto/*" = "py312"
+"src/xcbproto/*" = "py312"

src/mss/base.py

@@ -18,6 +18,15 @@
 
     from mss.models import Monitor, Monitors
 
+    # Prior to 3.11, Python didn't have the Self type.  typing_extensions does, but we don't want to depend on it.
+    try:
+        from typing import Self
+    except ImportError:  # pragma: nocover
+        try:
+            from typing_extensions import Self
+        except ImportError:  # pragma: nocover
+            Self = Any  # type: ignore[assignment]
+
 try:
     from datetime import UTC
 except ImportError:  # pragma: nocover
@@ -58,7 +67,7 @@ def __init__(
             msg = 'The only valid backend on this platform is "default".'
             raise ScreenShotError(msg)
 
-    def __enter__(self) -> MSSBase:  # noqa:PYI034
+    def __enter__(self) -> Self:
         """For the cool call `with MSS() as mss:`."""
         return self
 

src/mss/factory.py

@@ -29,7 +29,8 @@ def mss(**kwargs: Any) -> MSSBase:
     if os_ == "linux":
         from mss import linux  # noqa: PLC0415
 
-        return linux.MSS(**kwargs)
+        # Linux has its own factory to choose the backend.
+        return linux.mss(**kwargs)
 
     if os_ == "windows":
         from mss import windows  # noqa: PLC0415