# Changelog

Все важные изменения в проекте Fishertools будут документированы в этом файле.

## [0.5.0] - 2026-02-08

### 🎯 Algorithm Expansion & API Unification Release

**Полный набор алгоритмов и унификация API с requests**

#### 🚀 Новые возможности

##### 🔌 Network Module Enhancements
- **requests-Compatible API** - NetworkResponse теперь совместим с requests
  - `.json()` метод - получение JSON данных (как в requests)
  - `.content` свойство - получение сырых байтов
  - `.text` свойство - получение текстового представления
  - Полная обратная совместимость с `.data` атрибутом

- **Timeout Support for Downloads**
  - `safe_download()` теперь принимает параметр `timeout`
  - Контроль времени ожидания для медленных загрузок
  - Валидация timeout параметра (должен быть положительным)
  - Описательные сообщения об ошибках при таймауте

##### 📊 Complete Algorithm Suite (8 алгоритмов)
- **5 Sorting Algorithms:**
  - bubble_sort (существующий)
  - quick_sort - быстрая сортировка с визуализацией разбиения
  - merge_sort - сортировка слиянием с отслеживанием диапазонов
  - insertion_sort - сортировка вставками с подсветкой отсортированной части
  - selection_sort - сортировка выбором с поиском минимума

- **3 Search Algorithms:**
  - binary_search (существующий) - O(log n)
  - linear_search - последовательный поиск O(n)
  - jump_search - блочный поиск O(√n)

- **Final Array Attribute**
  - Прямой доступ к результату через `result.final_array`
  - Автоматическое вычисление из последнего шага
  - Возвращает копию для предотвращения мутаций

##### 🌍 Enhanced Error Explanations
- **Context-Aware Explanations**
  - `explain_error()` теперь принимает параметр `context`
  - Специфичные советы для разных операций:
    - `list_access` - доступ к списку с указанием валидного диапазона
    - `dict_access` - доступ к словарю с перечислением доступных ключей
    - `division` - деление с контекстом операции
    - `concatenation` - конкатенация с информацией о типах
  - Упоминание имен переменных в объяснениях
  - Операционно-специфичные рекомендации

#### ✅ Качество и тестирование
- **1637+ тестов** - комплексное покрытие
  - 306 тестов визуализации
  - 118 тестов обратной совместимости
  - Property-based тесты с Hypothesis
  - Unit тесты для граничных случаев
  - Интеграционные тесты

- **100% Backward Compatible**
  - Весь код v0.4.x продолжает работать
  - Все улучшения аддитивные, без breaking changes
  - Существующие API сохраняют идентичное поведение

#### 🔧 Технические улучшения
- Полные type hints для всех новых функций
- Детальные docstrings с примерами
- PEP 8 соответствие
- Оптимизация производительности алгоритмов
- Чистая, поддерживаемая архитектура

#### 📚 Документация
- Обновлен README с примерами v0.5.0
- Примеры использования для всех новых возможностей
- Руководство по миграции с requests
- Документация context параметра для explain_error()

## [0.4.9] - 2026-02-08

### 🔍 Search Algorithms Release

**Расширение алгоритмов поиска: 2 новых алгоритма с полной визуализацией**

#### 🚀 Новые возможности

##### Новые алгоритмы поиска
- **Linear Search** - последовательный поиск
  - `visualize_linear_search()` - пошаговая визуализация linear search
  - Работает на несортированных массивах
  - Проверяет каждый элемент последовательно
  - Сложность O(n)
  - Подсветка текущего проверяемого элемента

- **Jump Search** - блочный поиск
  - `visualize_jump_search()` - пошаговая визуализация jump search
  - Требует отсортированный массив
  - Прыжки по блокам размером √n
  - Сложность O(√n)
  - Отображение размера прыжка и начала блока
  - Линейный поиск внутри найденного блока

##### Улучшения моделей данных
- **SearchStep Enhancement** - расширенная модель шага поиска
  - `jump_size` - размер прыжка для jump search
  - `block_start` - начало блока для jump search
  - Детальная информация о каждом шаге поиска

