Add a ReceiverInvalidatedError

This is raised when the receiver was invalidated, for example when it
was converted into a Peekable.

Fixes #52.

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

Author: llucax

RELEASE_NOTES.md

@@ -12,7 +12,7 @@
 
   `Receiver.consume()` doesn't raise any exceptions.
 
-  Receivers raising `EOFError` now raise `ReceiverError` instead.
+  Receivers raising `EOFError` now raise `ReceiverInvalidatedError` instead.
 
 * For channels which senders raise an error when the channel is closed or which receivers stop receiving when the channel is closed, the `SenderError` and `ReceiverStoppedError` are chained with a `__cause__` that is a `ChannelClosedError` with the channel that was closed.
 
@@ -30,6 +30,8 @@
 
   * `ReceiverClosedError`: Raised when a receiver don't have more messages to receive.
 
+  * `ReceiverInvalidatedError`: Raised when a receiver was invalidated (for example it was converted into a `Peekable`).
+
 ## Bug Fixes
 
 <!-- Here goes notable bug fixes that are worth a special mention or explanation -->

src/frequenz/channels/__init__.py

@@ -55,6 +55,10 @@
 
 * [ReceiverStoppedError][frequenz.channels.ReceiverStoppedError]: A receiver
   stopped producing messages.
+
+* [ReceiverInvalidatedError][frequenz.channels.ReceiverInvalidatedError]:
+  A receiver is not longer valid (for example if it was converted into
+  a peekable.
 """
 
 from . import util
@@ -67,6 +71,7 @@
     ChannelError,
     Error,
     ReceiverError,
+    ReceiverInvalidatedError,
     ReceiverStoppedError,
     SenderError,
 )
@@ -81,6 +86,7 @@
     "Peekable",
     "Receiver",
     "ReceiverError",
+    "ReceiverInvalidatedError",
     "ReceiverStoppedError",
     "Sender",
     "SenderError",

src/frequenz/channels/_broadcast.py

@@ -18,7 +18,7 @@
 from ._base_classes import T
 from ._exceptions import (
     ChannelClosedError,
-    ReceiverError,
+    ReceiverInvalidatedError,
     ReceiverStoppedError,
     SenderError,
 )
@@ -262,10 +262,14 @@ async def ready(self) -> None:
 
         Raises:
             ReceiverStoppedError: if there is some problem with the receiver.
-            ReceiverError: if the receiver is not longer active.
+            ReceiverInvalidatedError: if the receiver was converted into
+                a peekable.
         """
         if not self._active:
-            raise ReceiverError("This receiver is no longer active.", self)
+            raise ReceiverInvalidatedError(
+                "This receiver was converted into a Peekable so it is not longer valid.",
+                self,
+            )
 
         # Use a while loop here, to handle spurious wakeups of condition variables.
         #

src/frequenz/channels/_exceptions.py

@@ -104,3 +104,12 @@ def __init__(self, receiver: _base_classes.Receiver[T]):
                 error happened.
         """
         super().__init__(f"Receiver {receiver} was stopped", receiver)
+
+
+class ReceiverInvalidatedError(ReceiverError[T]):
+    """The [Receiver][frequenz.channels.Receiver] was invalidated.
+
+    This happens when the Receiver is converted
+    [into][frequenz.channels.Receiver.into_peekable]
+    a [Peekable][frequenz.channels.Peekable].
+    """

tests/test_broadcast.py

@@ -12,7 +12,7 @@
     Broadcast,
     ChannelClosedError,
     Receiver,
-    ReceiverError,
+    ReceiverInvalidatedError,
     ReceiverStoppedError,
     Sender,
     SenderError,
@@ -178,7 +178,7 @@ async def test_broadcast_peek() -> None:
     peekable = receiver.into_peekable()
     sender = bcast.new_sender()
 
-    with pytest.raises(ReceiverError, match=r"This receiver is no longer active."):
+    with pytest.raises(ReceiverInvalidatedError):
         await receiver.receive()
 
     assert peekable.peek() is None