Skip to main content

minimal lab example

Project description

Hello World

Set up the development environment and print to the console.

hello world example

The template folder structure

Writing a JupyterLab extension usually starts from a configurable template. It can be downloaded with the cookiecutter tool and the following command:

cookiecutter https://github.com/jupyterlab/extension-cookiecutter-ts

cookiecutter asks for some basic information that could for example be setup like this:

author_name []: tuto
author_email []: tuto@help.you
labextension_name [myextension]: hello-world
python_name [hello_world]:
project_short_description [A JupyterLab extension.]: Minimal JupyterLab example
has_settings [n]:
has_server_extension [n]:
has_binder [n]: y
repository [https://github.com/github_username/hello-world]:

The python name should not contain -. It is nice for user to test your extension online, so the has_binder was set to yes.

The cookiecutter creates the directory hello_world [or your extension name] that looks like this:

hello_world/
│   .eslintignore
│   .eslintrc.js
│   .gitignore
│   .prettierignore
│   .prettierrc
│   install.json
│   LICENSE
│   MANIFEST.in
│   package.json
│   pyproject.toml
│   README.md
│   setup.py
│   tsconfig.json
│
├───.github
│   └───workflows
│           build.yml
│
├───binder
│       environment.yml
│       postBuild
│
├───hello_world
│       __init__.py
│       _version.py
│
├───src
│       index.ts
│
└───style
        base.css
        index.css
        index.js

Those files can be separated in 4 groups:

  • Information about the extension:
    • README.md contains some instructions
    • LICENSE contains your extension code license; BSD-3 Clause by default (but you can change it).
  • Extension code (those files are mandatory):
    • package.json contains information about the extension such as dependencies
    • tsconfig.json contains information for the typescript compilation
    • src/index.ts this contains the actual code of your extension
    • style/ folder contains style elements that you can use
  • Validation:
    • .prettierrc and .prettierignore specify the code formatter prettier configuration
    • .eslintrc.js and .eslintignore specify the code linter eslint configuration
    • .github/workflows/build.yml sets the continuous integration tests of the code using GitHub Actions
  • Packaging as a Python package:
    • setup.py contains information about the Python package such as what to package
    • pyproject.toml contains the dependencies to create the Python package
    • MANIFEST.in contains list of non-Python files to include in the Python package
    • install.json contains information retrieved by JupyterLab to help users know how to manage the package
    • hello_world/ folder contains the final code to be distributed

The following sections will walk you through the extension code files.

A minimal extension that prints to the browser console

Start with the file src/index.ts. This typescript file contains the main logic of the extension. It begins with the following import section:

// src/index.ts#L1-L4

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

JupyterFrontEnd is the main Jupyterlab application class. It allows you to access and modify some of its main components. JupyterFrontEndPlugin is the class of the extension that you are building. Both classes are imported from a package called @jupyterlab/application. The dependency of your extension on this package is declared in the file package.json:

// package.json#L49-L51

"dependencies": {
  "@jupyterlab/application": "^3.1.0"
},

With this basic import setup, you can move on to construct a new instance of the JupyterFrontEndPlugin class:

// src/index.ts#L9-L12

const plugin: JupyterFrontEndPlugin<void> = {
  id: 'hello-world:plugin',
  autoStart: true,
  activate: (app: JupyterFrontEnd) => {
    console.log('JupyterLab extension hello-world is activated!');
// src/index.ts#L14-L17

  },
};

export default plugin;

A JupyterFrontEndPlugin contains a few attributes:

  • id: the unique id of the extension
  • autoStart: a flag to start the extension automatically or not
  • activate: a function (() => {} notation) that takes one argument app of type JupyterFrontEnd and will be called by the main application to activate the extension.

app is the main JupyterLab application. The activate function acts as an entry point into the extension. In this example, it calls the console.log function to output something into the browser developer tools console.

Your new JupyterFrontEndPlugin instance has to be finally exported to be visible to JupyterLab, which is done with the line export default plugin.

Now that the extension code is ready, you need to install it within JupyterLab.

Building and Installing an Extension

These are the instructions on how your extension can be installed for development:

You will need NodeJS to build the extension package.

# Install package in development mode
pip install -e .
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm run build

The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

The first command installs the dependencies that are specified in the setup.py file and in package.json. Among the dependencies are also all of the JupyterLab components that you want to use in your project.

It then runs the build script. In that step, the TypeScript code gets converted to javascript using the compiler tsc and stored in a lib directory. And a condensed form of the Javascript is copied in the Python package (in the folder hello_world/labextension). This is the code that would be installed by the user in JupyterLab.

The second command create a symbolic link to the folder hello_world/labextension so that extension is installed in development mode in JupyterLab.

The third command allows you to update the Javascript code each time you modify your extension code.

After all of these steps are done, running jupyter labextension list should show something like:

   local extensions:
        @jupyterlab-examples/hello-world: [...]/hello-world

Now let's check inside of JupyterLab if it works. Run [can take a while]:

jupyter lab --watch

Your extension writes something to the browser console. In most web browsers you can open the console pressing the F12 key. You should see something like:

JupyterLab extension hello-world is activated

Your extension works but it is not doing much. Let's modify the source code a bit. Simply replace the activate function with the following lines:

// src/index.ts#L12-L14

activate: (app: JupyterFrontEnd) => {
  console.log('the JupyterLab main application:', app);
},

To update the module, simply go to the extension directory and run jlpm build again. Since you used the --watch option when starting JupyterLab, you just have to refresh the JupyterLab website in the browser and should see in the browser console:

the JupyterLab main application:
Object { _started: true, _pluginMap: {…}, _serviceMap: Map(...), _delegate: {…}, commands: {…}, contextMenu: {…}, shell: {…}, registerPluginErrors: [], _dirtyCount: 0, _info: {…}, … }

This is the main application JupyterLab object and you will see how to interact with it in the other examples.

Checkout how the core packages of JupyterLab are defined on this page. Each package is structured similarly to the extension that you are writing. This modular structure makes JupyterLab very adaptable.

An overview of the classes and their attributes and methods can be found in the JupyterLab documentation. The @jupyterlab/application module documentation is here and here is the JupyterFrontEnd class documentation.

Where to Go Next

JupyterLab is built on top of three major concepts. It is advised to look through the corresponding examples in the following order:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupyterlab_examples_hello_world-0.1.0.tar.gz (16.3 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file jupyterlab_examples_hello_world-0.1.0.tar.gz.

File metadata

  • Download URL: jupyterlab_examples_hello_world-0.1.0.tar.gz
  • Upload date:
  • Size: 16.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.2 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.7.9

File hashes

Hashes for jupyterlab_examples_hello_world-0.1.0.tar.gz
Algorithm Hash digest
SHA256 f51853ed57b44b078ac3cb7e604190df68a4b44a21576b274a9f5c6e4825f382
MD5 0f0953b175555bd96cd7326efc0f20ef
BLAKE2b-256 28da61ded60e739f490453e9e48d571126686ecb3ea0b3069e187e960d3856be

See more details on using hashes here.

File details

Details for the file jupyterlab_examples_hello_world-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: jupyterlab_examples_hello_world-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 21.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.2 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.7.9

File hashes

Hashes for jupyterlab_examples_hello_world-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4cff4f9015a50447439d08a8ee59f12eb7709027e169b42a4c9aa6cbf4fc711c
MD5 0a4c7aec6d1f3770c7410f0e71d70991
BLAKE2b-256 9bce2bff7adc8aef35b9e68e417af8610feb6841f2e64c5dc8be8727fa8c866d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page