Edit the source code of Sage interactively


  • Nils Bruin

  • William Stein – touch up for inclusion in Sage.

  • Simon King: Make it usable on extension classes that do not have a docstring; include this module into the reference manual and fix some syntax errors in the doc strings.

This module provides a routine to open the source file of a python object in an editor of your choice, if the source file can be figured out. For files that appear to be from the sage library, the path name gets modified to the corresponding file in the current branch, i.e., the file that gets copied into the library upon ‘sage -br’.

The editor to be run, and the way it should be called to open the requested file at the right line number, can be supplied via a template. For a limited number of editors, templates are already known to the system. In those cases it suffices to give the editor name.

In fact, if the environment variable EDITOR is set to a known editor, then the system will use that if no template has been set explicitly.

sage.misc.edit_module.edit(obj, editor=None, bg=None)

Open source code of obj in editor of your choice.


  • editor – str (default: None); If given, use specified editor. Choice is stored for next time.


Nils Bruin (2007-10-03)


This is a typical example of how to use this routine:

# make some object obj
sage: edit(obj)    # not tested

Now for more details and customization:

sage: import sage.misc.edit_module as m
sage: m.set_edit_template("vi -c ${line} ${file}")

In fact, since vi is a well-known editor, you could also just use:

sage: m.set_editor("vi")

To illustrate:

sage: m.edit_template.template
'vi -c ${line} ${file}'

And if your environment variable EDITOR is set to a recognised editor, you would not have to set anything.

To edit the source of an object, just type something like:

sage: edit(edit)           # not tested
sage.misc.edit_module.edit_devel(self, filename, linenum)

This function is for internal use and is called by IPython when you use the IPython commands %edit or %ed.

This hook calls the default implementation, but changes the filename for files that appear to be from the sage library: if the filename begins with ‘SAGE_LOCAL/lib/python…/site-packages’, it replaces this by ‘SAGE_ROOT/src’.


sage: %edit gcd         # indirect doctest, not tested
sage: %ed gcd           # indirect doctest, not tested

The above should open your favorite editor (as stored in the environment variable EDITOR) with the file in which gcd is defined, and when your editor supports it, also at the line in which gcd is defined.


Look up source file and line number of obj.

If the file lies in the Sage library, the path name of the corresponding file in the current branch (i.e., the file that gets copied into the Sage library upon running ‘sage -br’). Note that the first line of a file is considered to be 1 rather than 0 because most editors think that this is the case.


  • Nils Bruin (2007-10-03)

  • Simon King (2011-05): Use sageinspect to get the file and the line.


sage: import sage.misc.edit_module as edit_module
sage: edit_module.file_and_line(sage)
('...sage/__init__.py', 0)

The following tests against a bug that was fixed in trac ticket #11298:

sage: edit_module.file_and_line(x)
('...sage/symbolic/expression...pyx', ...)

Set the default edit template string.

It should reference ${file} and ${line}. This routine normally needs to be called prior to using ‘edit’. However, if the editor set in the shell variable EDITOR is known, then the system will substitute an appropriate template for you. See edit_module.template_defaults for the recognised templates.


Nils Bruin (2007-10-03)


sage: from sage.misc.edit_module import set_edit_template
sage: set_edit_template("echo EDIT ${file}:${line}")
sage: edit(sage)      # not tested
EDIT /usr/local/sage/src/sage/__init__.py:1
sage.misc.edit_module.set_editor(editor_name, opts='')

Set the editor to be used by the edit command by basic editor name.

Currently, the system only knows appropriate call strings for a limited number of editors. If you want to use another editor, you should set the whole edit template via set_edit_template().


Nils Bruin (2007-10-05)


sage: from sage.misc.edit_module import set_editor
sage: set_editor('vi')
sage: sage.misc.edit_module.edit_template.template
'vi -c ${line} ${file}'

Given a String.Template object, returns the fields.


Nils Bruin (2007-10-22)


sage: from sage.misc.edit_module import template_fields
sage: from string import Template
sage: t = Template("Template ${one} with ${two} and ${three}")
sage: sorted(template_fields(t))
['one', 'three', 'two']