linux: add an XCB-based backend (#426)

* Working implementation of XCB-based screenshots

This version works fine, but needs improvements, especially to the
testing.

What has happened:

* A ctypes-based module to use XCB has been added.
* The mss.linux.MSS constructor is now a factory, which takes an
  optional `backend` keyword parameter.
* The previous mss.linux implementation has now been designated as the
  "xlib" backend.  Per #425, this will have "legacy" status, and new
  functionality like XShmGetImage won't be implemented there.
* A new XCB-based backend, named "getimage", has been added.  This is
  functionally the same as the existing "xlib" backend, in almost all
  respects, but has a different implementation.
* The GNU/Linux-specific tests that could easily be made to work with
  the new backend have been adjusted.

Notable improvement: I previously was seeing periodic thread failures
in `test_thread_safety`.  In one scenario (Docker container, Python
3.9, Xvfb), I tested 84% failures in `test_thread_safety`.  With the
XCB-based backend, I saw no failures.  (See also #251 and the test
failure I mentioned in #421.)

The performance is, in my brief testing, the same as the existing xlib
implementation.  This PR is about making clearer code and improving
thread safety, to pave the way for future improvements.

What's left to do (some before merging, some possibly later):

* The way the libraries are initialized needs to be rethought; I'll
  want to talk with @BoboTiG about that.
* Many tests in `test_gnu_linux` used monkey-patches that are specific
  to the Xlib implementation.  I've arranged for those to only use
  the Xlib implementation; I need to add corresponding tests for the
  XCB implementation.
* The tests outside of `test_gnu_linux` need to test both backends, as
  well as the different backends we may add to other OSs.  I need to
  add the right Pytest code to parameterize these.
* This code introduces new automatic memory management aspects that
  need tests assigned to them.
* The bulk of the `xcb.py` code is just hand-translations of the [XCB
  protocol specification XML
  files](https://gitlab.freedesktop.org/xorg/proto/xcbproto).
  Hand-translation can be error-prone (see #418).  Since the XCB specs
  are in XML, then the bulk of this code can be auto-generated, like
  xcffib does.  This can be done manually as needed, before shipping
  the distribution, so end users won't have to do this.  (See #425 for
  a discussion of why we're not using xcffib.)
* Even if we don't auto-generate the code, some of the repetitive
  parts can still be hoisted into higher-order functional programming,
  to reduce the risk of making errors in copying.
* There are some parts that I worsened, to satisfy ruff.  I want to
  revisit those.
* The proof-of-concept code in `xcb.py:main` includes some additional
  functionality should be integrated into the MSS class, either in
  this PR or in separate branches.  We also should delete that code
  before merging.
  * Additional testing on the X11 visual, to make sure it's really in
    the format we expect.  (This is probably the only part we'll merge
    in with this PR.)
  * Support for capturing an individual window, without needing its
    location.
  * Identifying whether the alpha channel is meaningful or not.  (This
    is only relevant with individual-window capture; there aren't many
    screens that can turn transparent!)

Fixes: #425

* Improve test coverage

Some tests now take a "backend" parameter.  A fixture will iterate
that through the backends implemented for that OS.

Many tests called mss(display=os.getenv("DISPLAY")).  Rather than add
"backend" parameters to each of them, and maybe need to make other
changes in the future, these now take an "mss_impl" fixture.  This is
a callable that will return the appropriate MSS object.

One reason for this is so that we might add a pyvirtualdisplay or
similar mechanism to these functions, when it's available.  This may
enable some tests to run in conditions they might not otherwise.  It
also may help standardize some of the testing.

* Ruff cleanups

* Small bug fixes to get the tests back to doing meaningful testing

* XCB: Verify visual, and improve error messages

The MSS object, when it's created, will now ensure that the X11
visual's format is exactly what we think it is: 32bpp, as a 24-bit
BGRx or 32-bit BGRA image, in that order, with no extra scanline
padding, color indexing, etc.  This is true of all modern X servers in
real-world situations, but it's not guaranteed.  For instance,
VNC-based servers can be run in depth 16 with RGB565 formats.

The error messages for protocol-level errors (such as bad coordinates)
are only available if the xcb-util-errors library is installed.
(That's libxcb-errors.so.0, in the libxcb-errors0 package on
Debian/Ubuntu.)  This isn't widely installed, and is mostly useful to
developers, so it's optional.  The connection-level errors (like the
hint to check $DISPLAY) are available everywhere.

* Move the library globals to a smart container class

* Improve testing

Test the cases of missing libraries when using XCB.

Add fixtures to reset the XCB library loader after each testcase.

Add fixtures to check for Xlib errors after each testcase.

* Use generated code to interface with XCB instead of hand-written code

* Fix bug in multithreaded initialization guard

* Improve testing and comments

* Add src/xcbproto/README.md

* Fix distribution list to include README.md

Author: jholveck

CHANGELOG.md

@@ -5,6 +5,7 @@ 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)
 - :heart: contributors: @jholveck
 
 ## 10.1.0 (2025-08-16)

pyproject.toml

@@ -72,6 +72,7 @@ mss = "mss.__main__:main"
 [project.optional-dependencies]
 dev = [
   "build==1.3.0",
+  "lxml==6.0.2",
   "mypy==1.18.2",
   "ruff==0.14.5",
   "twine==6.2.0",
@@ -134,6 +135,7 @@ strict_equality = true
 
 [tool.pytest.ini_options]
 pythonpath = "src"
+markers = ["without_libraries"]
 addopts = """
   --showlocals
   --strict-markers
@@ -187,3 +189,6 @@ ignore = [
   "S607",     # `subprocess` call without explicit paths
   "SLF001",   # private member accessed
 ]
+
+[tool.ruff.per-file-target-version]
+"src/xcbproto/*" = "py312"

src/mss/base.py

@@ -40,6 +40,7 @@ def __init__(
         self,
         /,
         *,
+        backend: str = "default",
         compression_level: int = 6,
         with_cursor: bool = False,
         # Linux only
@@ -51,6 +52,11 @@ def __init__(
         self.compression_level = compression_level
         self.with_cursor = with_cursor
         self._monitors: Monitors = []
+        # If there isn't a factory that removed the "backend" argument, make sure that it was set to "default".
+        # Factories that do backend-specific dispatch should remove that argument.
+        if backend != "default":
+            msg = 'The only valid backend on this platform is "default".'
+            raise ScreenShotError(msg)
 
     def __enter__(self) -> MSSBase:  # noqa:PYI034
         """For the cool call `with MSS() as mss:`."""

src/mss/linux/__init__.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+from mss.base import MSSBase
+from mss.exception import ScreenShotError
+
+
+def mss(backend: str = "default", **kwargs: Any) -> MSSBase:
+    backend = backend.lower()
+    if backend in {"default", "xlib"}:
+        from . import xlib  # noqa: PLC0415
+
+        return xlib.MSS(**kwargs)
+    if backend == "xgetimage":
+        from . import xgetimage  # noqa: PLC0415
+
+        return xgetimage.MSS(**kwargs)
+    msg = f"Backend {backend!r} not (yet?) implemented."
+    raise ScreenShotError(msg)
+
+
+# Alias in upper-case for backward compatibility.  This is a supported name in the docs.
+def MSS(*args, **kwargs) -> MSSBase:  # type: ignore[no-untyped-def] # noqa: N802, ANN002, ANN003
+    return mss(*args, **kwargs)

src/mss/linux/xcb.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from ctypes import Structure, c_int, c_uint8, c_uint16, c_uint32
+
+from . import xcbgen
+
+# We import these just so they're re-exported to our users.
+# ruff: noqa: F401
+from .xcbgen import (
+    RANDR_MAJOR_VERSION,
+    RANDR_MINOR_VERSION,
+    RENDER_MAJOR_VERSION,
+    RENDER_MINOR_VERSION,
+    XFIXES_MAJOR_VERSION,
+    XFIXES_MINOR_VERSION,
+    Atom,
+    BackingStore,
+    Colormap,
+    Depth,
+    DepthIterator,
+    Drawable,
+    Format,
+    GetGeometryReply,
+    GetImageReply,
+    GetPropertyReply,
+    ImageFormat,
+    ImageOrder,
+    Keycode,
+    Pixmap,
+    RandrCrtc,
+    RandrGetCrtcInfoReply,
+    RandrGetScreenResourcesCurrentReply,
+    RandrGetScreenResourcesReply,
+    RandrMode,
+    RandrModeInfo,
+    RandrOutput,
+    RandrQueryVersionReply,
+    RandrSetConfig,
+    RenderDirectformat,
+    RenderPictdepth,
+    RenderPictdepthIterator,
+    RenderPictformat,
+    RenderPictforminfo,
+    RenderPictscreen,
+    RenderPictscreenIterator,
+    RenderPictType,
+    RenderPictvisual,
+    RenderQueryPictFormatsReply,
+    RenderQueryVersionReply,
+    RenderSubPixel,
+    Screen,
+    ScreenIterator,
+    Setup,
+    SetupIterator,
+    Timestamp,
+    VisualClass,
+    Visualid,
+    Visualtype,
+    Window,
+    XfixesGetCursorImageReply,
+    XfixesQueryVersionReply,
+    depth_visuals,
+    get_geometry,
+    get_image,
+    get_image_data,
+    get_property,
+    get_property_value,
+    no_operation,
+    randr_get_crtc_info,
+    randr_get_crtc_info_outputs,
+    randr_get_crtc_info_possible,
+    randr_get_screen_resources,
+    randr_get_screen_resources_crtcs,
+    randr_get_screen_resources_current,
+    randr_get_screen_resources_current_crtcs,
+    randr_get_screen_resources_current_modes,
+    randr_get_screen_resources_current_names,
+    randr_get_screen_resources_current_outputs,
+    randr_get_screen_resources_modes,
+    randr_get_screen_resources_names,
+    randr_get_screen_resources_outputs,
+    randr_query_version,
+    render_pictdepth_visuals,
+    render_pictscreen_depths,
+    render_query_pict_formats,
+    render_query_pict_formats_formats,
+    render_query_pict_formats_screens,
+    render_query_pict_formats_subpixels,
+    render_query_version,
+    screen_allowed_depths,
+    setup_pixmap_formats,
+    setup_roots,
+    setup_vendor,
+    xfixes_get_cursor_image,
+    xfixes_get_cursor_image_cursor_image,
+    xfixes_query_version,
+)
+
+# These are also here to re-export.
+from .xcbhelpers import LIB, Connection, XError
+
+XCB_CONN_ERROR = 1
+XCB_CONN_CLOSED_EXT_NOTSUPPORTED = 2
+XCB_CONN_CLOSED_MEM_INSUFFICIENT = 3
+XCB_CONN_CLOSED_REQ_LEN_EXCEED = 4
+XCB_CONN_CLOSED_PARSE_ERR = 5
+XCB_CONN_CLOSED_INVALID_SCREEN = 6
+XCB_CONN_CLOSED_FDPASSING_FAILED = 7
+
+# I don't know of error descriptions for the XCB connection errors being accessible through a library (a la strerror),
+# and the ones in xcb.h's comments aren't too great, so I wrote these.
+XCB_CONN_ERRMSG = {
+    XCB_CONN_ERROR: "connection lost or could not be established",
+    XCB_CONN_CLOSED_EXT_NOTSUPPORTED: "extension not supported",
+    XCB_CONN_CLOSED_MEM_INSUFFICIENT: "memory exhausted",
+    XCB_CONN_CLOSED_REQ_LEN_EXCEED: "request length longer than server accepts",
+    XCB_CONN_CLOSED_PARSE_ERR: "display is unset or invalid (check $DISPLAY)",
+    XCB_CONN_CLOSED_INVALID_SCREEN: "server does not have a screen matching the requested display",
+    XCB_CONN_CLOSED_FDPASSING_FAILED: "could not pass file descriptor",
+}
+
+
+def initialize() -> None:
+    LIB.initialize(callbacks=[xcbgen.initialize])
+
+
+def connect(display: str | bytes | None = None) -> tuple[Connection, int]:
+    if isinstance(display, str):
+        display = display.encode("utf-8")
+
+    initialize()
+    pref_screen_num = c_int()
+    conn_p = LIB.xcb.xcb_connect(display, pref_screen_num)
+
+    # We still get a connection object even if the connection fails.
+    conn_err = LIB.xcb.xcb_connection_has_error(conn_p)
+    if conn_err != 0:
+        # XCB won't free its connection structures until we disconnect, even in the event of an error.
+        LIB.xcb.xcb_disconnect(conn_p)
+        msg = "Cannot connect to display: "
+        conn_errmsg = XCB_CONN_ERRMSG.get(conn_err)
+        if conn_errmsg:
+            msg += conn_errmsg
+        else:
+            msg += f"error code {conn_err}"
+        raise XError(msg)
+
+    return conn_p.contents, pref_screen_num.value
+
+
+def disconnect(conn: Connection) -> None:
+    conn_err = LIB.xcb.xcb_connection_has_error(conn)
+    # XCB won't free its connection structures until we disconnect, even in the event of an error.
+    LIB.xcb.xcb_disconnect(conn)
+    if conn_err != 0:
+        msg = "Connection to X server closed: "
+        conn_errmsg = XCB_CONN_ERRMSG.get(conn_err)
+        if conn_errmsg:
+            msg += conn_errmsg
+        else:
+            msg += f"error code {conn_err}"
+        raise XError(msg)