Swanky Python: Python development using Emacs' SLIME mode for Common Lisp

Install slime and slime-star and clone this git repository. Then in your emacs config add:

This is the configuration that I use, with vim style keybindings and using doom emacs, consult, and company. It'd be much appreciated if people could contribute sample configurations based on vanilla emacs with standard keybindings, and integrating with other completion frameworks besides company.

With pip:

pip install -e ~/research/swanky_python/ With uv:

uv pip install -e ~/path/to/swanky_python/

You probably want uv pip rather than uv add as the rest of your team might not be happy with the weird new dependency. Though if you're working alone or somehow all collaborators are emacs users ok with trying experimental unstable software, you could use uv add --dev

The -e flag is to install in editable mode, as this is in very early-stage development, and you will inevitably run into bugs in the course of normal usage that you will need to edit and fix.

Python objects are displayed as presentations rather than as plaintext. This includes results in the repl, function arguments and local variables in backtrace buffers, values within the object inspector, and function arguments and return values in trace buffers. This means it shows a text representation of the object, but keeps a reference to the actual python object on the backend, so you can open it in the inspector, copy it to the repl, assign it to a variable, display documentation, and more. You can also add custom actions to the right click menu for presentations of different kinds of objects.

Any presentation can be opened in the inspector, which for most objects will show their attributes, although you can write custom inspector displays for your classes. slime-inspector-filter will bring up a transient menu where you can toggle the display of different attribute types like dunder and private ones. A useful shortcut is slime-inspect-last-result which will open the inspector on the last evaluation result.

When editing python code you can evaluate the whole file (slime-compile-and-load-file), the current class (slime-py-eval-class), current function (slime-eval-defun), current block (slime-eval-python-block-at-point), current selection (slime-eval-region), current statement (slime-eval-python-statement-at-point), or current identifier (slime-eval-sexp-at-point). This will evaluate within the context of the module associated with the active file. The module that the REPL evaluates within can be changed with slime-repl-set-package.

On any uncaught exception, slime opens an interactive backtrace buffer. Here you can see all stack frames with their arguments and local variables as presentations. With the cursor on a stack frame, sldb-show-source will show the source code with the expression that triggered the exception highlighted, after which you can select a region and run slime-py-eval-region-in-frame, or sldb-set-repl-to-frame will spawn a repl in the context of that stack frame.

The various slime-help functions show documentation. This is mostly done by introspection on doc strings, type signatures, and attributes in the running process. So for example you can see in the video that python tells us the click package distribution is installed and a short description, but we need to import it before we can see documentation on its classes and methods. Also you can see it calls click a 'Common Lisp ASDF system', and upcases names as for CL. For now it's a bit rough around the edges. Eventually I'll have it display more information like where inherited behavior comes from, as in the Django Class-Based-View Inspector.

slime-list-threads presents a table with information on all running threads. From there you can press d or slime-thread-debug to get a backtrace buffer for any thread.

If an async event loop is running, slime-list-threads will default to presenting a table with information on all asyncio tasks, and slime-py-toggle-threads-tasks switches between viewing threads and tasks. Here you can press x or slime-thread-kill to cancel a task, subject to the limitations of task cancellation in asyncio. In the video you can see hung requests finally return with "Internal Server Error" when we cancel the associated Task. As for threads you can open a backtrace buffer, but it's considerably less useful as async in python is stackless. It uses Task.get_stack() which for suspended coroutines just returns the stack frame where that task was created, and for running coroutines returns the call stack up to the frame where the task was created, but not the currently executing frame inside the Task. To get that we can toggle to the thread view and get the backtrace for the event loop thread.

To use this, the swank backend must to be started after the event loop has started, from the same thread.

You can trace functions and methods with slime-trace-dialog-toggle-trace, and untrace all traced functions with slime-trace-dialog-untrace-all. All arguments and return values for traced functions will be shown as presentations in the *slime-trace* buffer. However, the presentations work by simply holding on to a reference of the object, not by making a deep copy of it. So while the text in the *slime-trace* buffer is the repr of the object at the time it was passed, by the time you inspect the presentation it may have mutated. For example in the video the file object is closed by the time we inspect it.

At present there's no full debugger. The options for debugging are the repl and backtrace buffer, the trace, thread, and async views, improved print debugging with pp (print presentation), and the integrated AI. In the future I plan to integrate with dape for traditional step debugging, and add more advanced tracing debugging.

To use pp import it with from swanky_python.swank_common import pp. It's like basic print debugging except that it prints a presentation of the objects rather than text, so you can go back and inspect it, copy it to the repl, and more. Use it by:

pp(object)

or:

pp("text description", obj1, obj2, ...)

When passed a single object it returns the same object, so that any expression can be substituted with pp(expression)

When the cursor is within any function call, slime-autodoc-mode shows the function signature in the echo buffer, with the current argument highlighted. For completion we use jedi, which does suprisingly good type inference. For example in the video despite function foo being untyped, it sees that it's called with a str and provides str completion options.

We use code adapted from the autoreload extension for IPython to update old references to functions and classes with the new version when code is changed. The goal is to enable interactive development where you never need to restart your program on changes. If you run into situations where you do need to restart python for changes to take effect, please open an issue.

It comes with a local AI model which is quite effective for debugging.

When the swanky python backend listens for a connection on TCP, the first message it receives needs to contain the contents of ~/.slime-secret

When you are running python and emacs as the same user, you don't need to worry about this, as emacs will generate a random ~/.slime-secret file if it doesn't exist, readable only by the current user.

For remote development, you'll need to manually create a ~/.slime-secret file where python is running, with the same contents as ~/.slime-secret for your emacs user. This is to ensure some other user can't connect to your python process and run code in it.

If you're connected via swank to a python process on some server or in some untrusted container, you don't want it having access to your emacs process. The python process can send elisp for emacs to evaluate if slime-enable-evaluate-in-emacs is enabled, although it's off by default. Also in order to let jedi infer types and provide better completions, we allow python to request the contents of the active emacs buffer. Emacs will only send it if it's in python-mode or slime-repl-mode, but be aware that if you're connected to swank running in an untrusted container or environment you shouldn't open sensitive python code from another project.

If you find any other way that the swank backend can run code in or retrieve information from emacs, I consider it a security issue so please let me know.