README.md

hy_kernel

A simple Jupyter kernel for Hy, a pythonic lisp.

The Hy tutorial as a Jupyter Notebook

Features

• basic REPL functionality
• autocomplete with most special Hy constructs
• syntax highlighting from lighttable-hylang
• cell and line magics
• interactive widgets
• pretty good tests

Installation

pip

pip install hy_kernel

docker

You can try out Hy Kernel in Docker with Docker Compose:

git clone https://github.com/bollwyvl/hy_kernel.git
cd hy_kernel && docker-compose up

Execution

To start the notebook in your directory of choice, with a running Hy kernel:

ipython console --kernel hy

Or the notebook web GUI:

ipython notebook

Or:

ipython qtconsole --kernel hy

Or: Your GUI might have a kernel selector: In the Web GUI it's in the upper-right-hand corner. Find it, and select Hy kernel from the kernel selector.

Implementation

This kernel subclasses IPythonKernel directly, as opposed to using KernelBase, which would probably the correct thing to do. This works, but might be brittle. Each cell is run through astor, so you're actually seeing hy → ast → py → ast. While this probably incurs additional overhead, the benefits (free magics, widgets, all the history works) are just too great to give up.

Limitations

QtConsole

A lot of things don't work quite right in the qt console, and this will not be supported to the same extent as the HTML notebook and terminal console.

Operators

Issue #5

Use of operators e.g. *, +, / as the left-most atom in an expression appears to work:

;; works
(+ 1 1)

Using operators as just about anything else doesn't:

;; breaks
(reduce + [1 2 3])

Workaround

Use the operator module:

(import (operator (mul add)))
(reduce mul [1 2 3])

This will probably need to be fixed upstream.

Magic

Cell and line magics are "supported", with the following caveats.

"Inline" Line Magics

Issue #13

Because we don't have much whitespace control over what gets compiled, and can't do dirty tricks with comments (the hy compiler strips them), inline/indented line magics are probably not going to work.

;; breaks
(if True (
  !ls
))

Raw Magics

Additionally, cell magics that should not be parsed as Hy need to be extra- magiced, with %%%. This is because there is no way to know whether a particular magic expects python, or some other crazy thing e.g. html, ruby, a file... not that %%file works anyway (see #12).

%%html
<h1>This Breaks!</h1>

breaks, while

%%%html
<h1>This Works!</h1>

works.

Collaboration

Issues, pull requests, and forks are all supported and encouraged on the Github repository.

This discussion on hylang-discuss is also a good place to chime in.

Additionally, the Jupyter list can provide a larger perspective on how this stuff fits into the larger picture of interactive computing.