Kotlin Notebook
Kotlin Notebook(英語) は、ノートブックの汎用性を IntelliJ IDEA にもたらします。
ノートブックは、コード、グラフィック、テキストを単一の環境に統合した対話的なエディターです。 ノートブックを使用すると、コードセルを実行してすぐに出力を確認し、リアルタイムでコードに関するインサイトを得ることができます。
Kotlin Notebook は、Kotlin でコーディングしながら、IntelliJ IDEA エコシステム内でノートブックをスムーズに作成および編集できるプラグインです。
Kotlin Notebook は、次のようなタスクに対処するための豊富なツールセットを提供します。
データ分析と視覚化: コーディングしながら操作の出力を取得しながら、データを直感的に取得、変換、プロット、モデル化できます。
プロトタイピング:: コードを小さなチャンクで実行し、結果をリアルタイムで確認できます。 この実践的な環境により、迅速な実験と反復が可能になります。
API の調査とテスト:: Kotlin Notebook は、セル内で API を呼び出し、外部サービスと対話する機能を提供します。
コードのドキュメント:: コードセル内にインラインコメントを含めたり、Markdown セル内にテキストアノテーションを含めたりして、さらにコンテキスト、説明、手順などを追加できます。
さらに、Kotlin、Notebook、 Datalore(英語)、 Kotlin- ジュピター Notebook(英語) 間で問題なく作業を簡単に共有できます。 この互換性は、Kotlin、Notebook が Kotlin カーネル(英語)に基づいているため可能であり、さまざまな Kotlin ノートブックソリューション(英語)間のシームレスな統合が保証されます。
以下のセクションを読んで、Kotlin Notebook の使用方法と主な機能について学びましょう。
Kotlin Notebook プラグインを有効化する
この機能は、デフォルトで IntelliJ IDEA にバンドルされて有効化されている Kotlin Notebook（英語） プラグインに依存しています。関連する機能が利用できない場合は、プラグインを無効化していないか確認してください。 関連機能が利用できない場合は、プラグインを無効化していないことを確認してください。
Ctrl+Alt+S を押して設定を開き、 を選択します。
インストール済み タブを開き、 Kotlin Notebook プラグインを見つけて、プラグイン名の横にあるチェックボックスを選択します。
ノートブックを作成する
新しいノートブックを作成するには、次のいずれかのオプションを使用します。
'ようこそ' 画面で、 Kotlin Notebook ノードを開き、 新しい Notebook をクリックします。 ノートブックは、プロジェクトに追加せずに スクラッチファイルとして作成することも、新規または既存のプロジェクト内に作成することもできます。
現在のプロジェクトに新しいノートブックを作成するには を選択し、ノートブックを スクラッチファイルとして作成するには を選択します。
ノートブックを配置するディレクトリを右クリックし、 を選択します。
.ipynb 拡張子を持つファイルが作成されます。
ノートブックを管理する
Kotlin Notebook の上部に、ノートブックツールバーがあります。 このツールバーには、コードを動的に実行または変更し、出力をすぐに確認できるクイックセルアクションのボタンが含まれています。
ツールバーから実行できる主なアクションは次のとおりです。
下のコードセルを追加
カット選択
選択をコピー
選択範囲を貼り付け
セルを上に移動
セルを下に移動
セルを実行して以下を選択
カーネルを中断
カーネルを再起動
すべてのセルを実行
出力をクリア
セルを削除コード
セルの種類を選択
gist を作成
Kotlin Notebook の設定を参照
ノートブックを操作する際、各セルはノートブック全体の状態に影響を与えますが、セルを実行した後のみです。 ノートブック内のセルの順序は重要ではありませんが、セルを実行する順序は重要です。
例: ライブラリを使用する場合、いつでも任意のセルを実行できますが、ライブラリを呼び出すセルを実行する前に、ライブラリをインポートするセルを実行する必要があります。
従来のプログラミングとは異なり、ノートブックでは、異なるセル内で同じ名前の複数の変数を宣言できます。 ただし、同じ名前の変数を新たに宣言すると、以前の宣言が上書きされます。 後続のセルでは、最後に実行した宣言のみが有効になります。
通常、ノートブックでは内部でコードが実行されているため、セルを結合するときに予期しない動作が発生する可能性があります。 この動作は、結合されたセルの 1 つに環境を変更するコードが含まれている場合、変更が次のセルにすぐに反映されない可能性があるためです。
ノートブックには、特定の言語構造に制限がある場合があります。 通常、関数本体内での作業など、有効な関数レベルの操作のみが許可されます。
Kotlin Notebook API にアクセスする
セル内で直接 Kotlin Notebook API にアクセスできます。 Kotlin Notebook API は、出力の処理、以前に実行したコードスニペットからの情報の取得、ライブラリとのシームレスな統合など、ノートブックの動作をカスタマイズおよび構成する機能を提供します。
例: notebook は、Kotlin Notebook API のエントリポイントです。 特定のメソッドで notebook を使用すると、実行されたコードセルや宣言された変数などのノートブックの分析情報を取得できます。
依存関係を追加する
リモート Maven リポジトリまたはローカルリポジトリ（ローカル JAR）から、ノートブックに動的な依存関係を追加できます。 依存関係を追加するには、アノテーションまたは Gradle 風の構文の 2 つの方法があります。
アノテーションを使用して依存関係を追加する
Kotlin Notebook 内の依存関係を管理するためのアノテーションが 2 つあります。
@file:DependsOn():このアノテーションでは、依存関係の座標を指定する必要があります。 このアノテーションは、ノートブックのクラスパスにアーティファクト (JAR ファイルなど) を追加します。 クラスディレクトリまたは JAR への絶対パスと相対パス、および Ivy と Maven アーティファクトをサポートします。@file:DependsOn(“io.ktor:ktor-client-core-jvm:$ktorVersion“)@file:Repository():このアノテーションでは、依存関係の絶対パスを指定する必要があります。 このアノテーションは、ノートブック環境にディレクトリまたは Ivy または Maven リポジトリを追加します。 Maven ローカルリポジトリを指定するには、@file:Repository("*mavenLocal")を使用します。
Gradle のような構文を使用して依存関係を追加する
任意のセルで Gradle のような構文を使用して、リポジトリ、場所などを指定し、Maven リポジトリから任意のライブラリをロードできます。
ラインマジックを活用する
Kotlin Notebook は、 % 文字から始まる、行ごとにノートブックと対話する特別なコマンドを提供します。 ラインマジックと呼ばれるこれらのコマンドを使用すると、ライブラリをインポートしたり、出力設定を構成したり、その他の操作を実行したりできます。
サポートされているライブラリをインポートする
Kotlin Notebook には、ディープラーニングから HTTP ネットワーキングまで、さまざまなタスクを実行するための 統合ライブラリ(英語)のセットが付属しています。 ライブラリ名の前に %use ラインマジックを実行するだけで、これらの統合ライブラリをインポートできます。
%use キーワードとともに、特定のライブラリバージョンを指定したり、単一の %use ステートメントを使用して複数のライブラリを含めたりすることができます。
新しいライブラリを統合する
Kotlin Notebook にまだ統合されていないライブラリを追加して使用できます。 新しいライブラリを統合するには、JSON ライブラリ記述子を作成するか、Kotlin Notebook API を使用するという 2 つの方法があります。
JSON ライブラリ記述子を作成する
新しいライブラリをサポートし、 %use ラインマジック経由で使用できるようにするには、 ライブラリ記述子を作成する(英語)必要があります。 ライブラリ記述子は、プロパティ、 レンダラー 、初期インポートなど、最も頻繁に使用されるライブラリ機能を定義する .json ファイルです。
この例では、ライブラリ記述子内で定義されたカスタムレンダラーの使用方法を示します。
Kotlin Notebook API を使用する
Kotlin Notebook API を使用して新しいライブラリを追加するには、ライブラリ内に統合クラスを定義し、統合 クラス名が現在のノートブックのクラスパスにあるこ(英語)とを確認する必要があります。
統合クラスを定義すると、Kotlin Notebook API が提供するすべての 統合機能(英語)を活用できるようになります。 これらの機能により、ライブラリと Kotlin Notebook 環境間のシームレスな連携が可能になります。
USE {} ブロックと特徴法を組み合わせることで、ノートブックのセルから利用可能な積分機能を直接利用できます。 以下は import () メソッドの例です。
REPL コマンドを使用する
REPL コマンドを使用して、ノートブック環境を探索し、クラスパスを理解し、実行中に変数の値をインスペクションします。
Kotlin Notebook は次の REPL コマンドをサポートしています。
| ノートブックのバージョン、ラインマジック、サポートされているライブラリの詳細を含むヘルプ情報を表示します。 |
|---|---|
| ノートブック環境の現在のクラスパスを表示し、ノートブックがライブラリとリソースを検索する場所のリストを示します。 |
| 宣言された変数とその値に関する情報を表示します。 |
豊富な出力をレンダリングして表示する
デフォルトでは、Kotlin Notebook は戻り値をテキスト形式で表示します。 ただし、グラフィック、HTML、その他の MIME エンコードデータ形式をレンダリングすることで、出力を充実させることができます。
1 つの方法は、 MIME ヘルパー関数を使用して、MIME エンコードされた結果をクライアントに送信することです。 もう 1 つの方法は、HTML コンテンツを直接表示するより簡単な方法を提供する HTML ヘルパー関数を使用することです。 これらの関数のサンプルは、GitHub の Kotlin-Jupyter リポジトリで参照できます(英語)。
これらの機能以外にも、Kotlin、Notebook は値をレンダリングするためのさまざまな機能とメカニズムをサポートしています。
レンダラー:: 値を他の表現に変換します。 レンダラーは
RenderersProcessorメソッドを介して制御され、notebookAPI エントリポイントを使用してアクセスできます。DisplayResultおよびRenderableインターフェースを実装するDisplayResultおよびRenderable:オブジェクトは、出力 JSON にレンダリングされます。テキストレンダリング:: テキストレンダラーを使用してオブジェクトを文字列にレンダリングします。 テキストレンダラーは
TextRenderersProcessorメソッドを介して制御され、notebookAPI エントリポイントを使用してアクセスできます。Throwable レンダリング:: Throwable レンダラーは通常のレンダラーと同じように動作しますが、セル実行中に生成された例外とエラーを処理します。
データファイルをドラッグアンドドロップ
シンプルなドラッグアンドドロップ機能を使用してデータを簡単に取得し、プロジェクトディレクトリからノートブックのセルにデータを移動します。
数回クリックするだけで、CSV、XLS、JSON ファイルを読み込み、データフレームのような構造にして処理できるようになります。 ドラッグアンドドロップ機能の動作を確認するには、以下のビデオを参照してください。
データとグラフィックをエクスポートする
セル内のエクスポートオプションをクリックすると、ノートブックからデータとグラフィックの両方を直感的にエクスポートできます。
エラーを分析する
コード内で期待どおりに動作しない場合、Kotlin Notebook は出力セルにエラーメッセージとスタックトレースを表示し、デバッグのためのインサイトを提供します。
ベストプラクティス
Kotlin Notebook は Jupyter ノートブック(英語)のバリアントであり、同様の内部構造を共有しています。
ノートブックを開いて最初のセルを実行すると、ノートブックは内部でセッションを作成します。 このセッションはカーネルと通信し、カーネルは作業全体を通じてノートブックのランタイム状態を追跡します。
ノートブックでの作業は、通常の Kotlin ファイルでの作業と比べていくつかの影響があります。
セッションが開始されると、ノートブックの依存関係として選択したプロジェクトの依存関係がコンパイルされ、カーネルのクラスパスに追加されます。 このため、プロジェクトコードに変更を加えた場合、これらの変更はカーネルを再起動した後でのみノートブック内で使用可能になります。
カーネルが応答しなくなった場合や、環境に大幅な変更を加えた場合は、カーネルを再起動すると便利です。 このアクションにより、現在実行中の環境が終了し、宣言された変数、関数、オブジェクトがすべてクリアされます。
ノートブックの状態は、実行時およびコンパイル時のアスペクトを組み合わせたものです。 そのため、カーネルを再起動すると、それまでに評価されたすべての変数がノートブックのメモリから消去されます。 これにより、あるセルが他のセルの出力に依存している場合、シンボルの未解決エラーが発生することがあります。
カーネルを中断すると、環境全体が終了されることなく、現在実行中のセルのみが一時停止されます。 このアクションは、たとえばセルの実行に時間がかかりすぎる場合など、実行を一時停止して再開する必要がある場合に役立ちます。
セルに追加された依存関係は、それらのセルを実行した後にのみ利用可能になります。 つまり、あるセル内で依存関係を追加して同じセル内でその依存関係を使用すると、セルを初めて実行するまでシンボルは未解決としてマークされます。
ノートブック内の位置に関係なく、セルを任意の順序で独立して実行できます。 ノートブックのランタイム状態は、ノートブック内のセルの位置ではなく、実行順序によって決まります。
実行したセルには、実行順序を示す番号が付きます。 一方、未実行のセルには * シンボルが付きます。 カーネルを再起動し、 すべて実行 ボタンをクリックすると、すべてのコードセルが順番に実行されます。 各セルには、実行順に対応する番号が付きます。 すべてのセルを実行すると、上から下に実行されるため、実行順序は自然にノートブック内のセルの位置と一致します。
カーネルを再起動した後、 すべて実行 ボタンをクリックすることをお勧めします。 すべてのセルを実行すると、セルが正しい順序で実行され、メモリ内に必要な変数と関数が再作成されます。
アタッチ カーネル モード
アタッチ カーネル モードは、Kotlin ノートブックと Spring ベースのアプリケーション、他のライブアプリケーションとの緊密な統合を可能にする機能です。 これは、ノートブックから直接ライブアプリケーションの状態をイントロスペクトし、実験したいバックエンド開発者にとって便利です。
このモードでは、独自のアプリケーションプロセス（通常は Spring Boot アプリ）内から Kotlin/Jupyter カーネルを起動し、IntelliJ IDEA からそのカーネルに接続できます。 接続すると、ノートブックは Spring プロセス内で直接実行され、すべての Bean、設定、アプリケーションコンテキストに完全にアクセスできます。
アタッチされたカーネルのサポートを有効化
アタッチされたカーネルモードのサポートを有効化するには、IntelliJ IDEA の kotlin.notebook.allow.attached.kernel レジストリキーを切り替えます。
Ctrl+Shift+A を押す。
「レジストリ」と入力して、 Enter を押します。
kotlin.notebook.allow.attached.kernelキーを見つけて有効化します。
Spring Boot プロジェクトを構成する
アタッチされたカーネルモードのサポートを有効化したら、Spring Boot プロジェクトに開発専用の依存関係を追加します。
このスターターは、アプリケーション内で Kotlin/Jupyter カーネルを実行するために必要なすべての設定を行います。 アプリケーションが起動すると、ノートブックカーネルがホストされ、IntelliJ IDEA が接続できるエンドポイントが公開されます。
アプリケーションに接続する
ノートブックから、Kotlin ノートブックを実行中のアプリに接続できます。 接続するには、IntelliJ IDEA で 新しい Kotlin ノートブックを作成し 、ノートブックツールバーから 実行中のカーネルに接続},{ を選択します。 ノートブックセッションはアプリのコンテキスト内で動作し、以下のことが可能になります。
セルから直接 Spring Bean にアクセス
アプリケーションサービス、リポジトリ、構成をリアルタイムで操作します
ライブアプリケーションロジックを呼び出して、副作用をすぐに確認する
IDE 内でビジネスロジックのプロトタイプを作成したり、診断を調査したりする
詳細については、Roman Belov による 新しい Spring 統合に関するこちらのプレゼンテーション（英語）を参照してください。 この機能の開発状況については、 YouTrack のこちらの課題（英語）を参照してください。