Notebook, files and terminal

Cells and the shared document

A notebook is made of Python code cells and text cells. Edits sync between participants. A cell's output appears below it: text, tables, plots or a Python error. Line numbers to the left of the code are turned on by the teacher in the room rules (“Line numbers in code”), and then everyone sees them. What you can do depends on the room rules and the position of the cell's lock.

The run buttons also work on devices without a keyboard. To continue a notebook you prepared earlier, upload the .ipynb to the room's files and open it: it becomes the room's notebook. Code, text and embedded images carry over; saved outputs do not. You can download the notebook file from the Files panel, but it contains only the cells' code and text, without outputs.

A room can have several notebooks: each one is an .ipynb file in the Files panel, and “New notebook” creates another. Every notebook has its own Python kernel: the lecture's variables do not appear in the seminar, and the two can be computing at the same time. A dot on a tab means that notebook's kernel is busy right now. Version history and restore cover only the room's main notebook, whose name is shown in the History panel; edits in other notebooks do not appear there.

What appears under a cell

A cell can show: text and Python tracebacks, pandas tables (styled df.style included), Markdown from display(Markdown(...)), images from matplotlib and other libraries, SVG, and interactive plotly figures. Large images and figures are not kept inside the shared document: they live next to the room and arrive in a separate request, so a heavy chart does not slow down everybody else’s typing.

plotly works out of the box: it is in the base image, nothing has to be installed, and the plotting library is served from this server — no internet is needed in the classroom. As in Jupyter, only the last expression of a cell is shown; to show them all, add .show() to each:

import plotly.express as px

px.histogram(apartments, x="metro_time_min", nbins=28).show()
px.scatter(apartments, x="area_sqm", y="price_rub")

A figure can be zoomed by dragging, hovered for values and filtered through its legend; the mouse wheel over it scrolls the notebook instead of zooming the chart. It is drawn in a sandbox of its own inside the page, with no access to the class and no network at all — so an image referenced from layout.images by URL will not load. A very large figure (over 12 MB of data — hundreds of thousands of points) is not shown: the cell gets a line suggesting fewer points, or saving the figure to a file with fig.write_html("plot.html").

Outputs that need to run their own JavaScript — bokeh, folium, ipywidgets, altair without an image — are not executed: a cell’s output is produced by anyone allowed to run code, and it is rendered in every browser in the class. Instead of empty space, such a cell shows a line saying the output is interactive. Save it to an .html file, or produce an image.

One kernel per notebook

All cells in ONE notebook share the same Python memory. Run the setup once, then use its values in later cells of that same notebook:

# Teacher's setup
numbers = [2, 4, 6]

# A later cell in the same notebook
sum(numbers) / len(numbers)

The order in which cells ran matters more than where they sit in the notebook. If a variable is not defined, run the cell that creates it. Running a cell again may write data a second time or modify an object that has already been modified.

Restarting the kernel wipes that notebook's variables for everyone working in it; the class's other notebooks are untouched. The notebook text and files are kept. After a restart, run the setup cells again. Reloading the page is not the same as restarting Python.

The kernels of a class's notebooks live in one container and share its memory and CPU. Students' personal notebooks are the exception: their kernels run in a separate container with its own memory limit, and they are never given the class's GPU. A heavy cell in somebody's draft therefore cannot take down the lecture's kernel. A personal notebook's kernel that has idled for half an hour stops on its own — run a cell and it comes back.

Working with files

The Files panel shows a folder tree. You can upload a file from your computer, open it and download it. The room rules decide who can create and edit files; only the teacher can rename them, move them to another folder or delete them. A single file can be up to 50 MB, and all files in a room together up to 1 GB; the server owner changes these limits with the MAX_UPLOAD_MB and MAX_SESSION_MB variables. Text files can be edited together.

Python sees this room's working files. Use relative paths so the notebook stays portable:

from pathlib import Path

Path("results").mkdir(exist_ok=True)
Path("results/answer.txt").write_text("42\n", encoding="utf-8")

A downloaded .ipynb is not a backup of every file on the server. Before working on your own, also download the data, images and anything else the code depends on.

Shared terminal

The terminal runs commands in the room's environment and shows a shared output history. The “Run code” rule applies to it too. The command python analysis.py starts a separate Python process: notebook variables do not carry over to it, but the room's files are still shared. The “Run” button in the editor of a .py or .sh file saves your latest edits and runs the file in the same terminal.

In production, the room's root file system is read-only, and the room has no network access by default except DNS. Installing packages from the internet during class may not work. Add the libraries in advance with an environment release.

What survives a stop

The notebook, files and saved materials are stored on disk. Python memory and processes live only as long as the kernel. A server update or a consistent backup stops the kernels, and their memory is lost. If a room has had nobody in it and nothing running for two hours, the server stops its kernel on its own: the variables are lost, the notebook and files stay. Deleting the server's disk destroys the files too, unless you have an off-server backup.