#### ✅ Тестирование
- **166+ тестов** для алгоритмов поиска
  - Property-based тесты с Hypothesis
  - Unit тесты для граничных случаев
  - Тесты корректности алгоритмов
  - Тесты эффективности и производительности
  - Тесты работы с разными типами данных

#### 🎯 Checkpoint Verification
- ✅ Все 271 тестов визуализации проходят
- ✅ 5 алгоритмов сортировки работают корректно
- ✅ 3 алгоритма поиска работают корректно (binary, linear, jump)
- ✅ AlgorithmVisualizer правильно диспетчеризует все алгоритмы
- ✅ Атрибут final_array работает для всех алгоритмов

#### 🔧 Технические улучшения
- Валидация отсортированности массива для jump_search
- Автоматический расчет оптимального размера прыжка
- Детальная статистика для всех операций поиска
- Полная обратная совместимость с v0.4.8

#### 📊 Статистика
- Отслеживание количества сравнений
- Отслеживание количества прыжков (для jump search)
- Подсчет шагов выполнения
- Информация о найденном индексе или отсутствии элемента

#### 🎓 Образовательная ценность
- Визуализация разницы между линейным и блочным поиском
- Демонстрация важности сортировки для эффективных алгоритмов
- Сравнение производительности O(n) vs O(√n)
- Понимание компромиссов между простотой и эффективностью

## [0.4.8] - 2026-02-08

### 🔄 Algorithm Expansion Release

**Расширение алгоритмов: 4 новых алгоритма сортировки с полной визуализацией**

#### 🚀 Новые возможности

##### Новые алгоритмы сортировки
- **Quick Sort** - быстрая сортировка с разделением
  - `visualize_quick_sort()` - пошаговая визуализация quick sort
  - Отображение pivot элемента и границ разделения
  - Средняя сложность O(n log n)
  - Поддержка partition_index в шагах визуализации

- **Merge Sort** - сортировка слиянием
  - `visualize_merge_sort()` - пошаговая визуализация merge sort
  - Отображение процесса разделения и слияния
  - Гарантированная сложность O(n log n)
  - Поддержка merge_range для отображения границ

- **Insertion Sort** - сортировка вставками
  - `visualize_insertion_sort()` - пошаговая визуализация insertion sort
  - Подсветка отсортированной части массива
  - Эффективна для малых и почти отсортированных массивов
  - Сложность O(n²) в худшем случае

- **Selection Sort** - сортировка выбором
  - `visualize_selection_sort()` - пошаговая визуализация selection sort
  - Подсветка поиска минимального элемента
  - Простой алгоритм для обучения
  - Сложность O(n²)

##### Улучшения визуализации
- **Final Array Attribute** - прямой доступ к результату
  - `result.final_array` - финальный отсортированный массив
  - Автоматическое вычисление из последнего шага
  - Возвращает копию для предотвращения мутаций

- **Enhanced Data Models** - расширенные модели данных
  - `partition_index` в SortingStep для quick sort
  - `merge_range` в SortingStep для merge sort
  - Улучшенная статистика для всех алгоритмов

#### ✅ Тестирование
- **105+ тестов** для всех алгоритмов сортировки
  - Property-based тесты с Hypothesis
  - Unit тесты для граничных случаев
  - Тесты корректности алгоритмов
  - Тесты статистики и визуализации

#### 🔧 Технические улучшения
- Все алгоритмы следуют единому паттерну реализации
- Полная обратная совместимость с v0.4.7
- Comprehensive docstrings для всех новых функций
- Type hints для всех новых компонентов

#### 📊 Статистика
- Отслеживание сравнений для всех алгоритмов
- Отслеживание обменов (swaps) где применимо
- Подсчет шагов выполнения
- Детальная информация о каждом шаге

## [0.4.7] - 2026-02-05

### 🌐 Network, Visualization & Internationalization Release

**Расширение функциональности: сетевые операции, улучшенная визуализация и многоязычная поддержка**

#### 🚀 Новые возможности

