Update deprecations to a more standard syntax

Author: HexDecimal

tcod/bsp.py

@@ -29,8 +29,9 @@
 
 from typing import Any, Iterator
 
+from typing_extensions import deprecated
+
 import tcod.random
-from tcod._internal import deprecate
 from tcod.cffi import ffi, lib
 
 
@@ -72,7 +73,7 @@ def __init__(self, x: int, y: int, width: int, height: int) -> None:
         self.children: tuple[()] | tuple[BSP, BSP] = ()
 
     @property
-    @deprecate("This attribute has been renamed to `width`.", FutureWarning)
+    @deprecated("This attribute has been renamed to `width`.", category=FutureWarning)
     def w(self) -> int:  # noqa: D102
         return self.width
 
@@ -81,7 +82,7 @@ def w(self, value: int) -> None:
         self.width = value
 
     @property
-    @deprecate("This attribute has been renamed to `height`.", FutureWarning)
+    @deprecated("This attribute has been renamed to `height`.", category=FutureWarning)
     def h(self) -> int:  # noqa: D102
         return self.height
 
@@ -177,7 +178,7 @@ def split_recursive(  # noqa: PLR0913
         )
         self._unpack_bsp_tree(cdata)
 
-    @deprecate("Use pre_order method instead of walk.")
+    @deprecated("Use pre_order method instead of walk.")
     def walk(self) -> Iterator[BSP]:
         """Iterate over this BSP's hierarchy in pre order.
 

tcod/console.py

@@ -14,11 +14,11 @@
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
-from typing_extensions import Literal
+from typing_extensions import Literal, deprecated
 
 import tcod._internal
 import tcod.constants
-from tcod._internal import _check, _path_encode, deprecate
+from tcod._internal import _check, _path_encode
 from tcod.cffi import ffi, lib
 
 
@@ -248,7 +248,7 @@ def ch(self) -> NDArray[np.intc]:
         return self._tiles["ch"].T if self._order == "F" else self._tiles["ch"]
 
     @property
-    @deprecate("This attribute has been renamed to `rgba`.", category=FutureWarning)
+    @deprecated("This attribute has been renamed to `rgba`.", category=FutureWarning)
     def tiles(self) -> NDArray[Any]:
         """An array of this consoles raw tile data.
 
@@ -264,7 +264,7 @@ def tiles(self) -> NDArray[Any]:
         return self.rgba
 
     @property
-    @deprecate("This attribute has been renamed to `rgba`.", category=FutureWarning)
+    @deprecated("This attribute has been renamed to `rgba`.", category=FutureWarning)
     def buffer(self) -> NDArray[Any]:
         """An array of this consoles raw tile data.
 
@@ -276,7 +276,7 @@ def buffer(self) -> NDArray[Any]:
         return self.rgba
 
     @property
-    @deprecate("This attribute has been renamed to `rgb`.", category=FutureWarning)
+    @deprecated("This attribute has been renamed to `rgb`.", category=FutureWarning)
     def tiles_rgb(self) -> NDArray[Any]:
         """An array of this consoles data without the alpha channel.
 
@@ -288,7 +288,7 @@ def tiles_rgb(self) -> NDArray[Any]:
         return self.rgb
 
     @property
