pynotegram 0.3.0__tar.gz

pynotegram-0.3.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ipynb_checkpoints/

pynotegram-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serghei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pynotegram-0.3.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: pynotegram
+Version: 0.3.0
+Summary: Send simple Telegram notifications from Jupyter notebooks.
+Author: Serghei
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ipython,jupyter,notebook,notifications,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx[socks]<1,>=0.27
+Requires-Dist: ipython>=8
+Provides-Extra: relay
+Requires-Dist: fastapi>=0.115; extra == 'relay'
+Requires-Dist: uvicorn>=0.30; extra == 'relay'
+Description-Content-Type: text/markdown
+
+# PyNoteGram
+
+PyNoteGram отправляет сообщения из Jupyter в **один выбранный Telegram-чат**.
+
+После первой настройки в ноутбуках больше не нужно писать токен или `chat_id`.
+
+## Что нужно сделать
+
+### 1. Создать бота
+
+В Telegram откройте `@BotFather`, отправьте `/newbot` и сохраните полученный
+токен. Токен является паролем бота.
+
+### 2. Создать отдельную группу
+
+1. Создайте новую группу в Telegram, например **Мои расчеты**.
+2. Добавьте туда созданного бота.
+3. Напишите в группе `/start`.
+
+### 3. Установить и настроить PyNoteGram
+
+```powershell
+pip install pynotegram
+pynotegram setup
+```
+
+Во время настройки программа один раз попросит токен от BotFather. После этого
+она сама найдет группу, запомнит ее и отправит проверочное сообщение.
+
+## Использование в Jupyter
+
+Настроить библиотеку можно прямо в Jupyter:
+
+```python
+from pynotegram import setup
+
+setup()
+```
+
+Под ячейкой появится скрытое поле для токена. После проверки бот попросит
+отправить в группе команду вида `/start@NLP_bot` и подождет появления группы.
+
+После настройки перезапустите Jupyter. В любой ячейке можно написать:
+
+```python
+%telegram Расчет закончен!
+```
+
+## Получение сообщений из Telegram
+
+Запустите в Jupyter ячейку:
+
+```python
+%telegram_read 30
+```
+
+Она будет ждать сообщение из сохраненной группы до 30 секунд. Сообщения из
+других чатов игнорируются.
+
+Для постоянного ожидания в течение десяти минут:
+
+```python
+%telegram_watch 10
+```
+
+Новые сообщения будут появляться под ячейкой сразу после отправки. Остановить
+ожидание можно кнопкой прерывания ядра Jupyter.
+
+Чтобы код отображался с подсветкой, отправьте его в Telegram так:
+
+````text
+```python
+def hello():
+    print("Привет")
+```
+````
+
+В Jupyter он появится как отдельный блок Python-кода. Полученный код только
+показывается и никогда не запускается автоматически.
+
+Сообщение придет только в группу, выбранную во время настройки.
+
+Для многострочного сообщения:
+
+```python
+%%telegram
+Обучение модели закончено.
+Точность: 94%.
+```
+
+Также можно использовать обычный Python:
+
+```python
+from pynotegram import send
+
+send("Расчет закончен!")
+```
+
+## Если нужен VPN
+
+Включите VPN перед запуском `pynotegram setup` и Jupyter.
+
+Если есть отдельный SOCKS5-прокси:
+
+```powershell
+pynotegram setup --proxy "socks5://ЛОГИН:ПАРОЛЬ@АДРЕС:ПОРТ"
+```
+
+## Проверка
+
+Отправить сообщение без Jupyter:
+
+```powershell
+pynotegram send "Проверка"
+```
+
+Посмотреть сохраненный чат:
+
+```powershell
+pynotegram status
+```
+
+Чтобы выбрать другую группу, снова выполните `pynotegram setup`.
+
+## Важное ограничение
+
+Совсем обойтись только командой `pip install` нельзя: программа должна хотя бы
+один раз получить токен вашего бота и узнать, какую группу выбрать. Поэтому
+`pynotegram setup` выполняется один раз. В самих ноутбуках настройки больше не
+потребуются.
+
+## Безопасность
+
+- Никогда не публикуйте токен Telegram-бота и токен PyPI.
+- Если токен Telegram попал в переписку, Git или ноутбук, отзовите его через
+  `@BotFather` и создайте новый.
+- Код из Telegram отображается в Jupyter, но не запускается автоматически.
+
+## Лицензия
+
+MIT

pynotegram-0.3.0/README.md

