Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

A hy kernel for IPython

Project description

# [hy_kernel][]

[![build-badge][]][build] [![pypi-badge][]][pypi]

A simple [Jupyter][] kernel for [Hy](http://hylang.org), a pythonic lisp.

[![](screenshot.png) _The Hy tutorial as a Jupyter Notebook_][tutorial]


## Features
- basic REPL functionality
- autocomplete with most special Hy constructs
- syntax highlighting from [lighttable-hylang][]
- [cell and line magics][magic]
- [interactive widgets][widgets]
- [pretty good tests][build]


## Installation


### pip
```shell
pip install hy_kernel
```


### docker
You can try out Hy Kernel in Docker with [Docker Compose][docker-compose]:

```bash
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:

```console
ipython console --kernel hy
```

Or the notebook web GUI:

```shell
ipython notebook
```

Or:
```shell
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.

![IPython Kernel Selector][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:
```hylang
;; works
(+ 1 1)
```

Using operators as just about anything else doesn't:
```hylang
;; breaks
(reduce + [1 2 3])
```

#### Workaround
Use the `operator` module:

```hylang
(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.

```hylang
;; 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).

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

breaks, while

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

works.


## Collaboration
Issues, pull requests, and forks are all supported and encouraged on the [Github
repository][hy_kernel].

This [discussion on `hylang-discuss`][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.

[astor]: https://github.com/berkerpeksag/astor
[build-badge]: https://travis-ci.org/bollwyvl/hy_kernel.svg
[build]: https://travis-ci.org/bollwyvl/hy_kernel
[discuss]: https://groups.google.com/forum/#!topic/hylang-discuss/UkoET6pU5sM
[docker-compose]: https://docs.docker.com/compose/
[hy_kernel]: https://github.com/bollwyvl/hy_kernel
[IPythonKernel]: https://github.com/ipython/ipython/blob/master/IPython/kernel/zmq/ipkernel.py
[Jupyter]: http://jupyter.org
[Jupyter list]: https://groups.google.com/forum/#!forum/jupyter
[kernel-selector]: http://ipython.org/ipython-doc/dev/_images/kernel_selector_screenshot.png
[KernelBase]: https://github.com/ipython/ipython/blob/master/IPython/kernel/zmq/kernelbase.py
[lighttable-hylang]: https://github.com/cndreisbach/lighttable-hylang
[magic]: notebooks/Magics.ipynb
[pypi-badge]: https://img.shields.io/pypi/v/hy_kernel.svg
[pypi]: https://pypi.python.org/pypi/hy_kernel/
[tutorial]: http://nbviewer.ipython.org/github/bollwyvl/hy_kernel/blob/master/notebooks/Tutorial.ipynb
[widgets]: notebooks/Widgets.ipynb

Project details


Release history Release notifications

This version
History Node

0.3.0

History Node

0.2.0

History Node

0.1.3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
hy_kernel-0.3.0.tar.gz (24.8 kB) Copy SHA256 hash SHA256 Source None Jun 14, 2015

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page