refactor!: the whole source code was migrated to PEP 570 (Python Positional-Only Parameters)

Dropped Python 3.7 support at the same time.

Author: BoboTiG

.github/workflows/tests.yml

@@ -56,8 +56,6 @@ jobs:
           - emoji: 🪟
             runs-on: [windows-latest]
         python:
-          - name: CPython 3.7
-            runs-on: "3.7"
           - name: CPython 3.8
             runs-on: "3.8"
           - name: CPython 3.9

CHANGELOG

@@ -3,6 +3,8 @@ History:
 <see Git checking messages for history>
 
 8.0.0   2023/0x/xx
+      - the whole source code was migrated to PEP 570 (Python Positional-Only Parameters)
+      - removed support for Python 3.7
       - Linux: added mouse support (#232)
       - Linux: refactored how internal handles are stored to fix issues with multiple X servers, and TKinter.
                No more side effects, and when leaving the context manager, resources are all freed (#224, #234)

README.rst

@@ -22,7 +22,7 @@ Python MSS
 
 An ultra fast cross-platform multiple screenshots module in pure python using ctypes.
 
-- **Python 3.7+** and PEP8 compliant, no dependency, thread-safe;
+- **Python 3.8+** and PEP8 compliant, no dependency, thread-safe;
 - very basic, it will grab one screen shot by monitor or a screen shot of all monitors and save it to a PNG file;
 - but you can use PIL and benefit from all its formats (or add yours directly);
 - integrate well with Numpy and OpenCV;

docs/source/index.rst

@@ -12,7 +12,7 @@ Welcome to Python MSS's documentation!
 
 An ultra fast cross-platform multiple screenshots module in pure python using ctypes.
 
-    - **Python 3.7+** and :pep:`8` compliant, no dependency, thread-safe;
+    - **Python 3.8+** and :pep:`8` compliant, no dependency, thread-safe;
     - very basic, it will grab one screen shot by monitor or a screen shot of all monitors and save it to a PNG file;
     - but you can use PIL and benefit from all its formats (or add yours directly);
     - integrate well with Numpy and OpenCV;

docs/source/support.rst

@@ -5,7 +5,7 @@ Support
 Feel free to try MSS on a system we had not tested, and let us know by creating an `issue <https://github.com/BoboTiG/python-mss/issues>`_.
 
     - OS: GNU/Linux, macOS and Windows
-    - Python: 3.7 and newer
+    - Python: 3.8 and newer
 
 
 Future
@@ -32,4 +32,5 @@ Abandoned
 - Python 3.3 (2017-12-05)
 - Python 3.4 (2018-03-19)
 - Python 3.5 (2022-10-27)
-- Python 3.6 (202x-xx-xx)
+- Python 3.6 (2022-10-27)
+- Python 3.7 (2023-xx-xx)

mss/__main__.py

@@ -4,15 +4,15 @@
 """
 import os.path
 from argparse import ArgumentParser
-from typing import List, Optional
+from typing import List
 
 from . import __version__
 from .exception import ScreenShotError
 from .factory import mss
 from .tools import to_png
 
 
-def main(args: Optional[List[str]] = None) -> int:
+def main(args: List[str], /) -> int:
     """Main logic."""
 
     cli_args = ArgumentParser()

mss/base.py

@@ -22,6 +22,8 @@ class MSSBase(metaclass=ABCMeta):
 
     def __init__(
         self,
+        /,
+        *,
         compression_level: int = 6,
         display: Optional[Union[bytes, str]] = None,  # Linux only
         max_displays: int = 32,  # Mac only
@@ -48,7 +50,7 @@ def _cursor_impl(self) -> Optional[ScreenShot]:
         """Retrieve all cursor data. Pixels have to be RGB."""
 
     @abstractmethod
-    def _grab_impl(self, monitor: Monitor) -> ScreenShot:
+    def _grab_impl(self, monitor: Monitor, /) -> ScreenShot:
         """
         Retrieve all pixels from a monitor. Pixels have to be RGB.
         That method has to be run using a threading lock.
@@ -64,7 +66,7 @@ def _monitors_impl(self) -> None:
     def close(self) -> None:
         """Clean-up."""
 
-    def grab(self, monitor: Union[Monitor, Tuple[int, int, int, int]]) -> ScreenShot:
+    def grab(self, monitor: Union[Monitor, Tuple[int, int, int, int]], /) -> ScreenShot:
         """
         Retrieve screen pixels for a given monitor.
 
@@ -120,6 +122,8 @@ def monitors(self) -> Monitors:
 
     def save(
         self,
+        /,
+        *,
         mon: int = 0,
         output: str = "monitor-{mon}.png",
         callback: Optional[Callable[[str], None]] = None,
@@ -170,9 +174,8 @@ def save(
             mon = 0 if mon == -1 else mon
             try:
                 monitor = monitors[mon]
-            except IndexError:
-                # pylint: disable=raise-missing-from
-                raise ScreenShotError(f"Monitor {mon!r} does not exist.")
+            except IndexError as exc:
+                raise ScreenShotError(f"Monitor {mon!r} does not exist.") from exc
 
             output = output.format(mon=mon, date=datetime.now(), **monitor)
             if callable(callback):
@@ -181,7 +184,7 @@ def save(
             to_png(sct.rgb, sct.size, level=self.compression_level, output=output)
             yield output
 
-    def shot(self, **kwargs: Any) -> str:
+    def shot(self, /, **kwargs: Any) -> str:
         """
         Helper to save the screen shot of the 1st monitor, by default.
         You can pass the same arguments as for ``save``.
@@ -191,7 +194,7 @@ def shot(self, **kwargs: Any) -> str:
         return next(self.save(**kwargs))
 
     @staticmethod
-    def _merge(screenshot: ScreenShot, cursor: ScreenShot) -> ScreenShot:
+    def _merge(screenshot: ScreenShot, cursor: ScreenShot, /) -> ScreenShot:
         """Create composite image by blending screenshot and mouse cursor."""
 
         # pylint: disable=too-many-locals,invalid-name
@@ -244,6 +247,7 @@ def _cfactory(
         func: str,
         argtypes: List[Any],
         restype: Any,
+        /,
         errcheck: Optional[Callable] = None,
     ) -> None:
         """Factory to create a ctypes function and automatically manage errors."""

mss/darwin.py

@@ -66,23 +66,15 @@ def __repr__(self) -> str:
     "CFDataGetLength": ("core", [c_void_p], c_uint64),
     "CFRelease": ("core", [c_void_p], c_void_p),
     "CGDataProviderRelease": ("core", [c_void_p], c_void_p),
-    "CGGetActiveDisplayList": (
-        "core",
-        [c_uint32, POINTER(c_uint32), POINTER(c_uint32)],
-        c_int32,
-    ),
+    "CGGetActiveDisplayList": ("core", [c_uint32, POINTER(c_uint32), POINTER(c_uint32)], c_int32),
     "CGImageGetBitsPerPixel": ("core", [c_void_p], int),
     "CGImageGetBytesPerRow": ("core", [c_void_p], int),
     "CGImageGetDataProvider": ("core", [c_void_p], c_void_p),
     "CGImageGetHeight": ("core", [c_void_p], int),
     "CGImageGetWidth": ("core", [c_void_p], int),
     "CGRectStandardize": ("core", [CGRect], CGRect),
     "CGRectUnion": ("core", [CGRect, CGRect], CGRect),
-    "CGWindowListCreateImage": (
-        "core",
-        [CGRect, c_uint32, c_uint32, c_uint32],
-        c_void_p,
-    ),
+    "CGWindowListCreateImage": ("core", [CGRect, c_uint32, c_uint32, c_uint32], c_void_p),
 }
 
 
@@ -94,7 +86,7 @@ class MSS(MSSBase):
 
     __slots__ = {"core", "max_displays"}
 
-    def __init__(self, **kwargs: Any) -> None:
+    def __init__(self, /, **kwargs: Any) -> None:
         """macOS initialisations."""
 
         super().__init__(**kwargs)
@@ -124,12 +116,7 @@ def _set_cfunctions(self) -> None:
         cfactory = self._cfactory
         attrs = {"core": self.core}
         for func, (attr, argtypes, restype) in CFUNCTIONS.items():
-            cfactory(
-                attr=attrs[attr],
-                func=func,
-                argtypes=argtypes,
-                restype=restype,
-            )
+            cfactory(attrs[attr], func, argtypes, restype)
 
     def _monitors_impl(self) -> None:
         """Get positions of monitors. It will populate self._monitors."""
@@ -176,7 +163,7 @@ def _monitors_impl(self) -> None:
             "height": int_(all_monitors.size.height),
         }
 
