rpy-bridge Usage

rpy-bridge is a Python-controlled R execution orchestrator (not a thin rpy2 wrapper). It handles headless-safe R startup, project-root inference, out-of-tree renv activation, isolated script namespaces, and Python↔R conversion with dtype/NA normalization.

—

Getting Started

Installation

Prerequisites

  • System R installed and available on PATH (rpy2 requires a working R installation).

  • Python 3.11+ (tested on 3.11–3.12)

From PyPI:

python3 -m pip install rpy-bridge rpy2

Using uv package manager:

uv add rpy-bridge rpy2

—

Quickstart examples

Call a package function (no scripts):

from rpy_bridge import RFunctionCaller

rfc = RFunctionCaller()
samples = rfc.call("stats::rnorm", 5, mean=0, sd=1)
median_val = rfc.call("stats::median", samples)

Call a script function with renv activation (out-of-tree allowed):

from pathlib import Path
from rpy_bridge import RFunctionCaller

project = Path("/path/to/project")
script = project / "scripts" / "example.R"

rfc = RFunctionCaller(path_to_renv=project, scripts=script)
result = rfc.call("some_function", 42, named_arg="value")

See the full working examples in examples/basic_usage.py:

—

RFunctionCaller

class RFunctionCaller(path_to_renv: str | Path | None = None, scripts: str | Path | list[str | Path] | None = None, packages: str | list[str] | None = None)

Provides a Python interface to R scripts, functions, and environments.

Args:

  • path_to_renv (str | Path, optional): Directory containing a renv environment.

  • scripts (Path | str | list[Path] | list[str], optional): R scripts or directories to load.

  • packages (str | list[str], optional): R packages to load.

Raises:

  • FileNotFoundError: If a script path does not exist

  • RuntimeError: If R is not found or rpy2 is missing

Core Methods

call(func_name, *args, **kwargs)

Call an R function from a script, package, or global environment.

Args:
  • func_name (str): Name of the R function. Can be:

    • ‘function_name’ for functions in scripts or global env

    • ‘package::function_name’ for package functions

  • *args: Positional arguments for the R function

  • **kwargs: Keyword arguments for the R function

Returns:

Any: Python object corresponding to R return value.

Raises:

ValueError: Function not found RuntimeError: Function call failed in R

—

list_namespaces()

Return a list of all loaded script namespaces.

namespaces = rfc.list_namespaces()

—

list_namespace_functions(namespace)

List callable functions in a specific script namespace.

funcs = rfc.list_namespace_functions("script1")

—

print_function_tree(include_packages=False, max_display=10)

Pretty-print functions from loaded scripts and optionally packages. Example usage:

rfc.print_function_tree(include_packages=False, max_display=5)

Example output:

script1/
  add_numbers
  multiply_numbers
  ...
script2/
  divide_numbers
  subtract_numbers
  ...

—

Troubleshooting

R Not Found

  • Ensure R is installed and on PATH

  • Set R_HOME explicitly if R is installed in a non-default location

Function Not Found

  • Check that the script has been loaded

  • Use list_namespaces() and list_namespace_functions() to inspect

  • For package functions, use package::function syntax

Data Conversion Issues

  • Missing values in R map to None or pd.NA

  • Use clean_r_dataframe() or fix_r_dataframe_types() as needed

  • For dtype alignment, see normalize_dtypes / compare_r_py_dataframes

CI and headless tips

  • Headless defaults are applied automatically; avoid GUI probing in CI

  • To skip renv when R is absent in CI, set RPY_BRIDGE_SKIP_RENV=1

Logging

  • Logs emit through the Python logging stdlib with a dedicated [RFunctionCaller] handler

  • Adjust log level globally via stdlib logging configuration in your app

—

Examples Folder

See the examples in the repository:

  • examples/basic_usage.py — Loading scripts and calling functions

  • examples/renv_usage.py — Working with renv environments

  • examples/advanced_usage.py — More advanced examples and other features