# Справка для AI: Инструмент py2jupyter

Этот документ содержит инструкции для нейросетей по работе с конвертером Python ↔ Jupyter Notebook.

## Обзор инструмента

py2jupyter - это двунаправленный конвертер между Python файлами и Jupyter ноутбуками, который:
- Структурирует код по ячейкам
- Преобразует комментарии в markdown ячейки
- Поддерживает многофайловое слияние
- Обеспечивает взаимообратимость конвертации

## Спецификация написания Python кода

### 1. Заголовки и разделы

```python
""" # Заголовок раздела # """
```

**Правила:**
- Заключен в тройные кавычки с пробелами: `""" # текст # """`
- Можно использовать префикс `r` если нужен: `r""" # текст # """`
- Становится markdown ячейкой с содержанием `# Заголовок раздела #`
- Используется для четкого структурирования больших скриптов
- **Важно**: обычные Python комментарии `# текст` остаются комментариями!

### 2. Описательные блоки

```python
# С LaTeX формулами
r"""
Подробное описание с математикой.
Формула: $E = mc^2$
Интеграл: $\int_0^1 x dx = \frac{1}{2}$
"""

# Простое описание
"""
Обычное описание без специальных символов.
Может содержать списки, жирный текст и другие элементы markdown.
"""
```

**Правила:**
- Поддерживаются как `r"""..."""`, так и `"""..."""`
- При обратной конвертации префикс `r` **автоматически добавляется** при наличии `\` символов
- Тройные кавычки на отдельных строках
- Становится markdown ячейкой
- Поддерживает полный синтаксис Markdown

### 3. Структурирование функций и классов

```python
def calculate_something(param1, param2):
    """Обычная docstring - остается в коде"""
    return param1 + param2

class DataProcessor:
    """Класс для обработки данных"""
    
    def __init__(self, data):
        self.data = data
```

**Правила:**
- Функции и классы верхнего уровня → отдельные ячейки
- **Docstring'и внутри функций/классов остаются частью кода** (важно!)
- Вложенные функции остаются в одной ячейке с родительской

**Важное различие:**
```python
# Это КОММЕНТАРИЙ - станет markdown ячейкой
"""
Описание алгоритма вне функции
"""

def my_function():
    """Это DOCSTRING - останется в коде"""
    return "result"
```

### 4. Обычный код и комментарии

```python
# Обычные Python комментарии остаются как есть
import numpy as np
import matplotlib.pyplot as plt

# Инициализация переменных - это тоже обычный комментарий
x = np.linspace(0, 10, 100)
y = np.sin(x)

# Этот комментарий НЕ станет markdown ячейкой
result = x + y  # И этот тоже останется обычным комментарием
```

**Правила:**
- **Обычные комментарии `# текст` остаются Python комментариями**
- Только специальные форматы становятся markdown: `""" # заголовок # """` и `"""описание"""`
- Код между структурными элементами группируется в ячейки
- Импорты обычно в отдельной ячейке

## Использование конвертера

### Базовые команды

```bash
# Справка по использованию
python py2jupyter.py --help    # подробная справка с примерами
python py2jupyter.py -h        # то же самое
python py2jupyter.py           # краткая справка

# Одиночная конвертация
python py2jupyter.py script.py                    # → script.ipynb
python py2jupyter.py notebook.ipynb               # → notebook.py
python py2jupyter.py script.py my_notebook.ipynb  # явное имя

# Многофайловое слияние
python py2jupyter.py file1.py file2.py combined.ipynb
python py2jupyter.py nb1.ipynb nb2.ipynb merged.py
```

### Рекомендации для AI

1. **При создании научных скриптов:**
   - Используйте `""" # Заголовок # """` для крупных разделов
   - Описывайте алгоритмы в `"""..."""` блоках (r добавится автоматически)
   - Выносите каждую логическую функцию отдельно
   - Обычные `# комментарии` оставляйте для пояснений кода

2. **При структурировании существующего кода:**
   - Анализируйте логические блоки
   - Добавляйте заголовочные комментарии `""" # раздел # """`
   - Выносите описания алгоритмов в `"""markdown блоки"""`
   - Не трогайте обычные Python комментарии

