Clean up type errors, use standard deprecation functions

Fix minor typos

Improve deprecation docs

Set lower bound for typing_extensions

Author: HexDecimal

pyproject.toml

@@ -23,7 +23,7 @@ license = { text = "Simplified BSD License" }
 dependencies = [
     "cffi>=1.15",
     'numpy>=1.21.4; implementation_name != "pypy"',
-    "typing_extensions",
+    "typing_extensions>=4.12.2",
 ]
 keywords = [
     "roguelike",

tcod/_internal.py

@@ -2,17 +2,16 @@
 
 from __future__ import annotations
 
-import functools
 import locale
 import sys
 import warnings
 from pathlib import Path
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, AnyStr, Callable, NoReturn, SupportsInt, TypeVar, cast
+from typing import TYPE_CHECKING, Any, AnyStr, Callable, NoReturn, SupportsInt, TypeVar
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
-from typing_extensions import Literal
+from typing_extensions import Literal, LiteralString, deprecated
 
 from tcod.cffi import ffi, lib
 
@@ -24,31 +23,28 @@
 T = TypeVar("T")
 
 
-def deprecate(message: str, category: type[Warning] = DeprecationWarning, stacklevel: int = 0) -> Callable[[F], F]:
-    """Return a decorator which adds a warning to functions."""
+def _deprecate_passthrough(
+    message: str, /, *, category: type[Warning] = DeprecationWarning, stacklevel: int = 0
+) -> Callable[[F], F]:
+    """Return a decorator which skips wrapping a warning onto functions. This is used for non-debug runs."""
 
     def decorator(func: F) -> F:
-        if not __debug__:
-            return func
+        return func
 
-        @functools.wraps(func)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
-            warnings.warn(message, category, stacklevel=stacklevel + 2)
-            return func(*args, **kwargs)
+    return decorator
 
-        return cast(F, wrapper)
 
-    return decorator
+deprecate = deprecated if __debug__ or TYPE_CHECKING else _deprecate_passthrough
 
 
 def pending_deprecate(
-    message: str = "This function may be deprecated in the future."
+    message: LiteralString = "This function may be deprecated in the future."
     " Consider raising an issue on GitHub if you need this feature.",
     category: type[Warning] = PendingDeprecationWarning,
     stacklevel: int = 0,
 ) -> Callable[[F], F]:
     """Like deprecate, but the default parameters are filled out for a generic pending deprecation warning."""
-    return deprecate(message, category, stacklevel)
+    return deprecate(message, category=category, stacklevel=stacklevel)
 
 
 def verify_order(order: Literal["C", "F"]) -> Literal["C", "F"]:
@@ -119,7 +115,7 @@ def _unicode(string: AnyStr, stacklevel: int = 2) -> str:
             stacklevel=stacklevel + 1,
         )
         return string.decode("latin-1")
-    return string
+    return str(string)
 
 
 def _fmt(string: str, stacklevel: int = 2) -> bytes:

tcod/cffi.py

@@ -59,7 +59,7 @@ def get_sdl_version() -> str:
 
 
 verify_dependencies()
-from tcod._libtcod import ffi, lib  # noqa
+from tcod._libtcod import ffi, lib  # noqa: E402
 
 __sdl_version__ = get_sdl_version()
 

tcod/color.py

@@ -31,7 +31,7 @@ def r(self) -> int:
         return int(self[0])
 
     @r.setter
-    @deprecate("Setting color attributes has been deprecated.", FutureWarning)
+    @deprecate("Setting color attributes has been deprecated.", category=FutureWarning)
     def r(self, value: int) -> None:
         self[0] = value & 0xFF
 
@@ -45,7 +45,7 @@ def g(self) -> int:
         return int(self[1])
 
     @g.setter
-    @deprecate("Setting color attributes has been deprecated.", FutureWarning)
+    @deprecate("Setting color attributes has been deprecated.", category=FutureWarning)
     def g(self, value: int) -> None:
         self[1] = value & 0xFF
 
@@ -59,7 +59,7 @@ def b(self) -> int:
         return int(self[2])
 
     @b.setter
-    @deprecate("Setting color attributes has been deprecated.", FutureWarning)
+    @deprecate("Setting color attributes has been deprecated.", category=FutureWarning)
     def b(self, value: int) -> None:
         self[2] = value & 0xFF
 
@@ -82,7 +82,7 @@ def __getitem__(self, index: Any) -> Any:  # noqa: ANN401
             return super().__getitem__("rgb".index(index))
         return super().__getitem__(index)
 
-    @deprecate("This class will not be mutable in the future.", FutureWarning)
+    @deprecate("This class will not be mutable in the future.", category=FutureWarning)
     def __setitem__(self, index: Any, value: Any) -> None:  # noqa: ANN401, D105
         if isinstance(index, str):
             super().__setitem__("rgb".index(index), value)
@@ -99,7 +99,7 @@ def __eq__(self, other: object) -> bool:
         except TypeError:
             return False
 
