Kotlin kernel for IPython/Jupyter

Kotlin (1.4.0) kernel for Jupyter.

Alpha version. Tested with Jupyter 6.0.1 on OS X so far.

To start using Kotlin kernel for Jupyter take a look at introductory guide.

Example notebooks can be found in the samples folder

Try samples online:

Installation

There are three ways to install kernel:

Conda

If you have conda installed, just run the following command to install stable package version:

conda install -c jetbrains kotlin-jupyter-kernel (package home)

To install conda package from the dev channel:

conda install -c jetbrains-dev kotlin-jupyter-kernel (package home)

Uninstall: conda remove kotlin-jupyter-kernel

Pip

You can also install this package through pip:

Stable: pip install kotlin-jupyter-kernel (package home)

Dev: pip install -i https://test.pypi.org/simple/ kotlin-jupyter-kernel (package home)

Uninstall: pip uninstall kotlin-jupyter-kernel

From sources

git clone https://github.com/Kotlin/kotlin-jupyter.git
cd kotlin-jupyter
./gradlew install

Default installation path is ~/.ipython/kernels/kotlin/. To install to some other location use option -PinstallPath=, but note that Jupyter looks for kernel specs files only in predefined places

Uninstall: ./gradlew uninstall

Usage

• jupyter console --kernel=kotlin
• jupyter notebook
• jupyter lab

To start using kotlin kernel inside Jupyter Notebook or JupyterLab create a new notebook with kotlin kernel.

Supported functionality

REPL commands

The following REPL commands are supported:

• :help - displays REPL commands help
• :classpath - displays current classpath

Dependencies resolving annotations

It is possible to add dynamic dependencies to the notebook using the following annotations:

• @file:DependsOn(<coordinates>) - adds artifacts to classpath. Supports absolute and relative paths to class directories or jars, ivy and maven artifacts represented by colon separated string
• @file:Repository(<absolute-path>) - adds a directory for relative path resolution or ivy/maven repository

Default repositories

The following maven repositories are included by default:

• Bintray JCenter
• Maven Central
• JitPack

Line Magics

The following line magics are supported:

• %use <lib1>, <lib2> ... - injects code for supported libraries: artifact resolution, default imports, initialization code, type renderers
• %trackClasspath - logs any changes of current classpath. Useful for debugging artifact resolution failures
• %trackExecution - logs pieces of code that are going to be executed. Useful for debugging of libraries support
• %output [options] - output capturing settings.

See detailed info about line magics here.

Supported Libraries

When a library is included with %use keyword, the following functionality is added to the notebook:

• repositories to search for library artifacts
• artifact dependencies
• default imports
• library initialization code
• renderers for special types, e.g. charts and data frames

This behavior is defined by json library descriptor. Descriptors for all supported libraries can be found in libraries directory. A library descriptor may provide a set of properties with default values that can be overridden when library is included. The major use case for library properties is to specify particular version of library. If descriptor has only one property, it can be defined without naming:

%use krangl(0.10)

If library descriptor defines more than one property, property names should be used:

%use spark(scala=2.11.10, spark=2.4.2)

Several libraries can be included in single %use statement, separated by ,:

%use lets-plot, krangl, mysql(8.0.15)

List of supported libraries:

• klaxon - JSON parser for Kotlin
• lets-plot - ggplot-like interactive visualization for Kotlin
• krangl - Kotlin DSL for data wrangling
• kotlin-statistics - Idiomatic statistical operators for Kotlin
• kravis - Kotlin grammar for data visualization
• spark - Unified analytics engine for large-scale data processing
• gral - Java library for displaying plots
• koma - Scientific computing library
• kmath - Kotlin mathematical library analogous to NumPy
• numpy - Kotlin wrapper for Python NumPy package
• exposed - Kotlin SQL framework
• mysql - MySql JDBC Connector
• smile - Statistical Machine Intelligence and Learning Engine
• deeplearning4j - Deep learning library for the JVM

Rich output

By default the return values from REPL statements are displayed in the text form. To use richer representations, e.g. to display graphics or html, it is possible to send MIME-encoded result to the client using the MIME helper function:

fun MIME(vararg mimeToData: Pair<String, Any>): MimeTypedResult 

E.g.:

MIME("text/html" to "<p>Some <em>HTML</em></p>", "text/plain" to "No HTML for text clients")

HTML outputs can also be rendered with HTML helper function:

fun HTML(text: String): MimeTypedResult

Autocompletion

Press TAB to get the list of suggested items for completion.

Currently completion suggests only names for user-defined variables and functions.

Debugging

1. Run ./gradlew installDebug. Use option -PdebugPort= to specify port address for debugger. Default port is 1044.
2. Run jupyter-notebook
3. Attach remote debugger to JVM with specified port

Adding new libraries

To support new JVM library and make it available via %use magic command you need to create a library descriptor for it.

Check libraries directory to see examples of library descriptors.

Library descriptor is a <libName>.json file with the following fields:

• properties: a dictionary of properties that are used within library descriptor
• link: a link to library homepage. This link will be displayed in :help command
• repositories: a list of maven or ivy repositories to search for dependencies
• dependencies: a list of library dependencies
• imports: a list of default imports for library
• init: a list of code snippets to be executed when library is included
• initCell: a list of code snippets to be executed before execution of any cell
• renderers: a list of type converters for special rendering of particular types

*All fields are optional

Fields for type renderer:

• class: fully-qualified class name for the type to be rendered
• result: expression that produces output value. Source object is referenced as $it

Name of the file is a library name that is passed to '%use' command

Library properties can be used in any parts of library descriptor as $property

To register new library descriptor:

1. For private usage - add it to local settings folder <UserHome>/.jupyter_kotlin/libraries
2. For sharing with community - commit it to libraries directory and create pull request.

If you are maintaining some library and want to update your library descriptor, just create pull request with your update. After your request is accepted, new version of your library will be available to all Kotlin Jupyter users immediately on next kernel startup (no kernel update is needed).

If a library descriptor with the same name is found in several locations, the following resolution priority is used:

1. Local settings folder (highest priority)
2. libraries directory at the latest master branch of https://github.com/Kotlin/kotlin-jupyter repository
3. Kernel installation directory

If you don't want some library to be updated automatically, put fixed version of its library descriptor into local settings folder.