-    def _grab_impl(self, monitor: Monitor) -> ScreenShot:
+    def _grab_impl(self, monitor: Monitor, /) -> ScreenShot:
         """Retrieve all pixels from a monitor. Pixels have to be RGB."""
 
         # pylint: disable=too-many-locals

mss/exception.py

@@ -8,6 +8,6 @@
 class ScreenShotError(Exception):
     """Error handling class."""
 
-    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None) -> None:
+    def __init__(self, message: str, /, *, details: Optional[Dict[str, Any]] = None) -> None:
         super().__init__(message)
         self.details = details or {}

mss/linux.py

@@ -210,7 +210,7 @@ def _error_handler(display: Display, event: Event) -> int:
     return 0
 
 
-def _validate(retval: int, func: Any, args: Tuple[Any, Any]) -> Tuple[Any, Any]:
+def _validate(retval: int, func: Any, args: Tuple[Any, Any], /) -> Tuple[Any, Any]:
     """Validate the returned value of a Xlib or XRANDR function."""
 
     thread = current_thread()
@@ -237,52 +237,17 @@ def _validate(retval: int, func: Any, args: Tuple[Any, Any]) -> Tuple[Any, Any]:
     "XFixesGetCursorImage": ("xfixes", [POINTER(Display)], POINTER(XFixesCursorImage)),
     "XGetImage": (
         "xlib",
-        [
-            POINTER(Display),
-            POINTER(Display),
-            c_int,
-            c_int,
-            c_uint,
-            c_uint,
-            c_ulong,
-            c_int,
-        ],
+        [POINTER(Display), POINTER(Display), c_int, c_int, c_uint, c_uint, c_ulong, c_int],
         POINTER(XImage),
     ),
