https://github.com/jupyter/jvm-repr

API for converting JVM objects to representations by MIME type, for the Jupyter ecosystem.
https://github.com/jupyter/jvm-repr

Last synced: 27 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/jupyter/jvm-repr
• Owner: jupyter
• License: bsd-3-clause
• Created: 2017-03-14T19:09:20.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2020-01-16T20:05:48.000Z (almost 5 years ago)
• Last Synced: 2024-09-30T05:28:56.665Z (about 1 month ago)
• Language: Java
• Size: 76.2 KB
• Stars: 23
• Watchers: 7
• Forks: 19
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# JVM Repr

[![Build Status](https://travis-ci.org/jupyter/jvm-repr.svg?branch=master)](https://travis-ci.org/jupyter/jvm-repr)

[![JVM repr on jitpack](https://jitpack.io/v/jupyter/jvm-repr.svg)](https://jitpack.io/#jupyter/jvm-repr)

[**Configuration**](#configuration) | [**Usage for Library Authors**](#usage---library-authors) | [**Usage for Kernel Authors**](#usage---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](https://jitpack.io/#jupyter/jvm-repr) 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:

```scala

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)`:

```java

import java.util.HashMap;

import java.util.Map;

class Thing implements AsDisplayData {

  private int n;

  public Thing(int n) {

    this.n = n;

  }

  public Map display() {

    Map 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:

```java

import java.util.Map

// ...

  Object result = interpreter.eval(code);

  Map 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.