generateRWrappers: Generate R wrappers for Python classes and functions

In Sage-Bionetworks/PythonEmbedInR: Use an embedded Python from Within R

Generate R wrappers for Python classes and functions

Description

This function generates R wrappers for Python classes and functions in the given Python container

Usage

generateRWrappers(pyPkg, container, setGenericCallback, functionFilter = NULL,
  classFilter = NULL, functionPrefix = NULL, pySingletonName = NULL,
  transformReturnObject = NULL)

Arguments

pyPkg	The Python package name
container	The fully qualified name of a Python module or a Python class to be wrapped
setGenericCallback	The callback to setGeneric defined in the target R package
functionFilter	Optional function to intercept and modify the auto-generated function metadata.
classFilter	Optional function to intercept and modify the auto-generated class metadata.
functionPrefix	Optional text to add to the name of the wrapped functions.
pySingletonName	Optional parameter used to expose a set Python functions which are an object's methods, but without exposing the object itself. If the container parameter is a class then this must be the name of a Python variable referencing an instance of the class. Otherwise, this must be NULL. See example 4.
transformReturnObject	Optional function to change returned values in R.

Details

• container can take the same value as pyPkg, can be a module or class within the Python package.

• setGeneric function must be defined in the same environment that generateRWrappers is called. See example 1.

• functionFilter and classFilter are optional functions defined by the caller.

• functionFilter takes as input the metadata for a generated function and either modifies it or returns NULL to omit it from the set of generated functions. The metadata object is a list having fields:

  'name': character
  'args': named list having fields:
      'args': a list of the argument names
      'varargs':  character
      'keywords': character
      'defaults': character
  'doc': character
  'module':character
  

  Please see inspect.getargspec for more information about the named list args. See example 2.

• classFilter takes as input the metadata for a generated class and either modifies it or returns NULL to omit it from the set of generated classes The metadata object is a list having fields:

  'name': character
  'constructorArgs': named list having fields:
      'args': a list of the argument names
      'varargs':  character
      'keywords': character
      'defaults': character
  'doc': character
  'methods':named list having fields:
      'name': character
      'doc': character
      'args': named list having fields:
          'args': a list of the argument names
          'varargs':  character
          'keywords': character
          'defaults': character
  

  Please see inspect.getargspec for more information about the named list args. See example 3.

• transformReturnObject is used to intercept and modify the values returned by the auto-generated R functions.transformReturnObject will be applied to the returned values from all generated functions. The transformation cannot depend on the function which generated the returned value. See example 5.

Note

• generateRWrappers should be called at load time.

• generateRWrappers and generateRdFiles must be called with corresponding parameters to ensure all R wrappers has sufficient documentation.

Examples

1. Generate R wrappers for all functions and classes in "pyPackageName.aModuleInPyPackageName"

callback <- function(name, def) {
  setGeneric(name, def)
}
PythonEmbedInR::generateRWrappers(
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName",
  setGenericCallback = callback)

2. Generate R wrappers for module "pyPackageName.aModuleInPyPackageName", omitting function "myFun"

myfunctionFilter <- function(x) {
  if (any(x$name == "myFun")) NULL else x
}
PythonEmbedInR::generateRWrappers(
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName",
  setGenericCallback = callback,
  functionFilter = myfunctionFilter)

3. Generate R wrappers for module "pyPackageName.aModuleInPyPackageName", omitting the "MyObj" class

myclassFilter <- function(x) {
  if (any(x$name == "MyObj")) NULL else x
}
PythonEmbedInR::generateRWrappers(
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName",
  setGenericCallback = callback,
  classFilter = myclassFilter)

4. Generate R wrappers for class "synapseclient.client.Synapse" without exposing the "Synapse" object

.onLoad <- function(libname, pkgname) {
  pyImport("synapseclient")
  pyExec("syn = synapseclient.Synapse()")
  # `pySingletonName` must be the name of the object defined in Python.
  generateRWrappers(pyPkg = "synapseclient",
                    container = "synapseclient.client.Synapse",
                    setGenericCallback = callback,
                    pySingletonName = "syn")
}

5. Generate R wrappers for module "pyPackageName.aModuleInPyPackageName", transforming all returned values,
  and setting each returned object class name to "newName"
  
myTransform <- function(x) {
  # replace the object name
  class(x) <- "newName"
}
PythonEmbedInR::generateRWrappers(
  pyPkg = "pyPackageName",
  container = "pyPackageName.aModuleInPyPackageName",
  setGenericCallback = callback,
  transformReturnObject = myTransform)

Sage-Bionetworks/PythonEmbedInR documentation built on April 17, 2023, 4:23 p.m.