@@ -0,0 +1,141 @@
+# PyNoteGram
+
+PyNoteGram отправляет сообщения из Jupyter в **один выбранный Telegram-чат**.
+
+После первой настройки в ноутбуках больше не нужно писать токен или `chat_id`.
+
+## Что нужно сделать
+
+### 1. Создать бота
+
+В Telegram откройте `@BotFather`, отправьте `/newbot` и сохраните полученный
+токен. Токен является паролем бота.
+
+### 2. Создать отдельную группу
+
+1. Создайте новую группу в Telegram, например **Мои расчеты**.
+2. Добавьте туда созданного бота.
+3. Напишите в группе `/start`.
+
+### 3. Установить и настроить PyNoteGram
+
+```powershell
+pip install pynotegram
+pynotegram setup
+```
+
+Во время настройки программа один раз попросит токен от BotFather. После этого
+она сама найдет группу, запомнит ее и отправит проверочное сообщение.
+
+## Использование в Jupyter
+
+Настроить библиотеку можно прямо в Jupyter:
+
+```python
+from pynotegram import setup
+
+setup()
+```
+
+Под ячейкой появится скрытое поле для токена. После проверки бот попросит
+отправить в группе команду вида `/start@NLP_bot` и подождет появления группы.
+
+После настройки перезапустите Jupyter. В любой ячейке можно написать:
+
+```python
+%telegram Расчет закончен!
+```
+
+## Получение сообщений из Telegram
+
+Запустите в Jupyter ячейку:
+
+```python
+%telegram_read 30
+```
+
+Она будет ждать сообщение из сохраненной группы до 30 секунд. Сообщения из
+других чатов игнорируются.
+
+Для постоянного ожидания в течение десяти минут:
+
+```python
+%telegram_watch 10
+```
+
+Новые сообщения будут появляться под ячейкой сразу после отправки. Остановить
+ожидание можно кнопкой прерывания ядра Jupyter.
+
+Чтобы код отображался с подсветкой, отправьте его в Telegram так:
+
+````text
+```python
+def hello():
+    print("Привет")
+```
+````
+
+В Jupyter он появится как отдельный блок Python-кода. Полученный код только
+показывается и никогда не запускается автоматически.
+
+Сообщение придет только в группу, выбранную во время настройки.
+
+Для многострочного сообщения:
+
+```python
+%%telegram
+Обучение модели закончено.
+Точность: 94%.
+```
+
+Также можно использовать обычный Python:
+
+```python
+from pynotegram import send
+
+send("Расчет закончен!")
+```
+
+## Если нужен VPN
+
+Включите VPN перед запуском `pynotegram setup` и Jupyter.
+
+Если есть отдельный SOCKS5-прокси:
+
+```powershell
+pynotegram setup --proxy "socks5://ЛОГИН:ПАРОЛЬ@АДРЕС:ПОРТ"
+```
+
+## Проверка
+
+Отправить сообщение без Jupyter:
+
+```powershell
+pynotegram send "Проверка"
+```
+
+Посмотреть сохраненный чат:
+
+```powershell
+pynotegram status
+```
+
+Чтобы выбрать другую группу, снова выполните `pynotegram setup`.
+
+## Важное ограничение
+
+Совсем обойтись только командой `pip install` нельзя: программа должна хотя бы
+один раз получить токен вашего бота и узнать, какую группу выбрать. Поэтому
+`pynotegram setup` выполняется один раз. В самих ноутбуках настройки больше не
+потребуются.
+
+## Безопасность
+
+- Никогда не публикуйте токен Telegram-бота и токен PyPI.
+- Если токен Telegram попал в переписку, Git или ноутбук, отзовите его через
+  `@BotFather` и создайте новый.
+- Код из Telegram отображается в Jupyter, но не запускается автоматически.
+
+## Лицензия
+
+MIT

pynotegram-0.3.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pynotegram"
+version = "0.3.0"
+description = "Send simple Telegram notifications from Jupyter notebooks."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Serghei" },
+]
+keywords = ["telegram", "jupyter", "notebook", "notifications", "ipython"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "httpx[socks]>=0.27,<1",
+    "ipython>=8",
+]
+
+[project.optional-dependencies]
+relay = ["fastapi>=0.115", "uvicorn>=0.30"]
+
+[project.scripts]
+pynotegram = "pynotegram.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pynotegram"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pynotegram",
+    "tests",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+]

pynotegram-0.3.0/src/pynotegram/__init__.py

