jupyterlab / extension-template

A `copier` template for JupyterLab extensions

Installation | Documentation | Contributing | License | Team | Getting help |

JupyterLab

An extensible environment for interactive and reproducible computing, based on the Jupyter Notebook and Architecture.

JupyterLab is the next-generation user interface for Project Jupyter offering all the familiar building blocks of the classic Jupyter Notebook (notebook, terminal, text editor, file browser, rich outputs, etc.) in a flexible and powerful user interface.

JupyterLab can be extended using npm packages that use our public APIs. The prebuilt extensions can be distributed via PyPI, conda, and other package managers. The source extensions can be installed directly from npm (search for jupyterlab-extension) but require an additional build step. You can also find JupyterLab extensions exploring GitHub topic jupyterlab-extension. To learn more about extensions, see the user documentation.

Read the current JupyterLab documentation on ReadTheDocs.

Important

JupyterLab 3 reached its end of maintenance date on May 15, 2024. Fixes for critical issues will still be backported until December 31, 2024. If you are still running JupyterLab 3, we strongly encourage you to upgrade to JupyterLab 4 as soon as possible. For more information, see JupyterLab 3 end of maintenance on the Jupyter Blog.

---

Getting started

Installation

If you use conda, mamba, or pip, you can install JupyterLab with one of the following commands.

• If you use conda:

  conda install -c conda-forge jupyterlab

• If you use mamba:

  mamba install -c conda-forge jupyterlab

• If you use pip:

  pip install jupyterlab

  If installing using pip install --user, you must add the user-level bin directory to your PATH environment variable in order to launch jupyter lab. If you are using a Unix derivative (e.g., FreeBSD, GNU/Linux, macOS), you can do this by running export PATH="$HOME/.local/bin:$PATH". If you are using a macOS version that comes with Python 2, run pip3 instead of pip.

For more detailed instructions, consult the installation guide. Project installation instructions from the git sources are available in the contributor documentation.

Installing with Previous Versions of Jupyter Notebook

When using a version of Jupyter Notebook earlier than 5.3, the following command must be run after installing JupyterLab to enable the JupyterLab server extension:

jupyter serverextension enable --py jupyterlab --sys-prefix

Running

Start up JupyterLab using:

jupyter lab

JupyterLab will open automatically in the browser. See the documentation for additional details.

If you encounter an error like "Command 'jupyter' not found", please make sure PATH environment variable is set correctly. Alternatively, you can start up JupyterLab using ~/.local/bin/jupyter lab without changing the PATH environment variable.

Prerequisites and Supported Browsers

The latest versions of the following browsers are currently known to work:

• Firefox
• Chrome
• Safari

See our documentation for additional details.

---

Getting help

We encourage you to ask questions on the Discourse forum. A question answered there can become a useful resource for others.

Bug report

To report a bug please read the guidelines and then open a Github issue. To keep resolved issues self-contained, the lock bot will lock closed issues as resolved after a period of inactivity. If a related discussion is still needed after an issue is locked, please open a new issue and reference the old issue.

Feature request

We also welcome suggestions for new features as they help make the project more useful for everyone. To request a feature please use the feature request template.

---

Development

Extending JupyterLab

To start developing an extension for JupyterLab, see the developer documentation and the API docs.

Contributing

To contribute code or documentation to JupyterLab itself, please read the contributor documentation.

JupyterLab follows the Jupyter Community Guides.

License

JupyterLab uses a shared copyright model that enables all contributors to maintain the copyright on their contributions. All code is licensed under the terms of the revised BSD license.

Team

JupyterLab is part of Project Jupyter and is developed by an open community. The maintenance team is assisted by a much larger group of contributors to JupyterLab and Project Jupyter as a whole.

JupyterLab's current maintainers are listed in alphabetical order, with affiliation, and main areas of contribution:

