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`.

Author: jholveck

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
 

docs/source/examples.rst

@@ -83,7 +83,7 @@ Get PNG bytes, no file output
 You can get the bytes of the PNG image:
 ::
 
-    with mss.mss() as sct:
+    with mss.MSS() as sct:
         # The monitor or screen part to capture
         monitor = sct.monitors[1]  # or a region
 
@@ -203,7 +203,7 @@ Different possibilities to convert raw BGRA values to RGB::
         return Image.frombytes('RGB', im.size, im.bgra, 'raw', 'BGRX').tobytes()
 
 
-    with mss.mss() as sct:
+    with mss.MSS() as sct:
         im = sct.grab(sct.monitors[1])
         rgb = pil_frombytes(im)
         ...

docs/source/examples/callback.py

@@ -18,6 +18,6 @@ def on_exists(fname: str) -> None:
         file.rename(newfile)
 
 
-with mss.mss() as sct:
+with mss.MSS() as sct:
     filename = sct.shot(output="mon-{mon}.png", callback=on_exists)
     print(filename)