Scala backend for IPython
Switch branches/tags
Nothing to show
Clone or download

README.md

IScala

IScala is a Scala-language backend for IPython.

Build Status

Requirements

Usage

First obtain a copy of IScala from here. The package comes with pre-compiled IScala.jar and collection of scripts for running IPython's console, qtconsole and notebook. IScala.jar contains all project dependencies and resources, so you can move IScala easily around. To start IPython's console, simply issue bin/console in a terminal. This will start ipython console and setup it to use IScala backend instead of the default Python one. Issue bin/qtconsole or bin/notebook to start IPython's Qt console or notebook, respectively.

To start IPython with IScala backend manually, issue:

ipython console --KernelManager.kernel_cmd='["java", "-jar", "lib/IScala.jar", "--connection-file", "{connection_file}", "--parent"]'

The same works for qtconsole and notebook, and is, in principle, what scripts in bin/ do. Note that you may have to provide a full path to IScala.jar. Option --parent is important and tells IScala that it was started by IPython and is not a standalone kernel. If not provided, double ^C (INT signal) within 500 ms terminates IScala. Otherwise, TERM signal or shutdown message is needed to terminate IScala gracefully. As a safety measure, IScala also watches connection file that IPython provided. If the file is removed, the respective kernel is terminated.

You can also create a scala profile for IPython. To do this, issue:

$ ipython profile create scala
[ProfileCreate] WARNING | Generating default config file: u'~/.config/ipython/profile_scala/ipython_config.py'
[ProfileCreate] WARNING | Generating default config file: u'~/.config/ipython/profile_scala/ipython_qtconsole_config.py'
[ProfileCreate] WARNING | Generating default config file: u'~/.config/ipython/profile_scala/ipython_notebook_config.py'

Then add the following line:

c.KernelManager.kernel_cmd = ["java", "-jar", "$ISCALA_PATH/lib/IScala.jar", "--connection-file", "{connection_file}", "--parent"]"

to ~/.config/ipython/profile_scala/ipython_config.py. Replace $ISCALA_PATH with the actual location of IScala.jar. Then you can run IPython with ipython console --profile scala.

To start a standalone kernel simply issue:

$ java -jar lib/IScala.jar
connect ipython with --existing kernel-18271.json
Welcome to Scala 2.10.2 (OpenJDK 64-Bit Server VM, Java 1.6.0_27)

This creates a connection file kernel-PID.json, where PID is the process ID of IScala kernel. You can connect IPython using --existing kernel-PID.json. You can provide an existing connection file with --connection-file option.

IScala supports other options as well. See java -jar IScala.jar -h for details. Note that you can also pass options directly to Scala compiler after -- delimiter:

$ java -jar IScala.jar --connection-file kernel.json -- -Xprint:typer

This will start standalone IScala with preexisting connection file and make Scala compiler print Scala syntax trees after typer compiler phase.

Example

$ bin/console
Welcome to Scala 2.10.2 (OpenJDK 64-Bit Server VM, Java 1.6.0_27)

In [1]: 1
Out[1]: 1

In [2]: 1 + 2 + 3
Out[2]: 6

In [3]: (1 to 5).foreach { i => println(i); Thread.sleep(1000) }
1
2
3
4
5

In [4]: val x = 1
Out[4]: 1

In [5]: x
Out[5]: 1

In [6]: 100*x + 17
Out[6]: 117

In [7]: x.<TAB>
x.%             x.-             x.>>            x.isInstanceOf  x.toFloat       x.toString      x.|
x.&             x./             x.>>>           x.toByte        x.toInt         x.unary_+
x.*             x.>             x.^             x.toChar        x.toLong        x.unary_-
x.+             x.>=            x.asInstanceOf  x.toDouble      x.toShort       x.unary_~

In [7]: x.to<TAB>
x.toByte    x.toChar    x.toDouble  x.toFloat   x.toInt     x.toLong    x.toShort   x.toString

In [7]: x.toS<TAB>
x.toShort   x.toString

In [7]: 1/0
java.lang.ArithmeticException: / by zero

In [8]: java.util.UUID.fromString("abc")
java.lang.IllegalArgumentException: Invalid UUID string: abc
    java.util.UUID.fromString(UUID.java:226)

In [9]: class Foo(a: Int) { def bar(b: String) = b*a }

In [10]: new Foo(5)
Out[10]: Foo@70f4d063

In [11]: _10.bar("xyz")
Out[11]: xyzxyzxyzxyzxyz

In [12]: import scala.language.experimental.macros

In [13]: import scala.reflect.macros.Context

In [14]: object Macros {
    ...:     def membersImpl[A: c.WeakTypeTag](c: Context): c.Expr[List[String]] = {
    ...:         import c.universe._
    ...:         val tpe = weakTypeOf[A]
    ...:         val members = tpe.declarations.map(_.name.decoded).toList.distinct
    ...:         val literals = members.map(member => Literal(Constant(member)))
    ...:         c.Expr[List[String]](Apply(reify(List).tree, literals))
    ...:     }
    ...:
    ...:     def members[A] = macro membersImpl[A]
    ...: }
    ...:

In [15]: Macros.members[Int]
Out[15]: List(<init>, toByte, toShort, toChar, toInt, toLong, toFloat, toDouble, unary_~,
unary_+, unary_-, +, <<, >>>, >>, ==, !=, <, <=, >, >=, |, &, ^, -, *, /, %, getClass)