@@ -0,0 +1,63 @@
+from .notifier import PyNoteGram, TelegramError
+from .receiver import read, watch
+
+__all__ = [
+    "PyNoteGram",
+    "TelegramError",
+    "send",
+    "read",
+    "watch",
+    "setup",
+    "load_ipython_extension",
+]
+
+
+def send(message: object):
+    """Send a message to the one chat selected during setup."""
+    with PyNoteGram.from_config() as notifier:
+        return notifier.send(message)
+
+
+def setup(*, token=None, chat_id=None, proxy=None):
+    """Configure PyNoteGram interactively inside Jupyter or regular Python."""
+    from .cli import setup_notebook
+
+    return setup_notebook(token=token, chat_id=chat_id, proxy=proxy)
+
+
+def load_ipython_extension(ipython):
+    """Register %telegram and %%telegram in IPython/Jupyter."""
+    from IPython.core.magic import Magics, line_cell_magic, magics_class
+    from IPython.core.magic import line_magic
+
+    @magics_class
+    class TelegramMagics(Magics):
+        @line_cell_magic
+        def telegram(self, line, cell=None):
+            message = cell if cell is not None else line
+            if not message.strip():
+                raise ValueError("Сообщение Telegram не может быть пустым")
+
+            notifier = PyNoteGram.from_config()
+            try:
+                return notifier.send(message)
+            finally:
+                notifier.close()
+
+        @line_magic
+        def telegram_read(self, line):
+            try:
+                wait = int(line.strip() or "30")
+            except ValueError:
+                raise ValueError("Укажите время ожидания в секундах, например: %telegram_read 30") from None
+            read(wait=wait, show=True)
+
+        @line_magic
+        def telegram_watch(self, line):
+            try:
+                minutes = float(line.strip() or "10")
+            except ValueError:
+                raise ValueError("Укажите минуты, например: %telegram_watch 10") from None
+            watch(minutes=minutes)
+
+    ipython.register_magics(TelegramMagics)

