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.
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
$ opam pin add jupyter https://github.com/akabe/ocaml-jupyter.git
- 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 byyojson
andppx_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.
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
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 in Jupyter is also achieved by merlin. You can see documentation and type of an identifier by Shift+Tab key like
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.
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"
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"
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 |
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.
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.
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