Add timeseries.Source and Sink types

All tools provided by this package should be steps in a pipeline that
takes Source as input and produces values in a Sink.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/sdk/timeseries/__init__.py

@@ -5,17 +5,22 @@
 Handling of timeseries streams.
 
 A timeseries is a stream (normally an async iterator) of
-[samples][frequenz.sdk.timeseries.Sample].
+[`Sample`][frequenz.sdk.timeseries.Sample]s.
 
-This module provides tools to operate on timeseries.
+Timeseries can be consumed from
+[`Source`][frequenz.sdk.timeseries.Source]s and new timeseries can be
+generated by sending samples to
+a [`Sink`][frequenz.sdk.timeseries.Sink]
 """
 
-from ._base_types import Sample
+from ._base_types import Sample, Sink, Source
 from ._resampler import GroupResampler, Resampler, ResamplingFunction
 
 __all__ = [
     "GroupResampler",
     "Resampler",
     "ResamplingFunction",
     "Sample",
+    "Sink",
+    "Source",
 ]

src/frequenz/sdk/timeseries/_base_types.py

@@ -5,7 +5,7 @@
 
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Optional
+from typing import AsyncIterator, Callable, Coroutine, Optional
 
 
 @dataclass(frozen=True)
@@ -19,3 +19,27 @@ class Sample:
 
     timestamp: datetime
     value: Optional[float] = None
+
+
+Source = AsyncIterator[Sample]
+"""A source for a timeseries.
+
+A timeseries can be received sample by sample in a streaming way
+using a source.
+"""
+
+Sink = Callable[[Sample], Coroutine[None, None, None]]
+"""A sink for a timeseries.
+
+A new timeseries can be generated by sending samples to a sink.
+
+This should be an `async` callable, for example:
+
+``` python
+async some_sink(Sample) -> None:
+    ...
+```
+
+Args:
+    sample (Sample): A sample to be sent out.
+"""