Спасибо за ваш интерес к развитию ALT Booster! Этот документ поможет вам понять архитектуру приложения и стандарты кода, принятые в проекте.
ALT Booster — это не просто набор скриптов, а полноценное десктоп-приложение с продуманной архитектурой. Ключевые принципы:
-
Безопасность и надёжность: Все операции, особенно требующие прав
sudo, спроектированы так, чтобы быть максимально безопасными. Мы избегаем прямых вызовов системных команд в пользу обёрток изsrc/system/privileges.py, которые используют безопасный механизмSUDO_ASKPASS. Перед выполнением деструктивных действий (например, удаление пакетов) выполняются проверки зависимостей. -
Отзывчивый интерфейс: Ни одна операция не должна "замораживать" приложение. Все длительные задачи (сетевые запросы, установка пакетов, системные проверки) выполняются в отдельных потоках (
threading.Thread), а результаты безопасно передаются в основной поток GTK черезGLib.idle_add. -
Разделение логики: Код чётко разделён на:
- Вкладки (
src/tabs/): Каждая вкладка — отдельный модуль; сложные вкладки разбиты на подпакеты (например,src/tabs/timesync/). - UI-компоненты (
src/ui/): Переиспользуемые виджеты, диалоги, движок Data-Driven UI. - Бэкенд (
src/core/): Системная логика, выполнение команд, проверки. Фасадsrc/core/backend.py— единая точка входа для вкладок.
- Вкладки (
-
Data-Driven UI: Значительная часть интерфейса (вкладки "Обслуживание", "AMD", "Терминал") и каталоги (список приложений) не закодированы жёстко, а генерируются "на лету" из JSON-файлов в
src/modules/. Движок находится вsrc/ui/dynamic_page.py. Это позволяет легко добавлять новые твики и приложения, не трогая основной код на Python.
altbooster/
├── icons/ # Графические ресурсы (иконки .svg, .png)
├── src/ # Исходный код приложения
│ ├── altbooster.py # Точка входа в приложение
│ ├── core/ # Бэкенд-модули для взаимодействия с системой
│ │ ├── backend.py # Фасад, единая точка входа для вкладок
│ │ ├── checks.py # Функции проверки состояния системы
│ │ ├── config.py # Пути, версия, константы
│ │ ├── gsettings.py # Обёртки для gsettings/dconf
│ │ ├── packages.py # Логика epm и flatpak
│ │ ├── privileges.py # Безопасное выполнение команд через sudo/pkexec
│ │ └── tweaks.py # Реализация системных твиков
│ ├── modules/ # JSON-файлы, описывающие UI для Data-Driven страниц
│ ├── tabs/ # Модули вкладок приложения
│ │ ├── apps.py # Вкладка «Приложения»
│ │ ├── extensions.py # Вкладка «Расширения GNOME»
│ │ ├── flatpak.py # Вкладка «Flatpak»
│ │ ├── maintenance.py # Вкладка «Обслуживание»
│ │ ├── amd.py / amd_actions.py
│ │ ├── terminal.py / terminal_actions.py
│ │ └── timesync/ # Вкладка «Резервная копия» (BorgBackup)
│ │ ├── page.py # Главная страница; логика Borg/Btrfs — в core/borg.py, core/btrfs.py
│ │ ├── mirror.py, manual.py, restore.py, pickers.py, summary.py
│ └── ui/ # Переиспользуемые UI-компоненты
│ ├── window.py # Главное окно приложения
│ ├── dynamic_page.py # Движок, генерирующий UI на основе JSON
│ ├── dialogs.py # Кастомные диалоговые окна
│ ├── rows.py # Переиспользуемые Adw.ActionRow / Adw.ExpanderRow
│ └── widgets.py # Фабрики стандартных виджетов GTK
├── install.sh # Скрипт установки
├── uninstall.sh # Скрипт удаления
└── pyproject.toml # Метаданные проекта и зависимости (PEP 621)
Каталог приложений находится в src/modules/apps.json. Чтобы добавить новое приложение, найдите подходящую группу (например, "id": "browsers") и добавьте новый объект в массив items.
Структура объекта приложения:
id: Уникальный идентификатор (латиница,snake_case).label: Человекочитаемое название.desc: Краткое описание.sources: Список источников установки. Приложение может иметь несколько способов установки (например, Flatpak и EPM).
Структура источника (source):
label: Текст для бейджа в UI (например, "Flathub", "EPM").cmd: Команда для установки в виде списка аргументов.check: Команда для проверки, установлено ли приложение. Состоит из типа проверки и значения.
Примеры:
// Пример для Flatpak
{
"id": "telegram",
"label": "Telegram Desktop",
"desc": "Официальный клиент Telegram",
"sources": [
{
"label": "Flathub",
"cmd": ["flatpak", "install", "-y", "flathub", "org.telegram.desktop"],
"check": ["flatpak", "org.telegram.desktop"]
}
]
}
// Пример для EPM (RPM-пакет)
{
"id": "gimp",
"label": "GIMP",
"desc": "Графический редактор",
"sources": [
{
"label": "EPM",
"cmd": ["epm", "-i", "-y", "gimp"],
"check": ["rpm", "gimp"]
}
]
}Задачи обслуживания находятся в src/modules/maintenance.json. Просто добавьте новый объект в массив tasks.
Структура объекта задачи:
id: Уникальный идентификатор.icon: Имя иконки Adwaita (например,utilities-terminal-symbolic).label: Название задачи.desc: Краткое описание.cmd: Команда для выполнения. По умолчанию выполняется черезsudo.type(опционально): Если указать"user", команда будет выполнена от имени текущего пользователя безsudo.check(опционально): Объект для проверки, выполнена ли задача. Если проверка проходит, кнопка будет неактивна.
Пример:
{
"id": "clear_temp",
"icon": "user-trash-symbolic",
"label": "Очистить /tmp",
"desc": "Удаляет временные файлы из /tmp",
"cmd": ["rm", "-rf", "/tmp/*"],
"check": {
"type": "path_empty", // вымышленный тип, для примера
"value": "/tmp"
}
}Проект использует ruff для форматирования и линтинга. Перед коммитом, пожалуйста, выполните проверку:
# Установка (если не установлен)
pip install ruff
# Проверка кода
ruff check src/- Максимальная длина строки — 100 символов.
bare except(except:) запрещён — всегда указывайте тип исключения (except OSError:).- Комментарии и docstring не нужны — код должен быть самодокументируемым.
- Сделайте форк репозитория.
- Создайте новую ветку для вашей фичи:
git checkout -b feat/my-awesome-feature. - Внесите изменения и проверьте код с помощью
ruff. - Отправьте Pull Request, подробно описав, что и зачем вы изменили.
Спасибо за ваш вклад в улучшение ALT Booster!