Jupyter Notebook — прекрасный инструмент для исследовательской работы. Автоматическое форматирование LaTeX формул, структурированная логика в ячейках, результаты выполнения прямо в документе — всё это делает ноутбуки идеальными для презентации результатов анализа данных, обучения и демонстраций. Что может быть лучше?
Однако наличествуют проблемы.
Проблемы
Отладка: по сравнению с обычными Python-скриптами одновременно и проще, и сложнее. Но в основном — сложнее. С одной стороны, можно пошагово выполнять ячейки, что удобно. С другой — debugger-инструменты в редакторах вроде VSCode плохо работают с .ipynb файлами. Сами ноутбуки имеют тенденцию разрастаться, и при классической отладке приходится прогонять весь сценарий от начала до конца, что занимает время.
Проблема с LLM: да, уже сентябрь 2025 года, а это всё еще актуально. Современные AI-ассистенты испытывают сложности с ноутбуками по нескольким причинам:
ИИ предпочитают создавать тестовые .py скрипты для отладки вместо работы с ячейками.
Выводы ячеек (особенно картинки) кодируются в base64, что создает огромное количество "мусорных" токенов в контексте.
JSON-структура .ipynb файлов менее читаема для AI, чем обычный Python код.
А ещё я сталкивался с странным багом Сursor, когда AI "видят" изнутри кэша ячейку, которой уже нет в документе. Или записывает ячейку неведомо куда и отчитывается о проделанной работе. Куча хлопот с этими ячейками!
Эти проблемы проявляются у разных LLM: я тестировал на Cursor с Claude Sonnet 4, Grok Code Fast 1 и GPT5.
Решение
А решение, на самом деле, очевидно. Если нам нравятся ноутбуки, но неудобно с ними работать напрямую — давайте писать обычный Python код и автоматически превращать его в красивые ноутбуки.
Хорошо задокументированный .py файл содержит всё необходимое: комментарии можно превратить в markdown ячейки, блоки кода — в code ячейки. С таким подходом и отладчик работает нормально, и LLM не испытывают проблем, и структура кода остаётся читаемой.
Осталось найти инструмент, который бы это делал элегантно. Ну или написать свой, если готовых решений не найдётся.
Обзор инструментов
Jupytext
Первым в очереди на тестирование оказался популярный jupytext. Протестировав его на своих файлах, я обнаружил маленький недостаток: он не создает markdown ячеек. Мой python-скрипт оказался просто нарезан на блоки, и каждый блок был помещен в собственную python-ячейку, в том числе многострочные комментарии с LaTeX-формулами и описанием механики.
А как же LaTeX формулы? Зачем мне ipynb без математических формул?
Оказалось, что всё же можно получить через jupytext markdown. Для этого надо написать так:
# + [markdown] # # Заголовок ноутбука # # Это вводный текст в markdown ячейке. Здесь можно писать с форматированием, списками и т.д. # + # Это ячейка с кодом Python print("Hello, world!") # + [markdown] # ## Подзаголовок # # Еще один текстовый блок markdown с **жирным** текстом и списком: # - пункт 1 # - пункт 2 # + # Еще одна кодовая ячейка for i in range(3): print(i)
Удобно? Ну... so-so, как говорят британцы. Самым большим недостатком в моих глазах здесь является даже не принуждение к явной разметке + [markdown], а отсутствие возможности поместить содержимое markdown-ячейки в многострочный комментарий. Нет ничего сложного в том, чтобы сказать LLM оформлять будущие ячейки именно так, но довольно дико копировать это содержимое туда-сюда между файлами свободно, а в Python начинать расставлять символы # в начале каждой строки. А копировать приходится. У нас тут всё же наука, как-никак!
И, если честно, явная разметка файлов тоже немножко раздражает. Не хочется всё время думать о ней.
ipynb_generator, p2j, py2nb
Поискав в интернете ещё немного, находим несколько библиотек.
Ipynb_generator — её порекомендовал мне Perplexity — вообще не то, поскольку генерирует ipynb из markdown, а не python файла.
p2j — та же проблема с комментариями, что и у jupytext, только хуже. Определил как ячейку markdown все комментарии в файле вообще, и поломал tex-верстку формул.
py2nb — выглядел самым перспективным, пока не оказалось, что он точно так же не умеет правильно конвертировать ячейку markdown в python-комментарий.
py2notebook-ai — отличная попытка, но я не хочу вносить дополнительную сложность в свою работу, интегрируя искусственный интеллект в простенький инструмент.
Как гласит народная мудрость: если хочешь, чтобы что-то было сделано хорошо — сделай это сам!
Встречайте - py2jupyter!
Установить просто:
pip install py2jupyter
Пользоваться тоже просто:
py2jupyter input.py # создаст input.ipynb py2jupyter notebook.ipynb # создаст notebook.py.
Программа сама определяет направление конвертации по расширению файла.
Основные возможности
Двунаправленная конвертация: py ↔ ipynb с сохранением структуры кода. Можете спокойно работать в любом направлении - от Python к ноутбуку для презентации результатов, от ноутбука к Python для отладки.
Автоматическое распознавание markdown: многострочные комментарии """...""" становятся markdown ячейками. Можете писать LaTeX формулы, списки, заголовки - всё будет корректно отображаться в ноутбуке.
Структурирование кода: каждая функция и класс попадают в отдельную ячейку.
Многофайловое слияние: можете объединить несколько Python файлов в один ноутбук или наоборот - разложить большой ноутбук на модули. Супер-удобная фича, которой я не нашел в других инструментах: помните, как мы говорили про неудобство отладки больших файлов? Теперь при отладке мы их разделяем на короткие скрипты, а для демонстрации в виде ноутбука - объединяем.
Взаимообратимость: цикл py → ipynb → py не ломает код (и не изменяет его, если код был оформлен правильно).
Идеология работы с комментариями
Здесь кроется главная изюминка инструмента. Вместо того чтобы заставлять вас изучать специальный синтаксис разметки (как в jupytext), py2jupyter использует естественные конструкции Python.
Многострочные комментарии - это ваши будущие markdown ячейки:
""" Это описание алгоритма станет красивой markdown ячейкой. Можно использовать **жирный текст**, списки и LaTeX формулы: $E = mc^2$ """ r""" А этот блок содержит символы обратного слеша: \alpha, \beta При обратной конвертации автоматически получит префикс r """
Заголовочные комментарии для структурирования больших скриптов:
""" # Численные методы решения ОДУ # """
Становится заголовком первого уровня в ноутбуке.
Обычные комментарии # текст остаются комментариями - никаких сюрпризов.
Docstring'и внутри функций остаются частью кода - это важно для сохранения документации API.
Практические примеры
Допустим, у вас есть такой Python файл:
""" # Анализ данных о продажах # """ """ В этом скрипте мы проанализируем данные о продажах за последний квартал. Используем библиотеки pandas и matplotlib для визуализации. """ import pandas as pd import matplotlib.pyplot as plt def load_sales_data(filename): """Загружает данные о продажах из CSV файла""" return pd.read_csv(filename) def analyze_monthly_trends(df): """Анализирует месячные тренды продаж""" monthly_sales = df.groupby('month')['amount'].sum() return monthly_sales """ Теперь загрузим данные и построим график тренда: """ # Загружаем данные sales_df = load_sales_data('sales.csv') # Анализируем тренды trends = analyze_monthly_trends(sales_df) # Строим график plt.figure(figsize=(10, 6)) trends.plot(kind='bar') plt.title('Продажи по месяцам') plt.show()
После конвертации получается ноутбук с:
Заголовком первого уровня
Markdown ячейкой с описанием
Ячейкой с импортами
Отдельными ячейками для каждой функции
Markdown ячейкой с пояснением к коду
Ячейкой с исполняемым кодом
Magic и shell команды
Отдельно стоит упомянуть поддержку Jupyter magic команд. В Python файле пишете:
#> %matplotlib inline #> !pip install seaborn
В ноутбуке это становится полноценными magic и shell ячейками. При обратной конвертации всё возвращается на свои места.
Полная документация доступна через py2jupyter --help.
Оформление кода
Как вы уже поняли, инструмент предполагает обертывание описательных комментариев для создания ячейки md в тройные кавычки:
# Вместо такого комментария # который займет несколько строк # и будет выглядеть не очень # Напишите так: """ Комментарий который станет красивой markdown ячейкой с поддержкой LaTeX формул: $\sum_{i=1}^n x_i$ """
Что бы не делать это самим, скачайте в свой проект правила оформления и скажите своей LLM сделать всё за вас!
Заключение
py2jupyter - это попытка решить надоевшую проблему простым и понятным способом. Инструмент не претендует на революционность, а просто берет естественные конструкции Python и интерпретирует их здравым смыслом.
Лично я использую его ежедневно для семинаров и отчетов уже примерно два месяца, но только сейчас допилил до стадии, что бы было не стыдно поделиться с вами.
Исходный код лежит на GitHub. Если найдете баги или у вас есть идеи по улучшению — добро пожаловать в issues. Пул-реквесты тоже принимаются. Если понравится — поставьте звездочку, это мотивирует дальше развивать проект!
