OCaml Jupyter

Jupyter protocol License Travis Build Status

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.

Screenshot

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)/ocaml-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

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

Code completion

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

Inspection

API documentation

OCaml Jupyter includes some sub-packages:

Customize kernel parameters

A kernelspec JSON is saved at the following path:

$ cat "$(opam config var share)/ocaml-jupyter/kernel.json"
{
  "display_name": "OCaml 4.04.2",
  "language": "OCaml",
  "argv": [
    "/home/USERNAME/.opam/4.04.2/bin/ocaml-jupyter-kernel",
    "--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)/ocaml-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

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

In addition, the installer of OCaml Jupyter automatically adds the kernel to Jupyter.

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!

  1. Fork this repository and clone your repository.
  2. ln -sf $PWD/git/pre-commit $PWD/.git/hooks/pre-commit
  3. Create a new branch and commit your changes.
  4. git push the commits into your (forked) repository.
  5. Pull request to master of this repository from the branch you pushed.

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

$ export LWT_LOG='* -> debug'
$ jupyter notebook