##### Безопасные сетевые операции
- **SafeHTTPClient** - безопасные HTTP запросы с обработкой таймаутов
  - `safe_request()` - HTTP запросы с автоматическим таймаутом (10 сек по умолчанию)
  - Структурированные ответы (NetworkResponse) вместо исключений
  - Поддержка всех HTTP методов (GET, POST, PUT, DELETE, etc.)
  - Обработка ошибок сети, таймаутов и невалидных параметров

- **SafeFileDownloader** - безопасная загрузка файлов с отслеживанием прогресса
  - `safe_download()` - загрузка файлов с callback для прогресса
  - Обработка конфликтов файлов (overwrite параметр)
  - Автоматическая очистка при ошибках
  - Проверка свободного места на диске
  - DownloadProgress с процентами и скоростью

##### Улучшенная визуализация
- **EnhancedVisualizer** - расширенная визуализация данных
  - Tree-style иерархическое отображение
  - Цветовая подсветка по типам данных
  - Ограничение глубины вложенности (max_depth)
  - Экспорт в JSON и HTML форматы
  - VisualizationConfig для настройки стилей

- **AlgorithmVisualizer** - пошаговая визуализация алгоритмов
  - `visualize_sorting()` - визуализация сортировки (bubble sort)
  - `visualize_search()` - визуализация поиска (binary search)
  - Отслеживание шагов выполнения
  - Статистика (сравнения, обмены, операции)
  - AlgorithmStep, SortingStep, SearchStep модели

##### Многоязычная поддержка (i18n)
- **ErrorTranslator** - объяснение ошибок на разных языках
  - `translate_error()` - перевод объяснений ошибок
  - Поддержка русского (ru) и английского (en)
  - Автоопределение языка системы (lang='auto')
  - Fallback на английский для неподдерживаемых языков
  - ErrorExplanation с предложениями по исправлению

- **LanguageDetector** - определение языка системы
  - `detect_language()` - автоматическое определение locale
  - Поддержка Windows, Linux, macOS
  - Fallback на русский (оригинальное поведение)

##### Управление конфигурацией
- **NetworkConfig** - настройки сетевых операций
  - default_timeout, max_retries, retry_delay
  - chunk_size для загрузок
  
- **VisualizationConfig** - настройки визуализации
  - default_style, default_colors
  - color_scheme, export_directory
  
- **I18nConfig** - настройки интернационализации
  - default_language, fallback_language
  - auto_detect для автоопределения

##### Информация о версии
- **get_version_info()** - детальная информация о версии
  - Номер версии и автор
  - Список всех возможностей
  - История улучшений по версиям
  - Новые возможности v0.4.7

#### ✅ Тестирование
- **56 интеграционных тестов** - комплексное тестирование
  - Property-based тесты с hypothesis
  - Unit тесты для обратной совместимости
  - Интеграционные тесты для взаимодействия модулей
  - Тесты реальных сценариев использования

#### 🔄 Обратная совместимость
- **100% обратная совместимость** - весь существующий код работает
  - Все старые функции сохранены
  - Новые модули не влияют на существующие
  - Расширенный __all__ с новыми экспортами
  - Обновлен __init__.py для бесшовной интеграции

#### 📚 Документация
- Обновлен README с примерами новых возможностей
- Добавлены примеры интеграции модулей
- Документация по всем новым API
- Руководства по использованию

## [0.4.6] - 2026-02-02

### ⚡ Performance & Async Release

**Значительные улучшения производительности и поддержка асинхронного программирования**

#### 🚀 Новые возможности

##### Асинхронная поддержка
- **AsyncSimpleLogger** - асинхронная версия SimpleLogger для async/await приложений
  - Не блокирует event loop
  - Async-safe с `asyncio.Lock`
  - Те же методы: `info()`, `warning()`, `error()`
  - Использует `asyncio.to_thread()` для неблокирующих операций

- **Async Safe Utilities** - асинхронные версии безопасных утилит
  - `async_safe_read_file()` - асинхронное чтение файла
  - `async_safe_write_file()` - асинхронная запись файла
  - `async_safe_file_exists()` - асинхронная проверка существования
  - `async_safe_get_file_size()` - асинхронное получение размера
  - `async_safe_list_files()` - асинхронный список файлов

