tcod-ecs 5.3.0__tar.gz → 5.4.0__tar.gz

{tcod_ecs-5.3.0 → tcod_ecs-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tcod-ecs
-Version: 5.3.0
+Version: 5.4.0
 Summary: A type-hinted Entity Component System based on Python dictionaries and sets.
 Author-email: Kyle Benesch <4b796c65+github@gmail.com>
 Requires-Python: >=3.8
@@ -16,7 +16,7 @@ License-File: LICENSE
 Requires-Dist: attrs >=23.1.0
 Requires-Dist: cattrs >=23.1.2
 Requires-Dist: sentinel-value >=1.0.0
-Requires-Dist: typing-extensions >=4.4.0
+Requires-Dist: typing-extensions >=4.9.0
 Requires-Dist: attrs >=22.2.0 ; extra == "test"
 Requires-Dist: pytest >=7.2.0 ; extra == "test"
 Requires-Dist: pytest-cov >=4.0.0 ; extra == "test"

{tcod_ecs-5.3.0 → tcod_ecs-5.4.0}/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]
@@ -89,6 +89,7 @@ line-length = 120
 [tool.ruff.lint] # https://docs.astral.sh/ruff/rules/
 select = ["ALL"]
 ignore = [
+    "A005",   # stdlib-module-shadowing, workaround VSCode treating all modules as local
     "COM",    # flake8-commas, handled by formatter
     "E501",   # line-too-long
     "S101",   # assert

{tcod_ecs-5.3.0 → tcod_ecs-5.4.0}/tcod/ecs/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '5.3.0'
-__version_tuple__ = version_tuple = (5, 3, 0)
+__version__ = version = '5.4.0'
+__version_tuple__ = version_tuple = (5, 4, 0)

{tcod_ecs-5.3.0 → tcod_ecs-5.4.0}/tcod/ecs/entity.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import warnings
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -23,7 +22,7 @@ from weakref import WeakKeyDictionary, WeakValueDictionary
 
 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,17 +73,16 @@ 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
+    def __new__(cls, registry: Registry, uid: object = object) -> Self | Entity:
         """Return a unique entity for the given `registry` and `uid`.
 
         If an entity already exists with a matching `registry` and `uid` then that entity is returned.
@@ -126,10 +124,10 @@ class Entity:
 
         .. versionadded:: 4.2.0
         """
-        self.components(traverse=()).clear()
-        self.tags(traverse=()).clear()
-        self.relation_tags_many(traverse=()).clear()
-        self.relation_components(traverse=()).clear()
+        self.components.clear()
+        self.tags.clear()
+        self.relation_tags_many.clear()
+        self.relation_components.clear()
 
     def instantiate(self) -> Self:
         """Return a new entity which inherits the components, tags, and relations of this entity.
@@ -284,13 +282,13 @@ class Entity:
         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 @@ class Entity:
         """
         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 @@ class Entity:
         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 @@ class EntityComponents(MutableMapping[Union[Type[Any], Tuple[object, Type[Any]]]
         """
         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 @@ class EntityComponents(MutableMapping[Union[Type[Any], Tuple[object, Type[Any]]]
         """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 @@ class EntityComponents(MutableMapping[Union[Type[Any], Tuple[object, Type[Any]]]
         .. 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):
@@ -561,7 +553,7 @@ class EntityComponents(MutableMapping[Union[Type[Any], Tuple[object, Type[Any]]]
             return __default
 
     @overload
-    def pop(self, __key: ComponentKey[T], /) -> T | None: ...
+    def pop(self, __key: ComponentKey[T], /) -> T: ...
     @overload
     def pop(self, __key: ComponentKey[T], /, default: _T1) -> T | _T1: ...
 
@@ -602,6 +594,12 @@ class EntityComponents(MutableMapping[Union[Type[Any], Tuple[object, Type[Any]]]
         del self[__key]
         return value
 
+    def clear(self) -> None:
+        """Remove any components stored directly in this entity."""
+        if self.traverse:
+            return self(traverse=()).clear()
+        return super().clear()
+
 
 @attrs.define(eq=False, frozen=True, weakref_slot=False)
 class EntityTags(MutableSet[Any]):
@@ -950,6 +948,13 @@ class EntityComponentRelationMapping(Generic[T], MutableMapping[Entity, T]):
             """Validate attributes."""
             assert isinstance(self.entity, Entity), self.entity
 
+    def __call__(self, *, traverse: Iterable[object]) -> Self:
+        """Update this view with alternative parameters, such as a specific traversal relation.
+
+        .. versionadded:: 5.4
+        """
+        return self.__class__(self.entity, self.key, tuple(traverse))
+
     def __getitem__(self, target: Entity) -> T:
         """Return the component related to a target entity."""
         _relation_components_by_entity = self.entity.registry._relation_components_by_entity
@@ -1009,6 +1014,12 @@ class EntityComponentRelationMapping(Generic[T], MutableMapping[Entity, T]):
         """Return the count of targets for this component relation."""
         return len(self.keys())
 
+    def clear(self) -> None:
+        """Remove any components stored directly in this entity relation."""
+        if self.traverse:
+            return self(traverse=()).clear()
+        return super().clear()
+
 
 @attrs.define(eq=False, frozen=True, weakref_slot=False)
 class EntityComponentRelations(MutableMapping[ComponentKey[Any], EntityComponentRelationMapping[Any]]):

{tcod_ecs-5.3.0 → tcod_ecs-5.4.0}/tcod/ecs/query.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any, Iterable, Iterator, Protocol, TypeVar, ov
 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-5.3.0 → tcod_ecs-5.4.0}/tcod/ecs/registry.py

@@ -7,6 +7,7 @@ from collections import defaultdict
 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 @@ class Registry:
             >>> 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 @@ class Registry:
         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

{tcod_ecs-5.3.0 → tcod_ecs-5.4.0}/tcod/ecs/typing.py

@@ -1,4 +1,4 @@
-"""Common type-hints for tcod.ecs."""  # noqa: A005
+"""Common type-hints for tcod.ecs."""
 
 from __future__ import annotations