rpy-bridge 0.3.4__py3-none-any.whl → 0.3.6__py3-none-any.whl

rpy_bridge/rpy2_utils.py

@@ -29,7 +29,7 @@ import subprocess
 import sys
 import warnings
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Union
+from typing import TYPE_CHECKING, Any, Iterable, Union
 
 import numpy as np
 import pandas as pd
@@ -58,6 +58,47 @@ except ImportError:
     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}",  # Only show message
+    level="INFO",
+)
+
+
+def _log_r_call(func_name: str, source_info: str):
+    """
+    Log an R function call, showing only '[RFunctionCaller] Called ...'
+    """
+    _rfc_logger.opt(depth=1, record=False).info(
+        "[rpy-bridge.RFunctionCaller] Called R function '{}' from {}",
+        func_name,
+        source_info,
+    )
+
+
+# ---------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------
+def _normalize_scripts(
+    scripts: Union[str, Path, Iterable[Union[str, Path]], None],
+) -> list[Path]:
+    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:
+        raise TypeError(
+            f"Invalid type for 'scripts': {type(scripts)}. Must be str, Path, or list/iterable thereof."
+        )
+
+
 # ---------------------------------------------------------------------
 # R detection and rpy2 installation
 # ---------------------------------------------------------------------
@@ -104,31 +145,49 @@ def find_r_home() -> str | None:
     return None
 
 
-if "R_HOME" not in os.environ:
+# Determine if we're running in CI / testing
+CI_TESTING = (
+    os.environ.get("GITHUB_ACTIONS") == "true" or os.environ.get("TESTING") == "1"
+)
+
+R_HOME = os.environ.get("R_HOME")
+if not R_HOME:
     R_HOME = find_r_home()
     if not R_HOME:
-        raise RuntimeError("R not found. Please install R or add it to PATH.")
-    os.environ["R_HOME"] = R_HOME
-else:
-    R_HOME = os.environ["R_HOME"]
-
-logger.info(f"R_HOME = {R_HOME}")
-os.environ["R_HOME"] = R_HOME
-ensure_rpy2_available()
-
-# macOS dynamic library path
-if sys.platform == "darwin":
-    lib_path = os.path.join(R_HOME, "lib")
-    if lib_path not in os.environ.get("DYLD_FALLBACK_LIBRARY_PATH", ""):
-        os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = (
-            f"{lib_path}:{os.environ.get('DYLD_FALLBACK_LIBRARY_PATH','')}"
-        )
+        if CI_TESTING:
+            logger.warning(
+                "R not found; skipping all R-dependent setup in CI/testing environment."
+            )
+            R_HOME = None  # Explicitly None to signal "no R available"
+        else:
+            raise RuntimeError("R not found. Please install R or add it to PATH.")
+    else:
+        os.environ["R_HOME"] = R_HOME
+
+logger.info(
+    f"[rpy-bridge] R_HOME = {R_HOME if R_HOME else 'not detected; R-dependent code skipped'}"
+)
+
+# Only configure platform-specific library paths if R is available
+if R_HOME:
+    if sys.platform == "darwin":
+        lib_path = os.path.join(R_HOME, "lib")
+        if lib_path not in os.environ.get("DYLD_FALLBACK_LIBRARY_PATH", ""):
+            os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = (
+                f"{lib_path}:{os.environ.get('DYLD_FALLBACK_LIBRARY_PATH','')}"
+            )
+
+    elif sys.platform.startswith("linux"):
+        lib_path = os.path.join(R_HOME, "lib")
+        ld_path = os.environ.get("LD_LIBRARY_PATH", "")
+        if lib_path not in ld_path.split(":"):
+            os.environ["LD_LIBRARY_PATH"] = f"{lib_path}:{ld_path}"
 
-elif sys.platform.startswith("linux"):
-    lib_path = os.path.join(R_HOME, "lib")
-    ld_path = os.environ.get("LD_LIBRARY_PATH", "")
-    if lib_path not in ld_path.split(":"):
-        os.environ["LD_LIBRARY_PATH"] = f"{lib_path}:{ld_path}"
+    elif sys.platform.startswith("win"):
+        bin_path = os.path.join(R_HOME, "bin", "x64")
+        path_env = os.environ.get("PATH", "")
+        if bin_path not in path_env.split(os.pathsep):
+            os.environ["PATH"] = f"{bin_path}{os.pathsep}{path_env}"
 
 
 # ---------------------------------------------------------------------
