File: notebook.rst

package info (click to toggle)
jupyterlab 4.0.11%2Bds1%2B~cs11.25.27-7
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 43,496 kB
  • sloc: javascript: 18,395; python: 8,932; sh: 399; makefile: 95; perl: 33; xml: 1
file content (350 lines) | stat: -rw-r--r-- 12,033 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
.. Copyright (c) Jupyter Development Team.
.. Distributed under the terms of the Modified BSD License.

Notebook
========

Background
----------

.. _architecture-walkthrough:

A JupyterLab architecture walkthrough from June 16, 2016, provides an overview of the notebook architecture.

.. raw:: html

  <div class="jp-youtube-video">
     <iframe src="https://www.youtube-nocookie.com/embed/4Qm6oD_Rlw8?rel=0&amp;showinfo=0&amp;start=3326" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
  </div>


The most complicated plugin included in the **JupyterLab application**
is the **Notebook plugin**.

The
`NotebookWidgetFactory <../api/classes/notebook.NotebookWidgetFactory-1.html>`__
constructs a new
`NotebookPanel <../api/classes/notebook.NotebookPanel-1.html>`__
from a model and populates the toolbar with default widgets.

Structure of the Notebook plugin
--------------------------------

The Notebook plugin provides a model and widgets for dealing with
notebook files.

Model
^^^^^

The
`NotebookModel <../api/classes/notebook.NotebookModel-1.html>`__
contains an observable list of cells.

A `cell
model <../api/classes/cells.CellModel-1.html>`__
can be:

-  a code cell
-  a markdown cell
-  raw cell

A code cell contains a list of **output models**. The list of cells and
the list of outputs can be observed for changes.

Cell operations
"""""""""""""""

The NotebookModel cell list supports single-step operations such as
moving, adding, or deleting cells. Compound cell list operations, such
as undo/redo, are also supported by the NotebookModel. Right now,
undo/redo is only supported on cells and is not supported on notebook
attributes, such as notebook metadata. Currently, undo/redo for
individual cell input content is supported by the CodeMirror editor's
undo feature. (Note: CodeMirror editor's undo does not cover cell
metadata changes.)

Metadata
""""""""

The notebook model and the cell model (i.e. notebook cells) support
getting and setting metadata through method ``getMetadata``, ``setMetadata``
and ``deleteMetadata`` (see `NotebookModel <../api/classes/notebook.NotebookModel-1.html>`__
and `cell model <../api/classes/cells.CellModel-1.html>`__).
You can listen for changes in the metadata through the ``sharedModel.metadataChanged`` attribute
(see `cell shared model <https://jupyter-ydoc.readthedocs.io/en/latest/api/interfaces/ISharedBaseCell.html#metadataChanged>`__
and `notebook shared model <https://jupyter-ydoc.readthedocs.io/en/latest/api/interfaces/ISharedNotebook-1.html#metadataChanged>`__).

Notebook widget
^^^^^^^^^^^^^^^

After the NotebookModel is created, the NotebookWidgetFactory constructs
a new NotebookPanel from the model. The NotebookPanel widget is added to
the DockPanel. The **NotebookPanel** contains:

-  a
   `Toolbar <../api/classes/ui_components.Toolbar-1.html>`__
-  a `Notebook
   widget <../api/classes/notebook.Notebook-1.html>`__.

The NotebookPanel also adds completion logic.

The **Notebook toolbar** maintains a list of widgets to add to the
toolbar. The **Notebook widget** contains the rendering of the notebook
and handles most of the interaction logic with the notebook itself (such
as keeping track of interactions such as selected and active cells and
also the current edit/command mode).

The NotebookModel cell list provides ways to do fine-grained changes to
the cell list.

Higher level actions using NotebookActions
""""""""""""""""""""""""""""""""""""""""""

Higher-level actions are contained in the
`NotebookActions <../api/classes/notebook.NotebookActions-1.html>`__
namespace, which has functions, when given a notebook widget, to run a
cell and select the next cell, merge or split cells at the cursor,
delete selected cells, etc.

Widget hierarchy
""""""""""""""""

