OCaml Jupyter

An OCaml kernel for Jupyter notebook.

This provides an OCaml REPL with a great user interface such as markdown/HTML documentation, LaTeX formula by MathJax, and image embedding.

Getting started

OCaml Jupyter can be installed by OPAM as follows:

$ pip install jupyter
$ opam install jupyter
$ opam install jupyter-archimedes  # Jupyter-friendly 2D plotting library
$ jupyter kernelspec install --name ocaml-jupyter "$(opam config var share)/jupyter"

which will add the kernel to Jupyter. You can use ocaml-jupyter kernel by launching Jupyter notebook server:

$ jupyter notebook

Development version

$ opam pin add jupyter https://github.com/akabe/ocaml-jupyter.git

Usage

Examples

Introduction: a very simple example for use of OCaml Jupyter and sub-packages.
Get a description of a word from DuckDuckGo API: request to DuckDuckGo API server by cohttp.lwt, and parse a response JSON by yojson and ppx_deriving_yojson.

In addition, many examples (e.g, image processing, voice analysis, etc.) are available at docker-ocaml-jupyter-datascience/notebooks.

These examples are publish in public domain, e.g., you can edit, copy, and re-distribute with no copyright messages.

NBConvert

OCaml notebooks can be converted to HTML, markdown, LaTeX, .ml files, etc. by jupyter nbconvert command. For example, a .ipynb file is converted into a .html file as follows:

$ jupyter nbconvert --to html notebooks/introduction.ipynb
[NbConvertApp] Converting notebook notebooks/introduction.ipynb to html
[NbConvertApp] Writing 463004 bytes to notebooks/introduction.html

For exporting .ml files, we recommend Jupyter-NBConvert-OCaml. It outputs .ml files with markdown cells as comments. After installation of Jupyter-NBConvert-OCaml, you can use --to ocaml option to export a .ml file:

$ jupyter nbconvert --to ocaml notebooks/introduction.ipynb
[NbConvertApp] Converting notebook notebooks/introduction.ipynb to ocaml
[NbConvertApp] Writing 2271 bytes to notebooks/introduction.ml

Code completion

OCaml Jupyter kernel supports merlin-based code completion. Candidates are shown by Tab key like

The kernel uses .merlin file at a notebook directory for completion.

Inspection

Inspection in Jupyter is also achieved by merlin. You can see documentation and type of an identifier by Shift+Tab key like

API documentation

OCaml Jupyter includes some sub-packages:

jupyter is a core library of OCaml Jupyter. This package is internally used. You don't need it directly.
jupyter.notebook is a library to control Jupyter from OCaml REPL in notebooks. This provides dynamic generation of HTML/markdown, and image embedding.
jupyter.comm is a library for communication between OCaml notebooks and Jupyter/Web frontend.
jupyter-archimedes is Jupyter backend of Archimedes, an easy-to-use 2D plotting library. This package only registers the jupyter backend to Archimedes, and provides empty interface.

Registration of multiple kernels

You can add kernels of different versions of OCaml as different names like:

$ opam switch create 4.06.0
$ jupyter kernelspec install --name ocaml-jupyter-4.06.0 "$(opam config var share)/jupyter"
$ opam switch create 4.07.1
$ jupyter kernelspec install --name ocaml-jupyter-4.07.1 "$(opam config var share)/jupyter"

OCaml 4.06.0 and OCaml 4.07.1 are displayed on Jupyter. If you want to prepare kernels for each opam-switch environment, the following command is useful:

jupyter kernelspec install --name ocaml-jupyter-$(opam config var switch) "$(opam config var share)/jupyter"

Customize kernel parameters

A kernelspec JSON is saved at the following path:

$ cat "$(opam config var share)/jupyter/kernel.json"
{
  "display_name": "OCaml 4.04.2",
  "language": "OCaml",
  "argv": [
    "/bin/sh",
    "/home/USERNAME/.opam/4.04.2/share/jupyter/kernel.sh",
    "--init",
    "/home/USERNAME/.ocamlinit",
    "--verbosity",
    "info",
    "--connection-file",
    "{connection_file}"
  ]
}

See ocaml-jupyter-kernel --help for details of command-line parameters in argv. After you edit the file, re-register the kernel:

$ jupyter kernelspec install --name ocaml-jupyter "$(opam config var share)/jupyter"

Docker image

A ready-to-use Docker image akabe/ocaml-jupyter-datascience is available on DockerHub. It contains OCaml Jupyter and many packages for data science.

$ docker run -it -p 8888:8888 akabe/ocaml-jupyter-datascience
[I 15:38:04.170 NotebookApp] Writing notebook server cookie secret to /home/opam/.local/share/jupyter/runtime/notebook_cookie_secret
[W 15:38:04.190 NotebookApp] WARNING: The notebook server is listening on all IP addresses and not using encryption. This is not recommended.
[I 15:38:04.197 NotebookApp] Serving notebooks from local directory: /notebooks
[I 15:38:04.197 NotebookApp] 0 active kernels
[I 15:38:04.197 NotebookApp] The Jupyter Notebook is running at: http://[all ip addresses on your system]:8888/?token=4df0fee0719115f474c8dd9f9281abed28db140d25f933e9
[I 15:38:04.197 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[W 15:38:04.198 NotebookApp] No web browser found: could not locate runnable browser.
[C 15:38:04.198 NotebookApp]

    Copy/paste this URL into your browser when you connect for the first time,
    to login with a token:
        http://localhost:8888/?token=4df0fee0719115f474c8dd9f9281abed28db140d25f933e9

Related work

Many Jupyter kernels for functional programming languages are available such as IHaskell, Jupyter Scala, and Jupyter Rust. IOCaml is another practical OCaml kernel that inspires us, but it seems no longer maintained. OCaml Jupyter kernel differs from IOCaml in

	OCaml Jupyter	IOCaml v0.4.8
Jupyter protocol	v5.2	v3.2
OCaml PPX support	Yes	No
Session key support	Yes	No
Code completion	Yes	Yes
Introspection	Yes	Yes
User-defined messages	Yes	No
Stdin	Yes	No

Another OCaml kernel simple_jucaml seems too simple to use in practice. jupyter-kernel is a library to write OCaml kernels (not a kernel), but OCaml Jupyter kernel does not use this library.

Contact

Open Issue for any questions, bug reports, requests of new features. Your comments may help other users. Issues are a better way than direct contact (e.g., E-mails) to maintainers.

Contribution

We welcome your patch!

Fork this repository and clone your repository.
ln -sf $PWD/git/pre-commit $PWD/.git/hooks/pre-commit
opam install ocp-indent for code format (in the git pre-commit hook)
Create a new branch and commit your changes.
git push the commits into your (forked) repository.
Pull request to master of this repository from the branch you pushed.

Environment variable OCAML_JUPYTER_LOG controls a log level of OCaml Jupyter kernel. The following setting verbosely outputs log messages. They might help your debug.

$ export OCAML_JUPYTER_LOG='debug'
$ jupyter notebook

vbmithr / ocaml-jupyter