Magics

IScala supports magic commands similarly to IPython, but the set of magics is different to match the specifics of Scala and JVM. Magic commands consist of percent sign % followed by an identifier and optional input to a magic. Magic command's syntax may resemble valid Scala, but every magic implements its own domain specific parser.

Type information

To infer the type of an expression use %type expr. This doesn't require evaluation of expr, only compilation up to typer phase. You can also get compiler's internal type trees with %type -v or %type --verbose.

In [1]: %type 1
Int

In [2]: %type -v 1
TypeRef(TypeSymbol(final abstract class Int extends AnyVal))

In [3]: val x = "" + 1
Out[3]: 1

In [4]: %type x
String

In [5]: %type List(1, 2, 3)
List[Int]

In [6]: %type List("x" -> 1, "y" -> 2, "z" -> 3)
List[(String, Int)]

In [7]: %type List("x" -> 1, "y" -> 2, "z" -> 3.0)
List[(String, AnyVal)]

Library management

Library management is done by sbt. There is no need for a build file, because settings are managed by IScala. To add a dependency use %libraryDependencies += moduleID, where moduleID follows organization % name % revision syntax. You can also use %% to track dependencies that have binary dependency on Scala. Scala version used is the same that IScala was compiled against.

To resolve dependencies issue %update. If successful this will restart the interpreter to allow it to use the new classpath. Note that this will erase the state of the interpreter, so you will have to recompute all values from scratch. Restarts don't affect interpreter's settings.

In [1]: import scalaj.collection.Imports._
<console>:7: error: not found: value scalaj
       import scalaj.collection.Imports._
              ^

In [2]: %libraryDependencies += "org.scalaj" %% "scalaj-collection" % "1.5"

In [3]: %update
[info] Resolving org.scalaj#scalaj-collection_2.10;1.5 ...
[info] Resolving org.scala-lang#scala-library;2.10.2 ...

In [1]: import scalaj.collection.Imports._

In [2]: List(1, 2, 3)
Out[2]: List(1, 2, 3)

In [3]: _2.asJava
Out[3]: [1, 2, 3]

In [4]: _3.isInstanceOf[List[_]]
Out[4]: false

In [5]: _3.isInstanceOf[java.util.List[_]]
Out[5]: true

In [6]: %libraryDependencies
List(org.scalaj:scalaj-collection:1.5)

If a dependency can't be resolved, %update will fail gracefully. For example, if we use com.scalaj organization instead of org.scalaj, then we will get the following error:

In [1]: %libraryDependencies += "com.scalaj" %% "scalaj-collection" % "1.5"

In [2]: %update
[info] Resolving com.scalaj#scalaj-collection_2.10;1.5 ...
[warn] 	module not found: com.scalaj#scalaj-collection_2.10;1.5
[warn] ==== sonatype-releases: tried
[warn]   https://oss.sonatype.org/content/repositories/releases/com/scalaj/scalaj-collection_2.10/1.5/scalaj-collection_2.10-1.5.pom
[warn] 	::::::::::::::::::::::::::::::::::::::::::::::
[warn] 	::          UNRESOLVED DEPENDENCIES         ::
[warn] 	::::::::::::::::::::::::::::::::::::::::::::::
[warn] 	:: com.scalaj#scalaj-collection_2.10;1.5: not found
[warn] 	::::::::::::::::::::::::::::::::::::::::::::::
[error] unresolved dependency: com.scalaj#scalaj-collection_2.10;1.5: not found

By default IScala uses Sonatype's releases maven repository. To add more repositories use %resolvers += "Repo Name" at "https://path/to/repository" and run %update again.

Development

Obtain a copy of IScala either by cloning this repository or download it from here. We use SBT for dependency management, compilation and deployment. In a terminal issue:

$ cd IScala
$ ./sbt

This will start SBT console (which will be indicated by > prefix). On first run SBT will download itself, its dependencies and plugins, and compile project build file. From here you can compile the project by issuing compile command:

> compile

It implicitly run update task, so on first run it will download all project dependencies (including Scala standard library and compiler), so it may take a while. Note that dependencies are cached in ~/.ivy2 directory, so they will be picked up next time SBT is run (also in other projects compiled from the same account).

Ignore any (deprecation) warnings you will get. To start IScala issue:

> run
[info] Running org.refptr.iscala.IScala
[info] connect ipython with --existing kernel-18271.json
[info] Welcome to Scala 2.10.2 (OpenJDK 64-Bit Server VM, Java 1.6.0_27)

This is an equivalent of starting a standalone IScala kernel from a terminal. To terminate a kernel press Ctrl+C (SBT my signal an error). Finally to generate a JAR file with IScala's class files, resources and dependencies, issue assembly. You can run it with:

$ java -jar IScala.jar

Unless you made any changes, this is exactly the JAR you can download from IScala's releases page.

Status

This is an early work in progress. Main features and majority of IPython's message specification were implemented, however certain features are not yet available (e.g. introspection) or are limited in functionality and subject to major changes. Report any problems and submit enhancement proposals here.

Acknowledgment

This work is substantially based on IJulia, a Julia-language backend for IPython.

License

Copyright © 2013-2014 by Mateusz Paprocki and contributors.

Published under The MIT License, see LICENSE.