##### Потокобезопасность
- **SimpleLogger** теперь потокобезопасен
  - Добавлен `threading.Lock` для защиты от race conditions
  - Безопасное использование в многопоточных приложениях
  - Автоматическая синхронизация записи в файл

##### Кэширование
- **PatternLoader** использует LRU cache
  - Добавлен `@functools.lru_cache(maxsize=1)` декоратор
  - Паттерны загружаются только один раз
  - Ускорение повторных вызовов в ~10,000 раз

##### PEP 561 Support
- Добавлен `py.typed` marker file
  - Полная поддержка type checkers (mypy, pyright)
  - Type hints теперь доступны для внешних проектов
  - Обновлен `pyproject.toml` для включения файла

##### Future Annotations
- Добавлен `from __future__ import annotations` во все модули
  - Улучшена производительность импорта
  - Поддержка отложенной оценки аннотаций типов
  - Совместимость с Python 3.8+

#### 🏗️ Структурные изменения

##### Современная сборка
- **Удален setup.py** - используется только `pyproject.toml`
  - Соответствие PEP 517/518
  - Упрощенная структура проекта
  - Единый источник конфигурации

#### 📚 Документация
- Добавлено руководство по асинхронным возможностям (`ASYNC_GUIDE.md`)
- Подробная документация улучшений (`IMPROVEMENTS_v0.4.6.md`)
- Примеры использования async функций
- Сравнение производительности sync vs async

#### ✅ Тестирование
- Добавлены тесты для всех новых возможностей
- Тесты потокобезопасности SimpleLogger
- Тесты кэширования PatternLoader
- Тесты асинхронных функций
- Тесты PEP 561 compliance
- Тесты обратной совместимости

#### 🔄 Обратная совместимость
- **100% обратная совместимость**
- Все существующие API работают без изменений
- Новые возможности доступны через новые модули
- Старый код не требует изменений

### 📊 Производительность

| Функция | До | После | Улучшение |
|---------|-----|-------|-----------|
| `load_patterns()` (повторный) | 10ms | 0.001ms | 10,000x |
| `SimpleLogger` (многопоточность) | Race conditions | Thread-safe | ✅ |
| Async file operations | Блокирует | Неблокирующие | ✅ |
| Type checking | Не поддерживается | PEP 561 | ✅ |

## [0.4.5.1] - 2026-02-02

### 📦 Package Re-release

**Повторная публикация v0.4.5 на PyPI**

Версия 0.4.5.1 идентична 0.4.5 - это техническая повторная публикация для обеспечения доступности пакета на PyPI.

Все изменения и исправления описаны в секции [0.4.5] ниже.

## [0.4.5] - 2026-02-02

### 🐛 Critical Bug Fixes

**Исправлены критические ошибки в fishertools v0.4.4.2**

#### ✅ Исправлен модуль обучения (Learning Module)
- **Проблема:** FileNotFoundError при вызове `explain("lists")` - файл explanations.json не включался в пакет
- **Решение:** 
  - Создан `ExplanationLoader` с использованием `importlib.resources` для надежной загрузки
  - Обновлены MANIFEST.in и setup.py для включения JSON файлов
  - Добавлены fallback механизмы для разных версий Python
  - Четкие сообщения об ошибках при отсутствии файлов

#### 🔧 Улучшены сообщения об ошибках валидации
- **Проблема:** `validate_number("string", 0, 100)` выдавал непонятную ошибку сравнения операторов
- **Решение:**
  - Обернуты внутренние сравнения типов в try-catch блоки
  - ValidationError теперь содержит фактический и ожидаемый типы
  - Специальная обработка для None значений
  - Сообщения: "Expected number, got str" вместо технических ошибок Python

