Linear Notifier

Нативное Linux desktop приложение для Ubuntu/GNOME, которое интегрируется с Linear API для показа desktop уведомлений и простого UI.

Требования

• Python 3.10+
• Ubuntu/GNOME с GTK 4
• Системные зависимости:

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-ayatanaappindicator3-0.1 libnotify4 python3-xlib

Примечание: python3-xlib требуется для работы системного трея через pystray (X11 backend). Если иконка не появляется в трее, убедитесь, что этот пакет установлен.

Установка

Перед установкой пакета установите системные зависимости:

sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-ayatanaappindicator3-0.1 libnotify4 python3-xlib

Примечание: python3-xlib требуется для работы системного трея через pystray (X11 backend). Если иконка не появляется в трее, убедитесь, что этот пакет установлен.

Без этих зависимостей установка пакета через pip/pipx завершится ошибкой, так как PyGObject требует системных библиотек и должен устанавливаться через apt, а не через pip.

1. Клонируйте репозиторий или скачайте проект

2. Установите Python зависимости. Выберите один из способов:

Вариант 1: Использование pipx (рекомендуется для приложений)

# Установите pipx если еще не установлен
sudo apt install pipx
pipx ensurepath

# Установите приложение с доступом к системным пакетам
pipx install --system-site-packages .

# После установки установите desktop файл и иконки в главное меню
linear-notifier-install-desktop

Примечание:

• Флаг --system-site-packages необходим для доступа к системным пакетам (python3-gi и т.д.)
• Важно: После установки через pipx запустите linear-notifier-install-desktop для установки desktop файла и иконок в главное меню (pipx не поддерживает автоматическую установку desktop файлов)
• Для разработки используйте Вариант 2 (виртуальное окружение), так как pipx не поддерживает editable install (-e)
• Если возникают проблемы с pipx, используйте Вариант 2 (venv)

Вариант 2: Использование виртуального окружения

# Создайте виртуальное окружение с доступом к системным пакетам
python3 -m venv --system-site-packages venv

# Активируйте его
source venv/bin/activate

# Установите пакет
pip install -e .

Примечание: Флаг --system-site-packages необходим для доступа к системным пакетам (python3-gi и т.д.)

Вариант 3: Принудительная установка (не рекомендуется)

Если вы уверены в своих действиях, можете использовать флаг --break-system-packages:

pip install --user -e . --break-system-packages

⚠️ Использование --break-system-packages может нарушить системную установку Python. Рекомендуется использовать pipx или виртуальное окружение.

После установки приложение будет доступно как linear-notifier в PATH (при использовании pipx) или через venv/bin/linear-notifier (при использовании venv).

Примечание о desktop файле и иконках:

• При установке через pip install -e . (venv) desktop файл и иконки устанавливаются автоматически через post-install hook
• При установке через pipx нужно вручную запустить linear-notifier-install-desktop после установки (pipx не поддерживает post-install hooks)
• Desktop файл также будет установлен автоматически при первом запуске приложения через ensure_desktop_file()

Использование

Перед первым запуском убедитесь, что:

1. PATH обновлен (выполните pipx ensurepath и перезапустите терминал, или используйте полный путь ~/.local/bin/linear-notifier)
2. Все системные зависимости установлены (см. раздел "Требования")

Запустите приложение:

linear-notifier

Если команда не найдена, используйте полный путь:

~/.local/bin/linear-notifier

Или обновите PATH в текущей сессии:

export PATH="$HOME/.local/bin:$PATH"
linear-notifier

При первом запуске откроется окно настроек, где нужно ввести ваш Linear API токен. Токен будет сохранен в GNOME Keyring.

После сохранения токена приложение запустится в фоновом режиме. Откройте приложение через главное меню для просмотра уведомлений.

Приложение автоматически проверяет новые уведомления каждую минуту и показывает desktop уведомления для непрочитанных.

Главное окно:

• Отображает последние 25 уведомлений
• Список уведомлений обновляется автоматически каждую минуту, пока окно открыто
• Список обновляется сразу при обнаружении новых уведомлений в фоновом режиме
• Кнопка "Обновить" не требуется - обновление происходит автоматически

Удаление

Если установлено через pipx:

pipx uninstall linear-notifier

Это удалит:

• Пакет и все его зависимости из изолированного окружения pipx
• Символическую ссылку из ~/.local/bin/linear-notifier

Примечание: Desktop файл, иконки и токен в GNOME Keyring останутся. Удалите их вручную, если нужно:

# Удалить desktop файл
rm ~/.local/share/applications/com.example.LinearNotifier.desktop

# Удалить иконки
rm -rf ~/.local/share/icons/hicolor/*/apps/com.example.LinearNotifier.*

# Обновить кэш иконок
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor

# Токен в GNOME Keyring можно удалить через приложение "Пароли и ключи" (Seahorse)
# или оставить - он не занимает много места

Если установлено через venv:

# Просто удалите виртуальное окружение
rm -rf venv

Если установлено через --break-system-packages:

pip uninstall linear-notifier

Получение Linear API токена

1. Откройте Linear Settings → Security & access
2. Создайте Personal API Key
3. Скопируйте токен и вставьте в окно настроек приложения

Особенности

• Безопасное хранение токена в GNOME Keyring
• Desktop уведомления для новых непрочитанных уведомлений
• Главное окно с отображением последних 25 уведомлений
• Автоматическое обновление списка уведомлений:
  • Каждую минуту, пока главное окно открыто (соответствует ограничениям Linear API)
  • Сразу при обнаружении новых уведомлений в фоновом режиме
• Фоновый polling новых уведомлений каждую минуту
• Проверка системных зависимостей при запуске
• Автоматическая установка в главное меню рабочего стола

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

linear_push/
├── pyproject.toml
├── README.md
├── linear_notifier/
│   ├── __init__.py
│   ├── main.py          # Точка входа
│   ├── app.py           # Главное приложение
│   ├── keyring_manager.py  # Работа с GNOME Keyring
│   ├── linear_api.py    # Клиент Linear API
│   ├── settings_window.py  # Окно настроек
│   ├── main_window.py   # Главное окно
│   └── data/
│       ├── ui/
│       │   ├── settings.ui  # UI файл для настроек
│       │   └── main.ui      # UI файл для главного окна
│       └── com.example.LinearNotifier.desktop

Разработка

Для разработки рекомендуется использовать виртуальное окружение с editable install:

# Создайте виртуальное окружение с доступом к системным пакетам
python3 -m venv --system-site-packages venv

# Активируйте его
source venv/bin/activate

# Установите пакет в режиме разработки
pip install -e .

# Теперь изменения в коде будут сразу видны без переустановки

Примечание: Флаг --system-site-packages необходим для доступа к системным пакетам (python3-gi и т.д.)

UI файлы созданы для совместимости с Cambalache. Вы можете редактировать их в Cambalache для изменения дизайна.

Деинсталляция

pipx uninstall linear-notifier