PyQt5 App Template: NightPillow

Приложение для расчёта оптимального времени сна «NightPillow» — это простой проект-шаблон для создания десктопных приложений на Python с использованием фреймворка PyQt5.

👩🏻‍🔬 Опробовать проект: Последний релиз.

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

Цель данного репозитория — быть понятным и структурированным шаблоном (template).

Этот репозиторий будет полезен, если вы:

• Начинаете изучение PyQt и хотите увидеть пример структуры проекта, не прописывая весь код в одном файле.
• Ищете готовую основу для своей небольшой утилиты, чтобы не настраивать всё с нуля.
• Хотите понять, как отделить логику приложения от его визуального представления (принцип Model-View-Controller).
• Сталкивались с проблемами при работе с ресурсами (картинками, иконками) после сборки проекта в .exe файл и хотите увидеть рабочее решение.

✨ Возможности шаблона

Этот проект демонстрирует лучшие практики для создания небольших приложений:

• 🏗️ Архитектура, подобная «MVC»:
  • Model (calculator.py): Содержит всю бизнес-логику и вычисления, не зависит от интерфейса.
  • View (main_window.py): Отвечает только за создание, стилизацию и размещение виджетов.
  • Controller (main.py/AppController): Связывает логику и представление, обрабатывает действия пользователя.
• 🖼️ Управление ресурсами: Функция resource_path в utils.py обеспечивает корректный доступ к ресурсам (картинкам, иконкам, шрифтам) как при запуске из исходников, так и в собранном .exe файле.
• 🛠️ Централизованная конфигурация: Все константы (цвета, тексты, размеры, пути) вынесены в constants.py для лёгкой настройки.
• 🗃️ Чистая структура проекта: Логические части приложения разнесены по разным файлам и папкам.
• 🧩 Стилизация через QSS: Показан пример применения Qt Style Sheets для кастомизации внешнего вида.
• 📝 Управление зависимостями: Имеется файл requirements.txt для быстрой и простой установки.
• 📦 Готовность к сборке: Проект легко собирается в один исполняемый файл с помощью PyInstaller.

🚀 Установка и запуск

1. Клонирование репозитория:

   git clone https://github.com/n1xsi/nightpillow-pyqt5.git
   cd nightpillow-pyqt5

2. Создание виртуального окружения:

   • На Windows:

     python -m venv venv
     .\venv\Scripts\activate

   • На macOS / Linux:

     python3 -m venv venv
     source venv/bin/activate

3. Установление зависимостей:

   pip install -r requirements.txt

4. Запуск приложения:

   python main.py

📦 Сборка в единый .exe файл

Чтобы собрать проект в один исполняемый файл, который будет работать на Windows даже без установленного Python, используйте PyInstaller.

1. Установите PyInstaller:

   pip install pyinstaller

2. Запустите сборку из корневой папки проекта:

   pyinstaller --name "NightPillow" --onefile --windowed --icon "resources/images/logo.ico" --add-data "app;app" --add-data "resources;resources"  "main.py"

   • --name: устанавливает имя окна приложения.
   • --onefile: собирает всё в один единый файл.
   • --windowed: убирает консольное окно на фоне.
   • --icon: устанавливает иконку для приложения.
   • --add-data "ПАПКА;ПАПКА": добавить папку с ресурсами в сборку.

   Готовый .exe файл появится в папке dist.

⚙️ Функционал приложения-примера

Калькулятор сна, реализованный в данном шаблоне, основан на теории 90-минутных циклов сна. Алгоритм также учитывает, что в среднем человеку требуется около 15 минут, чтобы заснуть. Это позволяет приложению рассчитывать время пробуждения в конце цикла, что помогает чувствовать себя бодрым и отдохнувшим.

Основные возможности приложения:

• Два режима расчёта: С помощью переключателя можно выбрать один из двух сценариев:
  • "Надо встать": Вы указываете желаемое время пробуждения, и приложение рассчитывает 6 оптимальных вариантов времени, когда лучше всего лечь спать.
  • "Надо лечь": Вы указываете время, когда планируете лечь, и приложение предлагает 6 вариантов, когда лучше всего проснуться.
• Учёт времени на засыпание: Расчёты автоматически учитывают, что в среднем человеку требуется около 15 минут, чтобы заснуть.
• Удобный ввод времени: Поле для ввода использует маску ЧЧ:ММ, которая не позволяет вводить некорректные символы.
• Гибкий результат: Приложение всегда предлагает шесть вариантов времени, что даёт пользователю гибкость в планировании своего сна.

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

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

NightPillow/
├── app/                # Основной пакет с кодом приложения
│   ├── __init__.py       # Делает 'app' пакетом Python
│   ├── calculator.py     # Модель: вся логика расчетов
│   ├── constants.py      # Константы: тексты, цвета, размеры
│   ├── main_window.py    # Представление: всё, что касается UI
│   └── utils.py          # Вспомогательные утилиты (направление для путей к ресурсам)
│
├── resources/          # Папка для всех ресурсов
│   ├── fonts/            # Шрифты для приложения
│   └── images/           # Изображения для UI
│
├── .gitignore          # Настройки для игнорирования файлов в Git
├── LICENSE             # Лицензия проекта
├── README.md           # Файл, который вы сейчас читаете
├── requirements.txt    # Список зависимостей для работы проекта
└── main.py             # Точка входа в приложение

📄 Лицензия

Этот проект распространяется под лицензией MIT. Подробности смотрите в файле LICENSE.