feat: Add mermaid output to show_graph

[kjgoodrick]

This pull request would close #12075 and supersedes #20607. Thanks again to @ritchie46, @eitsupi, and @alexander-beedie for their feedback.

This PR adds support for mermaid string generation to polars. In #12075 it was suggested that mermaid output be added to explain, but I believe that it makes more sense to have mermaid output come from the show_graph method instead of explain because explain appears to be for generating printable representations of the query plan wheras show_graph is for generating strings that can be fed to a visualization engine (currently just graphviz).

In addition to being able to output mermaid strings this PR will output a mermaid diagram if the user is in a notebook and graphviz is not installed when calling show_graph. I think at some point it may be a better user experience to always export mermaid instead of the SVG in notebooks, but for now I did not want to change the behavior. I also considered adding functionality that would change the behavior of _repr_html_ to show a mermaid diagram if graphviz is not installed, but if without a way to check if the user can render mermaid this could be a worse user experience than the current behavior which calls explain.

Compared with #20607 this PR generates the mermaid string in rust instead of in python.

Here is a sample output:

Note that the mermaid renderer in Jupyter Lab and VS Code (with extension) is theme aware, so the graph changes color with the user theme.

[codecov]

Codecov Report

Attention: Patch coverage is 3.70370% with 78 lines in your changes missing coverage. Please review.

Project coverage is 78.97%. Comparing base (247f0b1) to head (6b93896).
Report is 29 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/polars-lazy/src/mermaid.rs	0.00%	38 Missing ⚠️
py-polars/polars/_utils/various.py	5.26%	18 Missing ⚠️
py-polars/polars/lazyframe/frame.py	5.26%	17 Missing and 1 partial ⚠️
crates/polars-python/src/lazyframe/general.rs	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #20631      +/-   ##
==========================================
- Coverage   79.03%   78.97%   -0.07%     
==========================================
  Files        1557     1560       +3     
  Lines      220528   221296     +768     
  Branches     2510     2537      +27     
==========================================
+ Hits       174303   174761     +458     
- Misses      45651    45954     +303     
- Partials      574      581       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mcrumiller]

Any way to set it to fixed-width font like Consolas? Reading code in variable-width font is just hard on the eyes.

[kjgoodrick]

@mcrumiller Yes, it is possible to specify a monospace font family in the initialization. If we were to do that, I think it would make sense to generate the raw output without any special settings, but we could insert it prior to displaying to users.

As an example, here is the same chart as above with an initialization of %%{init: {"fontFamily": "monospace"}}%%

[etiennebacher]

It seems to me that .show_graph() becomes quite complicated by returning various output types depending on the arguments. It's also not very clear from the outside how those arguments interact. For example if I read

.show_graph(show=True, raw_output_format="mermaid", output_path="foobar")

then it's not clear to me what I should expect (the current behavior would be to ignore show and output_path).

Since to_dot() and to_mermaid() already exist on the Rust side, wouldn't it be better to have the following function signatures in Python?

def to_dot(
    self,
    *,
    [ optimization args ]
) -> str

def to_mermaid(
    self,
    *,
    [ optimization args ]
) -> str

def show_graph(
    self,
    *,
    format = "graphviz",
    output_path = None,
    [ optimization args ]
) -> None

[kjgoodrick]

@etiennebacher thanks for these comments. Initially, I assumed that anyone needing to output a file would use Graphviz, but you're correct that it is confusing if output_path is silently ignored. It's also possible to generate the output files with a subprocess call in the same way that it is done for graphviz. I've updated the PR to support output file generation with both graphviz and mermaid.

I have also incorporated @mcrumiller's suggestion, and the mermaid graph now uses monospace font when showing or outputting.

My goal with this PR was to add mermaid support without changing the existing API. I have no issue with dedicated functions to access the dot or mermaid raw outputs, but to maintain backwards compatibility we would need to keep logic in show_graph, so it's not clear if that would be worth it.

One small change to note: previously, calls to show_graph with an output path or show=True raised an error if Graphviz wasn't installed. With this PR, in a notebook, a Mermaid graph is displayed without error, and if mmdc is installed, an output file is generated. I believe this is an improvement but wanted to flag it for clarity.

[etiennebacher]

My goal with this PR was to add mermaid support without changing the existing API. I have no issue with dedicated functions to access the dot or mermaid raw outputs, but to maintain backwards compatibility we would need to keep logic in show_graph, so it's not clear if that would be worth it.

I can open a dedicated issue based on my first comment so that this PR is only on the mermaid implementation.