Putting a comment above a cell magic fails like this:
In [1]: # setup
...: %%time
...: pass
UsageError: Line magic function `%%time` not found.
Blank lines above a cell magic are fine, since the leading_empty_lines cleanup transform drops them. Comment lines are the one thing that breaks.
From reading inputtransformer2, what seems to happen is: cell magic detection only looks at the first line of the cell, so the %%time line falls through to the escaped-command transform, which strips one % as the escape character and takes %time as the magic name. Names registered through the documented APIs come from Python function names, which can't contain %, so the lookup always fails. As far as we can tell the current parse serves no reachable purpose, with one exception: register_magic_function doesn't validate names, so a magic literally named %foo can be registered programmatically, and a mid-cell %%foo line does invoke it. We doubt anyone depends on that, but it's why we're not suggesting a hard error.
Two things seem worth improving, assuming we're not missing some history here:
-
The error message. The user wrote a cell magic, and the message says a line magic wasn't found. The doubled %% in the message also hides that the failed lookup was for %time. A message saying that a cell magic must be the first line of the cell would point at the actual mistake.
-
Possibly the parse itself. A leading_comment_lines cleanup transform in the spirit of leading_empty_lines, dropping leading blank and comment lines when the first real line starts with %%, would make the cell mean what the author obviously intended. A line starting with %% can't begin a Python statement, and a string continuation can't be the first real line of a cell, so we couldn't find currently valid code whose meaning would change, apart from the pathological registration above.
We ran into this through notebook tooling where both humans and LLM agents tend to put a narration comment at the top of a cell. We've added the transform to our own InteractiveShell subclass (execnb) and it has behaved well so far. Happy to send a PR for either or both parts, and equally happy to be told what nuance we've missed.
Tested on IPython 9.15.0.
Putting a comment above a cell magic fails like this:
Blank lines above a cell magic are fine, since the
leading_empty_linescleanup transform drops them. Comment lines are the one thing that breaks.From reading
inputtransformer2, what seems to happen is: cell magic detection only looks at the first line of the cell, so the%%timeline falls through to the escaped-command transform, which strips one%as the escape character and takes%timeas the magic name. Names registered through the documented APIs come from Python function names, which can't contain%, so the lookup always fails. As far as we can tell the current parse serves no reachable purpose, with one exception:register_magic_functiondoesn't validate names, so a magic literally named%foocan be registered programmatically, and a mid-cell%%fooline does invoke it. We doubt anyone depends on that, but it's why we're not suggesting a hard error.Two things seem worth improving, assuming we're not missing some history here:
The error message. The user wrote a cell magic, and the message says a line magic wasn't found. The doubled
%%in the message also hides that the failed lookup was for%time. A message saying that a cell magic must be the first line of the cell would point at the actual mistake.Possibly the parse itself. A
leading_comment_linescleanup transform in the spirit ofleading_empty_lines, dropping leading blank and comment lines when the first real line starts with%%, would make the cell mean what the author obviously intended. A line starting with%%can't begin a Python statement, and a string continuation can't be the first real line of a cell, so we couldn't find currently valid code whose meaning would change, apart from the pathological registration above.We ran into this through notebook tooling where both humans and LLM agents tend to put a narration comment at the top of a cell. We've added the transform to our own
InteractiveShellsubclass (execnb) and it has behaved well so far. Happy to send a PR for either or both parts, and equally happy to be told what nuance we've missed.Tested on IPython 9.15.0.