sage-shell-mode is an elisp package and provides an Emacs front end for Sage.

sage-shell-mode provides two main features:

1. sage-shell-mode to run the Sage terminal inside Emacs.
2. sage-shell:sage-mode for editing .sage source files and sending their contents directly to the Sage terminal. This major mode is derived from python-mode.

The package supports extensions with auto-complete-sage, helm-sage, anything-sage and ob-sagemath.

• Requirements
• Installation and Setup
• Aliases
• Basic Usage
• Input history
• SageTeX
• Customization
• Extensions
• Screenshots
• Workaround for flycheck
• License

1. GNU Emacs 24.1 (or 24.4) or later.

   For Sage 7.4 or later, sage-shell-mode requires Emacs 24.4. In that case, you should set sage-shell:use-prompt-toolkit as explained in the following section. The technical reason is that Sage 7.4 uses IPython 5, where python-prompt-toolkit is used instead of GNU readline

   For Sage 7.3 or earlier, Emacs 24.1 is sufficient.

2. Local installation of Sage.
3. The Emacs package deferred. This will be installed automatically if you follow the guide below.

The most convenient is to use the Emacs package manager to install sage-shell-mode from MELPA:

1. See http://melpa.org/#/getting-started if you do not have a configuration for MELPA.
2. Install sage-shell-mode by
   • M-x package-refresh-contents
   • M-x package-install RET sage-shell-mode.