3. **Для образовательных материалов:**
   - Обильно используйте заголовочные комментарии для навигации
   - Добавляйте формулы LaTeX в описательные блоки
   - Разбивайте сложные функции на этапы

## Примеры конвертации

### До (обычный Python):
```python
import numpy as np
# Алгоритм градиентного спуска - обычный комментарий
"""
Реализация градиентного спуска БЕЗ префикса r.
Теперь этот комментарий ТОЖЕ будет преобразован в markdown!
"""
def gradient_descent(X, y, learning_rate=0.01):
    # Инициализация
    theta = np.zeros(X.shape[1])
    # Итерации
    for i in range(1000):
        gradient = X.T @ (X @ theta - y)
        theta -= learning_rate * gradient
    return theta
```

### После (совместимый с py2jupyter):
```python
""" # Алгоритм машинного обучения # """

import numpy as np

"""
Реализация градиентного спуска для линейной регрессии.

Алгоритм минимизирует функцию потерь:
$J(\theta) = \frac{1}{2m} \sum_{i=1}^{m} (h_\theta(x^{(i)}) - y^{(i)})^2$
"""

def gradient_descent(X, y, learning_rate=0.01, max_iterations=1000):
    """
    Градиентный спуск для линейной регрессии
    
    Args:
        X: матрица признаков
        y: целевые значения
        learning_rate: скорость обучения
        max_iterations: максимальное число итераций
    """
    # Инициализация параметров
    theta = np.zeros(X.shape[1])
    
    # Итеративный процесс обучения
    for iteration in range(max_iterations):
        # Вычисление градиента
        predictions = X @ theta
        errors = predictions - y
        gradient = X.T @ errors / len(y)
        
        # Обновление параметров
        theta -= learning_rate * gradient
        
    return theta

""" # Тестирование алгоритма # """

# Создание тестовых данных
X_test = np.random.randn(100, 3)
y_test = X_test @ [1, 2, 3] + np.random.randn(100) * 0.1

# Обучение модели  
theta_learned = gradient_descent(X_test, y_test)
print(f"Найденные параметры: {theta_learned}")
```

## Лучшие практики

1. **Планирование структуры:**
   - Начинайте с общего заголовка файла
   - Группируйте связанные функции
   - Отделяйте теорию от реализации

2. **Качественные описания:**
   - Объясняйте "почему", а не только "что"
   - Используйте LaTeX для математических формул
   - Добавляйте примеры использования

3. **Читаемый код:**
   - Осмысленные имена переменных
   - Короткие, целенаправленные функции
   - Четкие комментарии для сложной логики

4. **Тестирование конвертации:**
   - Всегда проверяйте полный цикл: py → ipynb → py
   - Убедитесь, что код остается исполняемым
   - Проверяйте корректность отображения формул

## Частые ошибки

❌ **Неправильно:** `## Заголовок ##` (старый формат больше не поддерживается)
✅ **Правильно:** `""" # Заголовок # """`

❌ **Неправильно:** Ожидание что `# обычный комментарий` станет markdown
✅ **Правильно:** Только специальные форматы становятся markdown

❌ **Неправильно:** Ручное добавление `r` префикса везде
✅ **Правильно:** Позволить системе определить это автоматически по наличию `\` 

❌ **Неправильно:** Смешивание логики в одной ячейке
✅ **Правильно:** Четкое разделение по функциональности

💡 **Новая логика:**
- `# комментарий` → остается комментарием
- `""" # заголовок # """` → markdown заголовок
- `"""описание"""` → markdown блок
- Docstring'и остаются в коде
- Пустые строки в начале/конце → автоматически удаляются из code ячеек
- Две пустые строки на нулевом отступе → разделяют код на отдельные ячейки
- `#%magic_command` → code ячейка с magic командой
- `#%shell_command` → code ячейка с shell командой
- Code ячейка только с `%command` → `#%command`
- Code ячейка только с `!command` → `#!command`

## 📋 Дополнительные ресурсы

Для подробных правил оформления Python файлов для конвертации смотрите файл [`PY_FORMAT_RULES.md`](../PY_FORMAT_RULES.md).

Этот инструмент идеально подходит для создания образовательных материалов, научных расчетов и презентации исследований коллегам в интерактивном формате Jupyter.
