package jupyter
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=d0afa7c7ad515285413d75fe08d0cb6d070df2e455073b6cfe56a04ae2fb45fd
Description
OCaml Jupyter provides an OCaml REPL on Jupyter (a great interface with markdown/HTML documentation, LaTeX formula by MathJax, and image embedding). This is useful for data analysis in OCaml.
Published: 23 Jan 2023
README
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 requires the libraries zlib, libffi, libgmp, libzmq 5+. Type one of the following commands suitable for your environment.
# For Debian or Ubuntu:
sudo apt-get install -y zlib1g-dev libffi-dev libgmp-dev libzmq5-dev
# For REHL or CentOS:
sudo yum install -y epel-release
sudo yum install -y zlib-devel libffi-dev gmp-devel zeromq-devel
# For Mac OS X:
brew install zlib libffi gmp zeromq
OCaml Jupyter can be installed by OPAM as follows:
pip install jupyter
opam install jupyter
grep topfind ~/.ocamlinit || echo '#use "topfind";;' >> ~/.ocamlinit # For using '#require' directive
grep Topfind.log ~/.ocamlinit || echo 'Topfind.log:=ignore;;' >> ~/.ocamlinit # Suppress logging of topfind (recommended but not necessary)
ocaml-jupyter-opam-genspec
jupyter kernelspec install [ --user ] --name "ocaml-jupyter-$(opam var switch)" "$(opam var share)/jupyter"
If the last command fails due to permission, --user
option or sudo
is required. 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 byyojson
andppx_yojson_conv
.
In addition, many examples (e.g, image processing, voice analysis, etc.) are available at docker-ocaml-jupyter-datascience/notebooks.
These examples are placed in the public domain, e.g., you can edit, copy, and re-distribute with no copyright messages.
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.
NBConvert
OCaml notebooks can be converted to HTML, Markdown, LaTeX, .ml
files, etc. using the 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
Customize kernel parameters
ocaml-jupyter-opam-genspec
generates a configuration file like:
$ cat "$(opam var share)/jupyter/kernel.json"
{
"display_name": "OCaml 4.08.1",
"language": "OCaml",
"argv": [
"/bin/sh",
"-c",
"eval $(opam env --switch=4.08.1) && /home/xxxx/.opam/4.08.1/bin/ocaml-jupyter-kernel \"$@\"",
"-init", "/home/xxxx/.ocamlinit",
"--merlin", "/home/xxxx/.opam/4.08.1/bin/ocamlmerlin",
"--verbosity", "app",
"--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 var share)/jupyter"
Installation without OPAM
ocaml-jupyter-opam-genspec
depends on OPAM. If you use an other package manager, you need to write kernel.json
by hand or use provided suitable way for registering a new kernel (e.g., jupyter module on Nix).
Running OCaml Jupyter on other environments
Binder
OCaml Jupyter can be run on Binder. Click the button to get started:
For more information, see this repository.
Google Colab
OCaml Jupyter can be run on Google Colab. In order to do this you first have to run this Python notebook in your Colab instance. This will install the kernel and after that OCaml notebooks can be used on the same instance.
Sponsors
If you like this project, please support by becoming a sponsor via GitHub Sponsors.
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.
Dependencies (16)
-
dune
>= "1.0.0"
-
cryptokit
>= "1.12"
-
ppx_deriving
>= "5.2.1"
-
ppx_yojson_conv
>= "v0.14.0" & < "v0.16.0"
-
yojson
>= "1.6.0"
-
zmq-lwt
>= "5.0.0"
-
zmq
>= "5.0.0"
-
stdint
>= "0.4.2"
-
logs
>= "0.6.0"
-
lwt_ppx
>= "1.0.0"
-
lwt
>= "4.0.0"
-
base64
>= "3.2.0"
-
uuidm
>= "0.9.6"
- base-unix
- base-threads
-
ocaml
>= "4.10.0" & < "5.0"
Dev Dependencies (2)
-
ocp-indent
with-test & >= "1.7.0"
-
ounit2
with-test & >= "2.0.0"
Used by (2)
-
jupyter-archimedes
>= "2.7.3"
- owl-jupyter
Conflicts (1)
-
merlin
< "3.0.0"