Allow and test all kwargs on all platforms.

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.

Author: jholveck

src/mss/base.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import platform
+import warnings
 from abc import ABC, abstractmethod
 from datetime import datetime
 from threading import Lock
@@ -173,6 +174,22 @@ def __init__(
         compression_level: int = 6,
         **kwargs: Any,
     ) -> None:
+        # TODO(jholveck): #493 Accept platform-specific kwargs on all platforms
+        # for migration ease.  Foreign kwargs are silently stripped with a warning.
+        platform_only: dict[str, str] = {
+            "display": "linux",
+            "max_displays": "darwin",
+        }
+        os_ = platform.system().lower()
+        for kwarg_name, target_platform in platform_only.items():
+            if kwarg_name in kwargs and os_ != target_platform:
+                kwargs.pop(kwarg_name)
+                warnings.warn(
+                    f"{kwarg_name} is only used on {target_platform} and ignored on other platforms. This will be an error in the future.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
         self._impl: MSSImplementation = _choose_impl(
             backend=backend,
             **kwargs,

src/tests/test_compat_10_1.py

@@ -144,21 +144,29 @@ def test_factory_and_platform_constructor_are_compatible_types() -> None:
 
 
 def test_deprecated_factory_accepts_documented_kwargs() -> None:
-    os_ = platform.system().lower()
-    kwargs: dict[str, object] = {"compression_level": 1, "with_cursor": True}
+    """Verify that kwargs are accepted, even if not relevant.
+
+    All 10.1-documented kwargs were accepted on every platform, even
+    if only meaningful on one.  Verify that still works via the
+    deprecated factory.
+    """
+    kwargs = {
+        "compression_level": 1,
+        "with_cursor": True,
+        "max_displays": 1,
+        "display": getenv("DISPLAY"),  # None on non-Linux
+    }
+
+    with pytest.warns(DeprecationWarning) as caught:  # noqa: PT030 (we test the contents below)
+        context = mss.mss(**kwargs)
 
-    if os_ == "linux":
-        display = getenv("DISPLAY")
-        assert display
-        kwargs["display"] = display
-    elif os_ == "darwin":
-        kwargs["max_displays"] = 1
-    elif os_ != "windows":
-        msg = f"Unsupported platform for compatibility test: {os_!r}"
-        raise AssertionError(msg)
+    expected_messages = {"mss.mss is deprecated", "ignored on this platform"}
 
-    with pytest.warns(DeprecationWarning, match=r"^mss\.mss is deprecated"):
-        context = mss.mss(**kwargs)
+    assert any("mss.mss is deprecated" in str(w.message) for w in caught)
+    assert any("ignored on this platform" in str(w.message) for w in caught)
+    assert all(any(expected in str(w.message) for expected in expected_messages) for w in caught), (
+        f"Unexpected warnings: {[str(w.message) for w in caught]}"
+    )
 
     with context as sct:
         assert isinstance(sct, MSSBase)