jupyter / jupyter/nbformat

Validation should not mutate arguments

Open
#235 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
313
Forks
176
PR merge metrics
No merged PRs in 30d

Description

Currently if a code cell has a missing id, it will silently add one to it. This is problematic for a few reasons.

1) it mutates arguments.
2) it is counter intuitive WRT the name of the function and the docs that says it raises if invalid.

1 + 2 create signing issues, indeed validate is called when writing and most notebook manger do :
- compute signature
- save (indirectly validate).

They assume that what you save is identical to what you give to nbformat, but as validate mutates things it is untrue.

Now with validate mutating, what is saved has a different signature than what was computed just above, and worse, as it mutates you may be scratching your head as to why.

I thin that validate should raise unconditionally if the notebook is invalid or requires modifications, and that for convenience you may want to have a `normalise()` function/method that you can call to do any mutations if you wish to.

As raising is likely to break a bunch of stuff, we have to have a transition plan. I suggest to emit a warning.

Contributor guide

Open the contributing guide

Research direction

Start at the validate entry point described in the issue and trace its callers during notebook writing, including signature computation and saving. Determine the transition needed so invalid notebooks do not mutate during validation, and verify that the resulting behavior preserves the original arguments while providing the proposed warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.