py2jupyter 0.1.0

Конвертер Python ↔ Jupyter Notebook

Конвертер Python ↔ Jupyter Notebook

Этот инструмент автоматически конвертирует Python файлы в Jupyter ноутбуки и наоборот.

✨ Основные возможности

• 🔄 Двунаправленная конвертация: py ↔ ipynb
• 📝 Поддержка markdown: автоматическое распознавание комментариев как markdown ячеек
• 📊 Структурирование кода: функции и классы в отдельных ячейках
• 🔗 Многофайловое слияние: объединение нескольких файлов в один
• ⚡ Взаимообратимость: конвертация туда-обратно сохраняет исходную структуру

Логика конвертации

Python → Jupyter (.py → .ipynb)

1. Заголовочные комментарии """ # заголовок # """ становятся markdown ячейками заголовков
2. Многострочные комментарии r"""...""" и """...""" становятся markdown ячейками
3. Функции и классы становятся отдельными code ячейками
4. Остальной код группируется в code ячейки
5. Docstring'и внутри функций/классов остаются частью кода
6. Обычные Python комментарии # текст остаются обычными комментариями

Jupyter → Python (.ipynb → .py)

1. Markdown ячейки заголовки # заголовок # → заголовочные комментарии """ # заголовок # """
2. Markdown ячейки с \ символами → комментарии с префиксом r"""..."""
3. Обычные markdown ячейки → многострочные комментарии """..."""
4. Code ячейки остаются как обычный Python код
5. Каждая ячейка отделяется пустой строкой
6. Outputs игнорируются

🚀 Использование

Справка

# Подробная справка с примерами
python py2jupyter.py --help
python py2jupyter.py -h

# Краткая справка
python py2jupyter.py

Базовая конвертация

# Python → Jupyter (автоматическое имя выходного файла)
python py2jupyter.py script.py

# Python → Jupyter (указанное имя)
python py2jupyter.py script.py notebook.ipynb

# Python → Jupyter (автоматическое расширение)
python py2jupyter.py script.py output  # → создаст output.ipynb

# Jupyter → Python (автоматическое имя)
python py2jupyter.py notebook.ipynb

# Jupyter → Python (автоматическое расширение)
python py2jupyter.py notebook.ipynb output  # → создаст output.py

Многофайловое слияние

# Объединение нескольких Python файлов в один Notebook
python py2jupyter.py script1.py script2.py script3.py combined.ipynb

# Объединение нескольких Notebook в один Python файл
python py2jupyter.py notebook1.ipynb notebook2.ipynb merged.py

Примечания:

• При многофайловом слиянии выходной файл обязательно должен быть указан
• Если расширение выходного файла не указано, оно определяется автоматически (.py → .ipynb, .ipynb → .py)

📋 Правила оформления

Для правильной конвертации Python файлов в Jupyter ноутбуки следуйте правилам оформления, описанным в файле PY_FORMAT_RULES.md.

📋 Примеры

Входной Python файл:

""" # Моделирование физической системы # """

"""
Этот скрипт демонстрирует расчет энергии.
Формула: $E = \frac{1}{2}mv^2 + \frac{1}{2}kx^2$
"""

#!pip install matplotlib
#%matplotlib inline

import numpy as np
import matplotlib.pyplot as plt

def calculate_energy(x, v, m=1.0, k=100.0):
    """Расчет полной энергии системы (это docstring)"""
    kinetic = 0.5 * m * v**2
    potential = 0.5 * k * x**2
    return kinetic + potential

r"""
Раздел с анализом (содержит \ символы).
Интеграл: $\int_0^1 x^2 dx = \frac{1}{3}$
"""

""" # Параметры системы # """

# Обычный Python комментарий остается как есть
x0 = 0.1  # начальное смещение
v0 = 0.0  # начальная скорость

Результат конвертации в Jupyter:

• Cell 0 (markdown): # Моделирование физической системы #
• Cell 1 (markdown): Описание с LaTeX формулой
• Cell 2 (code): import numpy as np и import matplotlib.pyplot as plt
• Cell 3 (code): %matplotlib inline
• Cell 4 (code): ! pip install seaborn
• Cell 5 (code): Функция calculate_energy с docstring
• Cell 6 (markdown): Раздел с анализом и интегралом
• Cell 7 (markdown): # Параметры системы #
• Cell 8 (code): Комментарии и инициализация переменных

Результат обратной конвертации:

""" # Моделирование физической системы # """

"""
Этот скрипт демонстрирует расчет энергии.
Формула: $E = \frac{1}{2}mv^2 + \frac{1}{2}kx^2$
"""

# ... код функций ...

#%matplotlib inline

#! pip install seaborn

r"""
Раздел с анализом (содержит \ символы).
Интеграл: $\int_0^1 x^2 dx = \frac{1}{3}$
"""

""" # Параметры системы # """

Умное определение префиксов: ячейки с \ символами получают префикс r, остальные - нет

⚙️ Технические особенности

• ✅ UTF-8 кодировка: полная поддержка Unicode
• ✅ Сохранение структуры: функции и классы остаются читаемыми
• ✅ Умное распознавание: автоматическое определение типов ячеек
• ✅ Масштабируемость: работа с большими файлами (1000+ строк)
• ✅ Взаимообратимость: минимальные изменения при полном цикле конвертации
• ✅ Совместимость: поддержка Python 3.7+, адаптация под новые версии AST
• ✅ Автоматические расширения: умное определение .py/.ipynb при отсутствии расширения
• ✅ Заголовочные комментарии: специальный формат """ # заголовок # """ для четких заголовков
• ✅ Умные префиксы: автоматическое определение r на основе наличия \ символов
• ✅ Универсальные комментарии: поддержка как r"""...""", так и обычных """..."""
• ✅ Очистка пустых строк: автоматическое удаление пустых строк в начале и конце code ячеек
• ✅ Разделение по пустым строкам: автоматическое разделение больших блоков кода на меньшие ячейки при наличии двух и более пустых строк подряд (только на уровне нулевого отступа)
• ✅ Поддержка magic команд: автоматическая конвертация между #%command в .py и magic ячейками в .ipynb
• ✅ Поддержка shell команд: автоматическая конвертация между #!command в .py и shell ячейками в .ipynb
• ✅ Встроенная справка: подробная документация через --help с примерами и форматами

🔧 Требования

• Python 3.7+
• Стандартные библиотеки: ast, json, pathlib