#### 📖 Добавлены контекстные объяснения ошибок
- **Новая функция:** `explain_error()` для образовательных объяснений ошибок валидации
- Система сопоставления паттернов ошибок с объяснениями
- Примеры исправления для распространенных ошибок
- Fallback объяснения для неизвестных паттернов
- Прогрессивно детальные объяснения для повторяющихся ошибок

#### 🎨 Улучшено форматирование строк (safe_format)
- **Новая функция:** Настраиваемое поведение для отсутствующих плейсхолдеров
- **PlaceholderBehavior enum:**
  - `PRESERVE` - оставляет оригинальные плейсхолдеры: `{name}`
  - `MISSING` - заменяет на: `[MISSING: name]` (по умолчанию)
  - `EMPTY` - заменяет пустой строкой
- Четкий API для конфигурации поведения
- Обратная совместимость с существующим кодом

#### ➕ Добавлена функция safe_average()
- **Новая функция:** Безопасное вычисление среднего с защитой от ошибок
- Возвращает указанное значение по умолчанию для пустых списков
- Автоматически фильтрует нечисловые значения
- Примеры:
  - `safe_average([1, 2, 3])` → `2.0`
  - `safe_average([], default=0)` → `0`
  - `safe_average([1, "text", 3])` → `2.0` (фильтрует "text")

#### 🛡️ Комплексная обработка ошибок
- Образовательные сообщения об ошибках для всех функций fishertools
- Объяснения для начинающих для распространенных ошибок Python
- Двухуровневое логирование (детальное для отладки, простое для пользователей)
- Предложения по исправлению для ошибок импорта и файловых операций
- Graceful degradation вместо полного отказа

#### ✅ Обеспечена обратная совместимость
- Все существующие сигнатуры функций сохранены
- Иерархия исключений ValidationError не изменена
- Debug декораторы сохраняют тот же формат вывода
- Никакие публичные функции или классы не удалены/переименованы
- Существующий код продолжает работать без изменений

#### 📦 Целостность распространения пакета
- Правильная конфигурация MANIFEST.in для включения JSON файлов
- Обновлены setup.py/pyproject.toml с package_data
- Поддержка как development, так и production установки
- Модуль обучения успешно находит файлы данных независимо от метода установки

#### 📊 Тестирование
- **341 новых тестов** для всех исправлений
- **99.6% успешных тестов** (340 из 341)
- Property-based тесты с Hypothesis для универсальной корректности
- Unit тесты для конкретных примеров и граничных случаев
- Тесты интеграции между модулями
- Тесты обратной совместимости

**Приоритет исправлений:** Критические → Высокие → Средние
- ✅ Критические: Модуль обучения (Requirement 1)
- ✅ Высокие: Сообщения об ошибках валидации (Requirement 2)
- ✅ Высокие: Контекстные объяснения (Requirement 3)
- ✅ Средние: Улучшения safe_format (Requirement 4)
- ✅ Средние: Функция safe_average (Requirement 5)
- ✅ Критические: Обратная совместимость (Requirement 6)
- ✅ Критические: Целостность пакета (Requirement 7)
- ✅ Высокие: Надежность обработки ошибок (Requirement 8)

## [0.4.4] - 2026-02-01

### 🚀 Major Code Quality Improvements

**Профессиональный рефакторинг на основе Code Review**

#### ✨ Новые возможности:
- **Единый источник версии** - создан `fishertools/_version.py` для централизованного управления версией
- **Улучшенная валидация входных данных** - `ask_int()` и `ask_float()` теперь с защитой от бесконечных циклов
- **Оптимизированные регулярные выражения** - предкомпилированные паттерны в `helpers.py` для лучшей производительности

#### 🔧 Улучшения качества кода:
- **Полные type hints** - добавлены `TypeVar` и `ParamSpec` в `decorators.py` для строгой типизации
- **Улучшенная обработка ошибок** - валидация параметров в `input_utils.py` (проверка min_val < max_val)
- **Защита от DoS** - добавлен параметр `max_attempts` в функции ввода
- **Оптимизация производительности** - предкомпилированные regex паттерны в `helpers.py`

