R Interface to Python

Locating Python

If the version of Python you want to use is located on the system PATH then it will be automatically discovered (via Sys.which) and used.

Alternatively, you can use one of the following functions to specify alternate versions of Python:

For example:

library(reticulate)
use_python("/usr/local/bin/python")
use_virtualenv("~/myenv")
use_condaenv("myenv")

Note that the NumPy features of reticulate require NumPy >= 1.6 so versions of Python that satisfy this requirement will be preferred over ones that don’t.

Also note that the use functions are by default considered only hints as to where to find Python (i.e. they don’t produce errors if the specified version doesn’t exist). You can add the required parameter to ensure that the specified version of Python actually exists:

use_virtualenv("~/myenv", required = TRUE)

The order in which versions of Python will be discovered and used is as follows:

1. If specified, at the locations referenced by calls to use_python, use_virtualenv, and use_condaenv.

2. If specified, at the location referenced by the RETICULATE_PYTHON environment variable.

3. At the location of the Python binary discovered on the system PATH (via the Sys.which function).

4. At other customary locations for Python including /usr/local/bin/python, /opt/local/bin/python, etc.

The scanning for and binding to a version of Python typically occurs at the time of the first call to import within an R session. As a result, priority will be given to versions of Python that include the module specified within the call to import (i.e. versions that don’t include it will be skipped).

You can use the py_config function to query for information about the specific version of Python in use as well as a list of other Python versions discovered on the system:

py_config()

Object Conversion

By default when Python objects are returned to R they are converted to their equivalent R types. However, if you’d rather make conversion from Python to R explicit and deal in native Python objects by default you can pass convert = FALSE to the import function. In this case Python to R conversion will be disabled for the module returned from import. For example:

# import numpy and speicfy no automatic Python to R conversion
np <- import("numpy", convert = FALSE)

# do some array manipulations with NumPy
a <- np$array(c(1:4))
sum <- a$cumsum()

# convert to R explicitly at the end
py_to_r(sum)

As illustrated above, if you need access to an R object at end of your computations you can call the py_to_r function explicitly.

Python Objects

Typically interacting with Python objects from R involves using the $ operator to access whatever properties for functions of the object you need. When using the $, Python objects are automatically converted to their R equivalents when possible. The following functions enable you to interact with Python objects at a lower level (e.g. no conversion to R is done unless you explicitly call the py_to_r function):

Configuration

The following functions enable you to query for information about the Python configuration available on the current system.

Output Control

These functions enable you to capture or suppress output from Python:

Miscellaneous

The functions provide miscellaneous other lower-level capabilities:

Checking and Testing on CRAN

If you use reticulate in another R package you need to account for the fact that when your package is submitted to CRAN, the CRAN test servers may not have Python, NumPy, or whatever other Python modules you are wrapping in your package. If you don’t do this then your package may fail to load and/or pass it’s tests when run on CRAN.

There are two things you should do to ensure your package is well behaved on CRAN:

1. When importing Python modules for use inside your package you should use the delay_load option to ensure that the module (and Python) is loaded only on it’s first use. For example:

   # python 'foo' module I want to use in my package
   foo <- NULL
   
   .onLoad <- function(libname, pkgname) {
     # delay load foo module (will only be loaded when accessed via $)
     foo <<- import("foo", delay_load = TRUE)
   }

2. When writing tests, check to see if your module is available and if it isn’t then skip the test. For example, if you are using the testthat package, you might do this:

   # helper function to skip tests if we don't have the 'foo' module
   skip_if_no_foo <- function() {
     have_foo <- py_module_available("foo")
     if (!have_foo)
       skip("foo not available for testing")
   }
   
   # then call this function from all of your tests
   test_that("Things work as expected", {
     skip_if_no_foo()
     # test code here...
   })

S3 Methods

Python objects exposed by reticulate carry their Python classes into R, so it’s possible to write S3 methods to customize e.g. the str or print behavior for a given class (note that it’s not typically necessary that you do this since the default str and print methods call PyObject_Str, which typically provides an acceptable default behavior).

If you do decide to implement custom S3 methods for a Python class it’s important to keep in mind that when an R session ends the connection to Python objects is lost, so when the .RData saved from one R session is restored in a subsequent R session the Python objects are effectively lost (technically they become NULL R externalptr objects).

This means that you should always use the py_is_null_xptr function on objects before interacting with them in an S3 method. For example:

#' @export
summary.MyPythonClass <- function(object, ...) {
  if (py_is_null_xptr(object))
    stop("Object is NULL")
  else
    # interact with the object to generate the summary
}

There are a couple of shortcut methods you can use to make this more straightforward. The py_validate_xptr function will do the check and automatically throw an error if it fails. So the example above could be re-written as:

#' @export
summary.MyPythonClass <- function(object, ...) {
  py_validate_xptr(object)
  # interact with the object to generate the summary
}

Finally, the reticulate package exports a py_str generic method which is called from the str method only after doing appropriate validation (if the object is NULL then <pointer: 0x0> is returned). You can implement the py_str method as follows:

#' @importFrom reticulate py_str
#' @export 
py_str.MyPythonClass <- function(object, ...) {
  # interact with the object to generate the string
}

So in short, to provide custom str and print methods, just implement py_str. For other S3 methods be sure to call either py_validate_xptr or py_is_null_xptr before interacting with the object.