Skip to content

Commit 2de6e84

Browse files
vidartfvidartf
authored
Merge pull request jupyter-widgets#3405 from martinRenou/add_migration_guide
Add migration guide for 8.0
2 parents 27400b4 + 158f4b4 commit 2de6e84

File tree

1 file changed

+137
-4
lines changed

1 file changed

+137
-4
lines changed

‎docs/source/migration_guides.md‎

Lines changed: 137 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,139 @@ Migrating custom widget libraries
44
These are migration guides aimed specifically at developers of third-party
55
widgets.
66

7+
Migrating from 7.x to 8.0
8+
-------------------------
9+
10+
For example migrations, see these PRs:
11+
12+
- [ts-cookiecutter](https://github.com/jupyter-widgets/widget-ts-cookiecutter/pull/115)
13+
- [ipydatagrid](https://github.com/bloomberg/ipydatagrid/pull/282)
14+
- [bqplot](https://github.com/bqplot/bqplot/pull/1404)
15+
- [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet/pull/968)
16+
- [bqscales](https://github.com/bqplot/bqscales/pull/49)
17+
- [sidecar](https://github.com/jupyter-widgets/jupyterlab-sidecar/pull/86)
18+
19+
To avoid tying your development cycle to ipywidgets, we recommend starting
20+
the migration on a branch and keeping that branch open until ipywidgets 8.0
21+
is released.
22+
23+
We also recommend testing the migration in a completely new notebook, rather
24+
than one that contains widgets that you instantiated with ipywidgets 7.x.
25+
26+
### Updating setup.py
27+
28+
Start by updating the dependency in your `setup.py` or `setup.cfg` to support 8.x.
29+
30+
*e.g.*
31+
32+
```diff
33+
install_requires=[
34+
- 'ipywidgets>=7,<8',
35+
+ 'ipywidgets>=7,<9',
36+
],
37+
```
38+
39+
### Updating package.json
40+
41+
Next, you should update the JavaScript dependencies. You will need to update
42+
your `@jupyter-widgets/base` dependency and the `@jupyter-widgets/controls` **if**
43+
you depend on it.
44+
45+
The diff will look like the following in case you still want to support ipywidgets<8:
46+
47+
```diff
48+
- "@jupyter-widgets/base": "^2 || ^3 || ^4",
49+
+ "@jupyter-widgets/base": "^2 || ^3 || ^4 || ^5 || ^6",
50+
```
51+
52+
You can also apply the following diff if you only want to support ipywidgets==8 from now on:
53+
54+
```diff
55+
- "@jupyter-widgets/base": "^2 || ^3 || ^4",
56+
+ "@jupyter-widgets/base": "^5 || ^6",
57+
```
58+
59+
Note that "@jupyter-widgets/base" version 5 is for ipywidgets 8 support in the front-end, "@jupyter-widgets/base" version 6 is for ipywidgets 8 **and JupyterLab 4** support in the front-end.
60+
61+
The ``ManagerBase`` class has been moved from the ``@jupyter-widgets/base`` package to the new ``@jupyter-widgets/base-manager`` package. So if you used to depend on that ``ManagerBase`` class, you need to add the new dependency in your ``package.json`` as following, and update your imports accordingly.
62+
63+
```diff
64+
+ "@jupyter-widgets/base-manager": "^1",
65+
```
66+
67+
### Updating the client-side code
68+
69+
#### Phosphor -> Lumino
70+
71+
The Phosphor library has been archived. It has been forked and renamed "Lumino", and the maintenance is now done under the JupyterLab governance: https://github.com/jupyterlab/lumino
72+
73+
If you used to import classes like ``JupyterPhosphorPanelWidget`` and ``JupyterPhosphorWidget`` from the ``@jupyter-widgets/base`` library, you will need to update them:
74+
75+
```diff
76+
- import { JupyterPhosphorPanelWidget, JupyterPhosphorWidget } from '@jupyter-widgets/base';
77+
+ import { JupyterLuminoPanelWidget, JupyterLuminoWidget } from '@jupyter-widgets/base';
78+
```
79+
80+
The ``DOMWidgetView.pWidget`` property has been renamed ``DOMWidgetView.luminoWidget`` (though an alias for ``pWidget`` is available for conveniance):
81+
82+
```diff
83+
- this.pWidget
84+
+ this.luminoWidget
85+
```
86+
87+
The ``DOMWidgetView.processPhosphorMessage`` method has been renamed ``DOMWidgetView.processLuminoMessage``. If you want to support both ipywidgets 7.x and 8.x, you should implement both methods:
88+
89+
```diff
90+
- processPhosphorMessage(msg: Message): void {
91+
- super.processPhosphorMessage(msg);
92+
- switch (msg.type) {
93+
- case 'resize':
94+
- this.resize();
95+
- break;
96+
- }
97+
- }
98+
+ _processLuminoMessage(msg: Message, _super: (msg: Message) => void): void {
99+
+ _super.call(this, msg);
100+
+ switch (msg.type) {
101+
+ case 'resize':
102+
+ this.resize();
103+
+ break;
104+
+ }
105+
+ }
106+
+
107+
+ processPhosphorMessage(msg: Message): void {
108+
+ this._processLuminoMessage(msg, (DOMWidgetView as any).processPhosphorMessage);
109+
+ }
110+
+
111+
+ processLuminoMessage(msg: Message): void {
112+
+ this._processLuminoMessage(msg, (DOMWidgetView as any).processLuminoMessage);
113+
+ }
114+
```
115+
116+
I you're dropping ipywidgets 7.x support, you can simply rename the `processPhosphorMessage` method into `processLuminoMessage`.
117+
118+
#### ManagerBase import
119+
120+
As mentionned before, if you depend on the ``ManagerBase`` class, you will need to update the import:
121+
122+
```diff
123+
- import { ManagerBase } from '@jupyter-widgets/base';
124+
+ import { ManagerBase } from '@jupyter-widgets/base-manager';
125+
```
126+
127+
#### Backbone extend
128+
129+
If you were extending the base widget model with `var CustomWidgetModel = Widget.extend({ ... });` you will need to update the class definition using the ES6 notation:
130+
131+
```diff
132+
- var CustomWidgetModel = Widget.extend({
133+
- ...
134+
- });
135+
+ class CustomWidgetModel extends Widget {
136+
+ ...
137+
+ }
138+
```
139+
7140
Migrating from 6.0 to 7.0
8141
-------------------------
9142

@@ -14,7 +147,7 @@ For example migrations, see these PRs:
14147

15148
To avoid tying your development cycle to ipywidgets, we recommend starting
16149
the migration on a branch and keeping that branch open until ipywidgets 7.0
17-
is released.
150+
is released.
18151

19152
We also recommend testing the migration in a completely new notebook, rather
20153
than one that contains widgets that you instantiated with ipywidgets 6.0.
@@ -30,9 +163,9 @@ cycle through the tags until you see the latest 7.0.0 tag.
30163

31164
Next, we should update the JavaScript dependencies. The most important change
32165
for widget developers is that the JavaScript package for jupyter-widgets has
33-
been split between `@jupyter-widgets/base` and `@jupyter-widgets/controls`:
166+
been split between `@jupyter-widgets/base` and `@jupyter-widgets/controls`:
34167
- `@jupyter-widgets/base` contains the base widget classes and the layout
35-
classes
168+
classes
36169
- `@jupyter-widgets/controls` contains the widget classes for the
37170
user-facing widgets.
38171

@@ -105,7 +238,7 @@ that matches a release on NPM. The most common pattern is to request a
105238
version compatible with the version currently in your `package.json` by using,
106239
`~{{ version number }}` for `_model_module_version` and `_view_module_version`. See the [cookiecutter
107240
template](https://github.com/jupyter-widgets/widget-cookiecutter/blob/master/%7B%7Bcookiecutter.github_project_name%7D%7D/js/lib/example.js#L24)
108-
for details.
241+
for details.
109242

110243
Since you probably want to avoid repeating the module version in every
111244
widget, a common pattern is to import the version from `package.json` and

0 commit comments

Comments
 (0)