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.

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}. This will be an error in the future.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
         self._impl: MSSImplementation = _choose_impl(
             backend=backend,
             **kwargs,

src/tests/conftest.py

@@ -7,6 +7,7 @@
 from hashlib import sha256
 from pathlib import Path
 from platform import system
+from typing import Any
 from zipfile import ZipFile
 
 import pytest
@@ -78,7 +79,14 @@ def backend(request: pytest.FixtureRequest) -> str:
 def mss_impl(backend: str) -> Callable[..., MSS]:
     # We can't just use partial here, since it will read $DISPLAY at the wrong time.  This can cause problems,
     # depending on just how the fixtures get run.
-    return lambda *args, **kwargs: MSS(*args, display=os.getenv("DISPLAY"), backend=backend, **kwargs)
+    def impl(*args: Any, **kwargs: Any) -> MSS:
+        # I'm not really sure if adding an explicit display is needed anymore.  It was in a lot of existing code that
+        # mss_impl replaced, but it should now be the default at this point.  I'll have to investigate.
+        if system() == "Linux":
+            kwargs = {"display": os.getenv("DISPLAY")} | kwargs
+        return MSS(*args, backend=backend, **kwargs)
+
+    return impl
 
 
 @pytest.fixture(autouse=True, scope="session")

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", "is only used on"}
 
-    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("is only used on" 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)