Skip to content

Commit cb5eef5

Browse files
Chenzo1001Chenzo1001
authored
✨[Feature]: Add pip-based install support for JupyterLab side panel extension (#35399)
* Add pip installation * update CHANGES.md * Add license * update format * Fix whitspace problem * Fix isort problem * update ignore rules
1 parent b97ee31 commit cb5eef5

File tree

7 files changed

+212
-2
lines changed

7 files changed

+212
-2
lines changed

‎CHANGES.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@
7474
## New Features / Improvements
7575

7676
* X feature added (Java/Python) ([#X](https://github.com/apache/beam/issues/X)).
77+
* Add pip-based install support for JupyterLab Sidepanel extension ([#35397](https://github.com/apache/beam/issues/#35397)).
7778

7879
## Breaking Changes
7980

‎sdks/python/apache_beam/runners/interactive/extensions/apache-beam-jupyterlab-sidepanel/.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.yarn/
2+
apache_beam_jupyterlab_sidepanel/labextension/
3+
lib/
4+
tsconfig.tsbuildinfo
5+
node_modules/
6+
dist/

‎sdks/python/apache_beam/runners/interactive/extensions/apache-beam-jupyterlab-sidepanel/README.md

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,55 @@ Includes two different side panels:
2929
| v3 | v2.0.0-v3.0.0 |
3030
| v2 | v1.0.0 |
3131

32-
## Install
32+
## Installation
33+
34+
There are two ways to install the extension:
35+
36+
### 1. Via pip (recommended)
37+
38+
The extension is now available as a Python package on PyPI. You can install it with:
39+
40+
```bash
41+
pip install apache-beam-jupyterlab-sidepanel
42+
```
43+
44+
After installation, rebuild JupyterLab to activate the extension:
45+
46+
```bash
47+
jupyter lab clean
48+
jupyter lab build
49+
```
50+
51+
Then restart JupyterLab. The side panels will be available automatically.
52+
53+
54+
### 2. Via JupyterLab Extension Manager (legacy, will be deprecated soon)
3355

3456
```bash
3557
jupyter labextension install apache-beam-jupyterlab-sidepanel
3658
```
3759

60+
This installs the extension using JupyterLab's legacy extension system.
61+
62+
---
63+
64+
## Notes
65+
66+
- Pip installation is now the preferred method as it handles Python packaging and JupyterLab extension registration seamlessly.
67+
- After any upgrade or reinstallation, always rebuild JupyterLab to ensure the extension is activated.
68+
- For detailed usage and development, refer to the source code and issues on [GitHub](https://github.com/apache/beam).
69+
70+
---
71+
3872
## Contributing
3973

74+
> **Note**: When creating a Python package, the **module name (i.e., the folder name and import path)** must use underscores (`_`) instead of dashes (`-`). Dashes are **not allowed** in Python identifiers.
75+
> However, the **distribution name** (the name used in `pip install ...`) **can** include dashes, and this is a common convention in the Python ecosystem.
76+
> For example:
77+
> - `pip install apache-beam-jupyterlab-sidepanel` ✅
78+
> - `import apache_beam_jupyterlab_sidepanel` ✅
79+
> - `import apache-beam-jupyterlab-sidepanel` ❌ (invalid syntax)
80+
4081
### Install
4182

4283
The `jlpm` command is JupyterLab's pinned version of
@@ -117,8 +158,65 @@ jlpm eslint:check
117158
jlpm eslint
118159
```
119160

161+
### Packaging
162+
163+
This JupyterLab extension is distributed as a prebuilt Python package, and includes all necessary frontend assets (TypeScript-compiled JavaScript, styles, and metadata).
164+
165+
#### Build from source
166+
167+
To build the extension locally and package it into a wheel:
168+
169+
```bash
170+
# Ensure build dependencies are available
171+
pip install build jupyterlab jupyter_packaging hatch
172+
173+
# Build the wheel and source tarball
174+
hatch build
175+
```
176+
177+
This will generate `dist/*.whl` and `dist/*.tar.gz` files.
178+
179+
#### Install locally via pip
180+
181+
```bash
182+
pip install .
183+
```
184+
185+
After installation, JupyterLab will automatically discover and enable the extension. You can verify it was installed via:
186+
187+
```bash
188+
jupyter labextension list
189+
```
190+
191+
If properly installed, your extension should appear under the `prebuilt extensions` section.
192+
193+
#### File layout expectations
194+
195+
A typical prebuilt extension should include the following structure under your Python package:
196+
197+
```
198+
apache_beam_jupyterlab_sidepanel/
199+
├── __init__.py
200+
├── _version.py
201+
└── labextension/
202+
├── package.json
203+
├── install.json
204+
└── static/
205+
└── ...
206+
```
207+
208+
These will be copied to:
209+
210+
```
211+
$PREFIX/share/jupyter/labextensions/apache-beam-jupyterlab-sidepanel/
212+
```
213+
120214
### Uninstall
121215

122216
```bash
123217
jupyter labextension uninstall apache-beam-jupyterlab-sidepanel
124218
```
219+
or
220+
```bash
221+
pip uninstall apache-beam-jupyterlab-sidepanel
222+
```

‎sdks/python/apache_beam/runners/interactive/extensions/apache-beam-jupyterlab-sidepanel/apache_beam_jupyterlab_sidepanel/__init__.py

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
from ._version import __version__
17+
18+
19+
def _jupyter_labextension_paths():
20+
return [{"src": "labextension", "dest": "apache-beam-jupyterlab-sidepanel"}]

‎sdks/python/apache_beam/runners/interactive/extensions/apache-beam-jupyterlab-sidepanel/apache_beam_jupyterlab_sidepanel/_version.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# isort: skip_file
2+
3+
# Licensed to the Apache Software Foundation (ASF) under one or more
4+
# contributor license agreements. See the NOTICE file distributed with
5+
# this work for additional information regarding copyright ownership.
6+
# The ASF licenses this file to You under the Apache License, Version 2.0
7+
# (the "License"); you may not use this file except in compliance with
8+
# the License. You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
18+
__version__ = "4.0.0"

‎sdks/python/apache_beam/runners/interactive/extensions/apache-beam-jupyterlab-sidepanel/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@
9292
],
9393
"jupyterlab": {
9494
"extension": true,
95-
"outputDir": "apache-beam-jupyterlab-sidepanel/labextension"
95+
"outputDir": "apache_beam_jupyterlab_sidepanel/labextension"
9696
},
9797
"test": "jest",
9898
"resolutions": {

‎sdks/python/apache_beam/runners/interactive/extensions/apache-beam-jupyterlab-sidepanel/pyproject.toml

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
[build-system]
17+
requires = [
18+
"hatchling>=1.5.0",
19+
"jupyterlab>=4.0.0,<5",
20+
"hatch-nodejs-version>=0.3.2",
21+
]
22+
build-backend = "hatchling.build"
23+
24+
[project]
25+
name = "apache_beam_jupyterlab_sidepanel"
26+
version = "4.0.0"
27+
description = "JupyterLab Sidepanel for Apache Beam"
28+
readme = "README.md"
29+
requires-python = ">=3.9"
30+
license = { text = "Apache-2.0" }
31+
authors = [{ name = "Apache Beam", email = "[email protected]" }]
32+
classifiers = [
33+
"Framework :: Jupyter",
34+
"Framework :: Jupyter :: JupyterLab",
35+
"Framework :: Jupyter :: JupyterLab :: 4",
36+
"License :: OSI Approved :: Apache Software License",
37+
"Programming Language :: Python :: 3",
38+
]
39+
dependencies = ["jupyterlab>=4.0.0,<5", "jupyter_server>=2.0.0"]
40+
41+
[tool.hatch.version]
42+
source = "nodejs"
43+
44+
[tool.hatch.build]
45+
exclude = [".yarn/", "lib/", "node_modules/", "dist/", "tsconfig.tsbuildinfo"]
46+
47+
[tool.hatch.build.targets.sdist]
48+
artifacts = ["apache_beam_jupyterlab_sidepanel/labextension"]
49+
50+
[tool.hatch.build.targets.wheel.shared-data]
51+
"apache_beam_jupyterlab_sidepanel/labextension" = "share/jupyter/labextensions/apache-beam-jupyterlab-sidepanel"
52+
"install.json" = "share/jupyter/labextensions/apache-beam-jupyterlab-sidepanel/install.json"
53+
54+
[tool.hatch.build.hooks.jupyter-builder]
55+
dependencies = ["hatch-jupyter-builder>=0.5"]
56+
build-function = "hatch_jupyter_builder.npm_builder"
57+
ensured-targets = [
58+
"apache_beam_jupyterlab_sidepanel/labextension/static/style.js",
59+
"apache_beam_jupyterlab_sidepanel/labextension/package.json",
60+
]
61+
build-kwargs = { build_cmd = "build:prod", npm = ["jlpm"] }
62+
editable-build-kwargs = { build_cmd = "install:extension", npm = [
63+
"jlpm",
64+
], source_dir = "src", build_dir = "apache_beam_jupyterlab_sidepanel/labextension" }
65+
66+
[tool.jupyter-releaser.options]
67+
version_cmd = "hatch version"

0 commit comments

Comments
 (0)