A Notebook widget contains a list of `cell
widgets <../api/classes/cells.Cell-1.html>`__,
corresponding to the cell models in its cell list.

-  Each cell widget contains an
   `InputArea <../api/classes/cells.InputArea-1.html>`__,

   -  which contains a
      `CodeEditorWrapper <../api/classes/codeeditor.CodeEditorWrapper-1.html>`__,

      -  which contains a JavaScript CodeMirror instance.

A
`CodeCell <../api/classes/cells.CodeCell-1.html>`__
also contains an
`OutputArea <../api/classes/outputarea.OutputArea-1.html>`__.
An OutputArea is responsible for rendering the outputs in the
`OutputAreaModel <../api/classes/outputarea.OutputAreaModel-1.html>`__
list. An OutputArea uses a notebook-specific
`RenderMimeRegistry <../api/classes/rendermime.RenderMimeRegistry-1.html>`__
object to render ``display_data`` output messages.

The Notebook widget is represented in the DOM with a ``<div>`` element
with CSS classes ``jp-Notebook`` and ``jp-NotebookPanel-notebook``.
It contains a sequence of cells widgets.

 - Code cells have the following DOM structure:

   .. image:: images/code-cell-dom.svg

 - Rendered markdown cells have the following DOM structure:

   .. image:: images/rendered-markdown-cell-dom.svg

 - Active markdown cells have the following DOM structure:

   .. image:: images/active-markdown-cell-dom.svg

.. note::
   The default nbconvert template for the HTML exporter produces the same DOM
   as the JupyterLab notebook, allowing for the JupyterLab CSS to be used directly.
   In JupyterLab, input areas are rendered with the CodeMirror, with a custom theme
   making use of the CSS variables of JupyterLab.
   In the case of nbconvert, code cells are rendered using the Pygments Python
   library, which produces static HTML with syntax highlighting. The
   `jupyterlab_pygments <https://github.com/jupyterlab/jupyterlab_pygments.git>`_
   Pygments theme mimicks the default CodeMirror theme of JupyterLab.

.. note::
   The SVG figures presenting the DOM structures of the different cell types
   were produced with Draw.io, and contain the metadata allowing them to be
   directly opened and edited with Draw.io.

Rendering output messages
"""""""""""""""""""""""""

A **Rendermime plugin** provides a pluggable system for rendering output
messages. Default renderers are provided for markdown, html, images,
text, etc. Extensions can register renderers to be used across the
entire application by registering a handler and mimetype in the
rendermime registry. When a notebook is created, it copies the global
Rendermime singleton so that notebook-specific renderers can be added.
The ipywidgets widget manager is an example of an extension that adds a
notebook-specific renderer, since rendering a widget depends on
notebook-specific widget state.

.. _extend-notebook-plugin:

How to extend the Notebook plugin
---------------------------------

We'll walk through two notebook extensions:

-  adding a button to the toolbar
-  adding a widget to the notebook header
-  adding an ipywidgets extension

Adding a button to the toolbar
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Since JupyterLab 3.2, adding toolbar item can be done using a :ref:`toolbar-registry` and settings. In particular
for the notebook, if the button is linked to a new command, you can add a button in the toolbar using the
following JSON snippet in your extension settings file:

.. code:: js

   "jupyter.lab.toolbars": {
     "Notebook": [ // Widget factory name for which you want to add a toolbar item.
       // Item with default button widget triggering a command
       { "name": "run", "command": "runmenu:run" }
     ]
   }

You may add a ``rank`` attribute to modify the item position (the default value is 50).

Adding a widget to the notebook header
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Start from the extension template.

.. code-block:: shell

    pip install "copier~=8.0" jinja2-time
    mkdir myextension
    cd myextension
    copier copy --UNSAFE https://github.com/jupyterlab/extension-template .