-    @deprecate("Use NumPy instead for color math operations.", FutureWarning)
+    @deprecate("Use NumPy instead for color math operations.", category=FutureWarning)
     def __add__(self, other: object) -> Color:  # type: ignore[override]
         """Add two colors together.
 
@@ -108,7 +108,7 @@ def __add__(self, other: object) -> Color:  # type: ignore[override]
         """
         return Color._new_from_cdata(lib.TCOD_color_add(self, other))
 
-    @deprecate("Use NumPy instead for color math operations.", FutureWarning)
+    @deprecate("Use NumPy instead for color math operations.", category=FutureWarning)
     def __sub__(self, other: object) -> Color:
         """Subtract one color from another.
 
@@ -117,7 +117,7 @@ def __sub__(self, other: object) -> Color:
         """
         return Color._new_from_cdata(lib.TCOD_color_subtract(self, other))
 
-    @deprecate("Use NumPy instead for color math operations.", FutureWarning)
+    @deprecate("Use NumPy instead for color math operations.", category=FutureWarning)
     def __mul__(self, other: object) -> Color:
         """Multiply with a scaler or another color.
 

tcod/console.py

@@ -122,7 +122,7 @@ def __init__(
     ) -> None:
         """Initialize the console."""
         self._key_color: tuple[int, int, int] | None = None
-        self._order = tcod._internal.verify_order(order)
+        self._order: Literal["C", "F"] = tcod._internal.verify_order(order)
         if buffer is not None:
             if self._order == "F":
                 buffer = buffer.transpose()
@@ -345,53 +345,90 @@ def rgb(self) -> NDArray[Any]:
         """
         return self.rgba.view(self._DTYPE_RGB)
 
+    _DEPRECATE_CONSOLE_DEFAULTS_MSG = """Console defaults have been deprecated.
+Consider one of the following:
+
+    # Set parameters once then pass them as kwargs
+    DEFAULT_COLOR = {"bg": (0, 0, 127), "fg": (127, 127, 255)}
+    console.print(x, y, string, **DEFAULT_COLOR)
+
+    # Clear the console to a color and then skip setting colors on printing/drawing
+    console.clear(fg=(127, 127, 255), bg=(0, 0, 127))
+    console.print(x, y, string, fg=None)
+"""
+
     @property
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_bg(self) -> tuple[int, int, int]:
-        """Tuple[int, int, int]: The default background color."""
+        """Tuple[int, int, int]: The default background color.
+
+        .. deprecated:: 8.5
+            These should not be used. Prefer passing defaults as kwargs.
+
+            .. code-block::
+
+                DEFAULT_COLOR = {"bg": (0, 0, 127), "fg": (127, 127, 255)}
+                console.print(x, y, string, **DEFAULT_COLOR)
+        """
         color = self._console_data.back
         return color.r, color.g, color.b
 
     @default_bg.setter
-    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_bg(self, color: tuple[int, int, int]) -> None:
         self._console_data.back = color
 
     @property
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_fg(self) -> tuple[int, int, int]:
-        """Tuple[int, int, int]: The default foreground color."""
+        """Tuple[int, int, int]: The default foreground color.
+
+        .. deprecated:: 8.5
+            These should not be used. Prefer passing defaults as kwargs.
+        """
         color = self._console_data.fore
         return color.r, color.g, color.b
 
     @default_fg.setter
-    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_fg(self, color: tuple[int, int, int]) -> None:
         self._console_data.fore = color
 
     @property
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_bg_blend(self) -> int:
-        """int: The default blending mode."""
+        """int: The default blending mode.
+
+        .. deprecated:: 8.5
+            These should not be used. Prefer passing defaults as kwargs.
+        """
         return self._console_data.bkgnd_flag  # type: ignore
 
     @default_bg_blend.setter
-    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_bg_blend(self, value: int) -> None:
         self._console_data.bkgnd_flag = value
 
     @property
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_alignment(self) -> int:
-        """int: The default text alignment."""
+        """int: The default text alignment.
+
+        .. deprecated:: 8.5
+            These should not be used. Prefer passing defaults as kwargs.
+        """
         return self._console_data.alignment  # type: ignore
 
     @default_alignment.setter
-    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated(_DEPRECATE_CONSOLE_DEFAULTS_MSG, category=FutureWarning)
     def default_alignment(self, value: int) -> None:
         self._console_data.alignment = value
 
     def __clear_warning(self, name: str, value: tuple[int, int, int]) -> None:
         """Raise a warning for bad default values during calls to clear."""
         warnings.warn(
             f"Clearing with the console default values is deprecated.\nAdd {name}={value!r} to this call.",
-            DeprecationWarning,
+            FutureWarning,
             stacklevel=3,
         )
 
@@ -737,8 +774,8 @@ def print_frame(  # noqa: PLR0913
             explicit.
         """
         self.__deprecate_defaults("draw_frame", bg_blend)
-        string = _fmt(string) if string else ffi.NULL
-        _check(lib.TCOD_console_printf_frame(self.console_c, x, y, width, height, clear, bg_blend, string))
+        string_: Any = _fmt(string) if string else ffi.NULL
+        _check(lib.TCOD_console_printf_frame(self.console_c, x, y, width, height, clear, bg_blend, string_))
 
     def blit(  # noqa: PLR0913
         self,