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)[source]¶

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 [source]¶

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 [source]¶

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 [source]¶

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 [source]¶

Flush console¶

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

rpy2.rinterface_lib.callbacks.consoleflush()[source]¶

Yes/No/Cancel¶

rpy2.rinterface_lib.callbacks.yesnocancel(question: str) → int [source]¶

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: Optional[str], pager: Optional[str]) → None [source]¶

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.

Pager

Pager to use to show the list of 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 [source]¶

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 [source]¶

R is busy.

Parameters: x – TODO this is an integer but I 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