mirror of
https://github.com/EDeev/y.calendarkin.git
synced 2026-10-08 00:39:27 +03:00
README на русском и английском
This commit is contained in:
parent
73690afd8f
commit
5fdf39e0b5
2 changed files with 157 additions and 105 deletions
88
README.en.md
Normal file
88
README.en.md
Normal file
|
|
@ -0,0 +1,88 @@
|
||||||
|
# Y.Calendarkin
|
||||||
|
|
||||||
|
[Русский](README.md) · **English**
|
||||||
|
|
||||||
|
[](https://github.com/EDeev/y.calendarkin/actions/workflows/ci.yml)
|
||||||
|
[](https://github.com/EDeev/y.calendarkin/actions/workflows/docker.yml)
|
||||||
|
[](LICENSE)
|
||||||
|
|
||||||
|
A Telegram bot that sends notifications about Yandex Calendar events: a morning summary for the day, two
|
||||||
|
reminders before an event and a message when it starts. All it needs is the calendar's export link. The
|
||||||
|
bot speaks Russian.
|
||||||
|
|
||||||
|
**Status:** personal project, maintained · bot [@calendarkin_ybot](https://t.me/calendarkin_ybot)
|
||||||
|
|
||||||
|
**Stack:** Python 3.12 · aiogram 3 · aiohttp · icalendar · python-dateutil · pytz · SQLite · Docker
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- Subscription by iCal export link; the time zone is taken from the link
|
||||||
|
- Recurring events (`RRULE`) are expanded for today
|
||||||
|
- A day summary at 8:00 in the calendar's time zone (`/daily`)
|
||||||
|
- Two reminders before an event: 15 and 5 minutes by default, changed with `/edit_alarm`
|
||||||
|
- A message when an event starts (`/moment`)
|
||||||
|
- The calendar is refreshed every 13 minutes; if a refresh fails, the previous version stays
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
| Command | What it does |
|
||||||
|
|---|---|
|
||||||
|
| `/link` | how to get the calendar link |
|
||||||
|
| `/list` | today's events |
|
||||||
|
| `/daily` | toggle the morning summary |
|
||||||
|
| `/moment` | toggle the message at event start |
|
||||||
|
| `/get_alarm`, `/edit_alarm` | view and change reminder times |
|
||||||
|
| `/stop_alarm` | toggle the second reminder |
|
||||||
|
| `/notif` | pause or resume all notifications |
|
||||||
|
| `/unsubscribe` | remove the calendar subscription |
|
||||||
|
|
||||||
|
## Running
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/EDeev/y.calendarkin.git && cd y.calendarkin
|
||||||
|
cp .env.example .env # BOT_TOKEN from @BotFather
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
Prebuilt image: `docker pull ghcr.io/edeev/y.calendarkin` or `docker pull dcr.deev.su/edeev/y.calendarkin`.
|
||||||
|
The SQLite databases are created on first start.
|
||||||
|
|
||||||
|
Without Docker: Python 3.12, `pip install -r requirements.txt`, then `cd code && BOT_TOKEN=… python bot.py`.
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
```
|
||||||
|
code/bot.py entry point and two background loops: event checks every minute, calendar refresh
|
||||||
|
code/handlers.py commands and receiving the link
|
||||||
|
code/script.py link validation, download, iCal and recurrence parsing, notification text
|
||||||
|
code/sql.py users, subscriptions and reminder settings (SQLite)
|
||||||
|
```
|
||||||
|
|
||||||
|
Only `https://calendar.yandex.*` links are accepted, so the bot never downloads from arbitrary addresses.
|
||||||
|
An error for one user (a broken calendar or a blocked bot) doesn't stop notifications for others.
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r requirements-dev.txt
|
||||||
|
ruff check --select E9,F code tests && pytest
|
||||||
|
```
|
||||||
|
|
||||||
|
The tests cover calendar parsing: today's events, recurrences, `UNTIL` in different formats, link
|
||||||
|
validation and the notification text. The Docker image is built on `v*` tags and published to GitHub
|
||||||
|
Packages and `dcr.deev.su`.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT — see [LICENSE](LICENSE).
|
||||||
|
|
||||||
|
## Author
|
||||||
|
|
||||||
|
**Egor Deev** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
<sub>⭐ If you find this project useful, give it a star on GitHub!</sub>
|
||||||
|
<p><sub>Made with ❤️ — <a href="https://deev.space">deev.space</a></sub></p>
|
||||||
|
</div>
|
||||||
174
README.md
174
README.md
|
|
@ -1,136 +1,100 @@
|
||||||
# 🗓️ Y.Calendarkin
|
# Я.Календаркин
|
||||||
|
|
||||||
Telegram-бот для упрощенного получения уведомлений о событиях из Яндекс.Календаря.
|
**Русский** · [English](README.en.md)
|
||||||
|
|
||||||
[](https://python.org)
|
[](https://github.com/EDeev/y.calendarkin/actions/workflows/ci.yml)
|
||||||
[](https://docs.aiogram.dev/)
|
[](https://github.com/EDeev/y.calendarkin/actions/workflows/docker.yml)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
|
|
||||||
## 📖 Описание
|
Telegram-бот, который присылает уведомления о событиях из Яндекс.Календаря: утреннюю сводку на день,
|
||||||
|
два напоминания перед событием и сообщение в момент начала. Достаточно прислать ссылку экспорта календаря.
|
||||||
|
|
||||||
Y.Calendarkin — некоммерческий проект, предназначенный для автоматизации уведомлений о календарных событиях из Яндекс.Календаря через Telegram. Бот позволяет настроить гибкую систему напоминаний и получать актуальную информацию о предстоящих событиях.
|
**Статус:** личный проект, поддерживается · бот [@calendarkin_ybot](https://t.me/calendarkin_ybot)
|
||||||
|
|
||||||
## ✨ Основные возможности
|
**Стек:** Python 3.12 · aiogram 3 · aiohttp · icalendar · python-dateutil · pytz · SQLite · Docker
|
||||||
|
|
||||||
- 📅 **Импорт календаря** — поддержка ICal ссылок из Яндекс.Календаря
|
## Возможности
|
||||||
- ⏰ **Гибкие уведомления** — настройка времени напоминаний (до 60 минут)
|
|
||||||
- 🌅 **Ежедневные отчеты** — утренние сводки событий на день
|
|
||||||
- 🎯 **Моментальные уведомления** — оповещения в момент начала события
|
|
||||||
- 🌍 **Поддержка часовых поясов** — автоматическое определение из календаря
|
|
||||||
- 📋 **Просмотр событий** — список мероприятий на текущий день
|
|
||||||
|
|
||||||
## 🛠️ Технологический стек
|
- Подписка по ссылке экспорта iCal; часовой пояс берётся из ссылки
|
||||||
|
- Повторяющиеся события (`RRULE`) разворачиваются на сегодняшний день
|
||||||
|
- Сводка на день в 8:00 по часовому поясу календаря (`/daily`)
|
||||||
|
- Два напоминания перед событием: по умолчанию за 15 и 5 минут, меняются в `/edit_alarm`
|
||||||
|
- Сообщение в момент начала события (`/moment`)
|
||||||
|
- Календарь обновляется раз в 13 минут; если обновление не удалось, остаётся прошлая версия
|
||||||
|
|
||||||
- **Backend**: Python 3.8+
|
Пример уведомления:
|
||||||
- **Bot Framework**: Aiogram 3.x
|
|
||||||
- **Database**: SQLite
|
|
||||||
- **Calendar Processing**: icalendar, dateutil
|
|
||||||
- **HTTP Client**: wget
|
|
||||||
- **Timezone Support**: pytz
|
|
||||||
|
|
||||||
## 🚀 Установка и запуск
|
```
|
||||||
|
Напоминаю!
|
||||||
|
Через 15 минут будет событие:
|
||||||
|
|
||||||
### Предварительные требования
|
Созвон по проекту
|
||||||
|
Организатор: boss@example.com
|
||||||
|
|
||||||
|
10:00 — 11:00
|
||||||
|
```
|
||||||
|
|
||||||
|
## Команды
|
||||||
|
|
||||||
|
| Команда | Что делает |
|
||||||
|
|---|---|
|
||||||
|
| `/link` | как получить ссылку на календарь |
|
||||||
|
| `/list` | события на сегодня |
|
||||||
|
| `/daily` | включить или выключить утреннюю сводку |
|
||||||
|
| `/moment` | включить или выключить сообщение в момент начала |
|
||||||
|
| `/get_alarm`, `/edit_alarm` | посмотреть и изменить время напоминаний |
|
||||||
|
| `/stop_alarm` | включить или выключить второе напоминание |
|
||||||
|
| `/notif` | приостановить или возобновить все уведомления |
|
||||||
|
| `/unsubscribe` | удалить подписку на календарь |
|
||||||
|
|
||||||
|
## Запуск
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install -r requirements.txt
|
git clone https://github.com/EDeev/y.calendarkin.git && cd y.calendarkin
|
||||||
|
cp .env.example .env # BOT_TOKEN от @BotFather
|
||||||
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
### Настройка
|
Готовый образ: `docker pull ghcr.io/edeev/y.calendarkin` или `docker pull dcr.deev.su/edeev/y.calendarkin`.
|
||||||
|
Базы SQLite создаются при первом запуске.
|
||||||
|
|
||||||
1. Создайте нового бота через [@BotFather](https://t.me/BotFather)
|
Без Docker: Python 3.12, `pip install -r requirements.txt`, затем `cd code && BOT_TOKEN=… python bot.py`.
|
||||||
2. Получите токен и добавьте его в `config.py`:
|
|
||||||
|
|
||||||
```python
|
## Как устроено
|
||||||
TOKEN = "your_bot_token_here"
|
|
||||||
|
```
|
||||||
|
code/bot.py запуск и два фоновых цикла: проверка событий раз в минуту, обновление календарей
|
||||||
|
code/handlers.py команды и приём ссылки
|
||||||
|
code/script.py проверка ссылки, скачивание, разбор iCal и повторений, текст уведомления
|
||||||
|
code/sql.py пользователи, подписки и настройки напоминаний (SQLite)
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Создайте структуру каталогов:
|
Принимаются только ссылки `https://calendar.yandex.*`: бот не скачивает файлы по произвольным адресам.
|
||||||
|
Ошибка у одного пользователя — битый календарь или заблокированный бот — не останавливает рассылку
|
||||||
|
остальным.
|
||||||
|
|
||||||
|
## Разработка
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mkdir -p data/icals db
|
pip install -r requirements-dev.txt
|
||||||
|
ruff check --select E9,F code tests && pytest
|
||||||
```
|
```
|
||||||
|
|
||||||
### Запуск
|
Тесты проверяют разбор календаря: события на сегодня, повторения, `UNTIL` в разных форматах, проверку
|
||||||
|
ссылки и текст уведомления. Docker-образ собирается по тегу `v*` и публикуется в GitHub Packages и
|
||||||
|
`dcr.deev.su`.
|
||||||
|
|
||||||
```bash
|
## Лицензия
|
||||||
cd code
|
|
||||||
python bot.py
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📝 Использование
|
MIT — см. [LICENSE](LICENSE).
|
||||||
|
|
||||||
### Начало работы
|
## Автор
|
||||||
|
|
||||||
1. Запустите бота командой `/start`
|
**Деев Егор Викторович** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space)
|
||||||
2. Отправьте ICal ссылку вашего Яндекс.Календаря
|
|
||||||
3. Настройте уведомления по своему усмотрению
|
|
||||||
|
|
||||||
### Основные команды
|
|
||||||
|
|
||||||
| Команда | Описание |
|
|
||||||
|---------|----------|
|
|
||||||
| `/help` | Справочная информация |
|
|
||||||
| `/list` | События на сегодня |
|
|
||||||
| `/notif` | Включить/выключить уведомления |
|
|
||||||
| `/daily` | Ежедневные утренние сводки |
|
|
||||||
| `/moment` | Уведомления в момент события |
|
|
||||||
| `/get_alarm` | Информация о текущих настройках |
|
|
||||||
| `/edit_alarm` | Изменение времени уведомлений |
|
|
||||||
| `/stop_alarm` | Отключение второго уведомления |
|
|
||||||
|
|
||||||
### Получение ICal ссылки
|
|
||||||
|
|
||||||
1. Откройте Яндекс.Календарь
|
|
||||||
2. Перейдите в настройки календаря
|
|
||||||
3. Найдите раздел "Экспорт"
|
|
||||||
4. Скопируйте ссылку в формате ICal
|
|
||||||
5. Отправьте ссылку боту
|
|
||||||
|
|
||||||
## 🏗️ Архитектура проекта
|
|
||||||
|
|
||||||
```
|
|
||||||
y.calendarkin/
|
|
||||||
├── code/
|
|
||||||
│ ├── bot.py # Основная логика бота
|
|
||||||
│ ├── config.py # Конфигурация
|
|
||||||
│ ├── script.py # Обработка календарных файлов
|
|
||||||
│ └── sql.py # Работа с базой данных
|
|
||||||
├── data/
|
|
||||||
│ ├── icals/ # Загруженные календари
|
|
||||||
│ └── photo_edit_alarm.jpg
|
|
||||||
├── db/ # База данных SQLite
|
|
||||||
└── requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📊 База данных
|
|
||||||
|
|
||||||
Проект использует две основные таблицы:
|
|
||||||
|
|
||||||
- **user** — информация о пользователях и их календарях
|
|
||||||
- **alarm** — настройки уведомлений для каждого пользователя
|
|
||||||
|
|
||||||
## 🔧 Настройка уведомлений
|
|
||||||
|
|
||||||
- **Первое уведомление**: за 15 минут до события (по умолчанию)
|
|
||||||
- **Второе уведомление**: за 5 минут до события (по умолчанию)
|
|
||||||
- **Диапазон настройки**: от 1 до 59 минут
|
|
||||||
- **Ежедневные сводки**: в 8:00 по часовому поясу пользователя
|
|
||||||
|
|
||||||
## 📄 Лицензия
|
|
||||||
|
|
||||||
Этот проект является некоммерческим и распространяется под лицензией MIT.
|
|
||||||
|
|
||||||
## 👨💻 Автор
|
|
||||||
|
|
||||||
**Деев Егор Викторович** - Backend Developer
|
|
||||||
- GitHub: [@EDeev](https://github.com/EDeev)
|
|
||||||
- Email: egor@deev.space
|
|
||||||
- Telegram: [@Egor_Deev](https://t.me/Egor_Deev)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
<div align="center">
|
<div align="center">
|
||||||
<sub>Этот бот предназначен для личного использования и не является коммерческим продуктом.</sub>
|
<sub>⭐ Если проект оказался полезным, поставьте звёздочку на GitHub!</sub>
|
||||||
<p><sub>Создано с ❤️ от вашего дорогого - deev.space ©</sub></p>
|
<p><sub>Сделано с ❤️ — <a href="https://deev.space">deev.space</a></sub></p>
|
||||||
</div>
|
</div>
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue