rpy-bridge 0.3.9__py3-none-any.whl → 0.5.0__py3-none-any.whl

rpy_bridge/logging.py

@@ -0,0 +1,50 @@
+"""
+Logging utilities for rpy-bridge.
+
+Sets up a loguru-backed logger (fallback to the stdlib logger) and a dedicated
+[RFunctionCaller] sink used throughout the package.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from loguru import Logger as LoguruLogger
+
+    LoggerType = LoguruLogger | logging.Logger
+else:  # pragma: no cover - runtime does not need the alias
+    LoggerType = None
+
+try:
+    from loguru import logger as loguru_logger  # type: ignore
+
+    logger = loguru_logger
+except ImportError:  # pragma: no cover - fallback when loguru is absent
+    logging.basicConfig()
+    logger = logging.getLogger("rpy-bridge")
+
+# Remove default handler to override global default
+logger.remove()
+
+# Add a sink for RFunctionCaller logs
+_rfc_logger = logger.bind(tag="[RFunctionCaller]")
+_rfc_logger.add(
+    sys.stderr,
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}",
+    level="INFO",
+)
+
+
+def log_r_call(func_name: str, source_info: str) -> None:
+    """Log an R function call with minimal noise."""
+    _rfc_logger.opt(depth=1, record=False).info(
+        "[rpy-bridge.RFunctionCaller] Called R function '{}' from {}",
+        func_name,
+        source_info,
+    )
+
+
+__all__ = ["logger", "_rfc_logger", "log_r_call", "LoggerType"]

rpy_bridge/renv.py

@@ -0,0 +1,149 @@
+"""
+Helpers for locating project roots and activating renv environments.
+
+These utilities are shared by RFunctionCaller and exposed for compatibility.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .logging import logger
+from .rpy2_loader import ensure_rpy2
+
+
+def normalize_scripts(scripts: str | Path | list[str | Path] | None) -> list[Path]:
+    """
+    Normalize script inputs to a list of resolved Paths.
+    """
+    if scripts is None:
+        return []
+    if isinstance(scripts, (str, Path)):
+        return [Path(scripts).resolve()]
+    try:
+        return [Path(s).resolve() for s in scripts]
+    except TypeError as exc:
+        raise TypeError(
+            f"Invalid type for 'scripts': {type(scripts)}. Must be str, Path, or list/iterable thereof."
+        ) from exc
+
+
+def candidate_project_dirs(base: Path, depth: int = 3) -> list[Path]:
+    return [base] + list(base.parents)[:depth]
+
+
+def has_root_marker(path: Path) -> bool:
+    if (path / ".git").exists():
+        return True
+    if any(path.glob("*.Rproj")):
+        return True
+    if (path / ".here").exists():
+        return True
+    if (path / "DESCRIPTION").exists():
+        return True
+    if (path / "renv.lock").exists():
+        return True
+    return False
+
+
+def find_project_root(path_to_renv: Path | None, scripts: list[Path]) -> Path | None:
+    bases: list[Path] = []
+    if scripts:
+        bases.extend(candidate_project_dirs(scripts[0].parent))
+    if path_to_renv is not None:
+        bases.extend(candidate_project_dirs(path_to_renv))
+
+    seen = set()
+    for cand in bases:
+        resolved = cand.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        if has_root_marker(resolved):
+            return resolved
+    return None
+
+
+def activate_renv(path_to_renv: Path) -> None:
+    r = ensure_rpy2()
+    robjects = r["robjects"]
+
+    path_to_renv = Path(path_to_renv).resolve()
+
+    def _candidates(base: Path) -> list[Path]:
+        return [base] + list(base.parents)[:3]
+
+    project_dir = None
+    renv_dir = None
+    renv_activate = None
+    renv_lock = None
+
+    for cand in _candidates(path_to_renv):
+        cand_is_renv = cand.name == "renv" and (cand / "activate.R").exists()
+        if cand_is_renv:
+            rd = cand
+            pd = cand.parent
+        else:
+            rd = cand / "renv"
+            pd = cand
+
+        activate_path = rd / "activate.R"
+        lock_path = pd / "renv.lock"
+        if not lock_path.exists():
+            alt_lock = rd / "renv.lock"
+            if alt_lock.exists():
+                lock_path = alt_lock
+
+        if activate_path.exists() and lock_path.exists():
+            project_dir = pd
+            renv_dir = rd
+            renv_activate = activate_path
+            renv_lock = lock_path
+            break
+
+    if renv_dir is None or renv_activate is None or renv_lock is None:
+        raise FileNotFoundError(
+            f"[Error] renv environment incomplete: activate.R or renv.lock not found near {path_to_renv}"
+        )
+
+    renviron_file = project_dir / ".Renviron"
+    if renviron_file.is_file():
+        os.environ["R_ENVIRON_USER"] = str(renviron_file)
+        logger.info(f"[rpy-bridge] R_ENVIRON_USER set to: {renviron_file}")
+
+    rprofile_file = project_dir / ".Rprofile"
+    if rprofile_file.is_file():
+        try:
+            robjects.r(
+                f'old_wd <- getwd(); setwd("{project_dir.as_posix()}"); '
+                f"on.exit(setwd(old_wd), add = TRUE); "
+                f'source("{rprofile_file.as_posix()}")'
+            )
+            logger.info(f"[rpy-bridge] .Rprofile sourced: {rprofile_file}")
+        except Exception as exc:  # pragma: no cover - defensive fallback
+            logger.warning(
+                "[rpy-bridge] Failed to source .Rprofile; falling back to renv::activate(): %s",
+                exc,
+            )
+
+    try:
+        robjects.r("suppressMessages(library(renv))")
+    except Exception:
+        logger.info("[rpy-bridge] Installing renv package in project library...")
+        robjects.r(
+            f'install.packages("renv", repos="https://cloud.r-project.org", lib="{renv_dir / "library"}")'
+        )
+        robjects.r("library(renv)")
+
+    robjects.r(f'renv::load("{project_dir.as_posix()}")')
+    logger.info(f"[rpy-bridge] renv environment loaded for project: {project_dir}")
+
+
+__all__ = [
+    "activate_renv",
+    "normalize_scripts",
+    "candidate_project_dirs",
+    "has_root_marker",
+    "find_project_root",
+]