@@ -212,24 +271,24 @@ def activate_renv(path_to_renv: Path) -> None:
     renviron_file = project_dir / ".Renviron"
     if renviron_file.is_file():
         os.environ["R_ENVIRON_USER"] = str(renviron_file)
-        logger.info(f"R_ENVIRON_USER set to: {renviron_file}")
+        logger.info(f"[rpy-bridge] R_ENVIRON_USER set to: {renviron_file}")
 
     rprofile_file = project_dir / ".Rprofile"
     if rprofile_file.is_file():
         robjects.r(f'source("{rprofile_file.as_posix()}")')
-        logger.info(f".Rprofile sourced: {rprofile_file}")
+        logger.info(f"[rpy-bridge] .Rprofile sourced: {rprofile_file}")
 
     try:
         robjects.r("suppressMessages(library(renv))")
     except Exception:
-        logger.info("Installing renv package in project library...")
+        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"renv environment loaded for project: {project_dir}")
+    logger.info(f"[rpy-bridge] renv environment loaded for project: {project_dir}")
 
 
 # ---------------------------------------------------------------------
@@ -248,35 +307,54 @@ class NamespaceWrapper:
             return self._env[func_name]
         raise AttributeError(f"Function '{func_name}' not found in R namespace")
 
+    def list_functions(self):
+        """
+        Return a list of callable functions in this namespace.
+        """
+        return [k for k, v in self._env.items() if callable(v)]
+
 
 # ---------------------------------------------------------------------
 # RFunctionCaller
 # ---------------------------------------------------------------------
 class RFunctionCaller:
     """
-    Utility to load and call R functions from scripts, lazily loading rpy2 and activating renv.
-
-    Supports:
-    - Single or multiple R scripts
-    - R script directories (sources all `.R` files inside)
-    - Base R functions
-    - Functions in loaded packages
-    - Automatic conversion of Python types to R objects
-
-    Args:
-        scripts:
-            Path or list of Paths.
-            Each path may be:
-            - an R script (.R file)
-            - a directory containing R scripts (all *.R files are sourced)
-            - scripts in subdirectories are not automatically sourced
+    Primary interface for calling R functions from Python.
+
+    ``RFunctionCaller`` loads one or more R scripts into isolated namespaces
+    and provides a unified ``call()`` method for executing:
+
+    * Functions defined in sourced R scripts
+    * Base R functions (e.g. ``sum``, ``mean``)
+    * Functions from installed R packages (via ``package::function``)
+
+    In most workflows, users only need to interact with this class.
 
+    Parameters
+    ----------
+    path_to_renv : Path or None, optional
+        Path to an R project that uses ``renv``. This may be either the project
+        root or the ``renv/`` directory itself. If provided, the renv
+        environment is activated before any scripts are sourced.
+
+    scripts : str, Path, list[str | Path], or None, optional
+        One or more ``.R`` files or directories containing ``.R`` files.
+        Each script is sourced into its own namespace.
+
+    packages : str or list[str], optional
+        R packages to load (and install if missing) before calling functions.
+
+    Notes
+    -----
+    * Python objects are automatically converted to R objects.
+    * R return values are converted back to Python equivalents.
+    * Missing values (``None``, ``pd.NA``) are mapped to R ``NA``.
     """
 
     def __init__(
         self,
         path_to_renv: Path | None = None,
-        scripts: Path | list[Path] | None = None,
+        scripts: str | Path | list[str | Path] | None = None,
         packages: str | list[str] | None = None,
         **kwargs,  # catch unexpected keywords
     ):
@@ -297,6 +375,13 @@ class RFunctionCaller:
                     "'script_path' ignored because 'scripts' argument is also provided."
                 )
 