• Mehmet Bektas, Netflix (general development, extensions).
• Alex Bozarth, IBM (general development, extensions).
• Eric Charles, Datalayer, (general development, extensions).
• Frédéric Collonval, WebScIT (general development, extensions).
• Martha Cryan, Mito (general development, extensions).
• Afshin Darian, QuantStack (co-creator, application/high-level architecture, prolific contributions throughout the code base).
• Vidar T. Fauske, JPMorgan Chase (general development, extensions).
• Brian Granger, AWS (co-creator, strategy, vision, management, UI/UX design, architecture).
• Jason Grout, Databricks (co-creator, vision, general development).
• Michał Krassowski, Quansight (general development, extensions).
• Max Klein, JPMorgan Chase (UI Package, build system, general development, extensions).
• Gonzalo Peña-Castellanos, QuanSight (general development, i18n, extensions).
• Fernando Perez, UC Berkeley (co-creator, vision).
• Isabela Presedo-Floyd, QuanSight Labs (design/UX).
• Steven Silvester, MongoDB (co-creator, release management, packaging, prolific contributions throughout the code base).
• Jeremy Tuloup, QuantStack (general development, extensions).

Maintainer emeritus:

• Chris Colbert, Project Jupyter (co-creator, application/low-level architecture, technical leadership, vision, PhosphorJS)
• Jessica Forde, Project Jupyter (demo, documentation)
• Tim George, Cal Poly (UI/UX design, strategy, management, user needs analysis).
• Cameron Oelsen, Cal Poly (UI/UX design).
• Ian Rose, Quansight/City of LA (general core development, extensions).
• Andrew Schlaepfer, Bloomberg (general development, extensions).
• Saul Shanabrook, Quansight (general development, extensions)

This list is provided to give the reader context on who we are and how our team functions. To be listed, please submit a pull request with your information.

---

Weekly Dev Meeting

We have videoconference meetings every week where we discuss what we have been working on and get feedback from one another.

Anyone is welcome to attend, if they would like to discuss a topic or just listen in.

• When: Wednesdays 9:00 AM Pacific Time (USA)
• Where: jovyan Zoom
• What: Meeting notes

Notes are archived on GitHub Jupyter Frontends team compass.

extension-template's Issues

Tutorial steps give attribute error

Description

Tutorial step pip install -ve . results in error:

Installing collected packages: trove-classifiers, tomli, pluggy, pathspec, packaging, editables, hatchling, hatch-jupyter-builder
  Successfully installed editables-0.5 hatch-jupyter-builder-0.9.1 hatchling-1.24.2 packaging-24.0 pathspec-0.12.1 pluggy-1.5.0 tomli-2.0.1 trove-classifiers-2024.5.22
  Installing backend dependencies ... done
  Running command Preparing editable metadata (pyproject.toml)
  Traceback (most recent call last):
    File "/z/aolney/software/miniconda3/envs/starchat-ext-jl4/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 167, in prepare_metadata_for_build_editable
      hook = backend.prepare_metadata_for_build_editable
  AttributeError: module 'hatchling.build' has no attribute 'prepare_metadata_for_build_editable'

  During handling of the above exception, another exception occurred:

  Traceback (most recent call last):
    File "/z/aolney/software/miniconda3/envs/starchat-ext-jl4/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
      main()
    File "/z/aolney/software/miniconda3/envs/starchat-ext-jl4/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
      json_out['return_val'] = hook(**hook_input['kwargs'])
    File "/z/aolney/software/miniconda3/envs/starchat-ext-jl4/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 176, in prepare_metadata_for_build_editable
      whl_basename = build_hook(metadata_directory, config_settings)
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatchling/build.py", line 83, in build_editable
      return os.path.basename(next(builder.build(directory=wheel_directory, versions=['editable'])))
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatchling/builders/plugin/interface.py", line 90, in build
      self.metadata.validate_fields()
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatchling/metadata/core.py", line 265, in validate_fields
      _ = self.version
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatchling/metadata/core.py", line 149, in version
      self._version = self._get_version()
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatchling/metadata/core.py", line 244, in _get_version
      core_metadata = self.core
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatchling/metadata/core.py", line 196, in core
      metadata_hook.update(self.core_raw_metadata)
    File "/tmp/pip-build-env-7girfj34/overlay/lib/python3.10/site-packages/hatch_nodejs_version/metadata_source.py", line 175, in update
      new_metadata = {"name": package["name"]}
  KeyError: 'name'
  error: subprocess-exited-with-error
  
  × Preparing editable metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> See above for output.
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  full command: /z/aolney/software/miniconda3/envs/starchat-ext-jl4/bin/python3.10 /z/aolney/software/miniconda3/envs/starchat-ext-jl4/lib/python3.10/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py prepare_metadata_for_build_editable /tmp/tmpvmfj4uxj
  cwd: /z/aolney/repos/jupyterlab-starchat-extension
  Preparing editable metadata (pyproject.toml) ... error
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