pynotegram-0.3.0/src/pynotegram/cli.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .config import ConfigError, config_path, load_config, save_config
+from .notifier import PyNoteGram, TelegramError
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="pynotegram",
+        description="Простые уведомления из Jupyter в один Telegram-чат.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    setup_parser = commands.add_parser("setup", help="настроить бота и один чат")
+    setup_parser.add_argument("--token", help="токен бота; безопаснее вводить без этого параметра")
+    setup_parser.add_argument("--chat-id", help="использовать указанный chat_id")
+    setup_parser.add_argument("--proxy", help="HTTP- или SOCKS5-прокси")
+    setup_parser.add_argument(
+        "--no-jupyter-startup",
+        action="store_true",
+        help="не подключать команду %%telegram автоматически",
+    )
+
+    send_parser = commands.add_parser("send", help="отправить тестовое сообщение")
+    send_parser.add_argument("message")
+
+    commands.add_parser("status", help="показать выбранный чат")
+
+    args = parser.parse_args()
+    try:
+        if args.command == "setup":
+            _setup(args)
+        elif args.command == "send":
+            _send(args.message)
+        elif args.command == "status":
+            _status()
+    except (ConfigError, TelegramError, ValueError) as error:
+        parser.exit(1, f"Ошибка: {error}\n")
+
+
+def _setup(args: argparse.Namespace) -> None:
+    token = args.token or getpass.getpass("Вставьте токен от BotFather: ").strip()
+    if not token:
+        raise ValueError("токен не может быть пустым")
+
+    with httpx.Client(proxy=args.proxy, timeout=20, follow_redirects=True) as client:
+        bot = _telegram_request(client, token, "getMe")
+        username = bot.get("username", "")
+        print(f"Бот найден: @{username}" if username else "Бот найден.")
+
+        if args.chat_id:
+            chats: dict[str, dict[str, str]] = {}
+        else:
+            command = f"/start@{username}" if username else "/start"
+            print("Теперь откройте нужную группу Telegram.")
+            print("Добавьте туда бота, если еще не добавили.")
+            print(f"Отправьте в группе команду: {command}")
+            print("Ожидаю сообщение из группы...")
+            chats = _wait_for_chats(client, token)
+
+        existing_updates = _telegram_request(
+            client,
+            token,
+            "getUpdates",
+            params={"timeout": 0},
+        )
+
+    update_offset = (
+        max(int(update["update_id"]) for update in existing_updates) + 1
+        if existing_updates
+        else 0
+    )
+
+    chat_id = str(args.chat_id) if args.chat_id else _choose_chat(chats)
+    path = save_config(
+        {
+            "token": token,
+            "chat_id": chat_id,
+            "proxy_url": args.proxy,
+            "update_offset": update_offset,
+        }
+    )
+
+    if not args.no_jupyter_startup:
+        startup = _install_jupyter_startup()
+        print(f"Команда %telegram подключена для Jupyter: {startup}")
+
+    with PyNoteGram.from_config() as notifier:
+        notifier.send("PyNoteGram настроен. Сообщения будут приходить только сюда.")
+
+    username = bot.get("username", "бот")
+    title = chats.get(chat_id, {}).get("title", chat_id)
+    print(f"Готово. Бот: @{username}. Чат: {title}.")
+    print(f"Настройки сохранены: {path}")
+
+
+def setup_notebook(
+    *,
+    token: str | None = None,
+    chat_id: str | int | None = None,
+    proxy: str | None = None,
+) -> None:
+    """Run the same one-time setup directly from a Jupyter cell."""
+    args = argparse.Namespace(
+        token=token,
+        chat_id=chat_id,
+        proxy=proxy,
+        no_jupyter_startup=False,
+    )
+    _setup(args)
+
+
+def _telegram_request(
+    client: httpx.Client,
+    token: str,
+    method: str,
+    *,
+    params: dict[str, Any] | None = None,
+) -> Any:
+    try:
+        response = client.get(
+            f"https://api.telegram.org/bot{token}/{method}",
+            params=params,
+        )
+        data = response.json()
+    except (httpx.RequestError, ValueError):
+        raise TelegramError(
+            "не удалось связаться с Telegram. Включите VPN или укажите --proxy"
+        ) from None
+
+    if response.is_error or data.get("ok") is not True:
+        raise TelegramError(data.get("description", "Telegram отклонил запрос"))
+    return data.get("result")
+
+
+def _wait_for_chats(
+    client: httpx.Client,
+    token: str,
+    *,
+    wait_seconds: int = 90,
+) -> dict[str, dict[str, str]]:
+    deadline = time.monotonic() + wait_seconds
+    offset = 0
+    while time.monotonic() < deadline:
+        updates = _telegram_request(
+            client,
+            token,
+            "getUpdates",
+            params={
+                "offset": offset,
+                "timeout": 10,
+                "allowed_updates": json.dumps(["message"]),
+            },
+        )
+        if updates:
+            offset = max(int(update["update_id"]) for update in updates) + 1
+        group_chats = {
+            chat_id: chat
+            for chat_id, chat in _find_chats(updates).items()
+            if chat.get("type") in {"group", "supergroup"}
+        }
+        if group_chats:
+            return group_chats
+
+    raise ValueError(
+        "группа не найдена за 90 секунд. Проверьте VPN и отправьте команду "
+        "/start@имя_бота именно в группе"
+    )
+
+
+def _find_chats(updates: list[dict[str, Any]]) -> dict[str, dict[str, str]]:
+    chats: dict[str, dict[str, str]] = {}
+    message_keys = ("message", "edited_message", "channel_post", "edited_channel_post")
+    for update in updates:
+        for key in message_keys:
+            chat = update.get(key, {}).get("chat")
+            if not chat or "id" not in chat:
+                continue
+            chat_id = str(chat["id"])
+            title = chat.get("title") or chat.get("username") or chat.get("first_name")
+            chats[chat_id] = {"title": str(title or chat_id), "type": chat.get("type", "")}
+    return chats
+
+
+def _choose_chat(chats: dict[str, dict[str, str]]) -> str:
+    if not chats:
+        raise ValueError(
+            "чат не найден. Добавьте бота в группу, напишите /start и повторите setup"
+        )
+    if len(chats) == 1:
+        return next(iter(chats))
+
+    print("Найдено несколько чатов:")
+    items = list(chats.items())
+    for number, (chat_id, chat) in enumerate(items, start=1):
+        print(f"  {number}. {chat['title']} ({chat_id})")
+    answer = input("Введите номер нужного чата: ").strip()
+    try:
+        return items[int(answer) - 1][0]
+    except (ValueError, IndexError):
+        raise ValueError("выбран неправильный номер чата") from None
+
+
+def _install_jupyter_startup() -> Path:
+    startup = Path.home() / ".ipython" / "profile_default" / "startup"
+    startup.mkdir(parents=True, exist_ok=True)
+    file = startup / "90-pynotegram.py"
+    file.write_text(
+        "get_ipython().run_line_magic('load_ext', 'pynotegram')\n",
+        encoding="utf-8",
+    )
+    return file
+
+
+def _send(message: str) -> None:
+    with PyNoteGram.from_config() as notifier:
+        notifier.send(message)
+    print("Отправлено.")
+
+
+def _status() -> None:
+    data = load_config()
+    safe = {"chat_id": data["chat_id"], "proxy_url": data.get("proxy_url")}
+    print(json.dumps(safe, ensure_ascii=False, indent=2))
+    print(f"Файл настроек: {config_path()}")
+
+
+if __name__ == "__main__":
+    main()

pynotegram-0.3.0/src/pynotegram/config.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+def config_path() -> Path:
+    custom = os.getenv("PYNOTEGRAM_CONFIG")
+    if custom:
+        return Path(custom).expanduser()
+
+    if os.name == "nt":
+        base = Path(os.getenv("APPDATA", Path.home() / "AppData" / "Roaming"))
+        return base / "PyNoteGram" / "config.json"
+
+    base = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return base / "pynotegram" / "config.json"
+
+
+def load_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.exists():
+        raise ConfigError(
+            "PyNoteGram еще не настроен. Один раз выполните: pynotegram setup"
+        )
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as error:
+        raise ConfigError(f"Не удалось прочитать настройки: {path}") from error
+
+    if not data.get("token") or not data.get("chat_id"):
+        raise ConfigError("В настройках отсутствует token или chat_id")
+    return data
+
+
+def save_config(data: dict[str, Any]) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    if os.name != "nt":
+        temporary.chmod(0o600)
+    temporary.replace(path)
+    return path
+

