Allow Cython compilation to open a web browser containing the annotated HTML file

[user202729]

As in the title.

I think this is a rather common use case, to investigate whether the code does get the desired speedup.

Remark: there's sage.misc.viewer.browser() which could be used instead, but then a lot of existing code in SageMath uses webbrowser.open() anyway?

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion. (not aware of one)
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

Dependencies

Depends on #38945 .

[github-actions]

Documentation preview for this PR (built with commit 6116696; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[kwankyu]

This looks nice.

It would be nicer if the new argument view_annotate is accepted to the cell magic %%cython. For example,

%%cython view_annotate=True
def f(int n):
...

or

%%cython --view_annotate
def f(int n):
...

The cell magic is defined in https://github.com/sagemath/sage/blob/develop/src/sage/repl/ipython_extension.py. Find the line

def cython(self, line, cell):

line seems to accept the part after "%%cython". So we may use it to provide arguments to the cython function. What do you think?

[user202729]

Already did that in #38945 . (though whichever being merged first need to be modified to incorporate the other…)

[kwankyu]

You may set #38945 as a dependency and merge it here.

[kwankyu]

and instead of

- ``line`` -- parsed as keyword arguments. See :func:`~sage.misc.cython.cython` for details.

you may at least list the possible arguments for users' convenience, leaving details to sage.misc.cython.cython .

[user202729]

I learnt it's possible to view the result in the Sage notebook (if Jupyter-based notebook GUI is used) from looking at cython-provided magic, so I implement that here.

[user202729]

@kwankyu Can you review the PR? Thanks.

[kwankyu]

Conflicts?

[user202729]

Huh, that only come from the new commits for 10.6.beta2 today. This one is pretty harmless.

[kwankyu]

On comand line (on mac),

sage: %%cython --view-annotate
....: def f(int n):
....:     return n*n
....: 

does not open a web browser.

[user202729]

Not sure what's going on, but probably doesn't have anything to do with the code. There are some complaints e.g. https://stackoverflow.com/questions/65981130/python-webbrowser-module-doesnt-work-on-terminal or python/cpython#69143

You can try oeis.browse() which also uses webbrowser.open() — if it also doesn't work it probably isn't the program's fault.

If it does work, maybe you can try this patch

diff --git a/src/sage/misc/cython.py b/src/sage/misc/cython.py
index fde36372712..3689c896b4a 100644
--- a/src/sage/misc/cython.py
+++ b/src/sage/misc/cython.py
@@ -81,7 +81,7 @@ sequence_number = {}
 
 def cython(filename, verbose=0, compile_message=False,
            use_cache=False, create_local_c_file=False, annotate=True, view_annotate=False,
-           view_annotate_callback=webbrowser.open, sage_namespace=True, create_local_so_file=False):
+           view_annotate_callback=lambda x: webbrowser.open("file://" + x), sage_namespace=True, create_local_so_file=False):
     r"""
     Compile a Cython file. This converts a Cython file to a C (or C++ file),
     and then compiles that. The .c file and the .so file are

[kwankyu]

If it does work, maybe you can try this patch

diff --git a/src/sage/misc/cython.py b/src/sage/misc/cython.py
index fde36372712..3689c896b4a 100644
--- a/src/sage/misc/cython.py
+++ b/src/sage/misc/cython.py
@@ -81,7 +81,7 @@ sequence_number = {}
 
 def cython(filename, verbose=0, compile_message=False,
            use_cache=False, create_local_c_file=False, annotate=True, view_annotate=False,
-           view_annotate_callback=webbrowser.open, sage_namespace=True, create_local_so_file=False):
+           view_annotate_callback=lambda x: webbrowser.open("file://" + x), sage_namespace=True, create_local_so_file=False):
     r"""
     Compile a Cython file. This converts a Cython file to a C (or C++ file),
     and then compiles that. The .c file and the .so file are

Yes. That does the trick. For readability, you may want to store the lambda function to a variable first, before line 82.

[user202729]

I come across #33931 , while it looks like the PR is stalled it is recommended to use webbrowser over sage.misc.viewer. So I'll use webbrowser.open() anyway.

[kwankyu]

Thanks. LGTM.

[antonio-rojas]

A test is failing here

**********************************************************************
File "/usr/lib/python3.13/site-packages/sage/repl/ipython_extension.py", line 433, in sage.repl.ipython_extension.SageMagics.cython
Failed example:
    shell.run_cell('''
    %%cython --view-annotate=xx
    print(1)
    ''')
Expected:
    UsageError: argument --view-annotate: invalid choice: 'xx' (choose from 'none', 'auto', 'webbrowser', 'displayhtml')
Got:
    UsageError: argument --view-annotate: invalid choice: 'xx' (choose from none, auto, webbrowser, displayhtml)
**********************************************************************

[user202729]

Should be fixed in #39282