From 249ebef99f47ac331dce54e2c1791703f2f387c3 Mon Sep 17 00:00:00 2001 From: Solarboaters <354059055+Solarboaters@users.noreply.github.com> Date: Wed, 18 Nov 2026 07:49:11 +0000 Subject: [PATCH] Document zero-timeout BufferedReader polling with tests --- can/listener.py | 7 +++++-- doc/changelog.d/1919.changed.rst | 2 ++ doc/notifier.rst | 9 +++++++++ test/listener_test.py | 26 ++++++++++++++++++++++++++ 4 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 doc/changelog.d/1919.changed.rst diff --git a/can/listener.py b/can/listener.py index 5616f110a..e1b0bae8f 100644 --- a/can/listener.py +++ b/can/listener.py @@ -90,7 +90,7 @@ def __init__(self) -> None: def on_message_received(self, msg: Message) -> None: """Append a message to the buffer. - :raises: BufferError + :raises: RuntimeError if the reader has already been stopped """ if self.is_stopped: @@ -103,9 +103,12 @@ def get_message(self, timeout: float = 0.5) -> Message | None: Attempts to retrieve the message that has been in the queue for the longest amount of time (FIFO). If no message is available, it blocks for given timeout or until a message is received (whichever is shorter), or else returns None. This method does - not block after :meth:`can.BufferedReader.stop` has been called. + not block after :meth:`can.BufferedReader.stop` has been called; queued + messages can still be retrieved until the queue is empty. :param timeout: The number of seconds to wait for a new message. + Use ``0`` to return immediately with the oldest queued message, + or ``None`` if no message is available. :return: the received :class:`can.Message` or `None`, if the queue is empty. """ try: diff --git a/doc/changelog.d/1919.changed.rst b/doc/changelog.d/1919.changed.rst new file mode 100644 index 000000000..90335539f --- /dev/null +++ b/doc/changelog.d/1919.changed.rst @@ -0,0 +1,2 @@ +Clarify non-blocking polling with BufferedReader.get_message(timeout=0), +and correct the documented exception when adding to a stopped reader. diff --git a/doc/notifier.rst b/doc/notifier.rst index e1b160a6e..db1273827 100644 --- a/doc/notifier.rst +++ b/doc/notifier.rst @@ -73,6 +73,15 @@ readers are also documented here. BufferedReader -------------- +Pass ``timeout=0`` to poll a buffered reader without waiting for a message:: + + message = reader.get_message(timeout=0) + if message is not None: + print(message) + +This removes the oldest queued message, if any. An empty queue returns ``None`` +without waiting. A stopped reader can still be drained in the same way. + .. autoclass:: can.BufferedReader :members: diff --git a/test/listener_test.py b/test/listener_test.py index 77fd0d2e0..2baf7b848 100644 --- a/test/listener_test.py +++ b/test/listener_test.py @@ -159,6 +159,32 @@ def testBufferedListenerReceives(self): self.assertIsNotNone(a_listener.get_message(0.1)) +class BufferedReaderPollingTest(unittest.TestCase): + def test_zero_timeout_returns_none_when_empty(self): + reader = can.BufferedReader() + self.assertIsNone(reader.get_message(timeout=0)) + + def test_zero_timeout_drains_messages_in_order(self): + reader = can.BufferedReader() + first = can.Message(arbitration_id=1) + second = can.Message(arbitration_id=2) + reader(first) + reader(second) + self.assertIs(reader.get_message(timeout=0), first) + self.assertIs(reader.get_message(timeout=0), second) + self.assertIsNone(reader.get_message(timeout=0)) + + def test_stopped_reader_drains_without_waiting(self): + reader = can.BufferedReader() + message = can.Message(arbitration_id=1) + reader(message) + reader.stop() + self.assertIs(reader.get_message(timeout=0), message) + self.assertIsNone(reader.get_message(timeout=0)) + with self.assertRaises(RuntimeError): + reader(message) + + def test_deprecated_loop_arg(recwarn): try: loop = asyncio.get_running_loop()