pynotegram-0.3.0/src/pynotegram/notifier.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+
+TELEGRAM_MESSAGE_LIMIT = 4096
+
+
+class TelegramError(RuntimeError):
+    """A safe-to-display error raised for network or Telegram API failures."""
+
+
+class PyNoteGram:
+    """Send notebook notifications through Telegram Bot API or an HTTPS relay."""
+
+    def __init__(
+        self,
+        *,
+        chat_id: str | int,
+        token: str | None = None,
+        proxy_url: str | None = None,
+        relay_url: str | None = None,
+        relay_api_key: str | None = None,
+        timeout: float = 20.0,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not str(chat_id).strip():
+            raise ValueError("chat_id is required")
+        if not relay_url and not token:
+            raise ValueError("token is required when relay_url is not configured")
+        if relay_url and not relay_url.lower().startswith("https://"):
+            raise ValueError("relay_url must use HTTPS")
+        if client is not None and proxy_url:
+            raise ValueError("Pass either client or proxy_url, not both")
+
+        self.chat_id = str(chat_id)
+        self.token = token
+        self.relay_url = relay_url
+        self.relay_api_key = relay_api_key
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            proxy=proxy_url,
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> PyNoteGram:
+        """Create a notifier from TELEGRAM_* environment variables."""
+        config: dict[str, Any] = {
+            "token": os.getenv("TELEGRAM_BOT_TOKEN"),
+            "chat_id": os.getenv("TELEGRAM_CHAT_ID", ""),
+            "proxy_url": os.getenv("TELEGRAM_PROXY_URL"),
+            "relay_url": os.getenv("TELEGRAM_RELAY_URL"),
+            "relay_api_key": os.getenv("TELEGRAM_RELAY_API_KEY"),
+        }
+        config.update(overrides)
+        return cls(**config)
+
+    @classmethod
+    def from_config(cls, **overrides: Any) -> PyNoteGram:
+        """Create a notifier for the single chat selected by `pynotegram setup`."""
+        from .config import load_config
+
+        allowed = {
+            "token",
+            "chat_id",
+            "proxy_url",
+            "relay_url",
+            "relay_api_key",
+            "timeout",
+            "client",
+        }
+        config = {
+            key: value for key, value in load_config().items() if key in allowed
+        }
+        config.update(overrides)
+        return cls(**config)
+
+    def send(
+        self,
+        message: object,
+        *,
+        parse_mode: str | None = None,
+        silent: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Send text and return one API result for each Telegram-sized chunk."""
+        text = str(message)
+        if not text.strip():
+            raise ValueError("message must not be empty")
+
+        return [
+            self._send_chunk(
+                chunk,
+                parse_mode=parse_mode,
+                silent=silent,
+            )
+            for chunk in _split_message(text)
+        ]
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> PyNoteGram:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _send_chunk(
+        self,
+        text: str,
+        *,
+        parse_mode: str | None,
+        silent: bool,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "chat_id": self.chat_id,
+            "text": text,
+            "disable_notification": silent,
+        }
+        if parse_mode:
+            payload["parse_mode"] = parse_mode
+
+        headers: dict[str, str] = {}
+        if self.relay_url:
+            url = self.relay_url
+            if self.relay_api_key:
+                headers["Authorization"] = f"Bearer {self.relay_api_key}"
+        else:
+            url = f"https://api.telegram.org/bot{self.token}/sendMessage"
+
+        try:
+            response = self._client.post(url, json=payload, headers=headers)
+        except httpx.RequestError:
+            raise TelegramError(
+                "Не удалось подключиться к Telegram. Проверьте VPN, proxy_url "
+                "или доступность relay-сервера."
+            ) from None
+
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+
+        if response.is_error:
+            description = _safe_description(data)
+            raise TelegramError(
+                f"Сервис вернул HTTP {response.status_code}: {description}"
+            )
+
+        if not isinstance(data, dict):
+            raise TelegramError("Сервис вернул некорректный JSON")
+        if data.get("ok") is False:
+            raise TelegramError(
+                f"Telegram отклонил запрос: {_safe_description(data)}"
+            )
+
+        result = data.get("result", data)
+        return result if isinstance(result, dict) else {"result": result}
+
+
+def _safe_description(data: object) -> str:
+    if isinstance(data, dict):
+        description = data.get("description") or data.get("detail")
+        if description:
+            return str(description)
+    return "без описания"
+
+
+def _split_message(text: str) -> Iterator[str]:
+    remaining = text
+    while len(remaining) > TELEGRAM_MESSAGE_LIMIT:
+        split_at = remaining.rfind("\n", 0, TELEGRAM_MESSAGE_LIMIT)
+        if split_at <= 0:
+            split_at = TELEGRAM_MESSAGE_LIMIT
+        else:
+            split_at += 1
+        yield remaining[:split_at]
+        remaining = remaining[split_at:]
+    if remaining:
+        yield remaining

pynotegram-0.3.0/src/pynotegram/receiver.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import html
+import json
+import re
+import time
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from .config import load_config, save_config
+from .notifier import TelegramError, _safe_description
+
+
+def read(
+    wait: int = 30,
+    *,
+    show: bool = True,
+    show_empty: bool = True,
+    client: httpx.Client | None = None,
+) -> list[dict[str, Any]]:
+    """Wait for messages from the configured chat and optionally show them."""
+    if not 0 <= wait <= 50:
+        raise ValueError("wait должен быть от 0 до 50 секунд")
+
+    config = load_config()
+    token = config.get("token")
+    if not token:
+        raise TelegramError("Для чтения сообщений нужен токен Telegram-бота")
+
+    owns_client = client is None
+    active_client = client or httpx.Client(
+        proxy=config.get("proxy_url"),
+        timeout=max(20, wait + 10),
+        follow_redirects=True,
+    )
+    try:
+        updates = _get_updates(
+            active_client,
+            token,
+            offset=int(config.get("update_offset", 0)),
+            wait=wait,
+        )
+    finally:
+        if owns_client:
+            active_client.close()
+
+    if updates:
+        config["update_offset"] = max(int(item["update_id"]) for item in updates) + 1
+        save_config(config)
+
+    messages = [
+        message
+        for update in updates
+        if (message := _extract_message(update)) is not None
+        and str(message.get("chat", {}).get("id")) == str(config["chat_id"])
+    ]
+
+    if show:
+        if messages:
+            for message in messages:
+                _display_message(message)
+        elif show_empty:
+            print("Новых сообщений нет.")
+    return messages
+
+
+def watch(minutes: float = 10) -> list[dict[str, Any]]:
+    """Continuously display incoming messages for a limited time."""
+    if not 0 < minutes <= 1440:
+        raise ValueError("minutes должен быть больше 0 и не больше 1440")
+
+    print(f"Ожидаю сообщения из Telegram {minutes:g} мин. Для остановки прервите ядро.")
+    deadline = time.monotonic() + minutes * 60
+    collected: list[dict[str, Any]] = []
+    try:
+        while (remaining := deadline - time.monotonic()) > 0:
+            wait = max(0, min(30, int(remaining)))
+            if wait == 0:
+                break
+            collected.extend(read(wait=wait, show=True, show_empty=False))
+    except KeyboardInterrupt:
+        print("Ожидание остановлено.")
+    return collected
+
+
+def message_to_markdown(message: dict[str, Any]) -> str:
+    """Convert Telegram text and code entities to safe Jupyter Markdown."""
+    text = message.get("text") or message.get("caption") or ""
+    entities = message.get("entities") or message.get("caption_entities") or []
+    return _format_text(text, entities)
+
+
+def _get_updates(
+    client: httpx.Client,
+    token: str,
+    *,
+    offset: int,
+    wait: int,
+) -> list[dict[str, Any]]:
+    try:
+        response = client.get(
+            f"https://api.telegram.org/bot{token}/getUpdates",
+            params={
+                "offset": offset,
+                "timeout": wait,
+                "allowed_updates": json.dumps(["message", "edited_message"]),
+            },
+        )
+        data = response.json()
+    except (httpx.RequestError, ValueError):
+        raise TelegramError(
+            "Не удалось получить сообщения. Проверьте VPN или прокси."
+        ) from None
+
+    if response.is_error or not isinstance(data, dict) or data.get("ok") is not True:
+        raise TelegramError(f"Telegram отклонил запрос: {_safe_description(data)}")
+    result = data.get("result", [])
+    return result if isinstance(result, list) else []
+
+
+def _extract_message(update: dict[str, Any]) -> dict[str, Any] | None:
+    return update.get("message") or update.get("edited_message")
+
+
+def _display_message(message: dict[str, Any]) -> None:
+    from IPython.display import Markdown, display
+
+    sender = message.get("from", {})
+    name = " ".join(
+        part for part in (sender.get("first_name"), sender.get("last_name")) if part
+    ) or sender.get("username") or "Telegram"
+    timestamp = datetime.fromtimestamp(message.get("date", 0)).astimezone()
+    heading = f"**{html.escape(str(name))}** · {timestamp:%H:%M:%S}"
+    body = message_to_markdown(message)
+    display(Markdown(f"{heading}\n\n{body}"))
+
+
+def _format_text(text: str, entities: list[dict[str, Any]]) -> str:
+    if not entities:
+        return html.escape(text)
+
+    spans: list[tuple[int, int, dict[str, Any]]] = []
+    for entity in entities:
+        start = _utf16_to_python_index(text, int(entity.get("offset", 0)))
+        end = _utf16_to_python_index(
+            text,
+            int(entity.get("offset", 0)) + int(entity.get("length", 0)),
+        )
+        spans.append((start, end, entity))
+
+    # Code entities matter most in notebooks. Telegram can nest other style
+    # entities, so only non-overlapping top-level spans are rewritten here.
+    output: list[str] = []
+    cursor = 0
+    for start, end, entity in sorted(spans, key=lambda item: (item[0], -item[1])):
+        if start < cursor:
+            continue
+        output.append(html.escape(text[cursor:start]))
+        value = text[start:end]
+        entity_type = entity.get("type")
+        if entity_type == "pre":
+            language = re.sub(r"[^A-Za-z0-9_+.-]", "", entity.get("language", ""))
+            fence = "````" if "```" in value else "```"
+            output.append(f"\n{fence}{language}\n{value}\n{fence}\n")
+        elif entity_type == "code":
+            fence = "``" if "`" in value else "`"
+            output.append(f"{fence}{value}{fence}")
+        elif entity_type == "bold":
+            output.append(f"**{html.escape(value)}**")
+        elif entity_type == "italic":
+            output.append(f"*{html.escape(value)}*")
+        elif entity_type == "strikethrough":
+            output.append(f"~~{html.escape(value)}~~")
+        elif entity_type == "underline":
+            output.append(f"<u>{html.escape(value)}</u>")
+        elif entity_type == "text_link":
+            url = html.escape(str(entity.get("url", "")), quote=True)
+            output.append(f"[{html.escape(value)}]({url})")
+        else:
+            output.append(html.escape(value))
+        cursor = end
+    output.append(html.escape(text[cursor:]))
+    return "".join(output)
+
+
+def _utf16_to_python_index(text: str, utf16_index: int) -> int:
+    units = 0
+    for index, character in enumerate(text):
+        if units >= utf16_index:
+            return index
+        units += 2 if ord(character) > 0xFFFF else 1
+    return len(text)

pynotegram-0.3.0/tests/test_notifier.py

@@ -0,0 +1,245 @@
+import json
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+import httpx
+
+from pynotegram import PyNoteGram, TelegramError, read, setup, watch
+from pynotegram.cli import _find_chats, _wait_for_chats
+from pynotegram.config import save_config
+from pynotegram.receiver import message_to_markdown
+
+
+class PyNoteGramTests(unittest.TestCase):
+    def test_notebook_setup_is_public(self):
+        self.assertTrue(callable(setup))
+
+    def test_read_is_public(self):
+        self.assertTrue(callable(read))
+        self.assertTrue(callable(watch))
+
+    def test_direct_send(self):
+        def handler(request: httpx.Request) -> httpx.Response:
+            self.assertEqual(
+                str(request.url),
+                "https://api.telegram.org/botsecret/sendMessage",
+            )
+            return httpx.Response(200, json={"ok": True, "result": {"message_id": 7}})
+
+        client = httpx.Client(transport=httpx.MockTransport(handler))
+        notifier = PyNoteGram(token="secret", chat_id=123, client=client)
+
+        self.assertEqual(notifier.send("done"), [{"message_id": 7}])
+
+    def test_long_message_is_split(self):
+        messages = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            messages.append(request.read())
+            return httpx.Response(200, json={"ok": True, "result": {}})
+
+        client = httpx.Client(transport=httpx.MockTransport(handler))
+        notifier = PyNoteGram(token="secret", chat_id=123, client=client)
+
+        notifier.send("x" * 5000)
+
+        self.assertEqual(len(messages), 2)
+
+    def test_split_preserves_newlines(self):
+        chunks = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            chunks.append(json.loads(request.read())["text"])
+            return httpx.Response(200, json={"ok": True, "result": {}})
+
+        client = httpx.Client(transport=httpx.MockTransport(handler))
+        notifier = PyNoteGram(token="secret", chat_id=123, client=client)
+        original = ("line\n" * 900) + "end"
+
+        notifier.send(original)
+
+        self.assertEqual("".join(chunks), original)
+        self.assertTrue(all(len(chunk) <= 4096 for chunk in chunks))
+
+    def test_relay_uses_bearer_key(self):
+        def handler(request: httpx.Request) -> httpx.Response:
+            self.assertEqual(request.headers["Authorization"], "Bearer relay-secret")
+            self.assertEqual(str(request.url), "https://relay.example/send")
+            return httpx.Response(200, json={"ok": True, "result": {"message_id": 9}})
+
+        client = httpx.Client(transport=httpx.MockTransport(handler))
+        notifier = PyNoteGram(
+            chat_id=123,
+            relay_url="https://relay.example/send",
+            relay_api_key="relay-secret",
+            client=client,
+        )
+
+        self.assertEqual(notifier.send("done"), [{"message_id": 9}])
+
+    def test_api_error_is_readable(self):
+        transport = httpx.MockTransport(
+            lambda request: httpx.Response(
+                400,
+                json={"ok": False, "description": "Bad Request: chat not found"},
+            )
+        )
+        client = httpx.Client(transport=transport)
+        notifier = PyNoteGram(token="secret", chat_id=123, client=client)
+
+        with self.assertRaisesRegex(TelegramError, "chat not found"):
+            notifier.send("done")
+
+    def test_config_uses_one_saved_chat(self):
+        with tempfile.TemporaryDirectory() as directory:
+            old_path = os.environ.get("PYNOTEGRAM_CONFIG")
+            os.environ["PYNOTEGRAM_CONFIG"] = str(Path(directory) / "config.json")
+            try:
+                save_config(
+                    {
+                        "token": "secret",
+                        "chat_id": "-100777",
+                        "update_offset": 42,
+                    }
+                )
+                client = httpx.Client(
+                    transport=httpx.MockTransport(
+                        lambda request: httpx.Response(
+                            200,
+                            json={"ok": True, "result": {}},
+                        )
+                    )
+                )
+                notifier = PyNoteGram.from_config(client=client)
+                self.assertEqual(notifier.chat_id, "-100777")
+            finally:
+                if old_path is None:
+                    os.environ.pop("PYNOTEGRAM_CONFIG", None)
+                else:
+                    os.environ["PYNOTEGRAM_CONFIG"] = old_path
+
+    def test_find_group_chat(self):
+        chats = _find_chats(
+            [
+                {
+                    "update_id": 1,
+                    "message": {
+                        "chat": {
+                            "id": -100777,
+                            "type": "supergroup",
+                            "title": "Calculations",
+                        }
+                    },
+                }
+            ]
+        )
+
+        self.assertEqual(chats["-100777"]["title"], "Calculations")
+
+    def test_wait_for_group_ignores_private_chat(self):
+        updates = [
+            {
+                "update_id": 10,
+                "message": {
+                    "chat": {"id": 123, "type": "private", "first_name": "User"}
+                }
+            },
+            {
+                "update_id": 11,
+                "message": {
+                    "chat": {
+                        "id": -100777,
+                        "type": "supergroup",
+                        "title": "Calculations",
+                    }
+                }
+            },
+        ]
+        client = httpx.Client(
+            transport=httpx.MockTransport(
+                lambda request: httpx.Response(
+                    200,
+                    json={"ok": True, "result": updates},
+                )
+            )
+        )
+
+        chats = _wait_for_chats(client, "secret", wait_seconds=1)
+
+        self.assertEqual(list(chats), ["-100777"])
+
+    def test_read_only_returns_saved_chat_and_updates_offset(self):
+        with tempfile.TemporaryDirectory() as directory:
+            old_path = os.environ.get("PYNOTEGRAM_CONFIG")
+            os.environ["PYNOTEGRAM_CONFIG"] = str(Path(directory) / "config.json")
+            try:
+                save_config(
+                    {
+                        "token": "secret",
+                        "chat_id": "-100777",
+                        "update_offset": 5,
+                    }
+                )
+
+                def handler(request: httpx.Request) -> httpx.Response:
+                    self.assertEqual(request.url.params["offset"], "5")
+                    return httpx.Response(
+                        200,
+                        json={
+                            "ok": True,
+                            "result": [
+                                {
+                                    "update_id": 7,
+                                    "message": {
+                                        "chat": {"id": 999},
+                                        "text": "ignore",
+                                    },
+                                },
+                                {
+                                    "update_id": 8,
+                                    "message": {
+                                        "chat": {"id": -100777},
+                                        "text": "keep",
+                                    },
+                                },
+                            ],
+                        },
+                    )
+
+                client = httpx.Client(transport=httpx.MockTransport(handler))
+                messages = read(wait=0, show=False, client=client)
+
+                self.assertEqual([item["text"] for item in messages], ["keep"])
+                saved = json.loads(Path(os.environ["PYNOTEGRAM_CONFIG"]).read_text())
+                self.assertEqual(saved["update_offset"], 9)
+            finally:
+                if old_path is None:
+                    os.environ.pop("PYNOTEGRAM_CONFIG", None)
+                else:
+                    os.environ["PYNOTEGRAM_CONFIG"] = old_path
+
+    def test_telegram_python_code_becomes_fenced_markdown(self):
+        text = "Код:\nprint('Привет')"
+        start = len("Код:\n".encode("utf-16-le")) // 2
+        length = len("print('Привет')".encode("utf-16-le")) // 2
+        markdown = message_to_markdown(
+            {
+                "text": text,
+                "entities": [
+                    {
+                        "type": "pre",
+                        "offset": start,
+                        "length": length,
+                        "language": "python",
+                    }
+                ],
+            }
+        )
+
+        self.assertIn("```python\nprint('Привет')\n```", markdown)
+
+
+if __name__ == "__main__":
+    unittest.main()