Update deprecations to use PEP 702

Author: HexDecimal

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Updated deprecations to use [PEP 702](https://peps.python.org/pep-0702/).
+
 ## [5.3.0] - 2025-03-08
 
 ### Added

pyproject.toml

@@ -22,7 +22,7 @@ dependencies = [
     "attrs >=23.1.0",
     "cattrs >=23.1.2",
     "sentinel-value >=1.0.0",
-    "typing-extensions >=4.4.0",
+    "typing-extensions >=4.9.0",
 ]
 
 [tool.setuptools_scm]

tcod/ecs/entity.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import warnings
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -23,7 +22,7 @@
 
 import attrs
 from sentinel_value import sentinel
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 import tcod.ecs.callbacks
 import tcod.ecs.query
@@ -74,14 +73,13 @@ class Entity:
     """This entities unique identifier."""
 
     @property
+    @deprecated("Use '.registry' instead of '.world'")
     def world(self) -> Registry:
         """Deprecated alias for registry.
 
         .. deprecated:: 5.1
             Use :any:`registry` instead.
         """
-        if __debug__:
-            warnings.warn("Use '.registry' instead of '.world'", DeprecationWarning, stacklevel=2)
         return self.registry
 
     def __new__(cls, registry: Registry, uid: object = object) -> Entity:  # noqa: PYI034
@@ -284,13 +282,13 @@ def relation_tag(self) -> EntityRelationsExclusive:
         return EntityRelationsExclusive(self, (IsA,))
 
     @property
+    @deprecated("The '.relation_tags' attribute has been renamed to '.relation_tag'", category=FutureWarning)
     def relation_tags(self) -> EntityRelationsExclusive:
         """Access an entities exclusive relations.
 
         .. deprecated:: 3.2
             This attribute was renamed to :any:`relation_tag`.
         """
-        warnings.warn("The '.relation_tags' attribute has been renamed to '.relation_tag'", FutureWarning, stacklevel=2)
         return EntityRelationsExclusive(self, (IsA,))
 
     @property
@@ -303,12 +301,8 @@ def relation_tags_many(self) -> EntityRelations:
         """
         return EntityRelations(self, (IsA,))
 
-    def _set_name(self, value: object, stacklevel: int = 1) -> None:
-        warnings.warn(
-            "The name feature has been deprecated and will be removed.",
-            FutureWarning,
-            stacklevel=stacklevel + 1,
-        )
+    @deprecated("The name feature has been deprecated and will be removed.", category=FutureWarning)
+    def _set_name(self, value: object) -> None:
         old_name = self.name
         if old_name is not None:  # Remove self from names
             del self.registry._names_by_name[old_name]
@@ -333,8 +327,9 @@ def name(self) -> object:
         return self.registry._names_by_entity.get(self)
 
     @name.setter
+    @deprecated("The name feature has been deprecated and will be removed.", category=FutureWarning)
     def name(self, value: object) -> None:
-        self._set_name(value, stacklevel=2)
+        self._set_name(value)
 
     def __repr__(self) -> str:
         """Return a representation of this entity.
@@ -410,17 +405,13 @@ def __call__(self, *, traverse: Iterable[object]) -> Self:
         """
         return self.__class__(self.entity, tuple(traverse))
 
-    def set(self, value: object, *, _stacklevel: int = 1) -> None:
+    @deprecated("Setting values without an explicit key has been deprecated.", category=FutureWarning)
+    def set(self, value: object) -> None:
         """Assign or overwrite a component, automatically deriving the key.
 
         .. deprecated:: 3.1
             Setting values without an explicit key has been deprecated.
         """
-        warnings.warn(
-            "Setting values without an explicit key has been deprecated.",
-            FutureWarning,
-            stacklevel=_stacklevel + 1,
-        )
         key = value.__class__
         self[key] = value
 
@@ -498,15 +489,17 @@ def __len__(self) -> int:
         """Return the number of components belonging to this entity."""
         return len(self.keys())
 
-    def update_values(self, values: Iterable[object], *, _stacklevel: int = 1) -> None:
+    @deprecated("Setting values without an explicit key has been deprecated.", category=FutureWarning)
+    def update_values(self, values: Iterable[object]) -> None:
         """Add or overwrite multiple components inplace, deriving the keys from the values.
 
         .. deprecated:: 3.1
             Setting values without an explicit key has been deprecated.
         """
         for value in values:
-            self.set(value, _stacklevel=_stacklevel + 1)
+            self.set(value)
 
+    @deprecated("This method has been deprecated. Iterate over items instead.", category=FutureWarning)
     def by_name_type(self, name_type: type[_T1], component_type: type[_T2]) -> Iterator[tuple[_T1, type[_T2]]]:
         """Iterate over all of an entities component keys with a specific (name_type, component_type) combination.
 
@@ -515,7 +508,6 @@ def by_name_type(self, name_type: type[_T1], component_type: type[_T2]) -> Itera
         .. deprecated:: 3.1
             This method has been deprecated. Iterate over items instead.
         """
-        warnings.warn("This method has been deprecated. Iterate over items instead.", FutureWarning, stacklevel=2)
         # Naive implementation until I feel like optimizing it
         for key in self:
             if not isinstance(key, tuple):

tcod/ecs/query.py

@@ -9,7 +9,7 @@
 from weakref import WeakKeyDictionary, WeakSet
 
 import attrs
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 import tcod.ecs.entity
 from tcod.ecs.constants import IsA
@@ -333,14 +333,13 @@ class BoundQuery:
     _query: _Query = attrs.field(factory=_QueryLogicalAnd)
 
     @property
+    @deprecated("Use '.registry' instead of '.world'")
     def world(self) -> Registry:
         """Deprecated alias for registry.
 
         .. deprecated:: 5.1
             Use :any:`registry` instead.
         """
-        if __debug__:
-            warnings.warn("Use '.registry' instead of '.world'", DeprecationWarning, stacklevel=2)
         return self.registry
 
     def get_entities(self) -> AbstractSet[Entity]:

tcod/ecs/registry.py

@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING, Any, DefaultDict, Dict, Final, Iterable, Mapping, NoReturn, Set, TypeVar
 
 import attrs
+from typing_extensions import deprecated
 
 import tcod.ecs._converter
 import tcod.ecs.query
@@ -151,6 +152,10 @@ class Registry:
     """
 
     @property
+    @deprecated(
+        "The 'registry.global_' attribute has been deprecated. Use 'registry[None]' to access this entity.",
+        category=FutureWarning,
+    )
     def global_(self) -> Entity:
         """A unique globally accessible entity.
 
@@ -168,11 +173,6 @@ def global_(self) -> Entity:
             >>> registry[None].components[("turn", int)]
             0
         """
-        warnings.warn(
-            "The 'registry.global_' attribute has been deprecated. Use 'registry[None]' to access this entity.",
-            FutureWarning,
-            stacklevel=2,
-        )
         return Entity(self, None)
 
     def __setstate__(self, state: dict[str, Any]) -> None:
@@ -300,12 +300,12 @@ def new_entity(
         if isinstance(components, Mapping):
             entity.components.update(components)
         elif components:
-            entity.components.update_values(components, _stacklevel=2)
+            entity.components.update_values(components)
         entity_tags = entity.tags
         for tag in tags:
             entity_tags.add(tag)
         if name is not None:
-            entity._set_name(name, stacklevel=2)
+            entity._set_name(name)
         return entity
 
     @property

tests/test_traversal.py

@@ -212,7 +212,8 @@ def test_inherited_clear() -> None:
     world["A"].components[int] = 1
     world["A"].tags.add("foo")
     world["A"].relation_components[str][world["B"]] = "bar"
-    world["A"].relation_tags["baz"] = world["B"]
+    with pytest.warns():
+        world["A"].relation_tags["baz"] = world["B"]
     child = world["A"].instantiate()
     child.clear()  # Could hang if broken
     x = child.components