Study Streak Tracker 📚🔥

📝 О проекте

Study Streak Tracker — это мощный и интуитивно понятный инструмент для отслеживания учебной активности, разработанный с целью помочь студентам и всем желающим сформировать устойчивую привычку учиться каждый день. Вдохновленный популярным приложением для изучения языков Duolingo, данный трекер применяет проверенные методы геймификации для поддержания мотивации и превращения учебного процесса в увлекательную игру.

🎯 Зачем это нужно?

В современном мире, где информация обновляется с огромной скоростью, непрерывное обучение становится не просто преимуществом, а необходимостью. Однако поддерживать регулярность занятий часто бывает сложно из-за отсутствия видимого прогресса и внешней мотивации. Study Streak Tracker решает эту проблему, предоставляя пользователю:

• Визуализацию прогресса: Наглядные графики и статистика позволяют увидеть свои достижения и понять, сколько усилий уже вложено.
• Систему поощрений: Ачивки и серии дней создают дополнительную мотивацию не пропускать занятия.
• Аналитику: Детальный отчет по предметам помогает понять, чему уделяется больше всего времени и где есть пробелы.
• Автоматизацию: Инструмент самостоятельно считает серии, обновляет статистику и генерирует отчеты, освобождая пользователя от рутины.

✨ Ключевые возможности

📊 Логирование учебных сессий

Позволяет детально фиксировать каждое занятие. Вы можете указать:

• Предмет: Математика, Программирование, Иностранный язык и т.д.
• Длительность: Время, потраченное на занятие (в минутах).
• Количество заданий: Сколько задач, упражнений или страниц было выполнено.

Все данные сохраняются в структурированном формате CSV, что позволяет легко экспортировать и анализировать их в других программах.

🔥 Система серий (Streak)

Главный мотивационный механизм. Приложение автоматически подсчитывает:

• Текущую серию: Количество дней подряд, в которые была хотя бы одна учебная сессия.
• Максимальную серию: Ваш личный рекорд, к которому стоит стремиться.

Если вы пропустите день, серия прервется, что станет дополнительным стимулом заниматься регулярно.

🏆 Система достижений (Achievements)

По мере использования вы будете открывать различные ачивки, которые отмечают ваши успехи:

• Первые шаги: Награда за первую добавленную сессию.
• Усердный ученик: За 10 часов суммарной учебы.
• Марафонец: За 7-дневную серию.
• Легенда: За 30-дневную серию.
• Эрудит: За изучение 5 разных предметов.
• Ночная сова: За 10 сессий после 22:00.
• Ранняя пташка: За 10 сессий до 8:00.
• Трудоголик: За 100 выполненных заданий.
• Профессионал: За 50 часов учебы.

💬 Мотивационные сообщения

После каждой добавленной сессии или достижении новой вехи, приложение генерирует персонализированные мотивационные сообщения, чтобы поддержать ваш боевой дух и напомнить о целях.

📈 Визуализация в SVG

Одна из самых сильных сторон проекта. Приложение автоматически генерирует красивый SVG-график, который отображается прямо в README.md вашего репозитория. На графике наглядно показана ваша активность за последние 7 дней, что позволяет мгновенно оценить динамику обучения.

🤖 Автоматизация через GitHub Actions

Проект полностью автоматизирован благодаря использованию GitHub Actions. Два основных workflow обеспечивают его бесперебойную работу:

• Tests Workflow: Запускается при каждом пуше, проверяя код на соответствие стандартам PEP 8 (flake8) и прогоняя все юнит-тесты (pytest). Это гарантирует стабильность и качество кода.
• Daily Streak Workflow: Запускается ежедневно по расписанию (в 23:55 UTC). Он обновляет статистику, проверяет условия для разблокировки новых ачивок, генерирует свежий SVG-график и автоматически коммитит изменения в репозиторий. Таким образом, ваш README всегда актуален.

🏆 Полный список достижений

🚀 Быстрый старт

Предварительные требования

Для работы с проектом вам понадобится:

• Python версии 3.9, 3.10 или 3.11
• pip (менеджер пакетов Python)
• Git (для клонирования репозитория)

Пошаговая установка

Шаг 1: Клонируйте репозиторий

Откройте терминал и выполните команду:

Шаг 2: Создайте виртуальное окружение (рекомендуется)

Виртуальное окружение позволяет изолировать зависимости проекта и избежать конфликтов с другими Python-пакетами.

Для Windows:

Для macOS/Linux:

Шаг 3: Установите зависимости

Все необходимые библиотеки перечислены в файле

Шаг 4: Запустите программу

Теперь все готово к использованию:

📖 Подробное руководство пользователя

Основные команды

Проект имеет удобный интерфейс командной строки. Вот полный список доступных команд:

