Welcome to Emacs IPython Notebook’s documentation! — Emacs IPython Notebook 0.2.1alpha1 documentation (original) (raw)

Emacs IPython Notebook (EIN) provides a IPython Notebook client and integrated REPL (like SLIME) in Emacs. While EIN makes notebook editing very powerful by allowing you to use any Emacs features, it also expose IPython features such as code evaluation, object inspection and code completion to the Emacs side. These features can be accessed anywhere in Emacs and improve Python code editing and reading in Emacs.

Highlighted features:

Other notebook features:

Links:

[1] You need to setup ein:console-args properly
[2] Use the command ein:connect-to-notebook-command.

Contents

Quick try

This is a quick and clean way to try EIN separately from your Emacs setting. If you want to try EIN but think preparing all the requirements is too much, try this!:

git clone git://github.com/tkf/emacs-ipython-notebook.git cd emacs-ipython-notebook/ lisp/zeroein.el

This will launch a new Emacs instance.

You can use environment variable EMACS to control Emacs executable to use.:

EMACS=emacs-snapshot lisp/zeroein.el

The above command requires /bin/sh. If the above command does not work (e.g., you are using MS Windows), try the following command:

emacs -Q -l lisp/zeroein.el

Requirements

Also, EIN heavily relies on standard Emacs libraries including EWOC, EIEIO and json.el. EIN is currently tested against Emacs 23.3 and 24.3. It is known to work in Emacs 23.2, 24.1 and 24.2.

[3] SeeGotchas and caveats > python-mode.el.

Install

Warning

As EIN relies on many packages and it will not work properly with outdated versions, installing it using el-get or MELPA is highly recommended.

Using el-get

If you use developmental version of el-get, you can install it easily using it. Emacs IPython Notebook is registered as packageein. See el-get website for more information.

Using package.el (MELPA)

You can install EIN using package.el when MELPA package repository is added to its setting. See MELPA website for more information.

Manual install

Put Emacs lisp ein*.el files and Python file ein.py in a directory defined in your load-path.

You should byte compile EIN, especially when using MuMaMo, otherwise editing large notebook will be very slow. You can use the following command to compile EIN. If you don’t specify all the optional packages, there will be compiler warning but that is OK as long as you don’t use that optional package.

emacs -Q -batch -L . \ # don't forget the dot! -L PATH/TO/websocket/
-L PATH/TO/nxhtml/util/ \ # optional (for MuMaMo) -L PATH/TO/auto-complete/ \ # optional -L PATH/TO/popup/ \ # optional (for auto-complete) -L PATH/TO/fuzzy/ \ # optional (for auto-complete) -L PATH/TO/smartrep/ \ # optional -L PATH/TO/rst-mode/ \ # optional -f batch-byte-compile *.el

Setup

Here is the minimal configuration. See customization for more details.

Usage

  1. Start IPython notebook server.
  2. Hit M-x ein:notebooklist-open to open notebook list. This will open notebook list buffer.
  3. In the notebook list buffer, you can open notebooks by hitting[Open] buttons. See notebooksection for what you can do in the notebook buffer.

Commands/Keybinds

Notebook list

You can start notebook by M-x ein:notebooklist-open and enter the port or URL of the IPython notebook server.

function (ein:notebooklist-open &optional url-or-port no-popup)

Open notebook list buffer.

function (ein:notebooklist-new-notebook &optional url-or-port callback cbargs)

Ask server to create a new notebook and open it in a new buffer.

function (ein:notebooklist-open-notebook-global nbpath &optional callback cbargs)

Choose notebook from all opened notebook list and open it. Notebook is specified by a string NBPATH whose format is “URL-OR-PORT/NOTEBOOK-NAME”.

When used in lisp, CALLBACK and CBARGS are passed to ein:notebook-open.

function (ein:notebooklist-login url-or-port password)

Login to IPython notebook server.

function (ein:junk-new name url-or-port)

Open a notebook to try random thing. Notebook name is determined based onein:junk-notebook-name-template.

When prefix argument is given, it asks URL or port to use.

Keymap for ein:notebooklist-mode.

TAB widget-forward

C-M-i widget-backward

widget-backward

widget-backward

C-c C-r ein:notebooklist-reload

Reload current Notebook list.

