Rename OnlyIfPrevious to WithPrevious

With the new `take_while()` and `drop_while()` methods, the need for
using **only** in the name of the predicate is not necessary anymore.

Also, the new name makes is more clear that this predicate is adding an
extra condition to the message filtering based on the previous
message.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

RELEASE_NOTES.md

@@ -4,4 +4,4 @@
 
 ### Experimental
 
-- A new predicate, `OnlyIfPrevious`, to `filter()` messages based on the previous message.
+- A new composable predicate, `WithPrevious`, to filter messages based on the previous message.

src/frequenz/channels/experimental/__init__.py

@@ -10,11 +10,11 @@
 """
 
 from ._pipe import Pipe
-from ._predicates import OnlyIfPrevious
+from ._predicates import WithPrevious
 from ._relay_sender import RelaySender
 
 __all__ = [
-    "OnlyIfPrevious",
+    "WithPrevious",
     "Pipe",
     "RelaySender",
 ]

src/frequenz/channels/experimental/_predicates.py

@@ -20,7 +20,7 @@ def __str__(self) -> str:
 _SENTINEL: Final[_Sentinel] = _Sentinel()
 
 
-class OnlyIfPrevious(Generic[ChannelMessageT]):
+class WithPrevious(Generic[ChannelMessageT]):
     """A predicate to check if a message has a particular relationship with the previous one.
 
     This predicate can be used to filter out messages based on a custom condition on the
@@ -31,10 +31,10 @@ class OnlyIfPrevious(Generic[ChannelMessageT]):
     Example: Receiving only messages that are not the same instance as the previous one.
         ```python
         from frequenz.channels import Broadcast
-        from frequenz.channels.experimental import OnlyIfPrevious
+        from frequenz.channels.experimental import WithPrevious
 
         channel = Broadcast[int | bool](name="example")
-        receiver = channel.new_receiver().filter(OnlyIfPrevious(lambda old, new: old is not new))
+        receiver = channel.new_receiver().filter(WithPrevious(lambda old, new: old is not new))
         sender = channel.new_sender()
 
         # This message will be received as it is the first message.
@@ -53,11 +53,11 @@ class OnlyIfPrevious(Generic[ChannelMessageT]):
     Example: Receiving only messages if they are bigger than the previous one.
         ```python
         from frequenz.channels import Broadcast
-        from frequenz.channels.experimental import OnlyIfPrevious
+        from frequenz.channels.experimental import WithPrevious
 
         channel = Broadcast[int](name="example")
         receiver = channel.new_receiver().filter(
-            OnlyIfPrevious(lambda old, new: new > old, first_is_true=False)
+            WithPrevious(lambda old, new: new > old, first_is_true=False)
         )
         sender = channel.new_sender()
 

tests/experimental/test_predicates_only_if_previous.py

@@ -1,21 +1,21 @@
 # License: MIT
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""Tests for the OnlyIfPrevious implementation."""
+"""Tests for the WithPrevious implementation."""
 
 from dataclasses import dataclass
 from typing import Callable, Generic, TypeVar
 
 import pytest
 
-from frequenz.channels.experimental import OnlyIfPrevious
+from frequenz.channels.experimental import WithPrevious
 
 _T = TypeVar("_T")
 
 
 @dataclass(frozen=True, kw_only=True)
 class PredicateTestCase(Generic[_T]):
-    """Test case for testing OnlyIfPrevious behavior with different predicates."""
+    """Test case for testing WithPrevious behavior with different predicates."""
 
     title: str
     messages: list[_T]
@@ -113,12 +113,12 @@ def is_not_same_instance(old: object, new: object) -> bool:
     ids=lambda test_case: test_case.title,
 )
 def test_only_if_previous(test_case: PredicateTestCase[_T]) -> None:
-    """Test the OnlyIfPrevious with different predicates and sequences.
+    """Test the WithPrevious with different predicates and sequences.
 
     Args:
         test_case: The test case containing the input values and expected results.
     """
-    only_if_previous = OnlyIfPrevious(
+    only_if_previous = WithPrevious(
         test_case.predicate,
         first_is_true=test_case.first_is_true,
     )
@@ -127,9 +127,9 @@ def test_only_if_previous(test_case: PredicateTestCase[_T]) -> None:
 
 
 def test_only_if_previous_state_independence() -> None:
-    """Test that multiple OnlyIfPrevious instances maintain independent state."""
-    only_if_previous1 = OnlyIfPrevious(is_greater)
-    only_if_previous2 = OnlyIfPrevious(is_greater)
+    """Test that multiple WithPrevious instances maintain independent state."""
+    only_if_previous1 = WithPrevious(is_greater)
+    only_if_previous2 = WithPrevious(is_greater)
 
     # First message should be accepted (first_is_true default is True)
     assert only_if_previous1(1) is True
@@ -141,17 +141,17 @@ def test_only_if_previous_state_independence() -> None:
 
 
 def test_only_if_previous_str_representation() -> None:
-    """Test the string representation of OnlyIfPrevious."""
-    only_if_previous = OnlyIfPrevious(is_greater)
-    assert str(only_if_previous) == "OnlyIfPrevious:is_greater"
+    """Test the string representation of WithPrevious."""
+    only_if_previous = WithPrevious(is_greater)
+    assert str(only_if_previous) == "WithPrevious:is_greater"
     assert (
-        repr(only_if_previous) == f"<OnlyIfPrevious: {is_greater!r} first_is_true=True>"
+        repr(only_if_previous) == f"<WithPrevious: {is_greater!r} first_is_true=True>"
     )
 
 
 def test_only_if_previous_sentinel_str() -> None:
     """Test the string representation of the sentinel value."""
-    only_if_previous = OnlyIfPrevious(always_true)
+    only_if_previous = WithPrevious(always_true)
 
     # Access the private attribute for testing purposes
     # pylint: disable=protected-access