Add and test clear methods for attributes

Author: HexDecimal

CHANGELOG.md

@@ -7,10 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Allow setting the `traverse` state of an `entity.component_tags[type][entity](traverse=...)` attribute.
+
 ### Changed
 
 - Updated deprecations to use [PEP 702](https://peps.python.org/pep-0702/).
 
+### Fixed
+
+- Fixed `.clear` methods for `entity.components` and `entity.component_relations`.
+
 ## [5.3.0] - 2025-03-08
 
 ### Added

tcod/ecs/entity.py

@@ -124,10 +124,10 @@ def clear(self) -> None:
 
         .. 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.
@@ -594,6 +594,12 @@ def pop(
         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]):
@@ -942,6 +948,13 @@ def __attrs_post_init__(self) -> None:
             """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:: Unreleased
+        """
+        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
@@ -1001,6 +1014,12 @@ def __len__(self) -> int:
         """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]]):

tests/test_relations.py

@@ -168,3 +168,46 @@ def test_relation_tag_tables() -> None:
     assert set(w.Q.all_of(relations=[(..., "tag", None)])) == {e2}
     assert set(w.Q.all_of(relations=[(e1, "tag", None)])) == {e2}
     assert not set(w.Q.all_of(relations=[(e3, "tag", None)]))
+
+
+def test_clear_with_relation() -> None:
+    world = tcod.ecs.Registry()
+    parent = world["parent"]
+    child = parent.instantiate()
+    entity_other = world[object()]
+    for i in range(5):
+        parent.components[(i, int)] = i
+        parent.tags.add(i)
+        parent.relation_components[(i, int)][entity_other] = i
+        parent.relation_tag[i] = entity_other
+
+    for i in range(10):
+        child.components[(i, int)] = i
+        child.tags.add(i)
+        child.relation_components[(i, int)][entity_other] = i
+        child.relation_tag[i] = entity_other
+
+    components_all = {(i, int) for i in range(10)}
+    components_after = {(i, int) for i in range(5)}
+    tags_all = set(range(10))
+    tags_after = set(range(5))
+
+    assert child.components.keys() == components_all
+    assert child.relation_components.keys() == components_all
+    assert set(child.tags) == tags_all
+    assert set(child.relation_tag.keys()) == tags_all | {tcod.ecs.IsA}
+
+    # Clear direct values, keeping values from parent as long as the IsA relation exists
+    child.components.clear()
+    assert child.components.keys() == components_after
+    child.relation_components.clear()
+    assert child.relation_components.keys() == components_after
+    child.tags.clear()
+    assert set(child.tags) == tags_after
+
+    # Clearing relation_tags means breaking the IsA link to the parent
+    child.relation_tag.clear()
+    assert not child.relation_tag.keys()
+    assert not child.components.keys()
+    assert not child.tags
+    assert not child.relation_components.keys()