From 94886eaa4e9c002272ab9db6668a97ff73f3ab6e Mon Sep 17 00:00:00 2001
From: Antoine Beyeler <49431240+abey79@users.noreply.github.com>
Date: Wed, 14 Aug 2024 16:23:59 +0200
Subject: [PATCH] Add columnar APIs to the Python docs (#7183)
### What
This PR adds the columnar API to the python docs.
I had to rename the `send_columns.py` file to `_send_columns.py`,
because:
- `rerun.send_columns` is ambiguous (is that the submodule or the
function that `__init__.py` re-exports?
- mkdocs is thus confused
- all such module (aka whose content is reexported in the top `rerun`
namespace) should be named as private (leading `_`)
Also added/modified a few docstrings to make the docs nicer.
Edit:
- also had to reexport `ComponentColumn` and add it to the index for the
build to pass.
### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested the web demo (if applicable):
* Using examples from latest `main` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/7183?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/7183?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG
* [x] If applicable, add a new check to the [release
checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)!
* [x] If have noted any breaking changes to the log API in
`CHANGELOG.md` and the migration guide
- [PR Build Summary](https://build.rerun.io/pr/7183)
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)
To run all checks from `main`, comment on the PR with `@rerun-bot
full-check`.
---
rerun_py/docs/gen_common_index.py | 17 +++++-
rerun_py/rerun_sdk/rerun/__init__.py | 15 +++---
rerun_py/rerun_sdk/rerun/_baseclasses.py | 2 +-
.../{send_columns.py => _send_columns.py} | 54 +++++++++++++++----
4 files changed, 71 insertions(+), 17 deletions(-)
rename rerun_py/rerun_sdk/rerun/{send_columns.py => _send_columns.py} (82%)
diff --git a/rerun_py/docs/gen_common_index.py b/rerun_py/docs/gen_common_index.py
index 83e2e5757341..db8490543894 100755
--- a/rerun_py/docs/gen_common_index.py
+++ b/rerun_py/docs/gen_common_index.py
@@ -113,6 +113,17 @@ class Section:
"reset_time",
],
),
+ Section(
+ title="Columnar API",
+ func_list=[
+ "send_columns",
+ ],
+ class_list=[
+ "TimeNanosColumn",
+ "TimeSecondsColumn",
+ "TimeSequenceColumn",
+ ],
+ ),
################################################################################
# These sections don't have tables, but generate pages containing all the archetypes, components, datatypes
Section(
@@ -227,7 +238,11 @@ class Section:
Section(
title="Interfaces",
mod_path="rerun",
- class_list=["AsComponents", "ComponentBatchLike"],
+ class_list=[
+ "AsComponents",
+ "ComponentBatchLike",
+ "ComponentColumn",
+ ],
default_filters=False,
),
################################################################################
diff --git a/rerun_py/rerun_sdk/rerun/__init__.py b/rerun_py/rerun_sdk/rerun/__init__.py
index 2d192e51f373..933df96bbd3f 100644
--- a/rerun_py/rerun_sdk/rerun/__init__.py
+++ b/rerun_py/rerun_sdk/rerun/__init__.py
@@ -22,6 +22,9 @@
experimental as experimental,
notebook as notebook,
)
+from ._baseclasses import (
+ ComponentColumn as ComponentColumn,
+)
from ._image_encoded import (
ImageEncoded as ImageEncoded,
ImageFormat as ImageFormat,
@@ -37,6 +40,12 @@
log_file_from_path as log_file_from_path,
new_entity_path as new_entity_path,
)
+from ._send_columns import (
+ TimeNanosColumn as TimeNanosColumn,
+ TimeSecondsColumn as TimeSecondsColumn,
+ TimeSequenceColumn as TimeSequenceColumn,
+ send_columns as send_columns,
+)
from .any_value import (
AnyValues as AnyValues,
)
@@ -139,12 +148,6 @@
script_setup as script_setup,
script_teardown as script_teardown,
)
-from .send_columns import (
- TimeNanosColumn as TimeNanosColumn,
- TimeSecondsColumn as TimeSecondsColumn,
- TimeSequenceColumn as TimeSequenceColumn,
- send_columns as send_columns,
-)
from .sinks import (
connect as connect,
disconnect as disconnect,
diff --git a/rerun_py/rerun_sdk/rerun/_baseclasses.py b/rerun_py/rerun_sdk/rerun/_baseclasses.py
index 894be2e01297..447d58f67b56 100644
--- a/rerun_py/rerun_sdk/rerun/_baseclasses.py
+++ b/rerun_py/rerun_sdk/rerun/_baseclasses.py
@@ -269,7 +269,7 @@ def as_arrow_array(self) -> pa.Array:
class ComponentColumn:
"""
- A column of components that can be send using `send_columns`.
+ A column of components that can be sent using `send_columns`.
This is represented by a ComponentBatch array that has been repartitioned into multiple segments.
This is useful for reinterpreting a single contiguous batch as multiple sub-batches
diff --git a/rerun_py/rerun_sdk/rerun/send_columns.py b/rerun_py/rerun_sdk/rerun/_send_columns.py
similarity index 82%
rename from rerun_py/rerun_sdk/rerun/send_columns.py
rename to rerun_py/rerun_sdk/rerun/_send_columns.py
index 0dd7cc714bb6..945c1e3d8349 100644
--- a/rerun_py/rerun_sdk/rerun/send_columns.py
+++ b/rerun_py/rerun_sdk/rerun/_send_columns.py
@@ -27,14 +27,26 @@ class TimeSequenceColumn(TimeColumnLike):
"""
A column of time values that are represented as an integer sequence.
- Equivalent to `rr.set_time_sequence`.
+ Columnar equivalent to [`rerun.set_time_sequence`][rerun.set_time_sequence].
"""
def __init__(self, timeline: str, times: Iterable[int]):
+ """
+ Create a column of integer sequence time values.
+
+ Parameters
+ ----------
+ timeline:
+ The name of the timeline.
+ times:
+ An iterable of integer time values.
+
+ """
self.timeline = timeline
self.times = times
def timeline_name(self) -> str:
+ """Returns the name of the timeline."""
return self.timeline
def as_arrow_array(self) -> pa.Array:
@@ -43,16 +55,28 @@ def as_arrow_array(self) -> pa.Array:
class TimeSecondsColumn(TimeColumnLike):
"""
- A column of time values that are represented as an floating point seconds.
+ A column of time values that are represented as floating point seconds.
- Equivalent to `rr.set_time_seconds`.
+ Columnar equivalent to [`rerun.set_time_seconds`][rerun.set_time_seconds].
"""
def __init__(self, timeline: str, times: Iterable[float]):
+ """
+ Create a column of floating point seconds time values.
+
+ Parameters
+ ----------
+ timeline:
+ The name of the timeline.
+ times:
+ An iterable of floating point second time values.
+
+ """
self.timeline = timeline
self.times = times
def timeline_name(self) -> str:
+ """Returns the name of the timeline."""
return self.timeline
def as_arrow_array(self) -> pa.Array:
@@ -61,16 +85,28 @@ def as_arrow_array(self) -> pa.Array:
class TimeNanosColumn(TimeColumnLike):
"""
- A column of time values that are represented as an integer nanoseconds.
+ A column of time values that are represented as integer nanoseconds.
- Equivalent to `rr.set_time_nanos`.
+ Columnar equivalent to [`rerun.set_time_nanos`][rerun.set_time_nanos].
"""
def __init__(self, timeline: str, times: Iterable[int]):
+ """
+ Create a column of integer nanoseconds time values.
+
+ Parameters
+ ----------
+ timeline:
+ The name of the timeline.
+ times:
+ An iterable of integer nanosecond time values.
+
+ """
self.timeline = timeline
self.times = times
def timeline_name(self) -> str:
+ """Returns the name of the timeline."""
return self.timeline
def as_arrow_array(self) -> pa.Array:
@@ -89,7 +125,7 @@ def send_columns(
strict: bool | None = None,
) -> None:
r"""
- Directly log a columns of data to Rerun.
+ Send columnar data to Rerun.
Unlike the regular `log` API, which is row-oriented, this API lets you submit the data
in a columnar form. Each `TimeColumnLike` and `ComponentColumnLike` object represents a column
@@ -101,7 +137,7 @@ def send_columns(
Furthermore, this will _not_ inject the default timelines `log_tick` and `log_time` timeline columns.
When using a regular `ComponentBatch` input, the batch data will map to single-valued component
- instance at each timepoint.
+ instances at each timepoint.
For example, scalars would be logged as:
```py
@@ -145,8 +181,8 @@ def send_columns(
See for more on entity paths.
times:
The time values of this batch of data. Each `TimeColumnLike` object represents a single column
- of timestamps. Generally you should use one of the provided classes: [`TimeSequenceColumn`][],
- [`TimeSecondsColumn`][], or [`TimeNanosColumn`][].
+ of timestamps. Generally, you should use one of the provided classes: [`TimeSequenceColumn`][rerun.TimeSequenceColumn],
+ [`TimeSecondsColumn`][rerun.TimeSecondsColumn], or [`TimeNanosColumn`][rerun.TimeNanosColumn].
components:
The columns of components to log. Each object represents a single column of data.