Metadata-Version: 2.5
Name: telegram-python
Version: 1.0.0
Summary: Send Telegram notifications from Python services
Project-URL: Repository, https://git.7n.ai/nitra/telegram-python
Author-email: Tatiana Durachevska <tetyana.d@nitra.dev>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests<3,>=2.32.3
Description-Content-Type: text/markdown

# telegram-python

Надсилання Telegram-повідомлень із Python-сервісів через Bot API `sendMessage`.

```bash
uv add telegram-python
```

```python
from telegram_python import TelegramError, send

send('job_caps failed', chat_id=-1001234567890, message_thread_id=7)
```

## Налаштування

Аргументи `send` мають пріоритет над змінними оточення.

| Змінна | Аргумент | Призначення |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | `token` | токен бота |
| `TELEGRAM_CHAT_ID` | `chat_id` | чат або група |
| `TELEGRAM_THREAD_ID` | `message_thread_id` | тема в групі з темами (topics) |
| `TELEGRAM_SOUND_START_HOUR` | — | початок годин зі звуком, за замовчуванням `9` |
| `TELEGRAM_SOUND_END_HOUR` | — | кінець годин зі звуком, за замовчуванням `18` |

Поза годинами зі звуком повідомлення надсилається беззвучно, якщо не передано
`disable_notification`.

## Поведінка

- Налаштування читаються під час виклику: імпорт не падає без змінних оточення.
- `parse_mode` за замовчуванням не задано — текст надсилається як є. Тексти
  помилок із `_`, `*`, `` ` `` ламають Markdown, і Telegram відхиляє повідомлення.
- Текст довший за 4096 символів обрізається.
- Помилка відправки піднімає `TelegramError`; токен у текст помилки не потрапляє.
- Повертає об'єкт `Message` з відповіді Telegram.

## Зміни 1.0.0

Несумісні з 0.x:

- `send` піднімає `TelegramError` замість запису в лог-файл `py_log.log`;
- `parse_mode` за замовчуванням `None` (було `Markdown`);
- `send` приймає лише keyword-аргументи після `message`.

Нове: `message_thread_id` / `TELEGRAM_THREAD_ID`, явні `chat_id` і `token`,
тести, збірка через `uv`.

## Розробка

```bash
uv run pytest
uv run ruff check . && uv run ruff format --check .
```

Репозиторій: https://git.7n.ai/nitra/telegram-python. GitHub
`nitra/telegram-python` — лише дзеркало (Forgejo push mirror, deploy key);
зміни туди напряму не вносяться, бо дзеркало їх перезапише.

Реліз: підняти `version` у `pyproject.toml`, злити в `main` на Forgejo і
поставити тег `v<version>`. Дзеркало переносить тег на GitHub, де
`.github/workflows/publish.yml` проганяє тести й публікує пакет на PyPI через
Trusted Publishing (environment `pypi`, лише теги `v*`). Токена PyPI немає.
