jupyter / jvm-repr

API for converting JVM objects to representations by MIME type, for the Jupyter ecosystem.

JVM Repr

Configuration | Usage for Library Authors | Usage for Kernel Authors

Standardizing object representation and inspection across JVM kernels (Scala, Clojure, Groovy, ...).

Purpose

JVM languages use various conventions to convert REPL outputs to forms that can be displayed. This project is an attempt to standardize by providing an API that libraries can use to register display methods for any jupyter frontend, whether console, notebook, or dashboard.

This API has two main uses:

• For library authors to provide a way to convert from a library's JVM objects to useful representations by MIME type
• For kernel authors to convert any JVM object to useful representations by MIME type

As it is with IPython, this is a contract between the libraries within the ecosystem, the kernel that inspects the objects, and the frontends that display them.

Configuration

See instructions on JitPack for gradle, maven, sbt, or leiningen.

Usage

Usage - Library authors

Library authors can register conversion code either

• by implementing a Displayer and registering it with Displayers, or
• by having classes extend AsDisplayData, whose display method returns how an instance should be displayed.

For example, the following will register a displayer for Vegas graphs:

import java.util.Map
import jupyter.Displayer
import jupyter.Displayers
import scala.collection.JavaConverters._
import vegas.DSL.ExtendedUnitSpecBuilder

...

  Displayers.register(classOf[ExtendedUnitSpecBuilder],
    new Displayer[ExtendedUnitSpecBuilder] {
      override def display(plot: ExtendedUnitSpecBuilder): Map[String, String] = {
        val plotAsJson = plot.toJson
        Map(
          "text/plain" -> plotAsJson,
          "application/json" -> plotAsJson,
          "text/html" -> new StaticHTMLRenderer(plotAsJson).frameHTML()
        ).asJava
      }
    })

The following has Thing be represented as simple text in Jupyter front-ends, like Thing(2) for new Thing(2):

import java.util.HashMap;
import java.util.Map;

class Thing implements AsDisplayData {
  private int n;
  public Thing(int n) {
    this.n = n;
  }
  public Map<String, String> display() {
    Map<String, String> result = new HashMap<>();
    result.put(MIMETypes.TEXT, "Thing(" + n + ")");
    return result;
  }
}

Any kernel implementation can use the method to display Vegas graphs for the DSL objects.

Library authors can optionally implement setMimeTypes(String...) to receive hints for the MIME types that the kernel or front-end supports. It is recommended that library authors use these hints to avoid expensive conversions.

Usage - Kernel authors

Kernel authors can use this API to display registered objects:

import java.util.Map

// ...

  Object result = interpreter.eval(code);
  Map<String, String> resultByMIME = Displayers.display(result);
  Kernel.this.display(resultByMIME);

Kernel authors can optionally call Displayers.setMimeTypes(String...) to send hints to display implementations with the set of MIME types that can be used by the kernel or front-end.

jvm-repr's Issues

Publish on Maven Central

Right now, jvm-repr is published via jitpack. This requires not only direct users of the library to add jitpack to their repository list, but also transitive users to add it too. (E.g. the scala-interpreter-api of almond now depends on jvm-repr, and its downstream users also have to add jitpack for jvm-repr to be pulled fine.)

jvm-repr could be pushed to Maven Central, like most JVM libraries already do, so that adding the jitpack repo isn't required.

IndexOutOfBoundsException in ToStringDisplay with zero-length array

ToStringDisplay.displayArray unconditionally accesses arr[0] when passed an array of objects. This fails when the array length is zero.

Tabular Data Format

Mimetype: application/vnd.dataresource+json

I'm not sure if this belongs here or across every single kernel we'd want to target. For Spark DataFrames in particular, I'd like to see a standardized table come back. The leg work was done in Pandas, nteract, and a Jupyter notebook/lab extension to prove this out.

• Pandas Implementation: pandas-dev/pandas#14904
• nteract rendering: nteract/nteract#1534
• Data Resource Spec
• Table Schema Spec

Registering displayers for interfaces doesn't work

The implementation of Registration.find() walks the superclass chain looking for a matching displayer. This means that registering a displayer for an interface has no effect (the registration will succeed, but the displayer will never be found).

There would need to be some way to resolve the ambiguity if matches were found for both a class and an interface or for two interfaces.

How do you use display updates with the JVM Repr?

I'd like to be able to use update display in a Scala kernel. It involves using two things:

• display_data message with a transient field (alongside data, metadata) that has a display_id
• update_display_data message that also sets the display_id inside of transient

From a Python perspective, this is some of the interface provided to users: