Содержание
Памятка по комментированию кода в Jupyter
- Используйте # для однострочных комментариев.
- Для многострочных комментариев применяйте тройные кавычки.
- Шорткат Ctrl + / комментирует выделенные строки.
- Переключайте ячейки в Markdown для отключения выполнения.
- Используйте %%script false для пропуска целой ячейки.
- Не путайте комментарии с docstring.
- Комментарии улучшают читаемость кода.
- Избегайте очевидных комментариев.
- Проверяйте комментарии при экспорте в HTML или PDF.
- Используйте магию %history для просмотра закомментированного кода.
Основные команды
Быстро получить доступ к сочетаниям клавиш можно с помощью комбинаций Ctrl+Shift+P или Cmd+Shift+P, тогда откроется диалоговое окно, похожее на Spotlight Search на Mac. Это поможет вам запустить любую команду по имени, что очень удобно, когда ещё не знаешь нужного сочетания клавиш.
Esc переводит в командный режим. Он позволяет перемещаться по документу с помощью клавиш-стрелок.
- А, чтобы вставить новую ячейку над текущей ячейкой;
- B, чтобы вставить новую ячейку под текущей ячейки;
- M, чтобы изменить текущую ячейку на Markdown;
- Y, чтобы перейти обратно в кодовую ячейку;
- D+D (двойное нажатие клавиши), чтобы удалить текущую ячейку;
- Enter, чтобы вернуться из командного режима в режим редактирования.
Shift+Tab — покажет документацию для объекта, который вы только что ввели в ячейку кода. Для переключения между несколькими режимами продолжайте нажимать это сочетание клавиш.Esc+F — поможет найти и заменить информацию в коде (кроме выходных данных).Esc+0 — переключает вывод ячейки.Shift+J (или Shift+Down) — выделяет ячейки ниже текущей. Shift+K (или Shift+Up) выделяет ячейки выше текущей. Как только ячейки выбраны, их можно удалить/скопировать/вырезать/вставить/запустить как пакет. Это удобно, когда нужно переместить только часть документа.Shift+M — позволяет объединить несколько ячеек.
Кроме того, в документе можно запускать bash-команды, если в начале поставить восклицательный знак:
Чтобы отключить отображение результата выражения в последней строчке ячейки, добавьте в конце последней строчки точку с запятой (;).
Вставка кода
Данная команда возьмёт файл basic_imports.py и загрузит его в ваш документ.
Сохранение и повторное использование кода
Теперь, чтобы определить макрос, нужен код для использования. Можно сохранить практически всё, от строки до функции.
Для настройки макроса используется магия %macro и %load. Обычно принято имена макросов начинать с двойного подчеркивания, чтобы отличать их от других переменных.
Магия %macro принимает имя и номер ячейки (или несколько номеров), а специальный ключ -q делает магию менее подробной. %store позволяет сохранить любую переменную для использования в других сессиях. В коде выше передаётся имя созданного макроса, чтобы можно было использовать его снова после выключения ядра или в других документах.
Это работает, потому что макросы выполняют сохраненный код в пространстве имён ячейки. Если name будет не определено, вы получите ошибку.
Если вы хотите использовать один и тот же макрос во всех своих документах, в этом может помочь %store.
%store позволяет хранить макрос и использовать его во всех Jupyter Notebook.
Настройка среды разработки
Можно легко управлять переменными среды вашего документа с помощью %env без перезагрузок. Выполните эту команду без каких-либо переменных, она отобразит все ваши переменные среды.
LaTex
Вы можете писать на LaTex в Markdown-ячейках, и они будет отображены в виде формулы.
Отображение данных из всех ячеек
По умолчанию отображается только последний вывод в ячейке. Для всего остального необходимо вручную добавить print(). Такой вариант хорош, но не очень удобен. Можно изменить это, добавив вверху документа следующее:
Изменение настроек следует запускать в отдельной ячейке, чтобы оно вступило в силу при следующем запуске ячейки.
Расширения
В этом репозитории можно узнать больше о расширениях, об их включении в ваш документ и исключении из него.
Для работы просто нажмите «Nbextensions» в верхней части экрана, выберите интересующее вас расширение, а затем прокрутите вниз, чтобы найти нужную информацию.
Магия
Магия — это удобные команды, которые облегчают жизнь, когда вы хотите выполнить определённые задачи. Они часто выглядят как команды Unix, но все они реализованы на Python.
Есть два вида магии: строчная магия (применяется к одной строке) и магия ячейки (применяется ко всей ячейке). Строчная магия начинается с символа процента (%), а магия ячейки — с двух таких символов (%%).
Магия run
%run выполнит ваш код и отобразит любые выводные данные, включая графики Matplotlib. Таким образом можно выполнять даже целые документы. Также %run может выполнить код Python из файлов.py.
Магия pycat
Автосохранение
%autosave определяет, как часто ваш документ будет автоматически сохранять контрольные точки в файл.
После данной команды автосохранение будет происходить каждые 60 секунд.
Отображение графиков
Эта команда отобразит графики Matplotlib прямо в выводе ячейки. Это означает, что диаграммы и графики Matplotlib можно включать прямо в свои документы. Имеет смысл запустить команду в начале вашего документа, прямо в первой ячейке.
Измерение времени
Для измерения времени используются две магические команды IPython: %%time и %timeit. Они очень полезны, когда ваш код медленно выполняется и вы пытаетесь определить, в чём проблема. Они обе имеют как строковый режим, так и режим запуска из ячейки.
Основное различие между %timeit и %time состоит в том, что первая выполняет указанный код много раз и вычисляет среднее значение.
%%timeit использует Python-модуль timeit, который выполняет выражение множество раз, а затем выдаёт среднее значение результатов. Вы можете указать количество запусков с помощью опции -n, количество повторов с помощью -r и т. д.
Запуск кода из другого ядра
Можно запустить выполнение ячейки с использованием указанного языка. Существуют расширения для нескольких языков. Есть опции вроде:
- %%HTML,
- %%python,
- %%python2,
- %%python3,
- %%ruby,
- %%perl,
- %%capture,
- %%javascript,
- %%js,
- %%latex,
- %%markdown,
- %%pypy.
Например, для рендеринга HTML в вашем документе вы должны выполнить следующее:
Магия who
Команда %who без аргументов выводит список всех переменных, существующих в глобальной области видимости. При передаче параметра, например str, будут перечислены только переменные этого типа:
Магия prun
%prun показывает, сколько времени ваша программа потратила на каждую функцию. Использование %prun statement_name даёт упорядоченную таблицу, показывающую, сколько раз каждая внутренняя функция была вызвана в блоке. А также время, которое потребовалось на каждый вызов, и суммарное время всех запусков функции.
Магия отладчика в Python
Jupyter имеет собственный интерфейс для отладчика Python. Это позволяет заглянуть внутрь функции и посмотреть, что там происходит. Включить эту магию можно, запустив %pdb в начале ячейки.
Графики высокого разрешения
Одна простая магическая строка IPython может предоставит вам на выводе график с двойным разрешением для экранов Retina. Стоит отметить, что на других экранах график может не отображаться.
Пропуск ячейки для выполнения
%%script false Можете поместить здесь длинный код, который вхотите исключить из выполнения прямо сейчас
Оповещения
Оповещения могут пригодиться, когда вы запускаете код, требующий долгого выполнения. Вы можете настроить уведомление, которое будет отправлено, когда код выполнится.
На Windows
Чтобы использовать такое оповещение, у вас должен быть установлен sox. Установить его можно с помощью следующей строки:
О том, что такое Jupyter Notebook¶
В ноутбуке есть интерактивный контент, в связи с чем его рекомендуется просматривать его в jupyter notebook/lab.
2⋅1052⋅105 2⋅105 2⋅105 2⋅105 2⋅105 2 ⋅ 105 105 10 10 5 5 2⋅105 2.5⋅1062.5⋅106 2.5⋅106 2.5⋅106 2.5⋅106 2.5⋅106 2.5 ⋅ 106 106 10 10 6 6 2.5⋅106
«Why Jupyter is data scientists’ computational notebook of choice» — статья с таким заголовком вышла в октябрьском номере Nature в 2018 году. Она посвящена Jupyter Notebook — опенсорсному веб-приложению для интерактивной разработки, которое за последние несколько лет покорило сердца миллионов и стало де-факто стандартом в аналитике, науке о данных, машинном обучении и много где ещё. Количество.ipynb-файлов на GitHub выросло с в 2015 году до в 2018. Ниже мы разберём основные причины такой взрывной популярности:
Лабораторный журнал 21 века¶
Работа аналитика или учёного отличается от индустриальной разработки отсутствием чёткого техзадания. В этих сферах правильная постановка задачи это уже половина решения. На начальную фазу — тщательный анализ исходных данных (exploratory data analysis (EDA)) и последующую постановку гипотез — уходит много времени. Как следствие, до самого конца неясно, как организовать процесс разработки: что в итоге важно, а о чём можно будет забыть. В таких условиях тратить силы на скурпулёзное написание кода бессмысленно — на первый план выходит умение быстро прототипировать, ставить эксперименты. Кроме того, свои результаты приходится постоянно презентовать как коллегам, там и заказчику или начальству. Jupyter Notebook убивает этих двух зайцев одним выстрелом:
По своей сути Jupyter это интерактивный лабораторный журнал: он позволяет создавать отчёт с помощью markdown с формулами из latex, писать и запускать в нем код, дополнять отчет иллюстрациями, в том числе интерактивными, пересчитывать всё на лету и обмениваться результатами в читаемом формате. Это дало новую жизнь парадигме reproducible research — в формате.ipynb или R-Markdown пишут статьи и даже книги, где заинтересованный читатель может сразу же воспроизводить описанные результаты. Автор не уверен, что впечатляет его больше — потенциальный полёт человечества к Юпитеру или то, насколько более демократичной Jupyter Notebook сделал высокую науку. Которая, к слову, страдает от того, что 70% учёных не смогли воспроизвести чужие результаты, а ещё 50% — свои согласно опросу в Nature.
Нелинейная последовательность исполнения¶
Jupyter позволяет запускать клетки с кодом в произвольном порядке и, в отличие от IPython, в нём это делать удобно. Конечно, это повышает требования к разработчику, который должен помнить, какая конкретно последовательность ячеек решает задачу, и провоцирует писать очень плохой код, но в реалиях, когда полный перезапуск пайплайна требует нескольких часов на суперкомпьютере, это не прихоть, а необходимость.
Вавилонская башня от программирования¶
Вопреки расхожему мнению, Jupyter поддерживает не только Julia, Python и R (Ju-Py-teR, именно потому), но более 40 языков, включая C++, да-да, компилируемый язык, check it out. Более того, для того, чтобы писать код на нескольких языках одновременно, обычно это Bash, Python и R, не нужно создавать разные ноутбуки. Это инструмент, который не ограничивает возможности разработчика.
Переносимость и платформонезависимость¶
Jupyter позволяет развернуть дружелюбный интерфейс на любой удалённой машине, от учебного сервера до гигантской распределённой map-reduce сети. Учитывая, что работать с данными на своём ноутбуке почти никогда не приходится, что либо нельзя контракту, либо в оперативку не влезает, возможность оставить в прошлом сумрачную серверную консоль многие восприняли с облегчением. В сочетании с инструментами в духе conda, jupyter позволяет развернуть привычное и настроенное под себя окружение, не задумываясь о том, с каким железом и в какой системе приходится работать. Более того, Jupyter Hub позволяет создать точку входа, через которую над проектом могут совместно работать несколько человек. Это позволяет специалисту настроить окружение один раз, после чего им смогут пользоваться сотни человек. Неудивительно, что многие онлайн-курсы переходят на формат jupyter-ноутбуков.
Основы¶
Установка всего необходимого в conda-env обсуждалась в прошлом ноутбуке. Для того, чтобы поднять jupyter-сервер, активируйте conda-env и наберите в терминале:
Когда вы откроете jupyter-ноутбук, в меню Help можно будет найти интерактивные вводные руководства. Советуем ознакомиться с ними, если интерфейс вам вновинку.
- code — собственно, код;
- markdown — текст с формулами на latex (в одинарных или двойных $);
- raw — неформатированный текст.
Изменить тип можно либо в меню (Cell —> Cell Type), либо с помощью клавиатурных сокращений (см. ниже). В целом, базовый интерфейс довольно интуитивный, в нём полезно разобраться самостоятельно.
Плагины¶
Встроенный редактор довольно удобный, но с плагинами он становится по-настоящему хорош. Установка библиотеки jupyter_contrib_nbextensions, которая отвечает за поддержку плагинов, освещалась в прошлом ноутбуке. Давайте разберёмся, какие плагины из стандартного списка наиболее полезны:
- Ruler — отображает красным границу в 80 символов в строке. Этот плагин нужно поставить обязательно, чтобы не расстраивать проверяющих тем, что при конвертации в pdf у вас опять что-то не влезло в одну строку.
- Codefolding, Codefolding in editor — незаменимый плагин, который позволяет сворачивать код для лучшей читаемости.
- ExecuteTime — автоматически запоминает, когда ячейка начала выполняться и сколько времени это заняло.
- Notify — посылает push-уведомление в браузере, когда ячейка закончила выполняться. Если она отрабатывала достаточно долго.
- Move selected cells — позволяет одновременно перемещать выделенные ячейки вверх или вниз.
- Limit Output — ограничивает размер вывода ячейки. С этим плагином всё не упадёт, если из-за ошибки в коде вы решите распечатать многогигабайтную таблицу прямо в окошке браузера, что бывает чаще, чем хотелось бы.
Этим список плагинов не исчерпывается, остальные можете выбрать на свой вкус.
Command mode¶
В jupyter есть command mode — режим, где можно вводить команды для быстрого редактирования текста. Как и в vim, из которого эта концепция была позаимствована, его можно активировать кнопкой Esc, после чего возможны варианты. Esc + h откроет справку:
В ней перечислено много команд, из которых чаще всего используются такие:
- Esc + I — прервать исполнение;
- Esc + 0 — перезапустить ядро;
- Esc + D + D — удалить все выделенные ячейки (включая текущую);
- Esc + Z — отменить удаление ячеек;
- Esc + C — скопировать выделенные ячейки;
- Esc + X — вырезать выделенные ячейки;
- Esc + V — вставить ранее скопированные ячейки;
- Esc + A — вставить ячейку выше;
- Esc + B — вставить ячейку ниже;
- Esc + Shift + M — объединить выделенные ячейки (или текущую ячейку с нижней);
- Esc + M — заменить код на markdown;
- Esc + Y — наоборот, markdown —> код.
Edit mode¶
Эти сокращения доступны в редакторе. Здесь всё стандартно. Если вы не привыкли пользоваться такими сокращениями, то настоятельно рекомендуем потратить время и научиться: это сэкономит вам много времени в будущем.
- Ctrl + / — закомментировать строку;
- Ctrl + D — удалить строку;
- Ctrl + ↑ — перейти к началу ячейки;
- Ctrl + ↓ — перейти к концу ячейки;
- Ctrl + Shift + — — разбить ячейку по текущей строке;
- Shift + ↑↓ — выделить ячейку выше/ниже текущей;
- Ctrl + Enter — запустить выделенные ячейки;
- Shift + Enter — запустить ячейку и перейти на одну ниже, что удобно, когда последовательно запускаете сразу много.
Магия Jupyter¶
jupyter magics — метаязык, команды которого обычно начинаются с % или %%.Работают они или нет — зависит от реализации. Стандартные jupyter-magics поставляются с ядром IPython. Для других языков или ядер набор команд может быть другим.
Available line magics: %alias %alias_magic %autoawait %autocall %automagic %autosave %bookmark %cat %cd %clear %colors %conda %config %connect_info %cp %debug %dhist %dirs %doctest_mode %ed %edit %env %gui %hist %history %killbgscripts %ldir %less %lf %lk %ll %load %load_ext %loadpy %logoff %logon %logstart %logstate %logstop %ls %lsmagic %lx %macro %magic %man %matplotlib %mkdir %more %mv %notebook %page %pastebin %pdb %pdef %pdoc %pfile %pinfo %pinfo2 %pip %popd %pprint %precision %prun %psearch %psource %pushd %pwd %pycat %pylab %qtconsole %quickref %recall %rehashx %reload_ext %rep %rerun %reset %reset_selective %rm %rmdir %run %save %sc %set_env %store %sx %system %tb %time %timeit %unalias %unload_ext %who %who_ls %whos %xdel %xmode Available cell magics: %%! %%HTML %%SVG %%bash %%capture %%debug %%file %%html %%javascript %%js %%latex %%markdown %%perl %%prun %%pypy %%python %%python2 %%python3 %%ruby %%script %%sh %%svg %%sx %%system %%time %%timeit %%writefile Automagic is ON, % prefix IS NOT needed for line magics.
А если вы хотите почитать краткую справку по IPython, используйте команду
Видно, что команды делятся на два типа: line magics и cell magics. Как следует из названия, разница между ними в том, что cell magics влияют на состояние всей ячейки, и работают только если написаны в самом её начале, в то время как line magics могут быть написаны в любом месте и либо влияют на строку с кодом, скажем, замеряют время исполнения, как %timeit, либо выполняют какую-то системную команду (как %ls). Если вы забыли, что делает конкретная команда, то добавьте перед ней знак вопроса — откроется справка.
К слову, таким же образом можно вызвать справку для произвольной функции. Синтаксис привычен тем, кто работал с R:
%load_ext, %autoreload¶
%load_ext позволяет загружать сторонние модули (например, Cython). Нам важно, что с её помощью можно активировать самую важную команду — %autoreload. Без неё вам пришлось бы перезапускать ядро каждый раз, когда вы меняете библиотеки со своим кодом. autoreload делает это за вас, в больших проектах это незаменимо.
%load_ext autoreload # здесь 2 означает, что все библиотеки будут подгружаться заново, # если только явно не указано иное %autoreload 2 import jupyter_lesson
%matplotlib¶
Скорее всего, эту команду вам придётся писать в начале каждого домашнего задания. Она определяет, каким образом будут отображаться ваши графики. Есть два основных варианта: inline и notebook. Разберёмся, в чём между ними разница:
Видно, что открылось интерактивное окошко, в котором можно масштабировать участки графика по своему усмотрению. Это удобно, когда хочется рассмотреть детали, но требовательно к ресурсам при сложных визуализациях. А ещё работает не всегда.
В этом режиме в ноутбук просто вставляется статическая картинка. Именно этим режимом вы будете пользоваться чаще всего.
%time, %timeit, %%time¶
Эти три команды замеряют, как долго исполняется код. Коменда %timeit запускает команду несколько раз. По результатам вычисляется среднее и стандартное отклонение. Это уместно, если функция зависит от случайных битов. Для примера напишем функцию, которая генерирует случайное число и засыпает на одну секунду, если оно нечётное.
import time import numpy as np def sleep_if_odd(): rvs = (low=0, high=int(1e9)) randbit = rvs % 2 if randbit % 2 == 1: (1)
При использовании %timeit можно указать, сколько раз нужно запустить функцию. Синтаксис — %timeit -n Дефолтное значение — 7.
Видно, что только результаты %timeit отражают реальное поведение функции. Это стоит иметь в виду при тестировании кода.
%system, %%bash¶
%%bash for word in {‘IPython’, ‘and’, ‘bash’ ‘are’, ‘friends!’} do echo $word done
Часто задаваемые вопросы о комментировании строк в Jupyter
Вопрос: Как закомментировать одну строку в Jupyter Notebook?
Ответ: Используйте символ # в начале строки.
Вопрос: Какой шорткат для комментирования нескольких строк?
Ответ: Выделите строки и нажмите Ctrl + / (Cmd + / на Mac).
Вопрос: Работает ли Ctrl + / в режиме редактирования?
Ответ: Да, шорткат работает только в режиме редактирования (Edit mode).
Вопрос: Как закомментировать блок кода в Python?
Ответ: Используйте тройные кавычки »’ или «»» для многострочного комментария.
Вопрос: Чем отличается комментарий от docstring?
Ответ: Docstring — это строка документации, а комментарий игнорируется интерпретатором.
Вопрос: Можно ли комментировать ячейки в Jupyter?
Ответ: Ячейки можно переключить в Markdown, чтобы они не выполнялись как код.
Вопрос: Как временно отключить выполнение ячейки?
Ответ: Превратите ячейку в Markdown или закомментируйте весь код внутри неё.
Вопрос: Есть ли магия для комментирования?
Ответ: Нет, но можно использовать %%script false для пропуска выполнения ячейки.
Вопрос: Как закомментировать строку с помощью магии?
Ответ: Магия не предназначена для комментирования, используйте #.
Вопрос: Почему комментарии не сохраняются при экспорте?
Ответ: Комментарии сохраняются, проверьте настройки экспорта.