Install the dependencies. Note that extensions are built against the
released npm packages, not the development versions.

.. code-block:: shell

    jlpm add -D @jupyterlab/notebook @jupyterlab/application @jupyterlab/ui-components @jupyterlab/docregistry @lumino/disposable @lumino/widgets

Copy the following to ``src/index.ts``:

.. code:: typescript

    import { IDisposable, DisposableDelegate } from '@lumino/disposable';

    import { Widget } from '@lumino/widgets';

    import {
      JupyterFrontEnd,
      JupyterFrontEndPlugin
    } from '@jupyterlab/application';

    import { DocumentRegistry } from '@jupyterlab/docregistry';

    import { NotebookPanel, INotebookModel } from '@jupyterlab/notebook';

    /**
    * The plugin registration information.
    */
    const plugin: JupyterFrontEndPlugin<void> = {
      activate,
      id: 'my-extension-name:widgetPlugin',
      description: 'Add a widget to the notebook header.',
      autoStart: true
    };

    /**
    * A notebook widget extension that adds a widget in the notebook header (widget below the toolbar).
    */
    export class WidgetExtension
      implements DocumentRegistry.IWidgetExtension<NotebookPanel, INotebookModel>
    {
      /**
      * Create a new extension object.
      */
      createNew(
        panel: NotebookPanel,
        context: DocumentRegistry.IContext<INotebookModel>
      ): IDisposable {
        const widget = new Widget({ node: Private.createNode() });
        widget.addClass('jp-myextension-myheader');

        panel.contentHeader.insertWidget(0, widget);
        return new DisposableDelegate(() => {
          widget.dispose();
        });
      }
    }

    /**
    * Activate the extension.
    */
    function activate(app: JupyterFrontEnd): void {
      app.docRegistry.addWidgetExtension('Notebook', new WidgetExtension());
    }

    /**
    * Export the plugin as default.
    */
    export default plugin;

    /**
    * Private helpers
    */
    namespace Private {
      /**
      * Generate the widget node
      */
      export function createNode(): HTMLElement {
        const span = document.createElement('span');
        span.textContent = 'My custom header';
        return span;
      }
    }


And the following to ``style/base.css``:

.. code-block:: css

    .jp-myextension-myheader {
        min-height: 20px;
        background-color: lightsalmon;
    }


Run the following commands:

.. code-block:: shell

    pip install -e .
    jupyter labextension develop . --overwrite
    jupyter lab

Open a notebook and observe the new "Header" widget.

The *ipywidgets* third party-extension
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This discussion will be a bit confusing since we've been using the term
*widget* to refer to *lumino widgets*. In the discussion below,
*Jupyter interactive widgets* will be referred to as *ipywidgets*. There is no
intrinsic relation between *lumino widgets* and *Jupyter interactive widgets*.

The *ipywidgets* extension registers a factory for a notebook *widget*
extension using the `Document
Registry <../api/classes/docregistry.DocumentRegistry-1.html>`__.
The ``createNew()`` function is called with a NotebookPanel and
`DocumentContext <../api/interfaces/docregistry.DocumentRegistry.IContext.html>`__.
The plugin then creates a ipywidget manager (which uses the context to
interact the kernel and kernel's comm manager). The plugin then
registers an ipywidget renderer with the notebook instance's rendermime
(which is specific to that particular notebook).

When an ipywidget model is created in the kernel, a comm message is sent
to the browser and handled by the ipywidget manager to create a
browser-side ipywidget model. When the model is displayed in the kernel,
a ``display_data`` output is sent to the browser with the ipywidget
model id. The renderer registered in that notebook's rendermime is asked
to render the output. The renderer asks the ipywidget manager instance
to render the corresponding model, which returns a JavaScript promise.
The renderer creates a container *lumino widget* which it hands back
synchronously to the OutputArea, and then fills the container with the
rendered *ipywidget* when the promise resolves.