+        self.scripts = _normalize_scripts(scripts)
+
+        # --- Check all scripts exist immediately ---
+        for script_path in self.scripts:
+            if not script_path.exists():
+                raise FileNotFoundError(f"R script path not found: {script_path}")
+
         # Raise error if other unexpected kwargs remain
         if kwargs:
             raise TypeError(
@@ -391,8 +476,10 @@ class RFunctionCaller:
 
             for script_path in r_files:
                 ns_name = script_path.stem
-                logger.info(
-                    f"Loading R script '{script_path.name}' as namespace '{ns_name}'"
+                logger.opt(depth=2).info(
+                    "[rpy-bridge.RFunctionCaller] Loading R script '{}' as namespace '{}'",
+                    script_path.name,
+                    ns_name,
                 )
 
                 r("env <- new.env(parent=globalenv())")
@@ -415,7 +502,7 @@ class RFunctionCaller:
                 }
 
                 logger.info(
-                    f"Registered {len(self._namespaces[ns_name])} functions in namespace '{ns_name}'"
+                    f"[rpy-bridge.RFunctionCaller] Registered {len(self._namespaces[ns_name])} functions in namespace '{ns_name}'"
                 )
 
             self._scripts_loaded[idx] = True
@@ -454,6 +541,105 @@ class RFunctionCaller:
 
         return x
 
+    def list_namespaces(self) -> list[str]:
+        """
+        Return the names of all loaded script namespaces.
+
+        Returns
+        -------
+        list[str]
+            Names of sourced R script namespaces.
+        """
+        self._ensure_r_loaded()
+        return list(self._namespaces.keys())
+
+    def list_namespace_functions(self, namespace: str) -> list[str]:
+        """
+        Return all callable functions in a specific namespace.
+        """
+        self._ensure_r_loaded()
+        if namespace not in self._namespaces:
+            raise ValueError(f"Namespace '{namespace}' not found")
+        return [k for k, v in self._namespaces[namespace].items() if callable(v)]
+
+    def _get_package_functions(self, pkg: str) -> list[str]:
+        """
+        Return a list of callable functions from a loaded R package.
+        """
+        r = self.robjects.r
+        try:
+            all_objs = list(r[f'ls("package:{pkg}")'])
+            funcs = [
+                name
+                for name in all_objs
+                if r(f'is.function(get("{name}", envir=asNamespace("{pkg}")))')[0]
+            ]
+            return funcs
+        except Exception:
+            logger.warning(f"Failed to list functions for package '{pkg}'")
+            return []
+
+    def list_all_functions(
+        self, include_packages: bool = False
+    ) -> dict[str, list[str]]:
+        """
+        Return all callable R functions grouped by script namespace and package.
+        """
+        self._ensure_r_loaded()
+        all_funcs = {}
+
+        # --- Script namespaces ---
+        for ns_name, ns_env in self._namespaces.items():
+            funcs = [name for name, val in ns_env.items() if callable(val)]
+            all_funcs[ns_name] = funcs
+
+        # --- Loaded R packages ---
+        if include_packages:
+            r = self.robjects.r
+            try:
+                pkgs = r("loadedNamespaces()")
+                for pkg in pkgs:
+                    funcs = self._get_package_functions(pkg)
+                    if not funcs:
+                        # Add a placeholder note
+                        funcs = [
+                            "[See official documentation for functions, datasets, and objects]"
+                        ]
+                    all_funcs[pkg] = funcs
+            except Exception:
+                pass
+
+        return all_funcs
+
+    def print_function_tree(
+        self, include_packages: bool = False, max_display: int = 10
+    ):
+        """
+        Pretty-print available R functions grouped by namespace.
+
+        Parameters
+        ----------
+        include_packages : bool, default False
+            Whether to include functions from loaded R packages.
+
+        max_display : int, default 10
+            Maximum number of functions displayed per namespace.
+
+        Notes
+        -----
+        This method is intended for interactive exploration and debugging.
+        """
+        all_funcs = self.list_all_functions(include_packages=include_packages)
+
+        for ns_name, funcs in all_funcs.items():
+            if not funcs:
+                continue
+            print(f"{ns_name}/")
+            for f in sorted(funcs)[:max_display]:
+                print(f"  {f}")
+            if len(funcs) > max_display:
+                print("  ...")
+
     # -----------------------------------------------------------------
     # Python -> R conversion
     # -----------------------------------------------------------------
@@ -562,8 +748,10 @@ class RFunctionCaller:
         try:
             r(f'suppressMessages(library("{pkg}", character.only=TRUE))')
         except Exception:
-            logger.info(f"Package '{pkg}' not found.")
-            logger.warning(f"Installing missing R package: {pkg}")
+            logger.info(f"[rpy-bridge.RFunctionCaller] Package '{pkg}' not found.")
+            logger.warning(
+                f"[rpy-bridge.RFunctionCaller] Installing missing R package: {pkg}"
+            )
             r(f'install.packages("{pkg}", repos="https://cloud.r-project.org")')
             r(f'suppressMessages(library("{pkg}", character.only=TRUE))')
 
@@ -571,6 +759,38 @@ class RFunctionCaller:
     # Public: call an R function
     # -----------------------------------------------------------------
     def call(self, func_name: str, *args, **kwargs):
+        """
+        Call an R function.
+
+        The function may be defined in:
+        * a sourced R script
+        * an installed R package (using ``package::function`` syntax)
+        * base R
+
+        Parameters
+        ----------
+        func_name : str
+            Name of the R function to call. Package functions should be specified
+            as ``package::function``.
+
+        *args
+            Positional arguments passed to the R function.
+
+        **kwargs
+            Named arguments passed to the R function.
+
+        Returns
+        -------
+        object
+            The result of the R function, converted to a Python object.
+
+        Examples
+        --------
+        >>> rfc.call("sum", [1, 2, 3])
+        >>> rfc.call("dplyr::n_distinct", [1, 2, 2, 3])
+        >>> rfc.call("add_and_scale", 2, 3, scale=10)
+        """
+
         self._ensure_r_loaded()
 
         func = None
@@ -629,7 +849,8 @@ class RFunctionCaller:
                 f"Error calling R function '{func_name}' from {source_info}: {e}"
             ) from e
 
