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]

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

[user202729]

This PR leads to an annoying consequence: look at https://doc-pr-39509--sagemath.netlify.app/html/en/reference/misc/sage/misc/cython#hunk1

sage.misc.cython.cython(filename, verbose=0, compile_message=False, use_cache=False, create_local_c_file=False, annotate=True, view_annotate=False, view_annotate_callback=<function _webbrowser_open_file at 0x7f3980c4dc60>, sage_namespace=True, create_local_so_file=False)[source]

the address in <function _webbrowser_open_file at 0x7f3980c4dc60> is essentially random, which leads to it showing up in the documentation diff every time.

So far the best way I can think of is to use something like https://stackoverflow.com/questions/6978328/documenting-with-sphinx-python-methods-that-do-have-default-parameters-with-sent to override __repr__ of the function object.

(the other is to let the default be None and in the function body handles accordingly, but that is somewhat semantically misleading in that normally None should represent a function that do nothing)

[kwankyu]

Right..

(the other is to let the default be None and in the function body handles accordingly, but that is somewhat semantically misleading in that normally None should represent a function that do nothing)

I prefer this approach. I think this is rather a "standard way". You may add an explanation in the docstring to avoid confusion.