g ein:notebooklist-reload

Reload current Notebook list.

p ein:notebooklist-prev-item

n ein:notebooklist-next-item

q bury-buffer

Notebook

The following keybinds are available in notebook buffers.

C-c C-c ein:worksheet-execute-cell

Execute code type CELL.

C-c C-' ein:worksheet-turn-on-autoexec

Turn on auto-execution flag of the cells in region or cell at point. When the prefix argument is given, turn off the flag instead.

To use autoexec feature, you need to turn on auto-execution mode in connected buffers, using the ein:connect-toggle-autoexeccommand.

C-c C-e ein:worksheet-toggle-output

Toggle the visibility of the output of the cell at point. This does not alter the actual data stored in the cell.

C-c C-v ein:worksheet-set-output-visibility-all

Show all cell output. When prefix is given, hide all cell output.

C-c C-l ein:worksheet-clear-output

Clear output from the current cell at point. Do not clear input prompt when the prefix argument is given.

C-c C-S-l ein:worksheet-clear-all-output

Clear output from all cells. Do not clear input prompts when the prefix argument is given.

C-c C-; ein:shared-output-show-code-cell-at-point

Show code cell at point in shared-output buffer. It is useful when the output of the cell at point is truncated. See also ein:cell-max-num-outputs.

C-c C-k ein:worksheet-kill-cell

Kill (“cut”) the cell at point or cells in region. Note that the kill-ring for cells is not shared with the default kill-ring of Emacs (kill-ring for texts).

C-c M-w ein:worksheet-copy-cell

Copy the cell at point. (Put the current cell into the kill-ring.)

C-c M-{ ein:notebook-worksheet-move-prev

Switch the current worksheet with the previous one.

C-c M-} ein:notebook-worksheet-move-next

Switch the current worksheet with the previous one.

C-c M-+ ein:notebook-worksheet-insert-prev

Insert a new worksheet before this worksheet and open it. See also ein:notebook-worksheet-insert-next.

(fn NOTEBOOK WS &optional (RENDER t) (SHOW (function switch-to-buffer)))

C-c C-w ein:worksheet-copy-cell

Copy the cell at point. (Put the current cell into the kill-ring.)

C-c C-y ein:worksheet-yank-cell

Insert (“paste”) the latest killed cell. Prefixes are act same as the normal yank command.

C-c C-a ein:worksheet-insert-cell-above

Insert cell above. Insert markdown cell instead of code cell when the prefix argument is given. See also: ein:worksheet-insert-cell-below.

C-c C-b ein:worksheet-insert-cell-below

Insert cell below. Insert markdown cell instead of code cell when the prefix argument is given.

When used as a lisp function, insert a cell of TYPE-OR-CELL just after PIVOT and return the new cell.

C-c C-t ein:worksheet-toggle-cell-type

Toggle the cell type of the cell at point. Use ein:worksheet-change-cell-type to change the cell type directly.

C-c C-u ein:worksheet-change-cell-type

Change the cell type of the current cell. Prompt will appear in the minibuffer.

When used in as a Lisp function, TYPE (string) should be chose from “code”, “markdown”, “raw” and “heading”. LEVEL is an integer used only when the TYPE is “heading”.

C-c C-s ein:worksheet-split-cell-at-point

Split cell at current position. Newlines at the splitting point will be removed. This can be omitted by giving a prefix argument (C-u).

C-c C-m ein:worksheet-merge-cell

Merge previous cell into current cell. If prefix is given, merge current cell into next cell.

C-c C-n ein:worksheet-goto-next-input

C-c C-p ein:worksheet-goto-prev-input

C-c ein:worksheet-move-cell-up

C-c ein:worksheet-move-cell-down

C-c C-f ein:pytools-request-tooltip-or-help

Show the help for the object at point using tooltip. When the prefix argument C-u is given, open the help in the pager buffer. You can explicitly specify the object by selecting it.

C-c C-i ein:completer-complete

Start completion for the code at point.

(fn KERNEL &rest ARGS &key CALLBACKS &allow-other-keys)

C-c C-x ein:tb-show

Show full traceback in traceback viewer.

C-c C-r ein:notebook-restart-kernel-command

Send request to the server to restart kernel.

C-c C-z ein:notebook-kernel-interrupt-command

Interrupt the kernel. This is equivalent to do C-c in the console program.

C-c C-q ein:notebook-kill-kernel-then-close-command

Kill kernel and then kill notebook buffer. To close notebook without killing kernel, just close the buffer as usual.

C-c C-# ein:notebook-close

Close NOTEBOOK and kill its buffer.

C-c C-o ein:console-open

Open IPython console. To use this function, ein:console-security-dir andein:console-args must be set properly. This function works best with the new python.el which is shipped with Emacs 24.2 or later. If you don’t have it, this function opens a “plain” command line interpreter (comint) buffer where you cannot use fancy stuff such as TAB completion. It should be possible to support python-mode.el. Patches are welcome!

C-c C-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

C-c C-, ein:pytools-jump-back-command

Go back to the point where ein:pytools-jump-to-source-commandis executed last time. When the prefix argument C-u is given, open the last point in the other window.

C-c C-/ ein:notebook-scratchsheet-open

Open “scratch sheet”. Open a new one when prefix argument is given. Scratch sheet is almost identical to worksheet. However, EIN will not save the buffer. Use this buffer like of normal IPython console. Note that you can always copy cells into the normal worksheet to save result.

C-c ! ein:worksheet-rename-sheet

Change worksheet name (not notebook name).

C-c { ein:notebook-worksheet-open-prev-or-last

Open previous or last worksheet. See also ein:notebook-worksheet-open-next-or-first andein:notebook-worksheet-open-prev.

C-c } ein:notebook-worksheet-open-next-or-first

Open next or first worksheet.

Try to open the worksheet to the worksheet WS using the functionein:notebook-worksheet-open-next, open the first worksheet if not found.

SHOW is a function to be called with the worksheet buffer if given.

C-c + ein:notebook-worksheet-insert-next

Insert a new worksheet after this worksheet and open it. See also ein:notebook-worksheet-insert-prev.

(fn NOTEBOOK WS &optional (RENDER t) (SHOW (function switch-to-buffer)))

C-c - ein:notebook-worksheet-delete

Delete the current worksheet. When used as a lisp function, delete worksheet WS from NOTEBOOk.

C-c 1 ein:notebook-worksheet-open-1th

Open 1-th worksheet.

C-c 2 ein:notebook-worksheet-open-2th

Open 2-th worksheet.

C-c 3 ein:notebook-worksheet-open-3th

Open 3-th worksheet.

C-c 4 ein:notebook-worksheet-open-4th

Open 4-th worksheet.

C-c 5 ein:notebook-worksheet-open-5th

Open 5-th worksheet.

C-c 6 ein:notebook-worksheet-open-6th

Open 6-th worksheet.

C-c 7 ein:notebook-worksheet-open-7th

Open 7-th worksheet.

C-c 8 ein:notebook-worksheet-open-8th

Open 8-th worksheet.

C-c 9 ein:notebook-worksheet-open-last

Open the last worksheet.

M-RET ein:worksheet-execute-cell-and-goto-next

Execute cell at point if it is a code cell and move to the next cell, or insert if none.

M-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

M-, ein:pytools-jump-back-command

Go back to the point where ein:pytools-jump-to-source-commandis executed last time. When the prefix argument C-u is given, open the last point in the other window.

M-p ein:worksheet-previous-input-history

Insert the previous input in the execution history. You can go back further in the history by repeating this command. Use ein:worksheet-next-input-history to go forward in the history.

M-n ein:worksheet-next-input-history

Insert next input in the execution history. You can go forward further in the history by repeating this command. Use ein:worksheet-previous-input-history to go back in the history.

ein:worksheet-execute-cell-and-insert-below

Execute cell at point if it is a code cell and insert a cell bellow.

ein:worksheet-goto-prev-input

ein:worksheet-goto-next-input

ein:worksheet-move-cell-up

ein:worksheet-move-cell-down

C-: ein:shared-output-eval-string

Evaluate a piece of code. Prompt will appear asking the code to run. This is handy when you want to execute something quickly without making a cell. If the code outputs something, it will go to the shared output buffer. You can open the buffer by the commandein:shared-output-pop-to-buffer.

C-x C-s ein:notebook-save-notebook-command

Save the notebook.

