Replace "value" with "message"

We prefer to use the term "message" as what's transported in a channel,
as "value" is too generic and used in many other contexts.

This means changing the code too, so `Selected.value` is now
`Selected.message`.

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

Author: llucax

README.md

@@ -141,8 +141,8 @@ async def send(
             await sender.send(f"{sender}: {counter}")
             counter += 1
         elif selected_from(selected, control_command):
-            print(f"{sender}: Received command: {selected.value.name}")
-            match selected.value:
+            print(f"{sender}: Received command: {selected.message.name}")
+            match selected.message:
                 case Command.STOP_SENDER:
                     print(f"{sender}: Stopping")
                     break
@@ -166,13 +166,13 @@ async def receive(
     merged = merge(*receivers)
     async for selected in select(merged, timer, control_command):
         if selected_from(selected, merged):
-            message = selected.value
+            message = selected.message
             print(f"receive: Received {message=}")
             timer.reset()
             print(f"{timer=}")
         elif selected_from(selected, control_command):
-            print(f"receive: received command: {selected.value.name}")
-            match selected.value:
+            print(f"receive: received command: {selected.message.name}")
+            match selected.message:
                 case Command.PING:
                     print("receive: Ping received, reply with pong")
                     await control_reply.send(Reply(ReplyCommand.PONG, "receive"))
@@ -181,7 +181,7 @@ async def receive(
                 case _ as unknown:
                     assert_never(unknown)
         elif selected_from(selected, timer):
-            drift = selected.value
+            drift = selected.message
             print(
                 f"receive: No data received for {timer.interval + drift} seconds, "
                 "giving up"

RELEASE_NOTES.md

@@ -79,9 +79,9 @@
 
 * `Peekable`
 
-  This class was removed because it was merely a shortcut to a receiver that caches the last value received. It did not fit the channel abstraction well and was infrequently used.
+  This class was removed because it was merely a shortcut to a receiver that caches the last message received. It did not fit the channel abstraction well and was infrequently used.
 
-  You can replace it with a task that receives and retains the last value.
+  You can replace it with a task that receives and retains the last message.
 
 * `Broadcast.new_peekable()`
 

src/frequenz/channels/__init__.py

@@ -32,8 +32,8 @@
 * [merge][frequenz.channels.merge]: Merge messages coming from multiple receivers into
   a single stream.
 
-* [select][frequenz.channels.select]: Iterate over the values of all
-  [receivers][frequenz.channels.Receiver] as new values become available.
+* [select][frequenz.channels.select]: Iterate over the messages of all
+  [receivers][frequenz.channels.Receiver] as new messages become available.
 
 Exception classes:
 

src/frequenz/channels/_anycast.py

@@ -79,7 +79,7 @@ class Anycast(Generic[_T]):
     When the channel is not needed anymore, it should be closed with the
     [`close()`][frequenz.channels.Anycast.close] method. This will prevent further
     attempts to [`send()`][frequenz.channels.Sender.send] data. Receivers will still be
-    able to drain the pending values on the channel, but after that, subsequent
+    able to drain the pending messages on the channel, but after that, subsequent
     [`receive()`][frequenz.channels.Receiver.receive] calls will raise a
     [`ReceiverStoppedError`][frequenz.channels.ReceiverStoppedError] exception.
 
@@ -181,15 +181,15 @@ async def main() -> None:
         sender_1 sending 11
         sender_1 sending 12
         Anycast channel [Anycast:numbers:_Sender] is full, blocking sender until a receiver
-        consumes a value
+        consumes a message
         sender_2 sending 20
         Anycast channel [Anycast:numbers:_Sender] is full, blocking sender until a receiver
-        consumes a value
+        consumes a message
         receiver_1 received 10
         receiver_1 received 11
         sender_2 sending 21
         Anycast channel [Anycast:numbers:_Sender] is full, blocking sender until a receiver
-        consumes a value
+        consumes a message
         receiver_1 received 12
         receiver_1 received 20
         receiver_1 received 21
@@ -219,16 +219,16 @@ def __init__(self, *, name: str, limit: int = 10) -> None:
         self._send_cv: Condition = Condition()
         """The condition to wait for free space in the channel's buffer.
 
-        If the channel's buffer is full, then the sender waits for values to
+        If the channel's buffer is full, then the sender waits for messages to
         get consumed using this condition until there's some free space
         available in the channel's buffer.
         """
 
         self._recv_cv: Condition = Condition()
-        """The condition to wait for values in the channel's buffer.
+        """The condition to wait for messages in the channel's buffer.
 
-        If the channel's buffer is empty, then the receiver waits for values
-        using this condition until there's a value available in the channel's
+        If the channel's buffer is empty, then the receiver waits for messages
+        using this condition until there's a message available in the channel's
         buffer.
         """
 
@@ -255,11 +255,11 @@ def is_closed(self) -> bool:
 
     @property
     def limit(self) -> int:
-        """The maximum number of values that can be stored in the channel's buffer.
+        """The maximum number of messages that can be stored in the channel's buffer.
 
         If the length of channel's buffer reaches the limit, then the sender
         blocks at the [send()][frequenz.channels.Sender.send] method until
-        a value is consumed.
+        a message is consumed.
         """
         maxlen = self._deque.maxlen
         assert maxlen is not None
@@ -271,7 +271,7 @@ async def close(self) -> None:
         Any further attempts to [send()][frequenz.channels.Sender.send] data
         will return `False`.
 
-        Receivers will still be able to drain the pending values on the channel,
+        Receivers will still be able to drain the pending messages on the channel,
         but after that, subsequent
         [receive()][frequenz.channels.Receiver.receive] calls will return `None`
         immediately.
@@ -342,7 +342,7 @@ async def send(self, msg: _T) -> None:
         if len(self._chan._deque) == self._chan._deque.maxlen:
             _logger.warning(
                 "Anycast channel [%s] is full, blocking sender until a receiver "
-                "consumes a value",
+                "consumes a message",
                 self,
             )
             while len(self._chan._deque) == self._chan._deque.maxlen:
@@ -367,7 +367,7 @@ def __repr__(self) -> str:
 
 
 class _Empty:
-    """A sentinel value to indicate that a value has not been set."""
+    """A sentinel to indicate that a message has not been set."""
 
 
 class _Receiver(Receiver[_T]):
@@ -389,9 +389,9 @@ def __init__(self, chan: Anycast[_T]) -> None:
         self._next: _T | type[_Empty] = _Empty
 
     async def ready(self) -> bool:
-        """Wait until the receiver is ready with a value or an error.
+        """Wait until the receiver is ready with a message or an error.
 
-        Once a call to `ready()` has finished, the value should be read with
+        Once a call to `ready()` has finished, the message should be read with
         a call to `consume()` (`receive()` or iterated over). The receiver will
         remain ready (this method will return immediately) until it is
         consumed.
@@ -416,10 +416,10 @@ async def ready(self) -> bool:
         return True
 
     def consume(self) -> _T:
-        """Return the latest value once `ready()` is complete.
+        """Return the latest message once `ready()` is complete.
 
         Returns:
-            The next value that was received.
+            The next message that was received.
 
         Raises:
             ReceiverStoppedError: If the receiver stopped producing messages.

src/frequenz/channels/_broadcast.py

@@ -190,12 +190,12 @@ def __init__(self, *, name: str, resend_latest: bool = False) -> None:
             name: The name of the channel. This is for logging purposes, and it will be
                 shown in the string representation of the channel.
             resend_latest: When True, every time a new receiver is created with
-                `new_receiver`, it will automatically get sent the latest value on the
-                channel.  This allows new receivers on slow streams to get the latest
-                value as soon as they are created, without having to wait for the next
-                message on the channel to arrive.  It is safe to be set in
-                data/reporting channels, but is not recommended for use in channels that
-                stream control instructions.
+                `new_receiver`, the last message seen by the channel will be sent to the
+                new receiver automatically. This allows new receivers on slow streams to
+                get the latest message as soon as they are created, without having to
+                wait for the next message on the channel to arrive.  It is safe to be
+                set in data/reporting channels, but is not recommended for use in
+                channels that stream control instructions.
         """
         self._name: str = name
         """The name of the broadcast channel.
@@ -213,14 +213,14 @@ def __init__(self, *, name: str, resend_latest: bool = False) -> None:
         """Whether the channel is closed."""
 
         self._latest: _T | None = None
-        """The latest value sent to the channel."""
+        """The latest message sent to the channel."""
 
         self.resend_latest: bool = resend_latest
-        """Whether to resend the latest value to new receivers.
+        """Whether to resend the latest message to new receivers.
 
         When `True`, every time a new receiver is created with `new_receiver`, it will
-        automatically get sent the latest value on the channel.  This allows new
-        receivers on slow streams to get the latest value as soon as they are created,
+        automatically get sent the latest message on the channel.  This allows new
+        receivers on slow streams to get the latest message as soon as they are created,
         without having to wait for the next message on the channel to arrive.
 
         It is safe to be set in data/reporting channels, but is not recommended for use
@@ -419,9 +419,9 @@ def __len__(self) -> int:
         return len(self._q)
 
     async def ready(self) -> bool:
-        """Wait until the receiver is ready with a value or an error.
+        """Wait until the receiver is ready with a message or an error.
 
-        Once a call to `ready()` has finished, the value should be read with
+        Once a call to `ready()` has finished, the message should be read with
         a call to `consume()` (`receive()` or iterated over). The receiver will
         remain ready (this method will return immediately) until it is
         consumed.
@@ -447,10 +447,10 @@ async def ready(self) -> bool:
         # pylint: enable=protected-access
 
     def consume(self) -> _T:
-        """Return the latest value once `ready` is complete.
+        """Return the latest message once `ready` is complete.
 
         Returns:
-            The next value that was received.
+            The next message that was received.
 
         Raises:
             ReceiverStoppedError: If there is some problem with the receiver.

src/frequenz/channels/_exceptions.py

@@ -50,8 +50,8 @@
     channel = Anycast[int](name="test-channel")
     receiver = channel.new_receiver()
 
-    async for value in receiver:
-        print(value)
+    async for message in receiver:
+        print(message)
     try:
         await receiver.receive()
     except ReceiverStoppedError as error:

src/frequenz/channels/_merge.py

@@ -17,8 +17,8 @@
 receiver1 = channel1.new_receiver()
 receiver2 = channel2.new_receiver()
 
-async for value in merge(receiver1, receiver2):
-    print(value)
+async for message in merge(receiver1, receiver2):
+    print(message)
 ```
 
 If the first message comes from `channel2` and the second message from `channel1`, the
@@ -135,9 +135,9 @@ async def stop(self) -> None:
         self._pending = set()
 
     async def ready(self) -> bool:
-        """Wait until the receiver is ready with a value or an error.
+        """Wait until the receiver is ready with a message or an error.
 
-        Once a call to `ready()` has finished, the value should be read with
+        Once a call to `ready()` has finished, the message should be read with
         a call to `consume()` (`receive()` or iterated over). The receiver will
         remain ready (this method will return immediately) until it is
         consumed.
@@ -171,10 +171,10 @@ async def ready(self) -> bool:
                 )
 
     def consume(self) -> _T:
-        """Return the latest value once `ready` is complete.
+        """Return the latest message once `ready` is complete.
 
         Returns:
-            The next value that was received.
+            The next message that was received.
 
         Raises:
             ReceiverStoppedError: If the receiver stopped producing messages.