The Rerun Python Log SDK.

Goal: an ergonomic Python library for logging rich data, over TCP, to a rerun server.

ℹ️ Note:

• The rust crate is called re_sdk_python, while the Python library is called rerun_sdk.
• These instructions assume you're running from the rerun root folder and have Python 3.7 or later available.

Simply build and install

To build from source and install the rerun_sdk into your current Python environment run:

python3 -m pip install --upgrade pip
pip3 install "./rerun_py"

ℹ️ Note:

• If you are unable to upgrade pip to version >=21.3, you need to pass --use-feature=in-tree-build to the pip3 install command.

Usage

See USAGE.md.

Running the example code

python examples/car/main.py

By default, the example runs Rerun in buffered mode, in the same process as the example code. This means all logged data is buffered until rerun_sdk.show() is called in the end, which shows the viewer and blocks until the viewer is closed.

Development

To set up a new virtualenv for development:

just py-dev-env
# For bash/zsh users:
source venv/bin/activate
# Or if you're using fish:
source venv/bin/activate.fish

Build, test, and run

For ease of development you can build and install in "editable" mode. This means you can edit the rerun_sdk Python code without having to re-build and install to see changes.

# Build the SDK and install in develop mode into the virtualenv
# Re-run this if the Rust code has changed!
just py-build

Test

# Run the unit tests
just py-test

# Run the linting checks
just py-lint

# Run an example
python examples/car/main.py

Logging and viewing in different processes

Rerun can also be run in non-blocking mode with viewer and logger in different processes.

In one terminal, start up a viewer with a server that the SDK can connect to:

cargo run -p rerun --release

In a second terminal, run the example with the --connect option:

examples/car/main.py --connect

Building an installable Python Wheel

The Python bindings to the core Rust library are built using https://github.com/PyO3/pyo3.

To build an installable Python wheel run:

pip install -r rerun_py/requirements-build.txt
maturin build -m rerun_py/Cargo.toml --release

By default the wheels will be built to target/wheels (use the -o flag to set a different output directory).

Now you can install rerun_sdk in any Python3 environment using:

pip3 install target/wheels/*.whl

Troubleshooting

You can run with RUST_LOG=debug to get more output out of the rerun SDK.

If you are using an Apple-silicon Mac, make sure rustc -vV outputs host: aarch64-apple-darwin. If not, this should fix it:

rustup set default-host aarch64-apple-darwin && rustup install 1.65

If you want to switch back, this is how:

rustup set default-host x86_64-apple-darwin && rustup install 1.65