rpy_bridge/rpy2_loader.py

@@ -0,0 +1,71 @@
+"""
+Lazy loader for rpy2 objects and converters.
+
+Provides cached access to rpy2 modules to avoid repeated imports.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_RPY2: dict[str, Any] | None = None
+
+
+def _require_rpy2(raise_on_missing: bool = True) -> dict[str, Any] | None:
+    """
+    Import rpy2 lazily and cache its key objects.
+    """
+    global _RPY2
+    if _RPY2 is not None:
+        return _RPY2
+
+    try:
+        import rpy2.robjects as ro
+        from rpy2 import robjects
+        from rpy2.rinterface_lib.sexp import NULLType
+        from rpy2.rlike.container import NamedList
+        from rpy2.robjects import pandas2ri
+        from rpy2.robjects.conversion import localconverter
+        from rpy2.robjects.vectors import (
+            BoolVector,
+            FloatVector,
+            IntVector,
+            ListVector,
+            StrVector,
+        )
+
+        _RPY2 = {
+            "ro": ro,
+            "robjects": robjects,
+            "pandas2ri": pandas2ri,
+            "localconverter": localconverter,
+            "BoolVector": BoolVector,
+            "FloatVector": FloatVector,
+            "IntVector": IntVector,
+            "ListVector": ListVector,
+            "StrVector": StrVector,
+            "NULLType": NULLType,
+            "NamedList": NamedList,
+        }
+        return _RPY2
+
+    except ImportError as exc:
+        if raise_on_missing:
+            raise RuntimeError(
+                "R support requires rpy2; install it in your Python env (e.g., pip install rpy2)"
+            ) from exc
+        return None
+
+
+def ensure_rpy2() -> dict[str, Any]:
+    """
+    Return the cached rpy2 bundle, raising if unavailable.
+    """
+    global _RPY2
+    if _RPY2 is None:
+        _RPY2 = _require_rpy2()
+    assert _RPY2 is not None, "_require_rpy2() returned None"
+    return _RPY2
+
+
+__all__ = ["ensure_rpy2", "_require_rpy2"]

rpy_bridge-0.5.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: rpy-bridge
+Version: 0.5.0
+Summary: Python-to-R interoperability engine with environment management, type-safe conversions, data normalization, and safe R function execution.
+Author-email: Victoria Cheung <victoriakcheung@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Victoria Cheung
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        Acknowledgement: This project builds on work originally developed at
+        Revolution Medicines and interfaces with the rpy2 project, which is licensed
+        under the GNU General Public License version 2 or later.
+        
+Project-URL: Homepage, https://github.com/vic-cheung/rpy-bridge
+Project-URL: Issue Tracker, https://github.com/vic-cheung/rpy-bridge/issues
+Keywords: python,r,rpy2,python-r,interoperability,data-science,statistics,bioinformatics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: loguru>=0.7
+Provides-Extra: r
+Requires-Dist: rpy2>=3.5; extra == "r"
+Provides-Extra: dev
+Requires-Dist: ipykernel>=7.1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Dynamic: license-file
+
+# rpy-bridge
+
+**rpy-bridge** is a Python-controlled **R execution orchestrator** that enables
+Python code to run R functions, scripts, and packages with **reproducible
+filesystem and environment semantics**.
+
+It is built on top of `rpy2`, but unlike thin wrappers, rpy-bridge stabilizes how
+R code is executed when invoked from Python: project roots are inferred, `renv`
+environments can be activated out-of-tree, relative paths behave as expected,
+and return values are normalized for safe Python consumption.
+
+This makes rpy-bridge suitable for production pipelines, CI, and bilingual
+Python/R teams where R code must run reliably outside an interactive R session.
+
+**Latest release:** [`rpy-bridge` on PyPI](https://pypi.org/project/rpy-bridge/)
+
+---
+
+## What this is (and is not)
+
+rpy-bridge **is not a thin rpy2 wrapper**.
+
+Typical rpy2 usage assumes:
+- the Python working directory is the R project root
+- `renv` lives next to the executing script
+- relative paths resolve correctly by default
+- all R code executes in `globalenv()`
+
+These assumptions break quickly in real-world Python workflows.
+
+rpy-bridge instead provides a **controlled R runtime** with explicit guarantees
+around execution context, filesystem behavior, and environment activation.
+
+---
+
+## Core capabilities
+
+### 1. R execution orchestration
+
+- Embeds R via `rpy2` with deterministic startup behavior
+- Disables interactive and GUI-dependent hooks for headless execution
+- Loads R scripts into isolated namespaces (not `globalenv()`)
+
+### 2. Project root inference and path stability
+
+- Infers R project roots using markers such as:
+  `.git`, `.Rproj`, `renv.lock`, `DESCRIPTION`, `.here`
+- Executes R code from the inferred project root regardless of Python CWD
+- Preserves relative-path behavior expected by R scripts
+- Supports R code using `here::here()` or project-local data
+
+### 3. Out-of-tree `renv` activation
+
+- Activates `renv` projects located **outside** the calling Python directory
+- Sources `.Rprofile` and `.Renviron` to reproduce R startup semantics
+- Does not require R scripts and `renv` to live in the same directory
+
+### 4. Python ↔ R data conversion
+
+- Converts Python scalars, lists, dicts, and pandas objects into R equivalents
+- Converts R vectors, lists, and data.frames back into Python-native types
+- Handles nested structures, missing values, and mixed types robustly
+
+### 5. Data normalization and diagnostics
+
+- Post-processes R data.frames to fix dtype, timezone, and NA semantics
+- Normalizes column types for reliable Python-side comparison
+- Supports structured mismatch diagnostics between Python and R data
+
+### 6. Function invocation across scripts and packages
+
+- Calls functions defined in sourced R scripts, base R, or installed packages
+- Supports qualified function names (e.g. `stats::median`)
+- Executes functions within the active project and library context
+
+---
+
+## Calling base R functions and managing packages
+
+In addition to sourcing local R scripts, rpy-bridge supports calling functions
+from base R and installed packages directly from Python.
+
+Current support includes:
+
+- Calling base R functions without a local R script
+- Executing functions from installed R packages within the active environment
+
+Planned extensions (roadmap):
+
+- Programmatic installation of R packages into the active `renv` or system
+  environment when explicitly enabled
+- Declarative package requirements at the Python call site
+- Safe, opt-in package installation for CI and ephemeral environments
+
+Package installation is intentionally **not automatic by default** to preserve
+reproducibility and avoid side effects during execution.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- System R installed and available on `PATH`
+- Python 3.12+
+
+### From PyPI
+
+Install rpy-bridge with rpy2 for full R support:
+
+```bash
+python3 -m pip install rpy-bridge rpy2
+```
+
+Using `uv`:
+
+```bash
+uv add rpy-bridge rpy2
+```
+
+### Development install
+
+```bash
+python3 -m pip install -e .
+```
+
+or:
+
+```bash
+uv sync
+```
+
+### Required Python dependencies
+
+- `rpy2`
+- `pandas`
+- `numpy`
+
+---
+
+## Usage
+
+### Call a function from a local R script
+
+```python
+from pathlib import Path
+from rpy_bridge import RFunctionCaller
+
+project_dir = Path("/path/to/your-r-project")
+script = project_dir / "scripts" / "example.R"
+
+caller = RFunctionCaller(
+    path_to_renv=project_dir,
+    script_path=script,
+)
+
+result = caller.call("some_function", 42, named_arg="value")
+```
+
+### Call base R functions (no local script)
+
+```python
+from rpy_bridge import RFunctionCaller
+
+caller = RFunctionCaller(path_to_renv=None)
+
+samples = caller.call("stats::rnorm", 10, mean=0, sd=1)
+median_val = caller.call("stats::median", samples)
+```
+
+---
+
+## Round-trip Python ↔ R behavior
+
+rpy-bridge attempts to convert Python objects to R and back. Most objects used in
+scientific and ML pipelines round-trip cleanly, but some heterogeneous Python
+structures may be wrapped or slightly altered due to differences in R’s type
+system.
+
+| Python type                                    | Round-trip fidelity | Notes                                                                 |
+| ---------------------------------------------- | ------------------- | --------------------------------------------------------------------- |
+| `int`, `float`, `bool`, `str`                  | High                | Scalars convert directly                                              |
+| Homogeneous `list` of numbers/strings          | High                | Converted to atomic R vectors                                         |
+| Nested homogeneous lists                       | High                | Converted to nested R lists                                           |
+| `pandas.DataFrame` / `pd.Series`               | High                | Converted to `data.frame` and normalized on return                    |
+| Mixed-type `list` or `dict`                    | Partial             | May be wrapped in single-element vectors                              |
+| `None` / `pd.NA`                               | High                | Converted to R `NULL`                                                 |
+
+---
+
+## R setup helpers
+
+Helper scripts are provided in `examples/r-deps/` to prepare R environments.
+
+- Install system R dependencies (macOS / Homebrew):
+
+```bash
+bash examples/r-deps/install_r_dev_deps_homebrew.sh
+```
+
+- Initialize an `renv` project:
+
+```r
+source("examples/r-deps/setup_env.R")
+```
+
+- Restore the environment on a new machine:
+
+```r
+renv::restore()
+```
+
+---
+
+## Who this is for
+
+rpy-bridge is designed for:
+
+- Python-first pipelines that rely on mature R code
+- Teams where R logic must remain authoritative
+- CI or production systems that cannot rely on interactive R sessions
+- Multi-repo or multi-directory projects with non-trivial filesystem layouts
+
+It is **not** intended as a convenience wrapper for exploratory R usage.
+
+---
+
+## Licensing
+
+- rpy-bridge is released under the MIT License © 2025 Victoria Cheung
+- Depends on [`rpy2`](https://rpy2.github.io), licensed under the GNU GPL (v2 or later)
+
+---
+
+## Acknowledgements
+
+This package was spun out of internal tooling I wrote at Revolution Medicines.
+Thanks to the team there for supporting its open-source release.

rpy_bridge-0.5.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+rpy_bridge/__init__.py,sha256=3UP1OOLuBaX7I9XsTaRsxr3EPYsGJere-Jh3xgc24QI,313
+rpy_bridge/compare.py,sha256=pwNOYLMrm7zJlsxzTooPl7OSmhPw-dc7owngJvV-7-0,4129
+rpy_bridge/convert.py,sha256=7DzdIGWl0eUYKzsfA5npL1DWKyhfk3gZ0CT2zAg2xfs,1952
+rpy_bridge/core.py,sha256=pkdsYsy0mXM7CDOkGA8Hev2KdfPn5NCsl_pP6zBalp0,18493
+rpy_bridge/dataframe.py,sha256=nocmc3yTyk1omCRKb1otNuwO73FzfxFeoVunH8oZC-Y,2310
+rpy_bridge/env.py,sha256=YN3tvl1eUp9IhbTmPgjSVKpRLTuf0OARgkMobQJd0Ks,3581
+rpy_bridge/logging.py,sha256=9U2RJHmxLqrXEwS38TkrSqeETXxn1AAfL8BGTjnzSGY,1360
+rpy_bridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rpy_bridge/renv.py,sha256=BYBFXP8SslKzD-GZ0yi7T-nMwqcIx2hYPY3BC_xSSZU,4511
+rpy_bridge/rpy2_loader.py,sha256=rQEnAiJbzkTzb4UlcOsG8D4MXZ0LWtYLMP8DequBNzg,1874
+rpy_bridge-0.5.0.dist-info/licenses/LICENSE,sha256=JwbWVcSfeoLfZ2M_ZiyygKVDvhBDW3zbqTWwXOJwmrA,1276
+rpy_bridge-0.5.0.dist-info/METADATA,sha256=6bkzCM7gFr1gtOUF007Zrhhjy9vvNtduX9Vq4o7_YN4,10188
+rpy_bridge-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rpy_bridge-0.5.0.dist-info/top_level.txt,sha256=z9UZ77ZuUPoLqMDQEpP4btstsaM1IpXb9Cn9yBVaHmU,11
+rpy_bridge-0.5.0.dist-info/RECORD,,