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://docs.aiogram.dev/)
|
||||
[](LICENSE)
|
||||
[](https://github.com/EDeev/y.calendarkin/actions/workflows/ci.yml)
|
||||
[](https://github.com/EDeev/y.calendarkin/actions/workflows/docker.yml)
|
||||
[](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
|
||||
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)
|
||||
2. Получите токен и добавьте его в `config.py`:
|
||||
Без Docker: Python 3.12, `pip install -r requirements.txt`, затем `cd code && BOT_TOKEN=… python bot.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
|
||||
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`
|
||||
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)
|
||||
**Деев Егор Викторович** — [GitHub](https://github.com/EDeev) · [Telegram](https://t.me/DeevEgor) · [egor@deev.space](mailto:egor@deev.space)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<sub>Этот бот предназначен для личного использования и не является коммерческим продуктом.</sub>
|
||||
<p><sub>Создано с ❤️ от вашего дорогого - deev.space ©</sub></p>
|
||||
<sub>⭐ Если проект оказался полезным, поставьте звёздочку на GitHub!</sub>
|
||||
<p><sub>Сделано с ❤️ — <a href="https://deev.space">deev.space</a></sub></p>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue