feat: move to a strategy implementation design. (#494)

* Move to a strategy implementation design.

See also BoboTiG/python-mss issue #486.

The user will always work with a single class: mss.MSS.  Differences
in implementation, such as platform or capture strategy, are hidden in
an internal implementation object held by the mss.MSS object.

This allows us to change the implementation, with arbitrary class
hierarchies, without worrying about preserving compatibility with
internal class names.

This deprecates the existing `mss` factory function, although it can
easily be kept for as long as needed to give users time to adapt.

It also deprecates the existing `mss.{platform}.MSS` types.  These are
exposed to the user, so somebody calling `mss.{platform}.MSS()` in
10.x can still reasonably expect to get a `mss.{platform}.MSS` object
back.  However, in 11.0, we can remove the type entirely, and either
remove those symbols, or make them deprecated aliases for `mss.MSS`.

Where possible, deprecated functionality emits a `DeprecationWarning`.
However, note that these are ignored by default, unless triggered by
code in `__main__`.

Many of the API docs are removed, since this change removes much of
the API surface.  However, they are still in available for
backwards-compatibility.

This change adds tests for everything that was in the 10.1 docs,
examples, etc, at least at a basic level: for instance, it tests that
`mss.linux.MSS` still works as both a constructor and a type (for
`isinstance`), and that `mss.linux.ZPIXMAP` still exists (it was
listed in the 10.1 docs).

The existing code, tests, and docs are changed to use `mss.MSS`.

* Add CHANGELOG / CHANGES entries

* Allow and test all kwargs on all platforms.

The mss_impl fixture would add an implicit display= argument,
regardless of platform.  The code at that time would ignore it, but we
should be (and in the previous commit, were) more strict.  Change
mss_impl to only use display= if appropriate, so we can be more strict
in the future.

In 10.1, these were allowed at all times, and ignored if the platform
didn't use them.  Emulate this behavior in mss.MSS (and mss.mss), with
DeprecationWarnings, and test.

* Don't explicitly pass display in one of the tests.

I'm pretty sure it's unnecessary there.  Not sure why it was being done.

* Comment fixes

* List the keyword args for mss.MSS explicitly, instead of using **kwargs.

This lets IDEs and code checkers know what is acceptable.  This lets
them autocomplete, and identify incorrect options in user code.

* Move the shm_fallback_reason to a more general performance_status property.

* Warn and ignore for --with-cursor in command line on non-Linux.

* Put the --with-cursor warning on stderr, not stdout

* Allow system-specific kwargs on multiple systems

Co-authored-by: Mickaël Schoentgen <contact@tiger-222.fr>

* Restore a TODO that was accidentally removed earlier

* Formatting fix

---------

Co-authored-by: Mickaël Schoentgen <contact@tiger-222.fr>

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