Skip to content

Latest commit

 

History

History
127 lines (78 loc) · 4.46 KB

magics.md

File metadata and controls

127 lines (78 loc) · 4.46 KB
Raw

Magics

Magics in IJava are very similar to those from IPython. There are:

  • Line magics: which are inline function calls via a magic function.

    %mavenRepo oss-sonatype-snapshots https://oss.sonatype.org/content/repositories/snapshots/
%maven io.github.spencerpark:jupyter-jvm-basekernel:2.0.0-SNAPSHOT
List<String> addedJars = %jars C:/all/my/*.jar

  • Cell magics: which are entire cell function calls that use the body of the cell as a special argument.

    %%loadFromPOM
<repository>
  <id>oss-sonatype-snapshots</id>
  <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository>

<dependency>
  <groupId>io.github.spencerpark</groupId>
  <artifactId>jupyter-jvm-basekernel</artifactId>
  <version>2.0.0-SNAPSHOT</version>
</dependency>

The magics simply desugar to calls to lineMagic and cellMagic in case programmatic access is desired. These functions are in the notebook namespace and have the signatures below. Note the return type which allows for an implicit cast to what ever type is required but there is no safety in these checks.

  • <T> T lineMagic(String name, java.util.List<String> args)
  • <T> T cellMagic(String name, java.util.List<String> args, String body)

Magics provided by IJava

Things that are likely to become magics are kernel meta functions or functions that operate on source code. Magics should only be used for things that only appear in a Jupyter-like context and only use string arguments. Other things (like display and render) should be provided as plain functions.

jars

Add jars to the notebook classpath.

Line magic
  • arguments:
    • varargs list of simple glob paths to jars on the local file system. If a glob matches a directory all files in that directory will be added.

classpath

Add entries to the notebook classpath.

Line magic
  • arguments:
    • varargs list of simple glob paths to entries on the local file system. This includes directories or jars.

addMavenDependencies

Add maven artifacts to the notebook classpath. All transitive dependencies are also added to the classpath. See also addMavenRepo.

Line magic
  • aliases: addMavenDependency, maven
  • arguments:
    • varargs list of dependency coordinates in the form groupId:artifactId:[packagingType:[classifier]]:version

addMavenRepo

Add a maven repository to search for when using addMavenDependencies.

Line magic
  • aliases: mavenRepo
  • arguments:
    • repository id
    • repository url

loadFromPOM

Load any dependencies specified in a POM. This ignores repositories added with addMavenRepo as the POM would likely specify it's own.

The cell magic is designed to make it very simple to copy and paste from any READMEs specifying maven POM fragments to use in depending on an artifact (including repositories other than central).

Line magic
  • arguments:
    • path to local POM file
    • varargs list of scope types to filter the dependencies by. Defaults to compile, runtime, system, and import if not supplied.
Cell magic

  • arguments:

    • varargs list of scope types to filter the dependencies by. Defaults to compile, runtime, system, and import if not supplied.

  • body: A partial POM literal.

    If the body is an xml <project> tag, then the body is used as a POM without being modified.

    Otherwise, the magic attempts to build a POM based on the xml fragments it gets.

    <modelVersion>, <groupId>, <artifactId>, and <version> are given default values if not supplied which there is no reason to supply other than if they happen to be what is copy-and-pasted.

    All children of <dependencies> and <repositories> are collected along with any loose <dependency> and repository tags.

    Ex: To add a dependency not in central simply add a valid <repository> and <dependency> and the magic will take care of putting it together into a POM.

    %%loadFromPOM
<repository>
  <id>oss-sonatype-snapshots</id>
  <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
</repository>

<dependency>
  <groupId>io.github.spencerpark</groupId>
  <artifactId>jupyter-jvm-basekernel</artifactId>
  <version>2.0.0-SNAPSHOT</version>
</dependency>