iodide-project / iodide-project/iodide

Compatibility with 'percent' notebook format

Open
#2,942 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
1.5k
Forks
145
PR merge metrics
No merged PRs in 30d

Description

The "percent" notebook format looks similar to the pyodide notebook format [1]. It may be advantageous to adopt the percent format so that pyodide notebooks can be run in other tools? A different solution would be to add "pyodide format" (?) to jupytext.

Jyve (JupyterLab as WASM with pyiodide) does not yet support jupytext and so does not yet support the 'percent' format: https://github.com/iodide-project/pyodide/issues/431

From [1] https://jupytext.readthedocs.io/en/latest/formats.html#the-percent-format :

*****

### The `percent` format

The `percent` format is a representation of Jupyter notebooks as scripts, in which all cells are explicitely delimited with a commented double percent sign `# %%`. The `percent` format is currently available for these [languages](https://github.com/mwouts/jupytext/blob/master/jupytext/languages.py).

The format was introduced by Spyder in 2013, and is now supported by many editors, including
- [Spyder IDE](https://docs.spyder-ide.org/editor.html#defining-code-cells),
- [Hydrogen](https://nteract.gitbooks.io/hydrogen/docs/Usage/NotebookFiles.html#notebook-export), a package for Atom,
- [VS
Code](https://code.visualstudio.com/docs/python/jupyter-support-py#_jupyter-code-cells),
- [Python Tools for Visual Studio](https://docs.microsoft.com/en-us/visualstudio/python/python-interactive-repl-in-visual-studio?view=vs-2019#work-with-code-cells),
- and [PyCharm Professional](https://www.jetbrains.com/help/pycharm/editing-jupyter-notebook-files.html#edit-content).

Our implementation of the `percent` format is as follows: cells can have
- a title
- a cell type (`markdown`, `md` or `raw`, omitted for code cells)
- and cell metadata
like in this example:

```python
# %% Optional title [cell type] key="value"
```

In the `percent` format, our previous example becomes:
```python
# %% [markdown]
# This is a multiline
# Markdown cell

# %% [markdown]
# Another Markdown cell

# %%
# This is a code cell
class A():
def one():
return 1

def two():
return 2
```

In the case of Python scripts, Markdown cells do accept multiline comments:
```python
# %% [markdown]
"""
This is a Markdown cell
that uses multiline comments
"""
```

*****

Whereas pyodide format looks like this:

```python
%% py
import this

%% js
console.log("hello");
```

The percent format looks like this:

```python
# %% [python]
import this

# %%
import this
```

Contributor guide

Open the contributing guide

Research direction

No repository files or tests are named in the issue. Start by comparing the linked percent-format description with the pyodide-format examples and review the linked Pyodide issue. Done requires an agreed compatibility direction and a clearly defined format scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, jupyter, python, wasm
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.