wip dosctring

streamable/stream.py

@@ -326,16 +326,17 @@ def group(
         """
         Yields upstream elements grouped into lists.
 
-        Each group will contain up to `size` elements for which `by` returns the same value, but it may contain fewer elements in the following cases:
-        - `interval` seconds have passed since the last group was yielded
-        - The upstream source is exhausted
-        - The upstream source raises an exception
+        A group is yielded as soon as one of the following conditions is met:
+        - The group reaches `size` elements.
+        - `interval` seconds have passed since the last group was yielded.
+        - The upstream source is exhausted.
+
+        If `by` is specified, a group will contain only elements for which `by` returns the same value (see also the `.groupby` operation).
 
         Args:
             size (Optional[int], optional): Maximum number of elements per group. (by default: no limit on the size of the group)
             interval (float, optional): Yields a group if `interval` seconds have passed since the last group was yielded. (by default: no limit on the time interval between yields)
-            by (Optional[Callable[[T], Any]], optional): If specified, a group will only contain elements for which this function returns the same value. (by default: does not cogroup)
-
+            by (Optional[Callable[[T], Any]], optional): If specified, determines the group key. A group will only contain elements that share the same by(elem) value. (Default: does not co-group elements.)
         Returns:
             Stream[List[T]]: A stream of upstream elements grouped into lists.
         """
@@ -350,17 +351,17 @@ def groupby(
         interval: Optional[datetime.timedelta] = None,
     ) -> "Stream[Tuple[U, List[T]]]":
         """
-        Yields elements grouped by a key as `(key, elements)` tuples.
+        Yields upstream elements grouped by a key as `(key, elements)` tuples.
 
-        Each group will contain up to `size` elements, but it may contain fewer elements in the following cases:
-        - `interval` seconds have passed since the last group was yielded
-        - The upstream source is exhausted
-        - The upstream source raises an exception
+        A group is yielded as soon as one of the following conditions is met:
+        - The group reaches `size` elements.
+        - `interval` seconds have passed since the last group was yielded.
+        - The upstream source is exhausted.
 
         Args:
-            key (Callable[[T], Any]): A function that returns the group key for an element.
-            size (Optional[int], optional): Maximum number of elements per group. (by default: no limit on the size of the group)
-            interval (float, optional): Yields a group if `interval` seconds have passed since the last group was yielded. (by default: no limit on the time interval between yields)
+            key (Callable[[T], U]): A function that returns the group key for an element.
+            size (Optional[int], optional): The maximum number of elements per group (default: no size limit).
+            interval (Optional[datetime.timedelta], optional): If specified, yields a group if `interval` seconds have passed since the last group was yielded (default: no time interval limit).
 
         Returns:
             Stream[Tuple[U, List[T]]]: A stream of upstream elements grouped by key, as `(key, elements)` tuples.