Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

User migration docs for 7.x -> 8.0 #3501

Merged
merged 2 commits into from
Jul 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

A summary of changes in ipywidgets. For more detailed information, see the issues and pull requests for the appropriate milestone on [GitHub](https://github.com/jupyter-widgets/ipywidgets).

## [8.0](https://github.com/jupyter-widgets/ipywidgets/releases/tag/v8.0) (not released yet)
## [8.0](https://github.com/jupyter-widgets/ipywidgets/releases/tag/v8.0)

To see the full list of pull requests and issues, see the [8.0 milestone](https://github.com/jupyter-widgets/ipywidgets/milestone/30?closed=1) on GitHub.
See also the
Expand Down
1 change: 1 addition & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ some custom widget packages built on top of the Jupyter Widgets framework.
:maxdepth: 1

changelog.md
user_migration_guides.md
migration_guides.md

.. toctree::
Expand Down
3 changes: 3 additions & 0 deletions docs/source/migration_guides.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ is released.
We also recommend testing the migration in a completely new notebook, rather
than one that contains widgets that you instantiated with ipywidgets 7.x.

For a summarized list of relevant changes, please consult the "Developers" section of the
[changelog](./changelog).

### Updating setup.py

Start by updating the dependency in your `setup.py` or `setup.cfg` to support 8.x.
Expand Down
92 changes: 92 additions & 0 deletions docs/source/user_migration_guides.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
Migrating user code
===================

These are migration guides aimed specifically at user of ipywidgets.

Migrating from 7.x to 8.0
-------------------------

For more details about the changes done for the 8.0 major version, please consult the
[changelog](./changelog).

### Code

#### FileUpload

The `data` and `metadata` traits have been removed, and the `value` trait revamped to
be a list of dicts containing the file information. The keys of these dicts are:

- `content`: The buffer of file data
- `name`: The name of the file
- `type`: The MIME type of the file content
- `size`: The size of the buffer in bytes
- `last_modified`: A UTC datetime representing the "last modified" value reported for the file

Suggested migration: Rewrite all usage of `FileUpload` to use the new structure.
If you need to support both 7.x and 8.x, you can e.g. write functions `get_file_buffer` and similar
to wrap reads from the widget.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to me to be the largest breaking change for users. I.e. it is likely to completely break code (exceptions will be raised that cannot be recovered from), and is likely to be heavily used.


#### Tooltips

As part of an effort to make it possible to
[set tooltips for all widgets](https://github.com/jupyter-widgets/ipywidgets/pull/2680),
the old `description_tooltip` attribute for certain widgets was removed. Now all widgets
that inherit `DOMWidget` have the attribute `tooltip` instead.

Suggested migration: Search and replace `description_tooltip` to `tooltip`.
TBD: ipywidgets should add a `description_tooltip` keyword argument to `DescriptionWidget`s, with
a deprecation warning.
vidartf marked this conversation as resolved.
Show resolved Hide resolved

#### Selection Widgets

These widgets include: `ToggleButtons`, `Dropdown`, `RadioButtons`, `Select`, `SelectMultiple` `Selection`, `SelectionSlider`, and `SelectionRangeSlider`.

For these, it is no longer possible to use `dict`s or other mapping types as values for the
`options` trait. Using mapping types in this way has been deprecated since version 7.4, and
will now raise a `TypeError`.

Suggested migration: Clean up the `options` use. The following snippet can be used to convert
a `dict` to the new format: `w.options = tuple((str(k), v) for k, v in your_dict.items())`.

#### Description Sanitization

The value of the `description` field of any widget that inherits `DescriptionWidget`
(most widgets in ipywidgets) will now have its value sanitized for certain HTML content
on the client side. If you are relying on HTML in this value, you might need to explicitly
set the `description_allow_html` trait to `True`, depending on what kind of tags/attributes
are used.

Suggested migration: Only set `description_allow_html` if you are in full control of the
value that is set.

#### Layout.border

While this change is strictly speaking backwards compatible, a word of caution is useful to
those that want to use the new functionality:

Four attributes have been added: `border_left`, `border_right`, `border_top` and `border_bottom`.
These can be used to set the corresponding CSS border strings individually. Setting the
`border` property overrides all of those four attributes to the new value of `border`. If
the individual values are set to different values, *the `border` property will return `None`
when you read its value*.

#### Layout.overflow_x / overflow_y

The previously deprecated traits `overflow_x` and `overflow_y`
[have been removed](https://github.com/jupyter-widgets/ipywidgets/pull/2688). Please
use the `overflow` trait instead.

### Deployments

#### Embedded CDN

Please note that the default CDN of ipywidgets have changed from unpkg to jsDelivr. If
you rely on the CDN being unpkg, this can be overridden by specifying the data
attribute `data-jupyter-widgets-cdn` on the HTML manager script tag. See
[embedding](./embedding) for details.

#### widgetsnbextension

The `widgetsnbextension` package is no longer a dependency of `ipywidgets`. Consequently,
neither is the `notebook` package. If you need to keep `notebook` and widget support for it
you will need to ensure they are explicitly stated in any environment bootstrapping.