-        logger.info(f"Called R function '{func_name}' from {source_info}")
+        _log_r_call(func_name, source_info)
+
         return self._r2py(result)
 
 

{rpy_bridge-0.3.4.dist-info → rpy_bridge-0.3.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rpy-bridge
-Version: 0.3.4
+Version: 0.3.6
 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
@@ -150,12 +150,12 @@ uv sync
 from pathlib import Path
 from rpy_bridge import RFunctionCaller
 
-caller = RFunctionCaller(
+rfc = RFunctionCaller(
     path_to_renv=Path("/path/to/project"),
-    script_path=Path("/path/to/script.R"),
+    script=Path("/path/to/script.R"),
 )
 
-summary_df = caller.call("summarize_cohort", cohort_df)
+summary_df = rfc.call("summarize_cohort", cohort_df)
 ```
 
 ---

rpy_bridge-0.3.6.dist-info/RECORD

@@ -0,0 +1,8 @@
+rpy_bridge/__init__.py,sha256=VDCx-CiTBJO0cMp59v-gyJGBVYHjLjATTIdtYxBsK5Q,875
+rpy_bridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rpy_bridge/rpy2_utils.py,sha256=1W1Lgt0HI3TGs20GugHceFih1uLTTilz_pmkzNkPujY,37516
+rpy_bridge-0.3.6.dist-info/licenses/LICENSE,sha256=JwbWVcSfeoLfZ2M_ZiyygKVDvhBDW3zbqTWwXOJwmrA,1276
+rpy_bridge-0.3.6.dist-info/METADATA,sha256=Apvq8djqUFDsq84IfPuTTDDkW7rrZaxJz0DykM9tSBQ,9580
+rpy_bridge-0.3.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rpy_bridge-0.3.6.dist-info/top_level.txt,sha256=z9UZ77ZuUPoLqMDQEpP4btstsaM1IpXb9Cn9yBVaHmU,11
+rpy_bridge-0.3.6.dist-info/RECORD,,

rpy_bridge-0.3.4.dist-info/RECORD

@@ -1,8 +0,0 @@
-rpy_bridge/__init__.py,sha256=VDCx-CiTBJO0cMp59v-gyJGBVYHjLjATTIdtYxBsK5Q,875
-rpy_bridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rpy_bridge/rpy2_utils.py,sha256=3xTxEOpT2xk6lFhY39stIwPs_oJmvQK5PowFxz6gSWg,30046
-rpy_bridge-0.3.4.dist-info/licenses/LICENSE,sha256=JwbWVcSfeoLfZ2M_ZiyygKVDvhBDW3zbqTWwXOJwmrA,1276
-rpy_bridge-0.3.4.dist-info/METADATA,sha256=XsKvCmOoWVqqC_xvZD3ckvApPWjfmC5xZ0g2QXRk8Fg,9591
-rpy_bridge-0.3.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rpy_bridge-0.3.4.dist-info/top_level.txt,sha256=z9UZ77ZuUPoLqMDQEpP4btstsaM1IpXb9Cn9yBVaHmU,11
-rpy_bridge-0.3.4.dist-info/RECORD,,