1. Добавление новой учебной сессии

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

Пример:

Пример вывода:

✅ Добавлена сессия: Python Programming, 1ч 0м, 3 заданий

🎉 НОВЫЕ ДОСТИЖЕНИЯ:
  🌱 Первые шаги: Добавьте первую учебную сессию

💬 Отличное начало! 🎯

2. Просмотр текущей статистики

Показывает вашу текущую серию, лучшую серию за все время, общее время учебы и количество сессий.

Пример вывода:

📊 ТЕКУЩАЯ СТАТИСТИКА
========================================
🔥 Текущая серия: 3 дней
🏆 Лучшая серия: 5 дней
⏱️ Всего времени: 4ч 30м
📚 Всего сессий: 8

💬 Три дня подряд! 🔥

3. Просмотр достижений

Выводит список всех разблокированных и еще доступных ачивок, а также общий прогресс.

Пример вывода:

🏅 ДОСТИЖЕНИЯ
========================================
Прогресс: 2/10 (20.0%)

✅ РАЗБЛОКИРОВАНО:
  🌱 Первые шаги
  📚 Усердный ученик

🔒 ЕЩЕ МОЖНО ПОЛУЧИТЬ:
  🏃 Марафонец: Достигните серии в 7 дней
  👑 Легенда: Достигните серии в 30 дней
  🧠 Эрудит: Изучайте 5 разных предметов

4. Генерация недельного отчета

Показывает подробную статистику за последние 7 дней: количество сессий, общее время, выполненные задания и разбивку по дням.

Пример вывода:

📈 ОТЧЕТ ЗА ПОСЛЕДНИЕ 7 ДНЕЙ
========================================
📊 Всего сессий: 6
⏱️ Всего времени: 5ч 15м
✅ Выполнено заданий: 18
📚 Предметов: 3

📅 По дням:
  2026-02-15: 1ч 30м
  2026-02-16: 45м
  2026-02-17: 1ч 0м
  2026-02-18: 1ч 0м
  2026-02-19: 45м
  2026-02-20: 1ч 15м

5. Генерация SVG-графика

Создает визуализацию вашей активности за последние 7 дней и сохраняет ее в файл

Пример вывода:

✅ SVG успешно сгенерирован: C:\...\study-streak-tracker\outputs\streak.svg

6. Ежедневное обновление (для CI/CD)

Эта команда предназначена для автоматического запуска из GitHub Actions. Она обновляет статистику, проверяет ачивки и генерирует SVG.

Примеры использования

Сценарий: Первая неделя использования

День 1:

Получаем ачивку "Первые шаги" 🌱.

День 2:

Смотрим статистику:

День 7:

Проверяем достижения:

Генерируем график и любуемся результатом:

Теперь красивый график активности отображается прямо в README!

📁 Структура проекта

Проект организован следующим образом, чтобы обеспечить чистоту кода, его тестируемость и удобство сопровождения:

study-streak-tracker/
│
├── .github/                      # Настройки GitHub
│   └── workflows/                # GitHub Actions CI/CD конфигурации
│       ├── tests.yml             # Запуск тестов при каждом пуше
│       └── daily-streak.yml      # Ежедневное обновление по расписанию
│
├── src/                          # Исходный код приложения
│   ├── __init__.py                # Делает папку Python-пакетом
│   ├── tracker.py                 # Основная логика: сессии, серии, статистика
│   ├── achievements.py            # Система достижений и ачивок
│   ├── visualizer.py              # Генерация SVG-графиков
│   └── utils.py                   # Вспомогательные функции (форматирование, валидация)
│
├── tests/                         # Модульные тесты
│   ├── __init__.py
│   ├── test_tracker.py            # Тесты для tracker.py
│   ├── test_achievements.py       # Тесты для achievements.py
│   └── test_visualizer.py         # Тесты для visualizer.py
│
├── data/                          # Директория для пользовательских данных
│   ├── sessions.csv                # CSV-файл со всеми учебными сессиями
│   └── achievements.json           # JSON-файл с разблокированными ачивками
│
├── outputs/                        # Сгенерированные выходные файлы
│   └── streak.svg                   # SVG-график прогресса за 7 дней
│
├── .gitignore                       # Список файлов, игнорируемых Git
├── requirements.txt                  # Зависимости Python-проекта
├── setup.py                          # Файл для установки пакета в режиме разработки
├── main.py                           # Главная точка входа в приложение (CLI)
└── README.md                         # Документация проекта (вы ее читаете)

🧪 Тестирование и качество кода

Проект серьезно относится к качеству кода. Все изменения проходят автоматическую проверку перед тем, как попасть в основную ветку.

Запуск тестов локально

Для запуска всех тестов выполните:

Для запуска тестов с отчетом о покрытии кода:

