Merge branch 'main' into release-notes

Author: jholveck

CHANGELOG.md

@@ -4,6 +4,7 @@ See Git commit messages for full history.
 
 ## v10.2.0.dev0
 (2026-xx-xx)
+- Introduce a new API, mss.MSS, that we can keep stable as we continue to improve MSS.  The previous documented API is deprecated, but still available, in 10.2.  Some parts of the existing API (such as certain type names and internal variables) may be removed in 11.0, but the most important parts will remain available for as long as can be reasonably supported. (#486, #494)
 - Add Versioning chapter to docs (#496)
 - Add `is_primary`, `name`, and `unique_id` keys to Monitor dicts for primary monitor detection, device names, and stable per-monitor identification (#153)
 - Add `primary_monitor` property to MSS base class for easy access to the primary monitor (#153)

CHANGES.md

@@ -3,6 +3,7 @@
 ## 10.2.0 (2026-xx-xx)
 
 ### base.py
+- (This affected almost every file in some respect, but base.py was the most affected.)  Introduced a new API, mss.MSS.  This class can be used instead of the previous various MSSBase subclasses, so that the user can work with a consistent class regardless of implementation details.  The methods implemented by MSSBase subclasses were renamed, and moved to MSSImplementation subclasses.  The mss.MSS class now holds an MSSImplementation instance as an instance variable. (#486, #494)
 - Added `primary_monitor` property to return the primary monitor (or first monitor as fallback).
 
 ### models.py

README.md

@@ -11,10 +11,10 @@
 > [![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/mschoentgen)
 
 ```python
-from mss import mss
+from mss import MSS
 
 # The simplest use, save a screenshot of the 1st monitor
-with mss() as sct:
+with MSS() as sct:
     sct.shot()
 ```
 

demos/cat-detector.py

@@ -240,7 +240,7 @@ def main() -> None:
     model_labels = weights.meta["categories"]
     cat_label = model_labels.index("cat")
 
-    with mss.mss() as sct:
+    with mss.MSS() as sct:
         monitor = sct.monitors[1]
 
         # Compute the minimum size, in square pixels, that we'll consider reliable.

demos/tinytv-stream-simple.py

@@ -79,7 +79,7 @@ def main() -> None:
         # Note that we use the same MSS object the whole time.  We don't try to keep creating a new MSS object each
         # time we take a new screenshot.  That's because the MSS object has a lot of stuff that it sets up and
         # remembers, and creating a new MSS object each time would mean that it has to repeat that setup constantly.
-        with mss.mss() as sct:
+        with mss.MSS() as sct:
             # It's time to get the monitor that we're going to capture.  In this demo, we just capture the first
             # monitor.  (We could also use monitors[0] for all the monitors combined.)
             monitor = sct.monitors[1]

demos/tinytv-stream.py

@@ -342,7 +342,7 @@ def capture_image(
         'width', 'height'.
     :yields: PIL Image objects from the captured monitor.
     """
-    with mss.mss() as sct:
+    with mss.MSS() as sct:
         rect = capture_area if capture_area is not None else sct.monitors[monitor]
         LOGGER.debug("Capture area: %i,%i, %ix%i", rect["left"], rect["top"], rect["width"], rect["height"])
 

demos/video-capture-simple.py

@@ -68,7 +68,7 @@ def main() -> None:
     # If we don't enable PyAV's own logging, a lot of important error messages from libav won't be shown.
     av.logging.set_level(av.logging.VERBOSE)
 
-    with mss.mss() as sct:
+    with mss.MSS() as sct:
         monitor = sct.monitors[1]
 
         # Because of how H.264 video stores color information, libx264 requires the video size to be a multiple of

demos/video-capture.py

@@ -164,7 +164,7 @@
 
 def video_capture(
     fps: int,
-    sct: mss.base.MSSBase,
+    sct: mss.MSS,
     monitor: mss.models.Monitor,
     shutdown_requested: Event,
 ) -> Generator[tuple[mss.screenshot.ScreenShot, float], None, None]:
@@ -434,7 +434,7 @@ def main() -> None:
     duration_secs = args.duration_secs
     region_crop_to_multiple_of_two = args.region_crop_to_multiple_of_two
 
-    with mss.mss() as sct:
+    with mss.MSS() as sct:
         if args.region:
             left, top, right, bottom = args.region
             monitor = {

docs/source/api.rst

@@ -7,67 +7,7 @@ Core Package
 
 .. automodule:: mss
 
-Screenshot Objects
-==================
-
-.. automodule:: mss.screenshot
-
-Base Classes
-============
-
-.. automodule:: mss.base
-
-Tools
-=====
-
-.. automodule:: mss.tools
-
-Exceptions
-==========
-
-.. automodule:: mss.exception
-
 Data Models
 ===========
 
 .. automodule:: mss.models
-
-Platform Backends
-=================
-
-macOS Backend
--------------
-
-.. automodule:: mss.darwin
-
-GNU/Linux Dispatcher
---------------------
-
-.. automodule:: mss.linux
-
-GNU/Linux Xlib Backend
-----------------------
-
-.. automodule:: mss.linux.xlib
-
-GNU/Linux XCB Base
-------------------
-
-.. automodule:: mss.linux.base
-
-GNU/Linux XCB XGetImage Backend
--------------------------------
-
-.. automodule:: mss.linux.xgetimage
-
-GNU/Linux XCB XShmGetImage Backend
-----------------------------------
-
-.. automodule:: mss.linux.xshmgetimage
-
-Windows Backend
----------------
-
-.. automodule:: mss.windows
-
-

docs/source/conf.py

@@ -9,11 +9,12 @@
 import ctypes
 
 # Monkey-patch PROT_READ into mmap if missing (Windows), so that we can
-# import mss.linux.xshmgetimage while building the documentation.
+# import the Linux shared-memory backend implementation while building the
+# documentation.
 import mmap
 
 if not hasattr(mmap, "PROT_READ"):
-    mmap.PROT_READ = 1  # type:ignore[attr-defined]
+    mmap.PROT_READ = 1
 
 import mss