-    "XGetWindowAttributes": (
-        "xlib",
-        [POINTER(Display), POINTER(XWindowAttributes), POINTER(XWindowAttributes)],
-        c_int,
-    ),
+    "XGetWindowAttributes": ("xlib", [POINTER(Display), POINTER(XWindowAttributes), POINTER(XWindowAttributes)], c_int),
     "XOpenDisplay": ("xlib", [c_char_p], POINTER(Display)),
-    "XQueryExtension": (
-        "xlib",
-        [
-            POINTER(Display),
-            c_char_p,
-            POINTER(c_int),
-            POINTER(c_int),
-            POINTER(c_int),
-        ],
-        c_uint,
-    ),
+    "XQueryExtension": ("xlib", [POINTER(Display), c_char_p, POINTER(c_int), POINTER(c_int), POINTER(c_int)], c_uint),
     "XRRFreeCrtcInfo": ("xrandr", [POINTER(XRRCrtcInfo)], c_void_p),
     "XRRFreeScreenResources": ("xrandr", [POINTER(XRRScreenResources)], c_void_p),
-    "XRRGetCrtcInfo": (
-        "xrandr",
-        [POINTER(Display), POINTER(XRRScreenResources), c_long],
-        POINTER(XRRCrtcInfo),
-    ),
-    "XRRGetScreenResources": (
-        "xrandr",
-        [POINTER(Display), POINTER(Display)],
-        POINTER(XRRScreenResources),
-    ),
-    "XRRGetScreenResourcesCurrent": (
-        "xrandr",
-        [POINTER(Display), POINTER(Display)],
-        POINTER(XRRScreenResources),
-    ),
+    "XRRGetCrtcInfo": ("xrandr", [POINTER(Display), POINTER(XRRScreenResources), c_long], POINTER(XRRCrtcInfo)),
+    "XRRGetScreenResources": ("xrandr", [POINTER(Display), POINTER(Display)], POINTER(XRRScreenResources)),
+    "XRRGetScreenResourcesCurrent": ("xrandr", [POINTER(Display), POINTER(Display)], POINTER(XRRScreenResources)),
     "XSetErrorHandler": ("xlib", [c_void_p], c_int),
 }
 
@@ -295,7 +260,7 @@ class MSS(MSSBase):
 
     __slots__ = {"xfixes", "xlib", "xrandr", "_handles"}
 
-    def __init__(self, **kwargs: Any) -> None:
+    def __init__(self, /, **kwargs: Any) -> None:
         """GNU/Linux initialisations."""
 
         super().__init__(**kwargs)
@@ -355,7 +320,7 @@ def close(self) -> None:
 
         _ERROR.clear()
 
-    def _is_extension_enabled(self, name: str) -> bool:
+    def _is_extension_enabled(self, name: str, /) -> bool:
         """Return True if the given *extension* is enabled on the server."""
         with lock:
             major_opcode_return = c_int()
@@ -385,13 +350,7 @@ def _set_cfunctions(self) -> None:
         }
         for func, (attr, argtypes, restype) in CFUNCTIONS.items():
             with suppress(AttributeError):
-                cfactory(
-                    attr=attrs[attr],
-                    errcheck=_validate,
-                    func=func,
-                    argtypes=argtypes,
-                    restype=restype,
-                )
+                cfactory(attrs[attr], func, argtypes, restype, errcheck=_validate)
 
     def _monitors_impl(self) -> None:
         """Get positions of monitors. It will populate self._monitors."""
@@ -435,7 +394,7 @@ def _monitors_impl(self) -> None:
             xrandr.XRRFreeCrtcInfo(crtc)
         xrandr.XRRFreeScreenResources(mon)
 
-    def _grab_impl(self, monitor: Monitor) -> ScreenShot:
+    def _grab_impl(self, monitor: Monitor, /) -> ScreenShot:
         """Retrieve all pixels from a monitor. Pixels have to be RGB."""
 
         ximage = self.xlib.XGetImage(