# Использование среды Jupyter Для исследовательских задач в проекте используется среда [Jupyter](https://jupyter.org/). Т.к. блокноты хранятся в текстовом формате под контролем версий, нужно также дополнение [Jupytext](https://jupytext.readthedocs.io/en/latest/) (как минимум для ручной конвертации блокнотов; см. ниже). Опционально можно использовать дополнение [papermill](https://papermill.readthedocs.io/en/latest/) для простого параметризованного исполнения блокнотов. ## Установка ### Общий порядок **Внимание**: Оптимальный порядок установки и конфигурации Jupyter для работы с проектом неоднозначен. См. обоснование выбранного здесь порядка работы с блокнотами Jupyter и возможные альтернативные варианты в статье [Использование Jupyter с виртуальными окружениями Python](https://asrelo.hashnode.dev/using-jupyter-with-python-virtual-environments-ru). 1. Jupyter и дополнения должны быть установлены в систему, а **не** в виртуальное окружение. При необходимости деактивируйте виртуальное окружение. ```sh deactivate ``` 2. [Установите Jupyter](https://jupyter.org/install) и Jupytext в систему (**не** в виртуальное окружение). ```sh pip install -U notebook jupytext ``` Полная инструкция по установке Jupytext: [Installation — Jupytext documentation](https://jupytext.readthedocs.io/en/latest/install.html). 3. **Опционально**, установите papermill в систему (**не** в виртуальное окружение). ```sh pip install -U papermill ``` Полная инструкция по установке: [Installation - papermill 2.4.0 documentation](https://papermill.readthedocs.io/en/stable/installation.html). 4. Активируйте **виртуальное окружение** повторно. 5. Установите ядро Jupyter, связанное с данным виртуальным окружением, в директорию этого виртуального окружения. Укажите следующее имя ядра: `python3_venv`. ```sh python -m ipykernel --sys-prefix --name python3_venv ``` 6. **Опционально**, **заранее** сохраните в переменную окружения `JUPYTER_PATH` путь к данным Jupyter в виртуальном окружении `` — см. п. 1 в инструкции по использованию. * Windows (PowerShell): ```ps [System.Environment]::SetEnvironmentVariable('JUPYTER_PATH', ";$env:JUPYTER_PATH", 'User') ``` * Windows (cmd): ```bat setx JUPYTER_PATH ";%PATH%;JUPYTER_PATH" ``` * UNIX (sh): ```sh echo 'export JUPYTER_PATH=":$JUPYTER_PATH"' >> ~/.profile ``` **Внимание**: На данном этапе могут отсутствовать пригодные для прямого использования блокноты `.ipynb` (например, если проект развёртывается с нуля). Об использовании спаренных блокнотов и конвертации форматов см. [Использование Jupytext](#использование-jupytext). ### Зависимости *Используемые при работе с Jupyter зависимости — пакеты Python — на данный момент включены в общие зависимости (см. выше), дополнительных действий не требуется.* ## Работа с блокнотами Jupyter ### Jupyter 1. **Если** при выполнении инструкции по установке Вы **не** сохранили в переменную окружения JUPYTER_PATH путь к данным Jupyter в виртуальном окружении, этот путь нужно добавить в переменную окружения сейчас. Добавьте в переменную окружения `JUPYTER_PATH` абсолютный путь (далее обозначаемый ``) `$VIRTUAL_ENV/share/jupyter`, где следует заменить `$VIRTUAL_ENV` на путь к директории, где развёрнуто виртуальное окружение. Для инструментов [`venv`](https://docs.python.org/3/library/venv.html), [`virtualenv`](https://virtualenv.pypa.io/en/stable/) можно просто в активном виртуальном окружении использовать подстановку переменной окружения `VIRTUAL_ENV` (активное виртуальное окружение не повлияет на дальнейшие шаги). * Windows (PowerShell): ```ps $env:JUPYTER_PATH = ";$env:JUPYTER_PATH" ``` * Windows (cmd): ```bat set "JUPYTER_PATH=;%JUPYTER_PATH%" ``` * UNIX (sh): ```sh export JUPYTER_PATH=":$JUPYTER_PATH" ``` 2. Запустите глобальный установленное приложение Jupyter (**не** из виртуального окружения). * Например, запустите Jupyter Notebook: ```sh jupyter notebook ``` Веб-приложение Notebook должно открыться в веб-браузере автоматически. Если этого не произошло, найдите в сообщениях сервера Jupyter строку примерно следующего содержания: [I 08:58:24.417 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/ Откройте веб-браузер и перейдите по ссылке, выведенной в конце указанного сообщения. См. также [документацию Jupyter](https://docs.jupyter.org/en/stable/running.html). 2. Используйте приложение для навигации по файловой системе (в частности, по каталогу `eda/`), редактирования и исполнения кода в блокнотах. 3. Если приложение Jupyter запрашивает **выбор ядра** Jupyter (**kernel**) или Вы сталкиваетесь с необъяснимыми **ошибками импортов**, выберите для текущего блокнота ядро с именем `python3_venv`. * **Jupyter Notebook**: Может понадобиться выбор вручную; кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу веб-страницы. ### Расширение Jupyter для Visual Studio Code 1. Запустите Visual Studio Code. 2. Откройте корневую директорию проекта в VS Code (*File* -> *Open Folder...*). 3. Если Вы открыли директорию проекта и VS Code запрашивает выбор автоматически обнаруженного виртуального окружения, согласитесь. 3. **Если** VS Code запрашивает выбор автоматически обнаруженного виртуального окружения, согласитесь. **Иначе** [укажите](https://code.visualstudio.com/docs/python/environments#_working-with-python-interpreters) своё виртуальное окружение самостоятельно. 4. Используйте VS Code с расширением Jupyter для навигации по файловой системе (в частности, по каталогу `eda/`), редактирования и исполнения кода в блокнотах. **Не забывайте** при открытии любого блокнота проверять, что выбрано корректное ядро Jupyter (принадлежащее корректному виртуальному окружению). (Кнопка для выбора ядра для открытого блокнота находится в верхнем правом углу области содержимого вкладки; по умолчанию Вы увидите название выбранного виртуального окружения; если ядро не выбрано, на кнопке написано *Select Kernel*.) ### Использование Jupytext Описанные ниже команды `jupytext` используют глобальной установленный экземпляр Jupytext (однако его можно запускать и изнутри виртуального окружения). Для автоматической синхронизации связанных блокнотов (включая создание блокнотов отсутствующих, но ожидаемых форматов): ```sh jupytext --sync eda/cars_eda.py ``` Jupytext довольно удобно работает в оригинальной среде Jupyter, синхронизируя изменения связанных файлов на лету при работе в Jupyter, **ориентируясь на метки времени на файлах**. См. документацию [Jupytext](https://jupytext.readthedocs.io/en/latest/index.html). **Внимание**: С расширением Jupyter для Visual Studio Code Jupytext **не работает напрямую**. Для использования блокнотов `.ipynb` с расширением Jupyter для VS Code нужно синхронизировать текстовый файл под контролем версий и файл `.ipynb` вручную указанными выше командами. Однако заметьте, что это же расширение может исполнять блокнот в текстовом формате самостоятельно, посредством автоматизированного ведения временного блокнота; и оно даже автоматически создаёт/подхватывает локальное ядро Jupyter в виртуальном окружении.