Тетрадь, файлы и терминал

Ячейки и общий документ

Тетрадь состоит из ячеек с Python-кодом и текстовых пояснений. Правки синхронизируются между участниками. Под ячейкой появляются результаты запуска: текст, таблицы, графики или ошибка Python. Номера строк слева от кода включает преподаватель в правилах комнаты («Номера строк в коде»): тогда их видят все. Доступные действия зависят от правил комнаты и состояния замка.

Кнопки запуска подходят и для устройств без клавиатуры. Чтобы продолжить подготовленную тетрадь, загрузите .ipynb в файлы комнаты и откройте его: она станет тетрадью комнаты. Переносятся код, текст и вложенные картинки, сохранённые результаты запуска — нет. Файл тетради можно скачать из панели файлов, но в нём только код и текст ячеек, без результатов.

В комнате может быть несколько тетрадей: каждая — файл .ipynb в панели файлов, новую создаёт «Новая тетрадь». У каждой тетради своё ядро Python: переменные лекции не появляются в семинаре, и считаться они могут одновременно. Точка на вкладке показывает, что ядро этой тетради сейчас занято. Лента версий и восстановление относятся только к основной тетради комнаты, имя которой показано в панели «История»; правки в других тетрадях там не видны.

Что видно под ячейкой

Под ячейкой показываются: текст и трейсбек ошибки, таблицы pandas (включая оформленные df.style), разметка Markdown из display(Markdown(...)), картинки matplotlib и других библиотек, SVG и интерактивные графики plotly. Крупные картинки и графики не лежат в общем документе: они хранятся рядом с комнатой и приезжают отдельным запросом, поэтому тяжёлый график не замедляет набор текста у остальных.

График plotly работает сам по себе: plotly есть в базовом образе, ставить ничего не нужно, и библиотека графиков лежит на самом сервере — интернет в аудитории не требуется. Как и в Jupyter, из нескольких выражений в одной ячейке показывается только последнее; чтобы показать все, допишите .show() к каждому:

import plotly.express as px

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

График можно приближать протяжкой, наводить курсор на точки и включать трассы в легенде; колесо мыши над ним прокручивает тетрадь, а не масштабирует график. Он рисуется в отдельной песочнице внутри страницы — у него нет доступа ни к занятию, ни к сети, поэтому картинка из layout.images по внешнему адресу не загрузится. Очень большой график (больше 12 МБ данных — это сотни тысяч точек) не показывается вовсе: под ячейкой встаёт строка с советом уменьшить число точек или сохранить график в файл через fig.write_html("plot.html").

Выводы, которым нужно исполнить свой JavaScript — bokeh, folium, ipywidgets, altair без картинки, — Colloq не исполняет: вывод ячейки формирует любой, кому разрешён запуск, а он показывается в браузере у всей группы. Вместо пустого места под такой ячейкой появляется строка о том, что вывод интерактивный. Сохраните его в файл (.html) или получите картинку.

Одно ядро на тетрадь

Все ячейки ОДНОЙ тетради используют общую память Python. Выполните подготовку один раз, затем используйте значения в следующих ячейках этой же тетради:

# Подготовка преподавателя
numbers = [2, 4, 6]

# Следующая ячейка той же тетради
sum(numbers) / len(numbers)

Порядок исполнения важнее положения ячейки в тетради. Если переменная не определена, выполните ячейку, где она создаётся. Повторный запуск может повторно записать данные или изменить уже изменённый объект.

Перезапуск ядра стирает переменные этой тетради — у всех, кто в ней работает; соседние тетради занятия он не трогает. Текст тетради и файлы сохраняются. После перезапуска выполняйте подготовительные ячейки заново. Перезагрузка страницы и перезапуск Python — разные операции.

Ядра тетрадей занятия живут в одном контейнере и делят его память и процессор. Личные тетради студентов — исключение: их ядра работают в отдельном контейнере со своим пределом памяти, и GPU занятия им не даётся. Поэтому тяжёлая ячейка в чужом черновике не может унести ядро лекции. Ядро личной тетради, простоявшее без дела полчаса, останавливается само — запустите ячейку, и оно поднимется снова.

Работа с файлами

В панели файлов есть дерево каталогов. Файл можно загрузить с компьютера, открыть и скачать. Создание и редактирование определяются правилами; переименование, перемещение в другую папку и удаление доступны только преподавателю. Один файл — до 50 МБ, все файлы комнаты вместе — до 1 ГБ; владелец сервера меняет эти пределы переменными MAX_UPLOAD_MB и MAX_SESSION_MB. Текстовые файлы можно редактировать совместно.

Python видит рабочие файлы этой комнаты. Используйте относительные пути, чтобы тетрадь оставалась переносимой:

from pathlib import Path

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

Скачанный .ipynb не является резервной копией всех файлов сервера. Перед самостоятельной работой заберите также данные, изображения и другие зависимости кода.

Общий терминал

Терминал исполняет команды в среде комнаты и показывает общую историю вывода. Правило «Запускать код» распространяется и на него. Команда python analysis.py запускает отдельный процесс Python: переменные ноутбука туда автоматически не переходят, а файлы комнаты остаются общими. Кнопка «Запустить» в редакторе файла .py или .sh сохраняет последние правки и выполняет файл в этом же терминале.

Производственный образ имеет защищённую корневую файловую систему, а выход в сеть комнаты по умолчанию закрыт, кроме DNS. Установка пакетов из интернета во время занятия может не работать. Подготовьте библиотеки заранее через выпуск окружения.

Что переживает остановку

Ноутбук, файлы и сохранённые материалы хранятся на диске. Python-память и процессы зависят от жизни ядра. Обновление сервера или согласованная резервная копия останавливают ядра и теряют их память. Если в комнате два часа никого нет и ничего не выполняется, сервер сам останавливает её ядро: переменные пропадут, тетрадь и файлы останутся. Удаление диска сервера уничтожит и файлы, если нет внешней резервной копии.