-    @deprecate("This attribute has been renamed to `rgb`.", category=FutureWarning)
+    @deprecated("This attribute has been renamed to `rgb`.", category=FutureWarning)
     def tiles2(self) -> NDArray[Any]:
         """This name is deprecated in favour of :any:`rgb`.
 
@@ -352,7 +352,7 @@ def default_bg(self) -> tuple[int, int, int]:
         return color.r, color.g, color.b
 
     @default_bg.setter
-    @deprecate("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
     def default_bg(self, color: tuple[int, int, int]) -> None:
         self._console_data.back = color
 
@@ -363,7 +363,7 @@ def default_fg(self) -> tuple[int, int, int]:
         return color.r, color.g, color.b
 
     @default_fg.setter
-    @deprecate("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
     def default_fg(self, color: tuple[int, int, int]) -> None:
         self._console_data.fore = color
 
@@ -373,7 +373,7 @@ def default_bg_blend(self) -> int:
         return self._console_data.bkgnd_flag  # type: ignore
 
     @default_bg_blend.setter
-    @deprecate("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
     def default_bg_blend(self, value: int) -> None:
         self._console_data.bkgnd_flag = value
 
@@ -383,7 +383,7 @@ def default_alignment(self) -> int:
         return self._console_data.alignment  # type: ignore
 
     @default_alignment.setter
-    @deprecate("Console defaults have been deprecated.", category=FutureWarning)
+    @deprecated("Console defaults have been deprecated.", category=FutureWarning)
     def default_alignment(self, value: int) -> None:
         self._console_data.alignment = value
 
@@ -830,7 +830,7 @@ def blit(  # noqa: PLR0913
                 bg_alpha,
             )
 
-    @deprecate("Pass the key color to Console.blit instead of calling this function.")
+    @deprecated("Pass the key color to Console.blit instead of calling this function.")
     def set_key_color(self, color: tuple[int, int, int] | None) -> None:
         """Set a consoles blit transparent color.
 
@@ -1234,7 +1234,7 @@ def get_height_rect(width: int, string: str) -> int:
     return int(lib.TCOD_console_get_height_rect_wn(width, len(string_), string_))
 
 
-@deprecate("This function does not support contexts.", category=FutureWarning)
+@deprecated("This function does not support contexts.", category=FutureWarning)
 def recommended_size() -> tuple[int, int]:
     """Return the recommended size of a console for the current active window.
 

tcod/context.py

@@ -32,15 +32,15 @@
 from pathlib import Path
 from typing import Any, Iterable, NoReturn, TypeVar
 
-from typing_extensions import Literal
+from typing_extensions import Literal, deprecated
 
 import tcod.console
 import tcod.event
 import tcod.render
 import tcod.sdl.render
 import tcod.sdl.video
 import tcod.tileset
-from tcod._internal import _check, _check_warn, pending_deprecate
+from tcod._internal import _check, _check_warn
 from tcod.cffi import ffi, lib
 
 __all__ = (
@@ -574,7 +574,7 @@ def new(  # noqa: PLR0913
     return Context._claim(context_pp[0])
 
 
-@pending_deprecate("Call tcod.context.new with width and height as keyword parameters.")
+@deprecated("Call tcod.context.new with width and height as keyword parameters.")
 def new_window(  # noqa: PLR0913
     width: int,
     height: int,
@@ -601,7 +601,7 @@ def new_window(  # noqa: PLR0913
     )
 
 
-@pending_deprecate("Call tcod.context.new with columns and rows as keyword parameters.")
+@deprecated("Call tcod.context.new with columns and rows as keyword parameters.")
 def new_terminal(  # noqa: PLR0913
     columns: int,
     rows: int,

tcod/image.py

@@ -17,9 +17,10 @@
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
+from typing_extensions import deprecated
 
 import tcod.console
-from tcod._internal import _console, _path_encode, deprecate
+from tcod._internal import _console, _path_encode
 from tcod.cffi import ffi, lib
 
 
@@ -357,10 +358,9 @@ def _get_format_name(format: int) -> str:
     return str(format)
 
 
-@deprecate(
+@deprecated(
     "This function may be removed in the future."
     "  It's recommended to load images with a more complete image library such as python-Pillow or python-imageio.",
-    category=PendingDeprecationWarning,
 )
 def load(filename: str | PathLike[str]) -> NDArray[np.uint8]:
     """Load a PNG file as an RGBA array.

tcod/libtcodpy.py

@@ -12,7 +12,7 @@
 
 import numpy as np
 from numpy.typing import NDArray
-from typing_extensions import Literal
+from typing_extensions import Literal, deprecated
 
 import tcod.bsp
 import tcod.console
@@ -77,6 +77,7 @@ def BKGND_ADDALPHA(a: int) -> int:
     return BKGND_ADDA | (int(a * 255) << 8)
 
 