После выполнения этой команды в папке

Проверка стиля кода

Проект соответствует стандарту PEP 8. Для проверки стиля используется

Для автоматического форматирования кода используется

Непрерывная интеграция (CI)

Каждый раз, когда вы пушите изменения в репозиторий, GitHub Actions автоматически запускает процесс CI, который:

1. Устанавливает Python (версии 3.9, 3.10, 3.11).
2. Устанавливает все зависимости.
3. Проверяет стиль кода с помощью
   flake8
   .
4. Проверяет форматирование с помощью
   black
   .
5. Запускает все тесты и проверяет покрытие кода.
6. Сохраняет отчет о покрытии как артефакт сборки.

Зеленый значок статуса в начале этого README означает, что последняя сборка прошла успешно и код находится в рабочем состоянии.

🤖 GitHub Actions: Автоматизация на полную

Проект использует два мощных workflow для автоматизации всех рутинных процессов.

Workflow 1: Tests (

tests.yml

)

Этот workflow обеспечивает качество кода.

• Триггер: Запускается на каждый
  push
  в ветки
  main
  или
  master
  , а также на каждый
  pull request
  .
• Задачи:
  1. Установка Python (версии 3.9, 3.10, 3.11).
  2. Установка зависимостей (
     pip install -r requirements.txt
     ).
  3. Проверка кода
     flake8
     .
  4. Проверка форматирования
     black
     (с возможностью продолжения в случае ошибки, чтобы не блокировать разработку).
  5. Запуск тестов
     pytest
     с измерением покрытия кода.
  6. Сохранение отчета о покрытии в артефакты сборки.

Workflow 2: Daily Streak Update (

daily-streak.yml

)

Это сердце автоматизации, которое делает ваш README "живым".

• Триггер: Запускается ежедневно в 23:55 UTC по расписанию (
  schedule
  ), а также может быть запущен вручную через
  workflow_dispatch
  .
• Задачи:
  1. Клонирование репозитория.
  2. Установка Python и зависимостей.
  3. Запуск команды
     python main.py --daily-update
     , которая обновляет статистику и проверяет ачивки.
  4. Запуск команды
     python main.py --generate-svg
     для создания свежего графика.
  5. Автоматический коммит и пуш: Если файлы
     streak.svg
     или
     achievements.json
     изменились, workflow автоматически коммитит их и пушит в репозиторий.
  6. Сохранение сгенерированного SVG как артефакта сборки.

Благодаря этому workflow, ваш график прогресса всегда актуален, и вам не нужно думать о его обновлении вручную.

🛠️ Технологии и библиотеки

Проект написан на Python 3.9+ и использует следующие ключевые библиотеки:

• pandas (>=1.3.0): Для удобной работы с CSV-данными, хотя в данном проекте мы используем встроенный модуль
  csv
  , pandas указан в зависимостях на будущее расширение функциональности.
• pytest (>=7.0.0): Фреймворк для написания и запуска модульных тестов.
• pytest-cov (>=4.0.0): Плагин для pytest, измеряющий покрытие кода тестами.
• flake8 (>=4.0.0): Инструмент для проверки кода на соответствие стандартам PEP 8.
• black (>=22.0.0): "Бескомпромиссный" форматтер кода, автоматически приводящий его к единому стилю.

💡 Идеи для дальнейшего развития

Проект имеет большой потенциал для улучшения. Вот несколько идей, которые можно реализовать:

• Telegram-бот: Создать бота, который позволит добавлять сессии и просматривать статистику прямо из мессенджера, без необходимости заходить в терминал.
• Веб-интерфейс: Разработать простое веб-приложение на Flask или Streamlit для более удобного взаимодействия.
• Экспорт отчетов: Добавить возможность экспорта статистики и графиков в PDF для печати или отправки.
• Социальный аспект: Добавить leaderboard (таблицу лидеров), чтобы можно было соревноваться с друзьями в регулярности занятий.
• Интеграция с календарем: Подключение к Google Calendar или Outlook для автоматического импорта запланированных учебных событий.
• Расширенная аналитика: Добавить графики по предметам, времени суток, дням недели для более глубокого анализа своих привычек.

👨‍💻 Автор: Patsyuk

• Статус: Студент УрФУ
• GitVerse: @Patsyuk

🙏 Благодарности

• Вдохновлен дизайном и механиками приложения Duolingo.
• Спасибо сообществу Python за отличные библиотеки и инструменты.
• Благодарность GitHub и GitVerse за предоставление платформы для хостинга кода и бесплатных CI/CD возможностей.
• Особая благодарность ChatGPT и DeepSeek за помощь в отладке кода, написании тестов и бесконечные советы по форматированию. Без вас этот проект был бы намного сложнее! 🤖