Callbacks

The R C-API allows front-end developpers to customize R’s interactive behavior to their needs using callbacks, and rpy2 is making those callbacks accessible with the ability to implement them in pure Python. In other words, rpy2 makes it possible to implement a completely an R front-end such as RStudio.

Console I/O

During an interactive session, much of the communication between R and the user happen through the console. How the console reads input and writes output, can be defined through callback functions.

Read console

The function “read console” is called whenever console input is expected.

The default callback for inputing data is rpy2.rinterface_lib.callbacks.consoleread()

rpy2.rinterface_lib.callbacks.consoleread(prompt)

Read input for the R console.

Parameters

prompt – The message prompted.

Returns

A string with the input returned by the user.

Any Python function with the same signature can be used instead. For example:

def  my_consoleread(prompt: str) -> str:
    custom_prompt = f'R is asking this: {promp}'
    return input(custom_prompt)

rpy2.rinterface_lib.callbacks.consoleread = my_consoleread

Write console

The function “write console” is called whenever output is sent to the R console. In R’s C API, there are two functions behind the hood, one for regular printing, and one for warnings and errors.

rpy2.rinterface_lib.callbacks.consolewrite_print(s: str) → None

R writing to the console/terminal.

Parameters

s – the data to write to the console/terminal.

rpy2.rinterface_lib.callbacks.consolewrite_warnerror(s: str) → None

An example should make it obvious:

buf = []
def f(x):
    # function that append its argument to the list 'buf'
    buf.append(x)

# output from the R console will now be appended to the list 'buf'
consolewrite_print_backup = rpy2.rinterface_lib.callbacks.consolewrite_print
rpy2.rinterface_lib.callbacks.consolewrite_print = f

date = rinterface.baseenv['date']
rprint = rinterface.baseenv['print']
rprint(date())

# the output is in our list (as defined in the function f above)
print(buf)

# restore default function
rpy2.rinterface_lib.callbacks.consolewrite_print = consolewrite_print_backup

rpy2.rinterface_lib.callbacks.consolewrite_print(s: str) → None

R writing to the console/terminal.

Parameters

s – the data to write to the console/terminal.

Show message

rpy2.rinterface_lib.callbacks.showmessage(s: str) → None

Flush console

The function “flush console” is called whenever output is sent to the R console.

rpy2.rinterface_lib.callbacks.consoleflush()

Yes/No/Cancel

rpy2.rinterface_lib.callbacks.yesnocancel(question: str) → int

Asking a user to answer yes, no, or cancel.

Parameters

question – The question asked to the user

Returns

An integer with the answer.

Files

Showing files

rpy2.rinterface_lib.callbacks.showfiles(filenames: Tuple[str], headers: Tuple[str], wtitle: str, pager: str) → None

R showing files.

Parameters

• filenames – A tuple of file names.

• headers – A tuple of strings (TODO: check what it is)

Wtitle

Title of the “window” showing the files.

Choosing files

File choosing a on basic R console has very little bells and whistles.

def choose_csv(prompt):
    print(prompt)
    return(filename)

Other

Process events

rpy2.rinterface_lib.callbacks.processevents() → None

Process R events.

This function can be periodically called by R to handle events such as window resizing in an interactive graphical device.

Busy

rpy2.rinterface_lib.callbacks.busy(x: int) → None

R is busy.

Parameters

x – TODO this is an integer but do not know what it does.

Clean up

When asked to terminate, through either its terminal console win32 or quartz GUI front-end, R will perform a cleanup operation at the begining of which whether the user wants to save the workspace or not.

What is happening during that cleaning step can be specified through a callback function that will take three parameters saveact, status, and runlast, return of 1 (save the workspace), 0 (do not save the workspace), and None (cancel the exit/cleanup, raising an RRuntimeError).

import rpy2.rinterface

rpy2.rinterface.initr()

rquit = rpy2.rinterface.baseenv['q']

def my_cleanup(saveact, status, runlast):
    # cancel all attempts to quit R programmatically
    print("One can't escape...")
    return None

>>> orig_cleanup = rpy2.rinterface_lib.callbacks.cleanup
>>> rpy2.rinterface_lib.callbacks.cleanup = my_cleanup
>>> rquit()

Restore the original cleanup:

>>> rpy2.rinterface_lib.callbacks.cleanup = orig_cleanup