3. Add the following to your Emacs init file (~/.emacs.d/init.el):

   (require 'sage-shell-mode)
       

   This must be added after the line (package-initialize). If you don’t already have that line in you Emacs init file, add it.

4. If you have Sage 7.4 or later, then also add the following:

   (setq sage-shell:use-prompt-toolkit t)
       

5. You can now run Sage inside Emacs by M-x sage-shell:run-sage, if Emacs can find the executable file of Sage.

   If Emacs cannot find the executable file, add the following line to your Emacs init file:

   (setq sage-shell:sage-root "/path/to/sage/root_directory")
       

   And replace /path/to/sage_root_directory by the root directory of Sage, i.e. $SAGE_ROOT. If you do not know the root directory of Sage, evaluate the following code in a Sage terminal:

   import os; print os.environ["SAGE_ROOT"]
       

   Alternatively, instead of setting sage-shell:sage-root, you may set the variable sage-shell:sage-executable.

   (setq sage-shell:sage-executable "/path/to/sage/executable")
       

   Here /path/to/sage/executable is the path of the executable file of Sage. This may be a symbolic link.

Here is a sample configuration.

(require 'sage-shell-mode)
;; Run SageMath by M-x run-sage instead of M-x sage-shell:run-sage
(sage-shell:define-alias)

;; Turn on eldoc-mode in Sage terminal and in Sage source files
(add-hook 'sage-shell-mode-hook #'eldoc-mode)
(add-hook 'sage-shell:sage-mode-hook #'eldoc-mode)

;; If you have Sage 7.4 or later, uncomment the following line.
;; (setq sage-shell:use-prompt-toolkit t)

The official Emacs major mode for Sage is sage-mode. To avoid name conflicts with this package, sage-shell-mode prefixes all names with sage-shell-.

If you are not using sage-mode at all, you can define more convenient aliases for sage-shell-mode by adding the following to your Emacs init file after the line (require 'sage-shell-mode):

(sage-shell:define-alias)

The following aliases will be defined:

This means e.g. that you can do M-x run-sage to run Sage, instead of M-x sage-shell:run-sage.

You can start a Sage process by M-x sage-shell:run-sage. If you need to open multiple Sage processes simultaneously, you can start new ones by M-x sage-shell:run-new-sage.

The major-mode of the Sage process buffer is sage-shell-mode.

The primary element of sage-shell-mode is interacting with the Sage process you just started. The Sage process buffer communicates directly with a Sage shell in the background and behaves very much like it. You just type and send the command with <Enter>:

sage: 2+2
4
sage: (x^2 + 2*x + 1).factor()
(x + 1)^2
sage:

The buffer behaves like an Emacs shell:

• M-p or C-up goes through earlier input.
• Previous input and output is retained earlier in the buffer. You can move around just as usual and e.g. copy from it or search.
• To exit, you can enter quit at the prompt, or simply kill the buffer.

The buffer also behaves much like the Sage terminal:

<Tab> at the prompt completes the current word. It understands all Sage and Python functions currently in scope, and it also completes attributes of objects. If there are multiple possibilities, they are presented in another window.

sage: G = graphs.PetersenGraph()
sage: G.<TAB>
<All methods on G are shown in a new buffer>
sage: G.charp<TAB>
<G.charp is completed uniquely to G.charpoly>

By default, Tab completion uses completion-at-point. Alternatively, you can use pcomplete by adding the following to your Emacs init file:

(setq sage-shell:completion-function 'pcomplete)

You can also use auto-complete, anything or helm for completion. This requires installing those extensions, see Extensions.

By writing the name of an object at the prompt, followed by ? and then RET, you are shown the documentation of that object:

sage: G = graphs.PetersenGraph()
sage: G.charpoly?
<Documentation is shown in a new Sage Document buffer>

This is identical to running C-c C-h and then typing the name of the object.

If you use ?? instead ? after a Sage object, then the source code for that object will be opened in a new buffer:

sage: G = graphs.PetersenGraph()
sage: G.charpoly??
<The file src/sage/graphs/generic_graph.py is opened at "def characteristic_polynomial(...):">

For more commands and key-bindings see the help using M-x describe-mode sage-shell-mode.

When you visit a file with the suffix .sage, then sage-shell:sage-mode will be the major-mode of the buffer automatically.

To switch to sage-shell:sage-mode on a .py file, run M-x sage-shell:sage-mode. To use sage-shell:sage-mode every time you visit that file, you can add the following magic comment at the first line of the file:

# -*- mode: sage-shell:sage -*-

If you’ve activated Aliases you can instead use the following magic comment:

# -*- mode: sage -*-

The major mode sage-shell:sage-mode is almost the same as python-mode. The following new key-bindings are added:

If you run multiple Sage processes, use M-x sage-shell:set-process-buffer to change which one will be used for the above functions.

To save the history of input evaluated in a Sage process and use in future Sage process (using the M-p keybinding), add the following to your Emacs init file:

(setq sage-shell:input-history-cache-file "~/.emacs.d/.sage_shell_input_history")

The file name in the above line is the path for storing the inputs and you can change it to what you prefer.

sage-shell-mode can be conveniently used when writing Sage-powered LaTeX files using SageTeX.

When a Sage process is spawned by sage-shell:run-sage or sage-shell:run-new-sage, then sage-shell-mode adds $SAGE_ROOT/local/share/texmf/tex/generic/sagetex/ to the environment variable TEXINPUTS in Emacs. If you do not want to change the environment variable, set sage-shell-sagetex:add-to-texinputs-p to nil.

Here is a list of commands for SageTeX. These commands load a .sagetex.sage file generated by SageTeX to the existing Sage process.

There are similar commands to above, sage-shell-sagetex:load-current-file, sage-shell-sagetex:run-latex-and-load-current-file and sage-shell-sagetex:compile-current-file.

Here is a sample setting for AUCTeX users.

(eval-after-load "latex"
  '(mapc (lambda (key-cmd) (define-key LaTeX-mode-map (car key-cmd) (cdr key-cmd)))
         `((,(kbd "C-c s c") . sage-shell-sagetex:compile-current-file)
           (,(kbd "C-c s C") . sage-shell-sagetex:compile-file)
           (,(kbd "C-c s r") . sage-shell-sagetex:run-latex-and-load-current-file)
           (,(kbd "C-c s R") . sage-shell-sagetex:run-latex-and-load-file)
           (,(kbd "C-c s l") . sage-shell-sagetex:load-current-file)
           (,(kbd "C-c s L") . sage-shell-sagetex:load-file)
           (,(kbd "C-c C-z") . sage-shell-edit:pop-to-process-buffer))))

For example, you can run sage-shell-sagetex:compile-current-file by C-c s c in a LaTeX-mode buffer with this setting.

You can change a latex command used by sage-shell-sagetex:compile-file and sage-shell-sagetex:compile-current-file by setting sage-shell-sagetex:latex-command or sage-shell-sagetex:auctex-command-name.

If you are an AUCTeX user, then customize sage-shell-sagetex:auctex-command-name to change the latex command. The value of sage-shell-sagetex:auctex-command-name should be a name of a command in TeX-command-list (i.e car of an element of the list TeX-command-list), e.g.:

(setq sage-shell-sagetex:auctex-command-name "LaTeX")

You can also use the variable sage-shell-sagetex:latex-command to change the latex command. For example, if you want to run latexmk after loading a .sagetex.sage file, then use the following setting:

(setq sage-shell-sagetex:latex-command "latexmk")

The default value of sage-shell-sagetex:latex-command is latex -interaction=nonstopmode. If sage-shell-sagetex:auctex-command-name is non-nil, then the value of sage-shell-sagetex:latex-command is ignored.

To customize sage-shell-mode, M-x customize-group RET sage-shell or M-x customize-group RET sage-shell-sagetex.

• auto-complete-sage provides an auto-complete source for sage-shell-mode.
• helm-sage provides a helm source for sage-shell-mode.
• anything-sage provides an anything source for sage-shell-mode.
• ob-sagemath provides org-babel functions for Sage.

Automatic indentation and syntax highlighting work.

Completion with auto-complete-sage.

Completion with helm-sage.

To use flycheck-mode in a sage-shell:sage-mode buffer and a python-mode buffer, try the following code.

(dolist (ckr '(python-pylint python-flake8))
  (flycheck-add-mode ckr 'sage-shell:sage-mode))

(defun sage-shell:flycheck-turn-on ()
  "Enable flycheck-mode only in a file ended with py."
  (when (let ((bfn (buffer-file-name)))
          (and bfn (string-match (rx ".py" eol) bfn)))
    (flycheck-mode 1)))

(add-hook 'python-mode-hook 'sage-shell:flycheck-turn-on)

Licensed under the GPL.