#### 🐛 Bug Fixes:
- **Fixed undefined variable** - `standalone_escape` in `errors/formatters.py` (existing bug)
- **Consolidated regex patterns** - removed duplicate `ansi_escape` definition

#### 📦 Управление зависимостями:
- **Точное версионирование** - requirements.txt теперь с фиксированными версиями (requests==2.31.0, click==8.3.1)
- **Опциональные зависимости** - pyyaml вынесен в `[config]` extra для уменьшения базовых зависимостей
- **Улучшенная структура** - pyproject.toml с правильными диапазонами версий (>=X.Y.Z,<X+1.0.0)

#### 🛡️ Безопасность:
- **Валидация параметров** - проверка пустых промптов и некорректных диапазонов
- **Graceful error handling** - правильная обработка KeyboardInterrupt и EOFError
- **Type safety** - полная типизация для предотвращения runtime ошибок

#### 📚 Документация:
- **Улучшенные docstrings** - добавлены примеры использования и описания исключений
- **Консистентная версия** - синхронизация версий между setup.py, pyproject.toml и __init__.py

**Технический долг:** Устранены критические проблемы из Code Review:
- ✅ Несоответствие версий (HIGH)
- ✅ Отсутствие type hints в legacy модулях (HIGH)
- ✅ Отсутствие версионирования зависимостей (HIGH)
- ✅ Недостаточная валидация входных данных (MEDIUM)
- ✅ Неоптимальные регулярные выражения (LOW)

## [0.4.3.3] - 2026-02-01

### 🔧 Code Quality Improvements

**Масштабная оптимизация кода - устранены дублирующиеся литералы и снижена когнитивная сложность**

#### 📝 Константы вместо дублирующихся литералов:
- **fishertools/documentation/generator.py** - константы для имен файлов (INDEX_RST, CONF_PY, etc.)
- **fishertools/documentation/visual.py** - константы для HTML тегов (DIV_CLOSE, DIV_OPEN)
- **fishertools/examples/logger_example.py** - константы для имен лог-файлов
- **fishertools/examples/repository.py** - полный набор констант для концепций и паттернов кода
- **fishertools/learn/repl/command_handler.py** - константы для сообщений пользователю
- **fishertools/learn/repl/command_parser.py** - константы для сообщений об ошибках

#### 🧠 Рефакторинг сложных функций:
- **fishertools/examples/repository.py** - разбита анонимная функция с когнитивной сложностью 46 на множество специализированных методов
- **fishertools/learn/repl/engine.py** - функция `_handle_command` (сложность 65→15) разбита на 15 специализированных методов

#### 🐛 Исправлены синтаксические ошибки:
- **fishertools/documentation/api.py** - исправлена индентация и удален дублирующийся код
- **fishertools/readme_transformer.py** - исправлена индентация в блоке try-except
- **fishertools/visualization/formatters.py** - удален дублирующийся код функции

Код стал значительно более читаемым, поддерживаемым и менее подверженным ошибкам.

## [0.4.3.2] - 2026-02-01

### 🐛 Bug Fixes

**Исправлена ошибка индентации в readme_transformer.py**

#### Исправленные файлы:
- `fishertools/readme_transformer.py` - исправлена индентация в методе write_transformed_readme

Это исправление устраняет IndentationError в блоке try-except, который препятствовал корректной работе трансформера README.

## [0.4.3.1] - 2026-02-01

### 🐛 Bug Fixes

**Исправлены синтаксические ошибки в модуле documentation**

#### Исправленные файлы:
- `fishertools/documentation/code_validator.py` - удален дублирующийся код метода
- `fishertools/documentation/examples_manager.py` - добавлен отсутствующий блок except
- `fishertools/documentation/generator.py` - исправлена индентация в методе _generate_readthedocs_config

Эти исправления устраняют ошибки IndentationError и SyntaxError, которые препятствовали корректной работе модуля документации.

## [Unreleased] - 2026-01-30

### 🔧 Code Quality Refactoring (v0.4.3)

**Исправлен "spaghetti code" - библиотека стала более человечной!**

