Rename close() to aclose() in Broadcast and Anycast (frequenz-floss#408)

This is done to follow Python's convention. With this change now
channels can be used with the `aclosing()` context manager for example.

The name `close()` is still available for backwards compatibility, but
deprecated.

Fixes frequenz-floss#379.

Author: llucax

RELEASE_NOTES.md

@@ -7,6 +7,9 @@
 ## Upgrading
 
 - Some minimal dependencies have been bumped, so you might need to adjust your dependencies accordingly.
+- `Broadcast` and `Anycast` channels method `close()` was renamed to `aclose()` to follow Python's convention. With this change now channels can be used with the [`aclosing()`](https://docs.python.org/3/library/contextlib.html#contextlib.aclosing) context manager for example.
+
+   The name `close()` is still available for backwards compatibility, but it will be removed in the next major release, so it is recommended to switch to `aclose()`.
 
 ## New Features
 

benchmarks/benchmark_anycast.py

@@ -66,7 +66,7 @@ async def update_tracker_on_receive(chan: Receiver[int]) -> None:
 
     await asyncio.gather(*senders)
     for bcast in channels:
-        await bcast.close()
+        await bcast.aclose()
     await receivers_runs
     return recv_trackers[0]
 

benchmarks/benchmark_broadcast.py

@@ -84,7 +84,7 @@ async def update_tracker_on_receive(chan: Receiver[int]) -> None:
 
     await asyncio.gather(*senders)
     for bcast in channels:
-        await bcast.close()
+        await bcast.aclose()
     await receivers_runs
     recv_tracker = sum(recv_trackers)
     assert recv_tracker == num_messages * num_channels * num_receivers

src/frequenz/channels/_anycast.py

@@ -10,7 +10,7 @@
 from collections import deque
 from typing import Generic, TypeVar
 
-from typing_extensions import override
+from typing_extensions import deprecated, override
 
 from ._exceptions import ChannelClosedError
 from ._generic import ChannelMessageT
@@ -78,7 +78,7 @@ class Anycast(Generic[ChannelMessageT]):
     respectively.
 
     When the channel is not needed anymore, it should be closed with the
-    [`close()`][frequenz.channels.Anycast.close] method. This will prevent further
+    [`aclose()`][frequenz.channels.Anycast.aclose] method. This will prevent further
     attempts to [`send()`][frequenz.channels.Sender.send] data. Receivers will still be
     able to drain the pending messages on the channel, but after that, subsequent
     [`receive()`][frequenz.channels.Receiver.receive] calls will raise a
@@ -266,7 +266,7 @@ def limit(self) -> int:
         assert maxlen is not None
         return maxlen
 
-    async def close(self) -> None:
+    async def aclose(self) -> None:
         """Close the channel.
 
         Any further attempts to [send()][frequenz.channels.Sender.send] data
@@ -283,6 +283,11 @@ async def close(self) -> None:
         async with self._recv_cv:
             self._recv_cv.notify_all()
 
+    @deprecated("The close() method is deprecated, use aclose() instead")
+    async def close(self) -> None:  # noqa: D402
+        """Close the channel, deprecated alias for `aclose()`."""  # noqa: D402
+        return await self.aclose()
+
     def new_sender(self) -> Sender[ChannelMessageT]:
         """Return a new sender attached to this channel."""
         return _Sender(self)

src/frequenz/channels/_broadcast.py

@@ -11,7 +11,7 @@
 from collections import deque
 from typing import Generic, TypeVar
 
-from typing_extensions import override
+from typing_extensions import deprecated, override
 
 from ._exceptions import ChannelClosedError
 from ._generic import ChannelMessageT
@@ -65,7 +65,7 @@ class Broadcast(Generic[ChannelMessageT]):
     respectively.
 
     When a channel is not needed anymore, it should be closed with
-    [`close()`][frequenz.channels.Broadcast.close]. This will prevent further
+    [`aclose()`][frequenz.channels.Broadcast.aclose]. This will prevent further
     attempts to [`send()`][frequenz.channels.Sender.send] data, and will allow
     receivers to drain the pending items on their queues, but after that,
     subsequent [receive()][frequenz.channels.Receiver.receive] calls will
@@ -248,7 +248,7 @@ def is_closed(self) -> bool:
         """
         return self._closed
 
-    async def close(self) -> None:
+    async def aclose(self) -> None:
         """Close this channel.
 
         Any further attempts to [send()][frequenz.channels.Sender.send] data
@@ -264,6 +264,11 @@ async def close(self) -> None:
         async with self._recv_cv:
             self._recv_cv.notify_all()
 
+    @deprecated("The close() method is deprecated, use aclose() instead")
+    async def close(self) -> None:  # noqa: D402
+        """Close the channel, deprecated alias for `aclose()`."""  # noqa: D402
+        return await self.aclose()
+
     def new_sender(self) -> Sender[ChannelMessageT]:
         """Return a new sender attached to this channel."""
         return _Sender(self)