From 6b3c3a0a182027d6af529cf69f2292790b0f1410 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Davide=20Sandon=C3=A0?= Date: Tue, 25 Oct 2022 11:20:35 +0200 Subject: [PATCH] Added plotly_intercept_code configuration option There are use cases where a Plotly figure is being generated by a user defined class and shown through one of the class methods. For example, one of the commands in my module might be: ```python plot(sin(x), (x, -10, 10)) ``` The function `plot` returns a custom `Plot` object, containing the Plotly figure. Inside the `plot` function, the Plotly figure will be shown before the return statement. With the current implementation of this extension it is impossible to visualize the resulting plot. Plotly doesn't have something similar to Matplotlib's figure managers, which "intercepts" the figures being shown at a lower level. Solution: create a new configuration option, `plotly_intercept_code`, which will eventually be set to a user-defined function, accepting the current code-block being processed and returning a modified code. The user can modify the code with regex or ast to extract the Plotly figure from the custom objects. Then, the current implementation will be able to continue successfully. Consider the following code-block example contained into a docstring. If a user executes it, it will show a Plotly figure. ```python fx = lambda u, v: (4 + np.cos(u)) * np.cos(v) fy = lambda u, v: (4 + np.cos(u)) * np.sin(v) fz = lambda u, v: np.sin(u) plot3d_parametric_surface(fx, fy, fz, ("u", 0, 2 * pi), ("v", 0, 2 * pi), rendering_kw=dict( contours={ "z": {"show": True, "start": -1, "end": 1, "size": 1/10, "width": 1, "usecolormap": True} }, showscale=False, colorscale="Aggrnyl"), zlim=(-2.5, 2.5), title="Torus", backend=PB) ``` If this extension executes the above code block, it will open the plot on a new browser window, but it won't be able to include the figure in the docs, because it doesn't know where the figure is actually stored. With this commit, the extension processes this code block, send it to the "intercept code function", where I can use the ast module to modify the code to: ```python fx = lambda u, v: (4 + np.cos(u)) * np.cos(v) fy = lambda u, v: (4 + np.cos(u)) * np.sin(v) fz = lambda u, v: np.sin(u) myplot = plot3d_parametric_surface(fx, fy, fz, ("u", 0, 2 * pi), ("v", 0, 2 * pi), rendering_kw=dict( contours={ "z": {"show": True, "start": -1, "end": 1, "size": 1/10, "width": 1, "usecolormap": True} }, showscale=False, colorscale="Aggrnyl"), zlim=(-2.5, 2.5), title="Torus", backend=PB, show=False) myplot.fig ``` Here: 1. I assigned the object returned by the plot command to a variable. 2. I added `show=False` to the plot command, so no figure will be shown on the browser (which is annoying if you have dozen of figures opening every time you build the docs). 3. I added a new command extracting the Plotly figure from my custom object. Once this modified code is returned, it will be normally processed by this extension and everything works as expected. --- sphinx_plotly_directive/__init__.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/sphinx_plotly_directive/__init__.py b/sphinx_plotly_directive/__init__.py index 6120b03..95848b8 100644 --- a/sphinx_plotly_directive/__init__.py +++ b/sphinx_plotly_directive/__init__.py @@ -151,6 +151,12 @@ plotly_template Provide a customized template for preparing restructured text. + + plotly_intercept_code + A function accepting one argument (the current code block being + processed), returning a modified code. This can be used to extract the + figure object from custom data classes in order for them to be + intercepted and rendered by this extension. """ import copy @@ -300,6 +306,7 @@ def setup(app): app.add_config_value("plotly_iframe_width", "100%", True) app.add_config_value("plotly_iframe_height", "500px", True) app.add_config_value("plotly_template", None, True) + app.add_config_value("plotly_intercept_code", None, True) app.add_config_value("plotly_include_directive_source", None, False) @@ -533,6 +540,13 @@ def run_code(code, code_path, ns=None, function_name=None, fig_vars=None): ns["__name__"] = "__main__" variable_name = "fig" + intercept_code = setup.config.plotly_intercept_code + if intercept_code is None: + intercept_code = lambda x: x + elif not callable(intercept_code): + raise TypeError("`plotly_intercept_code` must be a function " + "accepting one argument (the current code block being " + "processed), returning a modified code.") if ends_with_show(code): exec(strip_last_line(code), ns) @@ -545,7 +559,8 @@ def run_code(code, code_path, ns=None, function_name=None, fig_vars=None): exec(code, ns) figs = [ns[fig_var] for fig_var in fig_vars] else: - exec(assign_last_line_into_variable(code, variable_name), ns) + exec(assign_last_line_into_variable( + intercept_code(code), variable_name), ns) figs = [ns[variable_name]] except (Exception, SystemExit) as err: