Basic usage
Most of the functionality in this package is implemented in the EmacsBatch
and
EmacsClient
classes, which allow you to evaluate Emacs Lisp code and get the result in
Python. Both inherit from EmacsBase
and share the same API.
EmacsBatch
EmacsBatch
runs emacs --batch
with each invocation. The args
constructor argument
is a list of additional command line arguments to add. It is often a good idea to use the -Q
option to avoid loading personal configuration files each time, which can slow things down.
>>> from emacs import EmacsBatch
>>> emacs = EmacsBatch(args=['-Q'])
EmacsClient
EmacsClient
uses the emacsclient
command to connect to and execute code in a running
Emacs server. A server can be started in a running Emacs process by calling
(server-start <server-name>)
. Alternatively you can start a daemon server with
emacs --daemon=<server-name>
.
>>> from emacs import EmacsClient
>>> emacs = EmacsClient(server="my-server")
Executing Emacs lisp code
The main job of the interface is to execute elisp code. You can do this using the EmacsBase.eval()
method:
>>> emacs.eval('(+ 1 2)')
3
The source code can be passed in as a string, or you can build an Elisp expression using the
emacs.elisp
subpackage. This allows you to easily pass in data from Python:
>>> import emacs.elisp as el
>>> def emacs_add(a, b):
... expr = el.funccall('+', a, b)
... return emacs.eval(expr)
>>> emacs_add(1, 2)
3
Note that it does this by converting the value to JSON in Emacs and then decoding it in Python, so the value must be json-encodable.
Errors in evaluating the expression are caught in Emacs (see the catch_errors
argument to
EmacsBase.eval()
) and raised as an ElispException
in Python:
>>> emacs_add(1, "foo")
Traceback (most recent call last):
ElispException: Wrong type argument: number-or-marker-p, "foo"