+@deprecated("Console array attributes perform better than this class.")
 class ConsoleBuffer:
     """Simple console that allows direct (fast) access to cells. Simplifies use of the "fill" functions.
 
@@ -111,11 +112,6 @@ def __init__(
 
         Values to fill the buffer are optional, defaults to black with no characters.
         """
-        warnings.warn(
-            "Console array attributes perform better than this class.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
         self.width = width
         self.height = height
         self.clear(back_r, back_g, back_b, fore_r, fore_g, fore_b, char)
@@ -271,6 +267,7 @@ def blit(
             dest.ch.ravel()[:] = self.char
 
 
+@deprecated("Using this class is not recommended.")
 class Dice(_CDataWrapper):
     """A libtcod dice object.
 
@@ -286,11 +283,6 @@ class Dice(_CDataWrapper):
     """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        warnings.warn(
-            "Using this class is not recommended.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
         super().__init__(*args, **kwargs)
         if self.cdata == ffi.NULL:
             self._init(*args, **kwargs)

tcod/random.py

@@ -14,8 +14,9 @@
 import warnings
 from typing import Any, Hashable
 
+from typing_extensions import deprecated
+
 import tcod.constants
-from tcod._internal import deprecate
 from tcod.cffi import ffi, lib
 
 MERSENNE_TWISTER = tcod.constants.RNG_MT
@@ -127,7 +128,7 @@ def gauss(self, mu: float, sigma: float) -> float:
         """
         return float(lib.TCOD_random_get_gaussian_double(self.random_c, mu, sigma))
 
-    @deprecate("This is a typo, rename this to 'gauss'", category=FutureWarning)
+    @deprecated("This is a typo, rename this to 'gauss'", category=FutureWarning)
     def guass(self, mu: float, sigma: float) -> float:  # noqa: D102
         return self.gauss(mu, sigma)
 
@@ -146,7 +147,7 @@ def inverse_gauss(self, mu: float, sigma: float) -> float:
         """
         return float(lib.TCOD_random_get_gaussian_double_inv(self.random_c, mu, sigma))
 
-    @deprecate("This is a typo, rename this to 'inverse_gauss'", category=FutureWarning)
+    @deprecated("This is a typo, rename this to 'inverse_gauss'", category=FutureWarning)
     def inverse_guass(self, mu: float, sigma: float) -> float:  # noqa: D102
         return self.inverse_gauss(mu, sigma)
 

tcod/tileset.py

@@ -20,9 +20,10 @@
 
 import numpy as np
 from numpy.typing import ArrayLike, NDArray
+from typing_extensions import deprecated
 
 import tcod.console
-from tcod._internal import _check, _check_p, _console, _path_encode, _raise_tcod_error, deprecate
+from tcod._internal import _check, _check_p, _console, _path_encode, _raise_tcod_error
 from tcod.cffi import ffi, lib
 
 
@@ -235,7 +236,7 @@ def remap(self, codepoint: int, x: int, y: int = 0) -> None:
         )
 
 
-@deprecate("Using the default tileset is deprecated.")
+@deprecated("Using the default tileset is deprecated.")
 def get_default() -> Tileset:
     """Return a reference to the default Tileset.
 
@@ -248,7 +249,7 @@ def get_default() -> Tileset:
     return Tileset._claim(lib.TCOD_get_default_tileset())
 
 
-@deprecate("Using the default tileset is deprecated.")
+@deprecated("Using the default tileset is deprecated.")
 def set_default(tileset: Tileset) -> None:
     """Set the default tileset.
 
@@ -278,7 +279,7 @@ def load_truetype_font(path: str | PathLike[str], tile_width: int, tile_height:
     return Tileset._claim(cdata)
 
 
-@deprecate("Accessing the default tileset is deprecated.")
+@deprecated("Accessing the default tileset is deprecated.")
 def set_truetype_font(path: str | PathLike[str], tile_width: int, tile_height: int) -> None:
     """Set the default tileset from a `.ttf` or `.otf` file.