Reproduce

conda create -n starchat-ext-jl4 python=3.10 jupyterlab=4 nodejs=20 git copier=9 jinja2-time
conda activate starchat-ext-jl4
mkdir jupyterlab-starchat-extension
cd jupyterlab-starchat-extension
copier copy --trust https://github.com/jupyterlab/extension-template .
pip install -ve .

I've tried removing yarn.lock, node_modules, running jlpm install and jlpm install:extension. I've also tried creating a fresh conda env. What's weird is that this worked a month or so ago on the same machine.

Expected behavior

The tutorial steps to run without error.

Context

• Operating System and version: Ubuntu 22.04.4 LTS
• Browser and version: Chrome 125.0.6422.60 (Official Build) (64-bit)
• JupyterLab version: 4.2.1

Troubleshoot Output

Paste the output from running `jupyter troubleshoot` from the command line here.
You may want to sanitize the paths in the output.

Body too long to include

twine reports "InvalidDistribution: Metadata is missing required fields: Name, Version."

Using the template, a build seems to work fine, except for when I try to push to pypi with twine:

python -m build
twine upload dist/*

gives:

ERROR    InvalidDistribution: Metadata is missing required fields: Name, Version.                   
         Make sure the distribution includes the files where those fields are specified, and is     
         using a supported Metadata-Version: 1.0, 1.1, 1.2, 2.0, 2.1, 2.2.    

The package.json file has name and version both set.

Integration Tests Failing from Build Workflow

Description

The build workflow fails with my JupyterLab extension on the integration tests job.

I think you can see a workflow runs here?:

https://github.com/0Hughman0/jupyter_cassini/actions/runs/5823678174/job/15791243849

I get both

[WebServer] [I 2023-08-10 16:35:28.678 ServerApp] Registered HelloWorld extension at URL path /jupyter_cassini_server
[I 2023-08-10 16:35:28.678 ServerApp] jupyter_cassini_server | extension was successfully loaded.

In the log, indicating to me that extensions are activating correctly.

However, even the extension activates test fails.

Looking at the videos generated by the Playwright output, it appears like the extension doesn't activate.

Expected behavior

I would expect these tests to pass as they pass on my local system (is Windows 10?)

Context

One potential cause, that I haven't been able to diagnose is for my extension to run, I have to modify the jlpm start command:

https://github.com/0Hughman0/jupyter_cassini/blob/00a7b22898d58a2a61dcf56c5b2ffb91ac936f1d/ui-tests/package.json#L7

Which launches the server and configures it to work with Cassini, which is the backend for this project. But I haven't made any changes to the build.yml workflow and the tests run fine on my local machine.

Thanks for your help, or any suggestions on how to diagnose.

Hugh

Auto update releaser workflows

The releaser workflows are taken from https://github.com/jupyter-server/jupyter_releaser/blob/main/example-workflows/
But we don't test if they are up to date - for example for now they are missing jupyter-server/jupyter_releaser#500

...

...

Check release & publish release workflow errors

Description

Could not find any related issues despite getting this error with the most simple extension and after the first commit. My issue is that some of the workflows are failing with errors that seem a bit strange to me. The error that interrupts both the Populate Release step of the Step 2: Publish Release workflow and the Check Release of the Check Release workflow is the following :

...
npm notice === Tarball Details ===
npm notice name:          releasetest
npm notice version:       0.1.1
npm notice filename:      releasetest-0.1.1.tgz
npm notice package size:  4.3 kB
npm notice unpacked size: 11.7 kB
npm notice shasum:        a0e9f2b30fd7526837dd7e3ad359125de3316641
npm notice integrity:     sha512-GKXIuibxBSRAr[...]O+H2SEBPnV85g==
npm notice total files:   8
npm notice
releasetest-0.1.1.tgz
stderr:
 npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /home/runner/work/jupyterlab-test-release/jupyterlab-test-release/.jupyter_releaser_checkout/dist/package.json
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, open '/home/runner/work/jupyterlab-test-release/jupyterlab-test-release/.jupyter_releaser_checkout/dist/package.json'
npm ERR! enoent This is related to npm not being able to find a file.
npm ERR! enoent
...

To explore whether that could be caused by my extension in itself, I created a new empty extension with the last version of JupyterLab, and created a new public GitHub repository to host that extension, and ended up with the same error. The Check Release and Step 2: Publish Release workflows are both still failing with the same error.

Reproduce

1. Create new public GitHub repository
2. Create new extension and seed the project with the template :

conda create -n release-test --override-channels --strict-channel-priority -c conda-forge -c nodefaults jupyterlab=4 nodejs=18 git copier jinja2-time
conda activate release-test
mkdir release-test
cd release-test
copier copy --UNSAFE https://github.com/jupyterlab/extension-template .
pip install -ve .
jupyter labextension develop . --overwrite

3. Push code to GitHub repository :

git init
git add .
git commit -m "First commit"
git branch -M main
git remote add origin https://github.com/<path-to-repo>.git
git push -u origin main

4. Then this triggers the Check Release workflow. Set up job, Checkout and Base Setup pass but Check Release does not. Full log can be seen at : GitHub Actions job link.
5. If I now also try to manually trigger both Step 1: Prep Release and Step 2: Publish Release by providing my ADMIN_GITHUB_TOKEN, NPM_TOKEN and PYPI_TOKEN in my secrets, I also get the same error during the Step 2: Publish Release workflow.

Expected behavior

I would expect the template extension Check Release and Step 2: Publish Release workflows to pass without errors if I haven't modified the source code of my extension yet.

Context

• Operating System and version: Windows 11
• Browser and version: Chrome 115.0
• JupyterLab version: 4.0.5 (but I get the same with 4.0.1)

Troubleshoot Output

Paste the output from running `jupyter troubleshoot` from the command line here.
You may want to sanitize the paths in the output.

Command Line Output

Paste the output from your command line running `jupyter lab` here, use `--debug` if possible.

Browser Output

Paste the output from your browser Javascript console here, if applicable.

Should immutable installs be enabled by default?

Currently these are disabled:

extension-template/template/.yarnrc.yml

Line 1 in f256e36

enableImmutableInstalls: false

As jlpm on local machine and on CI matches (i.e. JupyterLab version is the same) there should be no issues. If needed users can disable it downstream. I know it is hard when trying to support multiple versions or with very complex dependencies, but maybe worth enabling by default anyways?

Fresh install has minor linting issues in package.json

diff --git a/package.json b/package.json
index d89db23..a3555c5 100644
--- a/package.json
+++ b/package.json
@@ -58,9 +58,9 @@
     },
     "dependencies": {
         "@jupyterlab/application": "^4.0.0",
-        "@jupyterlab/settingregistry": "^4.0.0",
         "@jupyterlab/coreutils": "^6.0.0",
-        "@jupyterlab/services": "^7.0.0"
+        "@jupyterlab/services": "^7.0.0",
+        "@jupyterlab/settingregistry": "^4.0.0"
     },
     "devDependencies": {
         "@jupyterlab/builder": "^4.0.0",
@@ -100,14 +100,14 @@
     },
     "jupyterlab": {
         "discovery": {
-        "server": {
-            "managers": [
-                "pip"
-            ],
-            "base": {
-                "name": "my_extension"
+            "server": {
+                "managers": [
+                    "pip"
+                ],
+                "base": {
+                    "name": "my_extension"
+                }
             }
-        }
         },
         "extension": true,
         "outputDir": "my_extension/labextension",

"Could not find @jupyterlab/builder" on CI in the build job

I encountered this error over in krassowski/jupyterlab-citation-manager#65 on python -m pip install .[test]. I wonder what am I missing.

• @jupyterlab/builder is in package.json
• locally running python -m pip install .[test] works fine

Remove Webpack plugins from development dependencies to simplify the `package.json` file

Hi! 👋

Problem

This is not exactly a problem, but I would like to suggest a small change to the package.json file to simplify it.

Currently, there are three Webpack plugins as development dependencies: css-loader, source-map-loader, and style-loader. They are all @jupyterlab/builder dependencies, so they are installed together. Therefore, to simplify the package.json file a bit (and consequently the template), especially for new extension developers, I think it would be good to remove them.

Proposed Solution

Delete the css-loader, source-map-loader, and style-loader development dependencies from the following file:

extension-template/template/package.json.jinja

Line 67 in eda2e0d

"devDependencies": {

Please let me know your opinion and if I can help/open a PR.

Thanks!

Change `npm-run-all` to `npm-run-all2`

Hi! 👋

Problem

npm-run-all is a useful but no longer maintained development dependency. It can be problematic for stricter contexts regarding the dependencies used.

Proposed Solution

Change npm-run-all to npm-run-all2, a currently maintained and improved fork. The change is as simple as changing npm-run-all to npm-run-all2 in the package.json file, as well as the respective version. Please let me know your opinion and if I can help/open a PR.

Additional context

• https://github.com/bcomnes/npm-run-all2
• https://github.com/es-tooling/module-replacements/blob/e834b84d6ebc621c449c3d3930ed688a924b60df/docs/modules/npm-run-all.md
• honojs/starter#15

Thanks!

metadata generation failed

I was trying to create extension with this template. I'm using Ubuntu 20.04 and Python 3.11.

I've used copier to copy the template, I selected frontend extension. Then I run pip install -e "." and got below error message:

pip install -e "."
Obtaining file:///home/piotr/sandbox/myextension
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Installing backend dependencies ... done
  Preparing editable metadata (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Preparing editable metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [46 lines of output]
      INFO:hatch_jupyter_builder.utils:Running jupyter-builder
      INFO:hatch_jupyter_builder.utils:Building with hatch_jupyter_builder.npm_builder
      INFO:hatch_jupyter_builder.utils:With kwargs: {'build_cmd': 'install:extension', 'npm': ['jlpm'], 'source_dir': 'src', 'build_dir': 'myextension/labextension'}
      INFO:hatch_jupyter_builder.utils:Installing build dependencies with npm.  This may take a while...
      INFO:hatch_jupyter_builder.utils:> /tmp/pip-build-env-ewv84fco/overlay/bin/jlpm install
      Usage Error: The nearest package directory (/home/piotr/sandbox/myextension) doesn't seem to be part of the project declared in /home/piotr.
      
      - If /home/piotr isn't intended to be a project, remove any yarn.lock and/or package.json file there.
      - If /home/piotr is intended to be a project, it might be that you forgot to list sandbox/myextension in its workspace configuration.
      - Finally, if /home/piotr is fine and you intend sandbox/myextension to be treated as a completely separate project (not even a workspace), create an empty yarn.lock file in it.
      
      $ yarn install [--json] [--immutable] [--immutable-cache] [--check-cache] [--inline-builds] [--mode #0]
      Traceback (most recent call last):
        File "/home/piotr/sandbox/myextension/extenv/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 167, in prepare_metadata_for_build_editable
          hook = backend.prepare_metadata_for_build_editable
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      AttributeError: module 'hatchling.build' has no attribute 'prepare_metadata_for_build_editable'
      
      During handling of the above exception, another exception occurred:
      
      Traceback (most recent call last):
        File "/home/piotr/sandbox/myextension/extenv/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/home/piotr/sandbox/myextension/extenv/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/piotr/sandbox/myextension/extenv/lib/python3.11/site-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 176, in prepare_metadata_for_build_editable
          whl_basename = build_hook(metadata_directory, config_settings)
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-ewv84fco/overlay/lib/python3.11/site-packages/hatchling/build.py", line 78, in build_editable
          return os.path.basename(next(builder.build(wheel_directory, ['editable'])))
                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-ewv84fco/overlay/lib/python3.11/site-packages/hatchling/builders/plugin/interface.py", line 150, in build
          build_hook.initialize(version, build_data)
        File "/tmp/pip-build-env-ewv84fco/normal/lib/python3.11/site-packages/hatch_jupyter_builder/plugin.py", line 87, in initialize
          raise e
        File "/tmp/pip-build-env-ewv84fco/normal/lib/python3.11/site-packages/hatch_jupyter_builder/plugin.py", line 82, in initialize
          build_func(self.target_name, version, **build_kwargs)
        File "/tmp/pip-build-env-ewv84fco/normal/lib/python3.11/site-packages/hatch_jupyter_builder/utils.py", line 113, in npm_builder
          run([*npm_cmd, "install"], cwd=str(abs_path))
        File "/tmp/pip-build-env-ewv84fco/normal/lib/python3.11/site-packages/hatch_jupyter_builder/utils.py", line 229, in run
          return subprocess.check_call(cmd, **kwargs)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/home/piotr/.pyenv/versions/3.11.5/lib/python3.11/subprocess.py", line 413, in check_call
          raise CalledProcessError(retcode, cmd)
      subprocess.CalledProcessError: Command '['/tmp/pip-build-env-ewv84fco/overlay/bin/jlpm', 'install']' returned non-zero exit status 1.
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

[notice] A new release of pip is available: 23.2.1 -> 23.3.1
[notice] To update, run: pip install --upgrade pip

`watch:src` script should use the `--sourceMap` option

Problem

Whenever I work on the frontend for a jupyterlab extension, I run jlpm watch, which then calls the watch:src script. This script is intended for development purposes, but it's only partially useful if you don't produce source maps. I think the default should be to include source maps in watch mode. This is a small quality of life change, but I've been working on a lot of extensions lately and this would be nice to have by default.

Proposed Solution

Change the "watch:src" script to "watch:src": "tsc -w --sourceMap".

Update snapshots does not work out of the box

Description

The update snapshots job fails in the step using jupyterlab/maintainer-tools/.github/actions/update-snapshots@v1 action with:

Run yarn install
yarn install v1.22.22
// omitted
Run yarn run test:update
yarn run v1.22.22
$ jlpm playwright test --update-snapshots
Internal Error: jupyterlab-my-extension-ui-tests@workspace:.: This package doesn't seem to be present in your lockfile; run "yarn install" to update the lockfile

Note that yarn in the image is now pointing to a very old version of yarn.

Changing npm_client to jlpm by adding an argument in:

extension-template/template/.github/workflows/{% if test %}update-integration-tests.yml{% endif %}

Lines 45 to 50 in b2e180b

	- uses: jupyterlab/maintainer-tools/.github/actions/update-snapshots@v1
	with:
	github_token: ${{ secrets.GITHUB_TOKEN }}
	# Playwright knows how to start JupyterLab server
	start_server_script: 'null'
	test_folder: ui-tests

Fixes the issue for me.

I am not sure if this should be fixed in maintainer-tools by ensuring that yarn berry is used, or here by adding npm_client argument.

Anyone else seen this?

Check-release action in fails on `check-npm`

I am not sure if this is a bug in the template or jupyter-releaser, but I saw this issue across two unrelated repositories, for example see runs:

• https://github.com/holoviz/pyviz_comms/actions/runs/5662287867/job/15341946761?pr=114 or
• https://github.com/krassowski/jupyterlab-vim/actions/runs/5703795057/job/15457008140

It looks like this:

Extracting 1 packages...
stderr:
 npm ERR! code 1
npm ERR! path /tmp/tmp0fk9x1hn/staging/@axlair/jupyterlab_vim
npm ERR! command failed
npm ERR! command sh -c jlpm run clean && jlpm run build:prod
npm ERR! Usage Error: The nearest package directory (/tmp/tmp0fk9x1hn/staging/@axlair/jupyterlab_vim) doesn't seem to be part of the project declared in /tmp/tmp0fk9x1hn.
npm ERR!
npm ERR! - If /tmp/tmp0fk9x1hn isn't intended to be a project, remove any yarn.lock and/or package.json file there.
npm ERR! - If /tmp/tmp0fk9x1hn is intended to be a project, it might be that you forgot to list staging/@axlair/jupyterlab_vim in its workspace configuration.
npm ERR! - Finally, if /tmp/tmp0fk9x1hn is fine and you intend staging/@axlair/jupyterlab_vim to be treated as a completely separate project (not even a workspace), create an empty yarn.lock file in it.
npm ERR!
npm ERR! $ yarn run [--inspect] [--inspect-brk] [-T,--top-level] [-B,--binaries-only] <scriptName> ...

npm ERR! A complete log of this run can be found in: /home/runner/.npm/_logs/2023-07-30T02_51_39_915Z-debug-0.log

I thought it is a berry issue at first, but now I wonder if maybe the template is missing something? Anyone else saw this?

AttributeError when upgrading extension

Description

When running python -m jupyterlab.upgrade_extension ., I get the following error:

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/home/julien/.conda/envs/jupyterlab-ext/lib/python3.11/site-packages/jupyterlab/upgrade_extension.py", line 315, in <module>
    update_extension(args.path, args.vcs_ref, args.no_input is False)
  File "/home/julien/.conda/envs/jupyterlab-ext/lib/python3.11/site-packages/jupyterlab/upgrade_extension.py", line 147, in update_extension
    copier.run_auto(template, output_dir, vcs_ref=vcs_ref, data=extra_context, defaults=True)
    ^^^^^^^^^^^^^^^
AttributeError: module 'copier' has no attribute 'run_auto'

Reproduce

1. Have (or create) a Jupyterlab 3.x.x extension
2. Follow the migration guide

Expected behavior

Upgrading the extension without an error

Context

• Operating System and version: Linux EndeavourOS 6.1.32-1-lts
• Browser and version: Firefox 114
• JupyterLab version: 4.0.1

Extension description from user input leads to broken `jlpm build`

Description

Following the instructions in the extension tutorial, during the copier copy https://github.com/jupyterlab/extension-template . step, one is prompted to enter an extension description. If the user enters a single quote anywhere in the description (e.g. as an apostrophe), that will break the extension build when running pip install -ve . later in the instructions.

Reproduce

1. Follow the extension tutorial
2. Run copier as instructed.
3. Add an extension description that includes a single quote (') anywhere within.
4. Proceed through the instructions to the build step which has you run pip install -ve .
5. Observe the following error during build:

INFO:hatch_jupyter_builder.utils:> /private/var/folders/yx/49ml7j3s7t31pwd25pyj6rb800n42n/T/pip-build-env-tcyq9c22/overlay/bin/jlpm run install:extension
  src/index.ts(11,59): error TS1005: ',' expected.

Inspecting src/index.ts at the given line number and character reveals the single quote breaking the description k:v pair.

Expected behavior

Single quotes provided by user in the description (or any user-submitted text) should either be escaped or stripped.

Context

• Operating System and version: MacOS Ventura
• Browser and version: Chrome 117
• JupyterLab version: 4.0.6
• Extension template version: 4.2.1

Duplicate slashes for URLs generated from the repository URL with a trailing slash

Hi! 👋

Description

When generating a new extension, if the repository URL has a trailing slash (e.g., https://github.com/jupyterlab/extension-template/), the URL in the bugs.url field of the package.json file will be generated with two slashes (e.g., https://github.com/jupyterlab/extension-template//issues). Same for the repository.url field (e.g., https://github.com/jupyterlab/extension-template/.git) and the Github Actions Status badge in the README.md file (e.g., https://github.com/jupyterlab/extension-template//workflows/Build/badge.svg)

Some kind of normalization (in the copier.yml file or in the package.json template file) would be handy from my perspective. Please let me know if I can help in any way.

Reproduce

1. Generate a new extension (using the pipx run --pip-args=jinja2-time==0.2.0 copier==9.2.0 copy --trust --vcs-ref v4.3.1 https://github.com/jupyterlab/extension-template demo command, for example).
2. Fill in the Git remote repository URL field with a URL with a trailing slash: https://github.com/jupyterlab/extension-template/
3. Check the bugs.url and repository.url fields of the generated package.json file, as well as the Github Actions Status badge URL at the top of the README.md file.

Expected behavior

URL repositories without duplicate slashes, whether the repository URL has a trailing slash.

Context

• Operating System and version: macOS Sonoma 14.2.1
• Browser and version: Chrome 123.0.6312.107
• JupyterLab version: 4.0.9
• Python version: 3.10.13
• Copier version: 9.2.0
• pipx version: 1.5.0

Unpin pyyaml-include and recommend copier in version which does not depend on it

This is to to track unpinning pyyaml-include which gets pinned in #64 once a new copier version gets released, see copier-org/copier#1568

root `package.json` should not be prettify

Description

hatch-nodejs-version save the package.json file using a 4 spaces indentation => when releasing an extension, the linter fails.

See:

• https://github.com/jupyterlab/jupyterlab-git/actions/runs/5312121015/jobs/9616212935
• jupyterlab-contrib/jupyterlab-theme-editor#17

`keywords` defined in the `package.json` file are not included in the Python package metadata

Hi! 👋

Description

keywords is one of the fields defined as dynamic in the pyproject.toml file, similarly to description and urls, for example. If I'm correct, the values ​​for these fields are obtained from the package.json file via the hatch-nodejs-version metadata hook plugin.

However, the keywords defined in the package.json file are not included as metadata of the Python package built from this template as expected. To do so, it is necessary to configure the respective metadata hook plugin to include this field, keywords, as well.

Reproduce

1. Create a Conda environment as described in the jupyterlab/extension-template repo. I used the following environment.yml file to do so:

name: try-jupyterlab-extension-template
channels:
  - conda-forge
  - nodefaults
dependencies:
  - python=3.10.14
  - pip=23.0.1
  - nodejs=18.18.2
  - jupyterlab=4.0.9
  - copier=9.2.0
  - jinja2-time=0.2.0

More information can be found in the try-jupyterlab-extension-template repo.

2. Generate a new extension via Copier (a theme extension with the default values, for example).
3. Install the extension in development mode.
4. Build the Python package following the instructions available in the RELEASE.md file.
5. Open the dist/ folder and unzip the wheel/built distribution and source distribution to manually check the metadata files. The PKG-INFO file from the source distribution, for example, should look like this (Dynamic: Keywords on line 4 is the relevant part):

Metadata-Version: 2.3
Name: mytheme
Version: 0.1.0
Dynamic: Keywords
Summary: A JupyterLab extension.
Project-URL: Homepage, https://gitlab.com/joaommpalmeiro/try-jupyterlab-extension-template
Project-URL: Bug Tracker, https://gitlab.com/joaommpalmeiro/try-jupyterlab-extension-template/issues
Project-URL: Repository, https://gitlab.com/joaommpalmeiro/try-jupyterlab-extension-template.git
Author-email: João Palmeiro <[email protected]>
License: BSD 3-Clause License
        
        Copyright (c) 2024, João Palmeiro
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown

...

Expected behavior

The keywords defined in the package.json file are included as metadata in the Python package by including the "keywords" value in the hatch-nodejs-version metadata hook plugin configuration (pyproject.toml file):

[tool.hatch.metadata.hooks.nodejs]
- fields = ["description", "authors", "urls"]
+ fields = ["description", "authors", "urls", "keywords"]

Line 4 of the PKG-INFO file shared above should disappear, and the expected Keywords entry for the default package.json file should look like the following snippet:

Keywords: jupyter,jupyterlab,jupyterlab-extension

Let me know what you think and if I can open a PR.

Context

• Operating System and version: macOS Sonoma 14.2.1
• Browser and version: Chrome 123.0.6312.107
• JupyterLab version: 4.0.9
• Python version: 3.10.13
• Copier version: 9.2.0

Adding type hints and ship `py.typed`, `mypy` config

Problem

While adding a simple labextension won't benefit from type checking, as soon as a REST API, widget, etc. is added, it becomes powerful tool for finding actual bugs, learning about how your code (and your dependencies' code) actually works, and particularly useful when upgrading to a new version of a well-typed upstream (e.g. jupyter_server).

Proposed Solution

Add:

• type hints in generated .py files
• ship py.typed
• pyproject.toml
  • Typing :: Typed trove classifier
  • [tool.mypy] with pretty strict defaults

There are of course other typecheckers, and choice is good, but of the typed upstreams, most rely on mypy.

By just being present in a well-known location, the settings will get picked up in some IDEs (even if another typecheker is used), helping folk fix typing issues per-keystroke.

As an option, be able to add a mypy check to... whatever, whether it's make, just GHA, pre-commit, some hatch env-in-env monstrosity or whatever is suggested to folk by this template this week.

Additional context

While jupyterlab_server does ship py.typed, jupyterlab itself does not.

4.0 should probably add type hints and ship py.typed, but luckily, it isn't imported in most well-behaved extensions

README claims three extension types, but lists four.

Description

The README.md claims three types of extension are supported, and then lists four.

Reproduce

Read the README.md.

Expected behavior

Should say "four".

Context

PR incoming.

Sometimes `_version.py` is need but not there

Description

Sometimes the package is imported without being installed in editable mode (or a script is called during that installation that import the Python package). This results in an error that ._version cannot be imported as it is only generated dynamically by hatch when installing or bundling the package.

Reproduce

This is for example the case in jupyterlab_pygments that runs a script generate_css.py when installing/bundling the package.

See workaround