Explore writing Jupyter Notebooks with the Basilisp Kernel

Basilisp is a Lisp implementation broadly compatible with Clojure, running on the Python VM. Refer to the documentation to get started.

Overview

This repository helps you explore writing Jupyter Notebooks in Basilisp Clojure using the basilisp-kernel.

It assumes you have some familiarity with Clojure and Jupyter Notebooks in Python.

It leverages the Poetry build tool to create a Python virtual environment that includes both the Jupyter Notebook and the basilisp-kernel dependencies to get you started.

Additionally, it includes a sample Basilisp Application library (basapp) that can be loaded into the development notebook.

Prerequisites

Ensure you have Poetry installed to manage the Python virtual environment.

Project Setup

First, clone the repository locally

git clone https://github.com/ikappaki/basilex-notebook.git

Before running the project for the first time, install the dependencies in a new virtual environment by running

poetry install

Optionally, you can add more Python or Basilisp libraries anytime using the add command. For example, to install seaborn:

poetry add seaborn

Usage

Activate the virtual environment by running

poetry shell

Then, start the Jupyter Notebook server

jupyter notebook

This should open the Jupyter Notebook home page in your browser.

👉 Open the tutorial.ipynb notebook to begin interacting with it.

The src/basapp/core.lpy path is automatically included in the python sys.path through poetry install ran at project setup. You can require it in the notebooks as normal

[1] (require '[basapp.core :as bc])

[2] (bc/hello)
:Hi 👋 The Basilisp Kernel supports autocompletion of functions and variables using the Tab key ⌨️. Give it a go!

Start Developing Using the nREPL Server

You can use the tutorial notebook or create a new one, selecting Basilisp as the kernel.

Refer to Connecting Your Editor to the nREPL Server for detailed instructions, covering various use cases.

Start the nREPL server

Note

You can skip this step if you are following the tutorial notebook.

The following instructions are assumed to be executed in Notebook cells running the Basilisp Kernel, as indicated by the [n]: prefix.

First load the nREPL server namespace

[n]: (require '[basilisp-kernel.nrepl-server :as nrepl-server])

Then, you can start the nREPL server

• Specify a fixed port with :port

[n]: (def server (server-start {:port 9998}))
nREPL server started on port 9998 on host 127.0.0.1 - nrepl://127.0.0.1:9998
#'user/server

Connect to the nREPL Server

Open the basilisp.edn file in the root of your project to enable Clojure-specific features in your editor.

Then use your Editor's Clojure nREPL commands to connect to the server.

Both Emacs/CIDER and VSCode/Calva offer explicit support for Basilisp.

To connect

CIDER (Emacs)

1. Run M-x cider-connect-clj.
2. Select localhost.
3. Enter the port number from the nREPL server output.

Calva (VSCode)

1. Press Ctrl-Shift-P to open the Command Palette.
2. Select Calva: Connect to a Running REPL Server, not in your project>basilisp.
3. Enter the port number from the nREPL server output.

You should now be connected to the Basilisp notebook from your editor. Follow the tutorial.ipynb nREPL section to explore and try out a few cool nREPL interactions.

Project Anatomy

.
├── basilisp.edn             (B)
├── tutorial.ipynb           (1)
├── poetry.lock              (2)
├── pyproject.toml           (3)
├── src
│   ├── basapp               (N)
│   │   └── core.lpy         (4)

🄑 An empty file indicating to Clojure-enabled editors that this is a Basilisp Project.

🄝 The root of the sample Basilisp App namespace.

① The tutorial notebook set up to use the basilisp-kernel.

② A lock file generated by Poetry that records the exact versions of dependencies installed.

③ The configuration file where project metadata, dependencies, and Poetry settings are defined.

④ The core namespace of the sample Basilisp App.