C-x C-w ein:notebook-rename-command

Rename current notebook and save it immediately.

NAME is any non-empty string that does not contain ‘/’ or ‘’.

function (ein:worksheet-delete-cell ws cell &optional focus)

Delete a cell. (WARNING: no undo!) This command has no key binding because there is no way to undo deletion. Use kill to play on the safe side.

If you really want use this command, you can do something like this (but be careful when using it!):

(define-key ein:notebook-mode-map "\C-c\C-d" 'ein:worksheet-delete-cell)

function (ein:junk-rename name)

Rename the current notebook based on ein:junk-notebook-name-templateand save it immediately.

function ein:notebook-kill-all-buffers

Close all opened notebooks.

function (ein:iexec-mode &optional arg)

Instant cell execution minor mode. Code cell at point will be automatically executed after any change in its input area.

Connected buffer

You can connect any buffer (typically buffer opening Python file) to opened notebook and use the kernel of the notebook to execute the code, inspect objects, auto-complete code, jump to the other source, etc. Once the buffer is connected to the notebook, minor modeein:connect-mode is enabled and the following keybinds are available.

C-c C-c ein:connect-run-or-eval-buffer

Run buffer using the %run magic command or eval whole buffer if the prefix C-u is given. Variable ein:connect-run-command sets the command to run. You can change the command and/or set the options. See also: ein:connect-run-buffer, ein:connect-eval-buffer.

C-c C-l ein:connect-reload-buffer

Reload buffer using the command set by ein:connect-reload-command.

C-c C-r ein:connect-eval-region

C-c C-f ein:pytools-request-tooltip-or-help

Show the help for the object at point using tooltip. When the prefix argument C-u is given, open the help in the pager buffer. You can explicitly specify the object by selecting it.

C-c C-i ein:completer-complete

Start completion for the code at point.

(fn KERNEL &rest ARGS &key CALLBACKS &allow-other-keys)

C-c C-z ein:connect-pop-to-notebook

C-c C-a ein:connect-toggle-autoexec

Toggle auto-execution mode of the current connected buffer.

When auto-execution mode is on, cells in connected notebook will be automatically executed whenever run, eval or reload command [4]is called in this buffer.

[4] Namely, one of ein:connect-run-buffer ein:connect-eval-buffer ein:connect-run-or-eval-buffer ein:connect-reload-buffer

Note that you need to set cells to run in the connecting buffer or no cell will be executed. Use the ein:worksheet-turn-on-autoexec command in notebook to change the cells to run.

C-c C-o ein:console-open

Open IPython console. To use this function, ein:console-security-dir andein:console-args must be set properly. This function works best with the new python.el which is shipped with Emacs 24.2 or later. If you don’t have it, this function opens a “plain” command line interpreter (comint) buffer where you cannot use fancy stuff such as TAB completion. It should be possible to support python-mode.el. Patches are welcome!

C-c C-x ein:tb-show

Show full traceback in traceback viewer.

C-c C-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

C-c C-, ein:pytools-jump-back-command

Go back to the point where ein:pytools-jump-to-source-commandis executed last time. When the prefix argument C-u is given, open the last point in the other window.

C-c C-/ ein:notebook-scratchsheet-open

Open “scratch sheet”. Open a new one when prefix argument is given. Scratch sheet is almost identical to worksheet. However, EIN will not save the buffer. Use this buffer like of normal IPython console. Note that you can always copy cells into the normal worksheet to save result.

C-: ein:shared-output-eval-string

Evaluate a piece of code. Prompt will appear asking the code to run. This is handy when you want to execute something quickly without making a cell. If the code outputs something, it will go to the shared output buffer. You can open the buffer by the commandein:shared-output-pop-to-buffer.

M-. ein:pytools-jump-to-source-command

Jump to the source code of the object at point. When the prefix argument C-u is given, open the source code in the other window. You can explicitly specify the object by selecting it.

M-, ein:pytools-jump-back-command

Go back to the point where ein:pytools-jump-to-source-commandis executed last time. When the prefix argument C-u is given, open the last point in the other window.

Other useful commands:

function (ein:connect-to-notebook-command &optional not-yet-opened)

Connect to notebook. When the prefix argument is given, you can choose any notebook on your server including the ones not yet opened. Otherwise, already chose from already opened notebooks.

function ein:connect-eval-buffer

Evaluate the whole buffer. Note that this will run the code inside the if __name__ == "__main__": block.

function (ein:connect-run-buffer &optional ask-command)

Run buffer using %run. Ask for command if the prefix C-u is given. Variable ein:connect-run-command sets the default command.

Traceback viewer

Traceback in notebook buffer is not easy to understand. You can open Traceback viewer by the command ein:notebook-view-traceback. In the Traceback viewer, following keybinds are available.

Keymap for ein:traceback-mode.

RET ein:tb-jump-to-source-at-point-command

p ein:tb-prev-item

n ein:tb-next-item

q bury-buffer

Misc

function helm-ein-kernel-history

Search kernel execution history then insert the selected one.

function helm-ein-notebook-buffers

Choose opened notebook using helm interface.

function anything-ein-kernel-history

Search kernel execution history then insert the selected one.

function anything-ein-notebook-buffers

Choose opened notebook using anything.el interface.

Org-mode integration

You can link to IPython notebook from org-mode files.

  1. Call org-mode function org-store-link [5] in notebook buffer. You can select a region to specify a position in the notebook.
  2. Go to org-mode file and type C-c C-l(org-insert-link). This will insert a link to the notebook.
  3. Type C-c C-o (org-open-at-point) to open the link at the point of cursor.
[5] See 1.3 Activation in org-mode manual.

Customization

You can customize EIN using the Emacs customization UI by typingM-x customize-group RET ein RET. All the configurable variables are listed below.

Subpackages

variable ein:use-auto-complete

Set to t to use preset auto-complete configuration. Use ein:use-auto-complete-superpack when you need more powerful auto completion.

variable ein:use-auto-complete-superpack

Set to t to use preset a little bit hacky auto-complete configuration. When this option is enabled, cached omni completion is available.

variable ein:ac-max-cache

Maximum number of cache to store.

variable ein:use-smartrep

Set to t to use preset smartrep configuration.

Warning

When used with MuMaMo (see ein:notebook-modes), keyboard macro which manipulates cell (add, remove, move, etc.) may start infinite loop (you need to stop it withC-g). Please be careful using this option if you are a heavy keyboard macro user. Using keyboard macro for other commands is fine.

variable ein:load-dev

Load development helper.

Notebook list

variable ein:url-or-port

List of default url-or-port values. This will be used for completion. So put your IPython servers. You can connect to servers not in this list (but you will need to type every time).

variable ein:default-url-or-port

Default URL or port. This should be your main IPython Notebook server.

function (ein:notebooklist-load &optional url-or-port)

Load notebook list but do not pop-up the notebook list buffer.

For example, if you want to load notebook list when Emacs starts, add this in the Emacs initialization file:

(add-to-hook 'after-init-hook 'ein:notebooklist-load)

or even this (if you want fast Emacs start-up):

;; load notebook list if Emacs is idle for 3 sec after start-up (run-with-idle-timer 3 nil #'ein:notebooklist-load)

You should setup ein:url-or-port or ein:default-url-or-portin order to make this code work.

See also:ein:connect-to-default-notebook, ein:connect-default-notebook.

Notebook

variable ein:worksheet-enable-undo

Configure undo in notebook buffers.

no : symbol

Do not use undo in notebook buffers. It is the safest option.

yes : symbol

Enable undo in notebook buffers. You can’t undo after modification of cell (execution, add, remove, etc.). This is default.

full : symbol

Enable full undo in notebook buffers. It is powerful but sometime (typically after the cell specific commands) undo mess up notebook buffer. Use it on your own risk. When the buffer is messed up, you can just redo and continue editing, or save it once and reopen it if you want to be careful.

You need to reopen the notebook buffer to reflect the change of this value.

variable ein:notebook-modes

Notebook modes to use (in order of preference).

When the notebook is opened, mode in this value is checked one by one and the first usable mode is used.

Available modes:

Examples:

Use MuMaMo if it is installed. Otherwise, use plain mode. This is the old default setting:

(setq ein:notebook-modes '(ein:notebook-mumamo-mode ein:notebook-plain-mode))

Avoid using MuMaMo even when it is installed:

(setq ein:notebook-modes '(ein:notebook-plain-mode))

Use simple python-mode based notebook mode when MuMaMo is not installed:

(setq ein:notebook-modes '(ein:notebook-mumamo-mode ein:notebook-python-mode))

variable ein:notebook-kill-buffer-ask

Whether EIN should ask before killing unsaved notebook buffer.

variable ein:notebook-querty-timeout-open

Query timeout for opening notebook. If you cannot open large notebook because of timeout error, try to increase this value. Setting this value to nil means to use global setting. For global setting and more information, seeein:query-timeout.

variable ein:notebook-querty-timeout-save

Query timeout for saving notebook. Similar to ein:notebook-querty-timeout-open, but for saving notebook. For global setting and more information, seeein:query-timeout.

variable ein:cell-traceback-level

Number of traceback stack to show. Hidden tracebacks are not discarded. You can always view them using the command ein:notebook-view-traceback.

variable ein:cell-autoexec-prompt

String shown in the cell prompt when the auto-execution flag is on. See also ein:connect-aotoexec-lighter.

variable ein:junk-notebook-name-template

Junk notebook name template. This value is used from ein:notebooklist-new-scratch-notebookand ein:notebook-rename-to-scratch-command. This must be a format string which can be passed to format-time-string.

variable ein:iexec-delay

Delay before executing cell after change in second.

variable ein:complete-on-dot

Start completion when inserting a dot. Note thatein:use-auto-complete (or ein:use-auto-complete-superpack) must be t to enable this option. This variable has effect on notebook buffers and connected buffers.

variable ein:helm-kernel-history-search-key

Bind helm-ein-kernel-history to this key in notebook mode.

Example:

(setq ein:helm-kernel-history-search-key "\M-r")

This key will be installed in the ein:notebook-mode-map.

variable ein:anything-kernel-history-search-key

Bind anything-ein-kernel-history to this key in notebook mode.

Example:

(setq ein:anything-kernel-history-search-key "\M-r")

This key will be installed in the ein:notebook-mode-map.

variable ein:helm-kernel-history-search-auto-pattern

Automatically construct search pattern when non-nil.

  1. Single space is converted to “*”.
  2. A backslash followed by a space is converted to a single space.
  3. A “*” is added at the beginning and end of the pattern.

This variable applies to both helm-ein-kernel-history andanything-ein-kernel-history.

variable ein:output-type-preference

Output types to be used in notebook. First output-type found in this list will be used. This variable can be a list or a function returning a list given DATA plist. See also ein:output-type-prefer-pretty-text-over-html.

Example: If you prefer HTML type over text type, you can set it as:

(setq ein:output-type-preference '(emacs-lisp svg png jpeg html text latex javascript))

Note that html comes before text.

variable ein:shr-env

Variables let-bound while calling shr-insert-document.

To use default shr setting:

Draw boundaries for table (default):

(setq ein:shr-env '((shr-table-horizontal-line ?-) (shr-table-vertical-line ?|) (shr-table-corner ?+)))

Console

variable ein:console-security-dir

Security directory setting.

Following types are valid:

string

Use this value as a path to security directory. Handy when you have only one IPython server.

alist

An alist whose element is “(URL-OR-PORT . DIR)”. Key (URL-OR-PORT) can be string (URL), integer (port), ordefault (symbol). The value of default is used when other key does not much. Normally you should have this entry.

function

Called with an argument URL-OR-PORT (integer or string). You can have complex setting using this.

variable ein:console-executable

IPython executable used for console.

Example: "/user/bin/ipython". Types same as ein:console-security-dir are valid.

variable ein:console-args

Additional argument when using console.

Warning

Space-separated string is obsolete now. Use a list of string as value now.

Setting to use IPython profile named “YOUR-IPYTHON-PROFILE”:

(setq ein:console-args '("--profile" "YOUR-IPYTHON-PROFILE"))

Together with ein:console-security-dir, you can open IPython console connecting to a remote kernel.:

(setq ein:console-args '("--ssh" "HOSTNAME")) (setq ein:console-security-dir "PATH/TO/SECURITY/DIR")

You can setup ein:console-args per server basis using alist form:

(setq ein:console-args '((8888 . '("--profile" "PROFILE")) (8889 . '("--ssh" "HOSTNAME")) (default . '("--profile" "default"))))

If you want to use more complex setting, you can set a function to it:

(setq ein:console-args (lambda (url-or-port) '("--ssh" "HOSTNAME")))

See also: ein:console-security-dir.

Connect

variable ein:connect-run-command

%run magic command used for ein:connect-run-buffer. Types same as ein:console-security-dir are valid.

variable ein:connect-reload-command

Setting for ein:connect-reload-buffer. Same as ein:connect-run-command.

variable ein:connect-save-before-run

Whether the buffer should be saved before ein:connect-run-buffer.

variable ein:propagate-connect

Set to t to connect to the notebook after jumping to a buffer.

variable ein:connect-aotoexec-lighter

String appended to the lighter of ein:connect-mode (ein:c) when auto-execution mode is on. When nil, use the same string as ein:cell-autoexec-prompt.

variable ein:connect-default-notebook

Notebook to be connect when ein:connect-to-default-notebook is called.

Example setting to connect to “My_Notebook” in the server at port 8888 when opening any buffer in python-mode:

(setq ein:connect-default-notebook "8888/My_Notebook") (add-hook 'python-mode-hook 'ein:connect-to-default-notebook)

ein:connect-default-notebook can also be a function without any argument. This function must return a string (notebook path of the form “URL-OR-PORT/NOTEBOOK-NAME”).

As ein:connect-to-default-notebook requires notebook list to be loaded, consider using ein:notebooklist-load to load notebook list if you want to connect to notebook without manually opening notebook list.

function ein:connect-to-default-notebook

Connect to the default notebook specified byein:connect-default-notebook. Set this to python-mode-hookto automatically connect any python-mode buffer to the notebook.

Jedi.el

function ein:jedi-setup

Setup auto-completion using EIN and Jedi.el together.

Jedi.el is a Python auto-completion library for Emacs. To use EIN and Jedi together, add the following in your Emacs setup.:

(add-hook 'ein:connect-mode-hook 'ein:jedi-setup)

MuMaMo

variable ein:mumamo-codecell-mode

Major Mode for Code Cell.

variable ein:mumamo-textcell-mode

Major Mode for Text Cell.

variable ein:mumamo-htmlcell-mode

Major Mode for HTML Cell.

variable ein:mumamo-markdowncell-mode

Major Mode for Markdown Cell.

variable ein:mumamo-rawcell-mode

Major Mode for Raw Cell.

variable ein:mumamo-headingcell-mode

Major Mode for Heading Cell.

variable ein:mumamo-fallback-mode

Fallback Major Mode.

variable ein:use-mumamo-indent-line-function-workaround

Turn on workaround for mumamo-indent-line-function.

In code cell, hitting TAB or C-j at the end of input area causes error from MuMaMo. When this variable is non-nil, EIN patchesmumamo-indent-line-function to workaround this problem. This workaround is on by default.

Note that python-mode’s indentation function has other problems with MuMaMo. For example, hitting TAB twice, which decreases the indentation level by one in normal Python buffer, causes similar error in code cell. The current workaround does not fix this problem.

Misc

variable ein:filename-translations

Convert file paths between Emacs and Python process.

This value can take these form:

alist

Its key specifies URL-OR-PORT and value must be a list of two functions: (TO-PYTHON FROM-PYTHON). Key (URL-OR-PORT) can be string (URL), integer (port), or default (symbol). The value of default is used when other key does not much.

function

Called with an argument URL-OR-PORT (integer or string). This function must return a list of two functions: (TO-PYTHON FROM-PYTHON).

Here, the functions TO-PYTHON and FROM-PYTHON are defined as:

TO-PYTHON

A function which converts a file name (returned bybuffer-file-name) to the one Python understands.

FROM-PYTHON

A function which converts a file path returned by Python process to the one Emacs understands.

Use ein:tramp-create-filename-translator to easily generate the pair of TO-PYTHON and FROM-PYTHON.

function (ein:tramp-create-filename-translator remote-host &optional username)

Generate a pair of TO-PYTHON and FROM-PYTHON forein:filename-translations.

Usage:

(setq ein:filename-translations `((8888 . ,(ein:tramp-create-filename-translator "MY-HOSTNAME")))) ;; Equivalently: (setq ein:filename-translations (lambda (url-or-port) (when (equal url-or-port 8888) (ein:tramp-create-filename-translator "MY-HOSTNAME"))))

This setting assumes that the IPython server which can be connected using the port 8888 in localhost is actually running in the host named MY-HOSTNAME.

Adapted from slime-create-filename-translator.

variable ein:query-timeout

Default query timeout for HTTP access in millisecond.

Setting this to nil means no timeout.

If you do the same operation before the timeout, old operation will be canceled (see also ein:query-singleton-ajax).

Note

This value exists because it looks like url-retrieveoccasionally fails to finish (start?) querying. Timeout is used to let user notice that their operation is not finished. It also prevent opening a lot of useless process buffers. You will see them when closing Emacs if there is no timeout.

If you know how to fix the problem with url-retrieve, please let me know or send pull request at github! (Related bug report in Emacs bug tracker:http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11469)

Gotchas and caveats

Although EIN mostly works fine, there are some deficits I noticed but have not fixed yet. It seems that they originate from some upstream bugs so there is little I can do in EIN (but I’m not sure – it’s possible that I am misusing the libraries!).

If you know how to fix/workaround them, patches are very welcome.

url-retrieve

While using EIN, probably most of the error messages are about server connections. It looks like the problem is in url-retrieve. But in those cases you don’t loose any notebook data and your IPython kernel is fine. You can just type the command again and it will go fine most of the time. For saving notebook, I implemented code to retry when there is an error comes from url-retrieve to make it even safer.

MuMaMo

When using MuMaMo based notebook mode, you will notice that highlighting outside of the cell input is turned off while you are in the input area. It seems there is a bug in MuMaMo [6].

If you are using smartrep and MuMaMo together, see also the warning inein:use-smartrep document.

[6] See the relevant bug report I posted:https://bugs.launchpad.net/nxhtml/+bug/1013794

python-mode.el

In my environment, using python-mode.el without byte-compiling it in MuMaMo based notebook mode produces segfault.

Also, mumamo-idle-set-major-mode messages error(wrong-type-argument listp python-saved-check-command)time to time, making minibuffer bit noisy while editing notebook. See Tips to fix this problem.

Advanced

By telling IPython a little bit about Emacs Lisp, you can execute Emacs Lisp from IPython, just like you can execute Javascript in the web client. See emacslisp.py for more details.

In [1]: %run PATH/TO/emacslisp.py

In [2]: EmacsLisp('(+ 1 2 3)') Out [2]: 6

Reporting issue

Please use M-x ein:dev-bug-report-template to write a bug report. It pops up a buffer containing some system information and instruction for bug report.

Logging

Sometime more information that the *Message* buffer provides is needed to debug.

  1. Execute (ein:log-set-level 'debug)(e.g., M-: (ein:log-set-level 'debug) RET).
  2. Then do some operation which cause the problem.
  3. Go to the log buffer _*ein:log-all* (it starts with a space) and paste the whole buffer to the issue tracker.
    Please enclose the log with three backquotes to make the snippet as a code block, like this:
[verbose] Start logging. @#<buffer *ein: 8888/NAME*>  
[info] Notebook NAME is ready @#<buffer *ein: 8888/NAME*>  
[info] Kernel started: 5e4f74d1-ce91-4e7e-9575-9646adea5172 @#<buffer *scratch*>

See also: GitHub Flavored Markdown - Introduction
If it is too long, you can use paste bin service such asgist.

websocket.el

websocket.el has its logging buffer. Sometime its useful to see its log. This is how to do that.

  1. (require 'ein-dev)
  2. (setq websocket-debug t) or call ein:dev-start-debug.
  3. Then do the operation which causes the problem.
  4. Go to log buffer usingein:dev-pop-to-debug-shell andein:dev-pop-to-debug-iopub. These command must be called in the notebook buffer.

Debugging

If you are interested in debugging EIN, you should start it with calling the command ein:dev-start-debug. This command sets debug-on-error to t and do some patching to debugger. This patching is required because printing EWOC objects freezes Emacs otherwise. It also changes log level to log everything the log buffer. You can reset the patch and log level with ein:dev-stop-debug.

License

Emacs IPython Notebook is licensed under GPL v3. See COPYING for details.