Skip to content

Commit d5d42c7

Browse files
committed
Move documentation from the module to the class
The module documentation is not being included in the rendered docs. Normally this is done by including it in the User Guide, but since this is an experimental module, we don't want to include it yet, so it is easier to just move the docs to the class so they are rendered in the API documentation. Signed-off-by: Leandro Lucarella <[email protected]>
1 parent 617c1cb commit d5d42c7

File tree

1 file changed

+38
-38
lines changed

1 file changed

+38
-38
lines changed

src/frequenz/channels/experimental/_grouping_latest_value_cache.py

Lines changed: 38 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,7 @@
11
# License: MIT
22
# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
33

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."""
415

426

437
import asyncio
@@ -59,7 +23,43 @@
5923

6024

6125
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+
"""
6363

6464
def __init__(
6565
self,

0 commit comments

Comments
 (0)