Mark KMOD_ names as deprecated

Author: HexDecimal

CHANGELOG.md

@@ -6,6 +6,10 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ## [Unreleased]
 
+### Deprecated
+
+- Keyboard bitmask modifiers `tcod.event.KMOD_*` have been replaced by `tcod.event.Modifier`.
+
 ## [16.2.3] - 2024-07-16
 
 ### Fixed

examples/samples_tcod.py

@@ -27,6 +27,7 @@
 import tcod.sdl.mouse
 import tcod.sdl.render
 from tcod import libtcodpy
+from tcod.sdl.video import WindowFlags
 
 # ruff: noqa: S311
 
@@ -82,11 +83,13 @@ def ev_keydown(self, event: tcod.event.KeyDown) -> None:
             cur_sample = (cur_sample - 1) % len(SAMPLES)
             SAMPLES[cur_sample].on_enter()
             draw_samples_menu()
-        elif event.sym == tcod.event.KeySym.RETURN and event.mod & tcod.event.KMOD_LALT:
-            libtcodpy.console_set_fullscreen(not libtcodpy.console_is_fullscreen())
-        elif event.sym == tcod.event.KeySym.PRINTSCREEN or event.sym == tcod.event.KeySym.p:
+        elif event.sym == tcod.event.KeySym.RETURN and event.mod & tcod.event.Modifier.ALT:
+            sdl_window = context.sdl_window
+            if sdl_window:
+                sdl_window.fullscreen = False if sdl_window.fullscreen else WindowFlags.FULLSCREEN_DESKTOP
+        elif event.sym in (tcod.event.KeySym.PRINTSCREEN, tcod.event.KeySym.p):
             print("screenshot")
-            if event.mod & tcod.event.KMOD_LALT:
+            if event.mod & tcod.event.Modifier.ALT:
                 libtcodpy.console_save_apf(root_console, "samples.apf")
                 print("apf")
             else:

tcod/event.py

@@ -95,7 +95,6 @@
 import tcod.sdl.sys
 from tcod.cffi import ffi, lib
 from tcod.event_constants import *  # noqa: F403
-from tcod.event_constants import KMOD_ALT, KMOD_CTRL, KMOD_GUI, KMOD_SHIFT
 from tcod.sdl.joystick import _HAT_DIRECTIONS
 
 T = TypeVar("T")
@@ -2807,6 +2806,14 @@ def __getattr__(name: str) -> int:
             FutureWarning,
             stacklevel=2,
         )
+    elif name.startswith("KMOD_"):
+        modifier = name[5:]
+        warnings.warn(
+            "Key modifiers have been replaced with the Modifier IntFlag.\n"
+            f"`tcod.event.{modifier}` should be replaced with `tcod.event.Modifier.{modifier}`",
+            FutureWarning,
+            stacklevel=2,
+        )
     return value
 
 
@@ -2859,23 +2866,6 @@ def __getattr__(name: str) -> int:
     "Scancode",
     "KeySym",
     # --- From event_constants.py ---
-    "KMOD_NONE",
-    "KMOD_LSHIFT",
-    "KMOD_RSHIFT",
-    "KMOD_SHIFT",
-    "KMOD_LCTRL",
-    "KMOD_RCTRL",
-    "KMOD_CTRL",
-    "KMOD_LALT",
-    "KMOD_RALT",
-    "KMOD_ALT",
-    "KMOD_LGUI",
-    "KMOD_RGUI",
-    "KMOD_GUI",
-    "KMOD_NUM",
-    "KMOD_CAPS",
-    "KMOD_MODE",
-    "KMOD_RESERVED",
     "MOUSEWHEEL_NORMAL",
     "MOUSEWHEEL_FLIPPED",
     "MOUSEWHEEL",

tcod/event_constants.py

@@ -540,23 +540,6 @@
 }
 
 __all__ = [
-    "KMOD_NONE",
-    "KMOD_LSHIFT",
-    "KMOD_RSHIFT",
-    "KMOD_SHIFT",
-    "KMOD_LCTRL",
-    "KMOD_RCTRL",
-    "KMOD_CTRL",
-    "KMOD_LALT",
-    "KMOD_RALT",
-    "KMOD_ALT",
-    "KMOD_LGUI",
-    "KMOD_RGUI",
-    "KMOD_GUI",
-    "KMOD_NUM",
-    "KMOD_CAPS",
-    "KMOD_MODE",
-    "KMOD_SCROLL",
     "MOUSEWHEEL_NORMAL",
     "MOUSEWHEEL_FLIPPED",
     "MOUSEWHEEL",

tests/test_deprecated.py

@@ -51,6 +51,13 @@ def test_deprecate_mouse_constants() -> None:
         _ = tcod.event.BUTTON_LMASK
 
 
+def test_deprecate_kmod_constants() -> None:
+    with pytest.warns(FutureWarning, match=r"Modifier.LSHIFT"):
+        _ = tcod.event.KMOD_LSHIFT
+    with pytest.warns(FutureWarning, match=r"Modifier.GUI"):
+        _ = tcod.event.KMOD_GUI
+
+
 def test_line_where() -> None:
     with pytest.warns():
         where = tcod.libtcodpy.line_where(1, 0, 3, 4)