diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 96a0240b..2583be48 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,16 +2,4 @@ ## Summary - - -## Upgrading - - - -## New Features - - - -## Bug Fixes - - +This release improves the documentation on `Receiver.filter`. diff --git a/docs/_scripts/macros.py b/docs/_scripts/macros.py index e316cc22..85600826 100644 --- a/docs/_scripts/macros.py +++ b/docs/_scripts/macros.py @@ -6,8 +6,7 @@ from typing import Any import markdown as md -from griffe import Object -from griffe.collections import ModulesCollection +from griffe import ModulesCollection, Object from markdown.extensions import toc from mkdocs_macros import plugin as macros from mkdocstrings_handlers.python.handler import PythonHandler diff --git a/src/frequenz/channels/_receiver.py b/src/frequenz/channels/_receiver.py index dbb533f3..c01c8102 100644 --- a/src/frequenz/channels/_receiver.py +++ b/src/frequenz/channels/_receiver.py @@ -55,6 +55,25 @@ [`map()`][frequenz.channels.Receiver.map] returns a new full receiver, so you can use it in any of the ways described above. +# Message Filtering + +If you need to filter the received messages, receivers provide a +[`filter()`][frequenz.channels.Receiver.filter] method to easily do so: + +```python show_lines="6:" +from frequenz.channels import Anycast + +channel = Anycast[int](name="test-channel") +receiver = channel.new_receiver() + +async for message in receiver.filter(lambda x: x % 2 == 0): + print(message) # Only even numbers will be printed +``` + +As with [`map()`][frequenz.channels.Receiver.map], +[`filter()`][frequenz.channels.Receiver.filter] returns a new full receiver, so you can +use it in any of the ways described above. + # Error Handling !!! Tip inline end @@ -254,10 +273,11 @@ def filter( original receiver and use that instead. Args: - filter_function: The function to be applied on incoming messages. + filter_function: The function to be applied on incoming messages to + determine if they should be received. Returns: - A new receiver that applies the function on the received messages. + A new receiver that only receives messages that pass the filter. """ return _Filter(receiver=self, filter_function=filter_function)