|
1 | 1 | # License: MIT |
2 | 2 | # Copyright © 2025 Frequenz Energy-as-a-Service GmbH |
3 | 3 |
|
4 | | -"""The GroupingLatestValueCache caches the latest values in a receiver grouped by key. |
5 | | -
|
6 | | -It provides a way to look up on demand, the latest value in a stream for any key, as |
7 | | -long as there has been at least one value received for that key. |
8 | | -
|
9 | | -[GroupingLatestValueCache][frequenz.channels.experimental.GroupingLatestValueCache] |
10 | | -takes a [Receiver][frequenz.channels.Receiver] and a `key` function as arguments and |
11 | | -stores the latest value received by that receiver for each key separately. |
12 | | -
|
13 | | -The `GroupingLatestValueCache` implements the [`Mapping`][collections.abc.Mapping] |
14 | | -interface, so it can be used like a dictionary. It is not |
15 | | -a [`MutableMapping`][collections.abc.MutableMapping] because users can't mutate the |
16 | | -cache directly, it is only mutated by the underlying receiver. There is one exception |
17 | | -though, users can clear individual keys from the cache using the |
18 | | -[clear][frequenz.channels.experimental.GroupingLatestValueCache.clear] method. |
19 | | -
|
20 | | -Example: |
21 | | - ```python |
22 | | - from frequenz.channels import Broadcast |
23 | | - from frequenz.channels.experimental import GroupingLatestValueCache |
24 | | -
|
25 | | - channel = Broadcast[tuple[int, str]](name="lvc_test") |
26 | | -
|
27 | | - cache = GroupingLatestValueCache(channel.new_receiver(), key=lambda x: x[0]) |
28 | | - sender = channel.new_sender() |
29 | | -
|
30 | | - assert cache.get(6) is None |
31 | | - assert 6 not in cache |
32 | | -
|
33 | | - await sender.send((6, "twenty-six")) |
34 | | -
|
35 | | - assert 6 in cache |
36 | | - assert cache.get(6) == (6, "twenty-six") |
37 | | -
|
38 | | - await cache.stop() |
39 | | - ``` |
40 | | -""" |
| 4 | +"""The GroupingLatestValueCache caches the latest values in a receiver grouped by key.""" |
41 | 5 |
|
42 | 6 |
|
43 | 7 | import asyncio |
|
59 | 23 |
|
60 | 24 |
|
61 | 25 | class GroupingLatestValueCache(Mapping[HashableT, ValueT_co]): |
62 | | - """A cache that stores the latest value in a receiver, grouped by key.""" |
| 26 | + """A cache that stores the latest value in a receiver, grouped by key. |
| 27 | +
|
| 28 | + It provides a way to look up on demand, the latest value in a stream for any key, as |
| 29 | + long as there has been at least one value received for that key. |
| 30 | +
|
| 31 | + [GroupingLatestValueCache][frequenz.channels.experimental.GroupingLatestValueCache] |
| 32 | + takes a [Receiver][frequenz.channels.Receiver] and a `key` function as arguments and |
| 33 | + stores the latest value received by that receiver for each key separately. |
| 34 | +
|
| 35 | + The `GroupingLatestValueCache` implements the [`Mapping`][collections.abc.Mapping] |
| 36 | + interface, so it can be used like a dictionary. It is not |
| 37 | + a [`MutableMapping`][collections.abc.MutableMapping] because users can't mutate the |
| 38 | + cache directly, it is only mutated by the underlying receiver. There is one exception |
| 39 | + though, users can clear individual keys from the cache using the |
| 40 | + [clear][frequenz.channels.experimental.GroupingLatestValueCache.clear] method. |
| 41 | +
|
| 42 | + Example: |
| 43 | + ```python |
| 44 | + from frequenz.channels import Broadcast |
| 45 | + from frequenz.channels.experimental import GroupingLatestValueCache |
| 46 | +
|
| 47 | + channel = Broadcast[tuple[int, str]](name="lvc_test") |
| 48 | +
|
| 49 | + cache = GroupingLatestValueCache(channel.new_receiver(), key=lambda x: x[0]) |
| 50 | + sender = channel.new_sender() |
| 51 | +
|
| 52 | + assert cache.get(6) is None |
| 53 | + assert 6 not in cache |
| 54 | +
|
| 55 | + await sender.send((6, "twenty-six")) |
| 56 | +
|
| 57 | + assert 6 in cache |
| 58 | + assert cache.get(6) == (6, "twenty-six") |
| 59 | +
|
| 60 | + await cache.stop() |
| 61 | + ``` |
| 62 | + """ |
63 | 63 |
|
64 | 64 | def __init__( |
65 | 65 | self, |
|
0 commit comments