#### ✅ Реализован safe_string_operations
- **Было:** Stub-метод с `pass` (ничего не делал)
- **Стало:** Полноценный модуль с 6 функциями:
  - `safe_strip()` - безопасный strip с обработкой None
  - `safe_split()` - безопасный split с обработкой None
  - `safe_join()` - безопасный join с пропуском None
  - `safe_format()` - безопасное форматирование строк
  - `safe_lower()` / `safe_upper()` - безопасное изменение регистра

#### 🔢 Исправлена математика в safe_divide
- **Было:** `safe_divide(10, 0) = 0` (математически НЕПРАВИЛЬНО!)
- **Стало:** `safe_divide(10, 0) = None` (честно: результат неопределен)
- Можно явно указать default: `safe_divide(10, 0, default=0)`

#### 🐍 Упрощена обработка ошибок (Pythonic подход)
- Убраны избыточные проверки типов (было 50+ строк, стало 10)
- Используется EAFP (Easier to Ask Forgiveness than Permission)
- Проверяются только явно неправильные типы (None, bool, complex)
- Код стал проще и понятнее

#### 📦 Упрощены функции коллекций
- `safe_max()`, `safe_min()`, `safe_sum()` - с 30+ строк до 5 строк
- `safe_get()` - универсальный getter для любых коллекций
- Меньше кода, больше читаемости

#### 📊 Результаты
- ✅ Все 82 теста проходят
- 📉 -150 строк избыточного кода
- 📈 +6 новых полезных функций
- 🎯 100% математическая корректность

#### 📝 Документация
- Добавлен `REFACTORING_SUMMARY.md` с подробным описанием изменений
- Добавлен `examples/refactored_safe_usage.py` с примерами использования
- Обновлены docstrings с честными примерами

## [0.4.1] - 2026-01-29

### 🎨 Phase 1: Core Modules (Visualization, Validation, Debug)

**Три новых мощных модуля для разработки и обучения:**

#### 📊 Visualization Module
- `visualize()` - визуализация структур данных в понятном формате
- Поддержка списков, словарей, вложенных структур
- Ограничение глубины и количества элементов
- Форматирование с индексами и ключами

#### ✅ Validation Module
- `@validate_types` - проверка типов через type hints
- `validate_email()`, `validate_url()` - валидация данных
- `validate_number()`, `validate_string()` - проверка значений
- `validate_structure()` - валидация структуры данных
- `ValidationError` - исключение для ошибок валидации

#### 🔍 Debug Module
- `@debug_step_by_step` - пошаговое выполнение функций
- `@trace` - трассировка вызовов функций
- `set_breakpoint()` - точки останова для отладки
- Визуализация стека вызовов и значений переменных

#### 📈 Тестирование
- 65+ новых тестов для всех модулей
- 90%+ покрытие кода
- Property-based тесты с Hypothesis

---

## [0.4.0] - 2026-01-29

### 🎓 Knowledge Engine Interactive REPL

**Полнофункциональный интерактивный REPL для обучения Python:**

#### 🎯 Основные компоненты
- **REPLEngine** - главный интерактивный цикл с управлением состоянием
- **CommandParser** - парсинг пользовательского ввода с поддержкой команд и тем
- **CodeSandbox** - безопасное выполнение кода с ограничениями и таймаутом
- **SessionManager** - отслеживание прогресса и сохранение состояния сессии
- **CommandHandler** - обработка всех команд REPL
- **TopicDisplay** - форматирование и отображение тем

#### 📚 Функциональность
- **Просмотр тем:** /list, /search, /random, /categories, /category, /path
- **Навигация:** /next, /prev, /goto, /related
- **Выполнение кода:** /run, /modify, /exit_edit
- **Отслеживание прогресса:** /progress, /stats, /reset_progress
- **Управление сессией:** /history, /clear_history, /session
- **Справка:** /help, /commands, /about, /hint, /tip, /tips

#### 🔒 Безопасность
- Ограничение доступа к опасным операциям (file I/O, imports)
- Таймаут выполнения кода (5 секунд по умолчанию)
- Валидация кода перед выполнением
