Initial refactoring to better handle graphics devices in notebooks. (#1144)

Refactoring to better handle default options for graphics devices and conversion rules for the R magics.

Author: lgautier

.github/workflows/pythonpackage.yml

@@ -25,7 +25,6 @@ jobs:
       uses: r-lib/actions/setup-r@v2
       with:
         r-version: release
-
     - name: Check type hints rinterface
       run: |
         cd rpy2-rinterface

NEWS

@@ -9,6 +9,21 @@ New features
   encoding is now the system's encoding (rather than assume utf-8).
   This may provide a fix to issue #1018.
 
+- Noteboook "R magic" features for ipython/jupyter support more
+  graphical devices to render R graphics in notebooks. Registered
+  devices are in :obj:`rpy2.ipython.rmags.graphics_devices`. This
+  allows the specification of fallbacks when the preferred device is
+  not available because of a missing R package. For SVG graphics,
+  it will first try to use the R package `svglite` to produce
+  lighter-weight SVG representations that are better when notebooks
+  may include many figures and figure with large number of visual
+  elements.
+
+- Experimental minimalist set of optional conversion rules to
+  convert Python :class:`list` objects to R vectors when all elements
+  are of atomic type: :obj:`rpy2.robjects.flatlist_converter`. Those
+  rules have been in used for the ipython/jupyter default converter.
+
 Changes
 -------
 
@@ -40,7 +55,14 @@ Changes
 
 - The wrapper for dplyr is now targeting the R package `dplyr`
   version 1.1.
-
+- The default converter for the ipython/jupyter magics depended on
+  what is the default converter at the time of module import. To
+  simplify this, the default converter is now fixed to
+  `robjects.default_converter` + `robjects.flatlist_converter` +
+  `robjects.numpy2ri.converter` + `robjects.pandas2ri.converter`.
+  If `pandas` cannot be imported
+  it falls back to `robjects.default_converter` + `robjects.numpy2ri.converter`.
+  If `numpy` cannot be imported it falls back to  `robjects.default_converter`.
 - The definition of `Rcomplex` from R's C-API was updated to match
   the definition in recent R release (>= 4.3) when rpy2 is in "API mode".
   This does not work with the "ABI mode" though, and the legacy
@@ -57,6 +79,9 @@ Bugs fixed
   play well with conversion rules in :mod:`rpy2.robjects.pandas2ri`.
   The default conversion rules are now forced (issue #1116).
 
+- The documentation for the notebook "magic" `Rdevice` was not
+  displayed in the module-level docstring for :mod:`rpy2.ipython.rmagic`.
+
 
 Release 3.5.17
 ==============

doc/notebooks/jupyter.md

@@ -156,11 +156,13 @@ p = (gp.ggplot(dataf) +
 image_png(p)
 ```
 
+# R "magics"
+
 So far we have shown that using `ggplot2` can be done from Python as if it
 was just an other Python library for visualization, but R can also be used
 in cells.
 
-First the so-called "R magic" extension should be loaded.
+First the so-called "R magic" extensions should be loaded.
 
 ```python
 %load_ext rpy2.ipython
@@ -205,3 +207,105 @@ p <- ggplot(dataf) +
      theme_light(base_size=16)
 print(p)
 ```
+
+## Options.
+
+The R "magics" use a number of configurable options that control
+aspects of the interaction between Python and R, or between ipython / jupyter
+and R. Some of the options can specified through arguments to "magics",
+but it is also possible to configure the default value for some of them
+when an argument to a "magic" does not specify otherwise. The easiest
+way to list these default-configurable options can be achieved
+with a "magic":
+
+```python
+%Roptions show
+```
+
+Changing these defaults requires to modify components of the attribute
+:attr:`rpy2.ipython.rmagic.RMagic.options`. Here is an example showing
+how to changing the default of R figures rendered in the notebook to "svg".
+
+```python
+import IPython
+ipy = IPython.get_ipython()
+ipy.magics_manager.registry['RMagics'].options.graphics_device_name = 'svg'
+```
+
+Another example is how to change conversion rules, that can be
+an expensive operation depending object sizes and rules, to a no-op:
+no convertion rules to keep all rpy2 objects as proxy wrappers
+to R objects for example, no conversion of Python objects to R:
+
+```python
+import rpy2.robjects
+import IPython
+ipy = IPython.get_ipython()
+
+noop_conv = rpy2.robjects.conversion.Converter('No-Op')
+noop_conv.rpy2py.register(rpy2.robjects.RObject,
+                          rpy2.robjects._rpy2py_robject)
+
+ipy.magics_manager.registry['RMagics'].options.converter = noop_conv
+```
+
+Modifying this come with risks though, or afterthoughts about changes made.
+While there are some checks in place, the new default options set this way
+may break the R "magics".
+To address this, options can be restore to
+"factory settings". Here again, there is no guarantee that this can work no
+matter what. A driven
+(or unlucky) user may break this mechanism if modifying it in the module.
+Restarting kernel will be needed in that case.
+
+```python
+%Roptions refresh
+```
+
+## Graphics devices
+
+Graphics devices can be specified precisely as a function in an R namespace.
+For example, "grDevices:png". It is also possible to specify a generic graphical
+device name that is a sequence of graphics devices to try. The first one in that
+sequence that appears to be functioning is then selected.
+
+For example, this is the case when
+the graphics device option is set to "svg". The R package `svglite` is
+the first to try in the sequence. If R fails to load that package there
+are other  SVG devices to try try as alternatives.
+
+To demonstrate this, let's set the graphics devices to "svg":
+
+```python
+import IPython
+ipy = IPython.get_ipython()
+ipy.magics_manager.registry['RMagics'].options.graphics_device_name = 'svg'
+```
+
+The output of the following magic depends on the R
+packages installed on your system. If the R package `svglite` is installed
+its device will be used. Otherwise alternatives will be tried.
+
+```python
+%Roptions show
+```
+
+### Options for graphics device
+
+Graphics devices, selected from a generic names when the case (see above),
+may havee options. These options can be specific to each graphics device.
+
+**note: this is prefixed with an underscore to indicate that the API is
+subject to changes.**
+
+Options to display graphics are under `_options_display`. For example,
+to change the default width:
+
+```python
+(
+    ipy.magics_manager.registry['RMagics'].graphics_device
+    ._options_display
+    .width
+) = 10
+```
+

rpy2-rinterface/src/rpy2/rinterface_lib/callbacks.py

@@ -8,6 +8,7 @@
 import logging
 import sys
 import typing
+import warnings
 import os
 from rpy2.rinterface_lib import openrlib
 from rpy2.rinterface_lib import ffi_proxy
@@ -21,6 +22,20 @@
 # TODO: rename to "replace_in_module"
 @contextmanager
 def obj_in_module(module, name: str, obj: typing.Any):
+    warnings.warn(
+        '"obj_in_module" was renamed to "replace_in_module".',
+        DeprecationWarning
+    )
+    obj_orig = getattr(module, name)
+    setattr(module, name, obj)
+    try:
+        yield
+    finally:
+        setattr(module, name, obj_orig)
+
+
+@contextmanager
+def replace_in_module(module, name: str, obj: typing.Any):
     obj_orig = getattr(module, name)
     setattr(module, name, obj)
     try: