# Telegram Notification Bot 🤖
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/tg-notification-bot)
A modern, type-safe Python library for sending notifications through Telegram bots. Built with the latest aiogram 3.x
and Pydantic 2.x for maximum reliability and developer experience.
## ✨ Features
- 🔒 **Type Safety**: Full type annotations with mypy support
- 🚀 **Modern**: Built on aiogram 3.x and Pydantic 2.x
- 🛡️ **Robust Error Handling**: Comprehensive exception handling with custom error types
- 📝 **Validation**: Input validation using Pydantic models
- 🎯 **Multiple Formats**: Send text, photos, and documents
- 🔧 **Flexible Configuration**: Support for various chat ID formats
- 🧪 **Well Tested**: Comprehensive test suite with high coverage
- 📦 **Zero Dependencies**: Only requires aiogram and pydantic
## 🚀 Installation
```bash
uv pip install tg-notification-bot
```
For development:
```bash
# Using uv (recommended)
uv add --dev tg-notification-bot
```
## 📖 Quick Start
### Basic Usage
```python
import asyncio
from tg_notification_bot import TelegramNotificationBot
async def main():
# Initialize with token and chat ID
bot = TelegramNotificationBot("YOUR_BOT_TOKEN", "YOUR_CHAT_ID")
# Send a simple message
await bot.send_message("Hello, World! 🌍")
# Send a photo
await bot.send_photo("path/to/photo.jpg", caption="Check this out!")
# Send a document
await bot.send_document("path/to/document.pdf", caption="Important file")
# Don't forget to close the session
await bot.close()
# Run the example
asyncio.run(main())
```
### Using Configuration Object
```python
import asyncio
from tg_notification_bot import TelegramNotificationBot, NotificationConfig
async def main():
# Create configuration
config = NotificationConfig(
token="YOUR_BOT_TOKEN",
chat_id="YOUR_CHAT_ID",
parse_mode="Markdown",
disable_notification=True
)
# Initialize bot with config
bot = TelegramNotificationBot(config)
await bot.send_message("*Bold text* with _italic_")
await bot.close()
asyncio.run(main())
```
### Context Manager (Recommended)
```python
import asyncio
from tg_notification_bot import TelegramNotificationBot
async def main():
async with TelegramNotificationBot("YOUR_BOT_TOKEN", "YOUR_CHAT_ID") as bot:
await bot.send_message("Message sent safely! ✅")
# Session automatically closed
asyncio.run(main())
```
## 🔧 Advanced Usage
### Structured Data with Pydantic Models
```python
import asyncio
from tg_notification_bot import (
TelegramNotificationBot,
MessageData,
PhotoData,
DocumentData
)
async def main():
async with TelegramNotificationBot("YOUR_BOT_TOKEN", "YOUR_CHAT_ID") as bot:
# Structured message
message = MessageData(
text="<b>Important</b> notification!",
parse_mode="HTML",
disable_notification=False
)
await bot.send_message(message)
# Structured photo
photo = PhotoData(
photo="https://example.com/image.jpg",
caption="Remote image",
parse_mode="Markdown"
)
await bot.send_photo(photo)
asyncio.run(main())
```
### File Handling
```python
import asyncio
from pathlib import Path
from io import BytesIO
from tg_notification_bot import TelegramNotificationBot
async def main():
async with TelegramNotificationBot("YOUR_BOT_TOKEN", "YOUR_CHAT_ID") as bot:
# Local file
await bot.send_photo(Path("image.jpg"))
# URL
await bot.send_photo("https://example.com/photo.jpg")
# File-like object
buffer = BytesIO(b"fake image data")
buffer.name = "generated.jpg"
await bot.send_photo(buffer, caption="Generated image")
asyncio.run(main())
```
### Error Handling
```python
import asyncio
from tg_notification_bot import (
TelegramNotificationBot,
ChatNotFoundError,
BotBlockedError,
RateLimitError,
TelegramNotificationError
)
async def main():
async with TelegramNotificationBot("YOUR_BOT_TOKEN", "YOUR_CHAT_ID") as bot:
try:
await bot.send_message("Test message")
except ChatNotFoundError as e:
print(f"Chat not found: {e.chat_id}")
except BotBlockedError as e:
print(f"Bot blocked in chat: {e.chat_id}")
except RateLimitError as e:
print(f"Rate limited. Retry after: {e.retry_after} seconds")
except TelegramNotificationError as e:
print(f"General error: {e}")
asyncio.run(main())
```
## 🔐 Configuration
### Environment Variables
```bash
# .env file
TG_BOT_TOKEN=your_bot_token_here
TG_CHAT_ID=your_chat_id_here
```
```python
import os
from tg_notification_bot import TelegramNotificationBot
# Load from environment
bot = TelegramNotificationBot(
token=os.getenv("TG_BOT_TOKEN"),
chat_id=os.getenv("TG_CHAT_ID")
)
```
### Chat ID Formats
The library supports various chat ID formats:
- `123456789` - User ID
- `-123456789` - Group chat ID
- `-100123456789` - Supergroup/channel ID
- `@username` - Public chat username
The bot automatically tries different formats if the initial one fails.
## 🧪 Testing
Run the test suite:
```bash
# Install development dependencies
uv sync --dev
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=tg_notification_bot --cov-report=html
# Type checking
uv run mypy tg_notification_bot
# Linting and formatting with ruff
uv run ruff check tg_notification_bot
uv run ruff format --check tg_notification_bot
```
## 📝 API Reference
### Classes
#### `TelegramNotificationBot`
Main bot class for sending notifications.
**Constructor:**
- `TelegramNotificationBot(token: NotificationConfig | str, chat_id: str | int = None)`
**Methods:**
- `send_message(message: str | MessageData, chat_id: str | int = None) -> None`
- `send_photo(photo: str | Path | IO | PhotoData, caption: str = None, chat_id: str | int = None) -> None`
- `send_document(document: str | Path | IO | DocumentData, caption: str = None, chat_id: str | int = None) -> None`
- `close() -> None`
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [aiogram](https://github.com/aiogram/aiogram) - Modern Telegram Bot API framework
- [pydantic](https://github.com/pydantic/pydantic) - Data validation using Python type hints
Raw data
{
"_id": null,
"home_page": null,
"name": "tg-notification-bot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "telegram, bot, notifications, aiogram",
"author": null,
"author_email": "AI-Stratov <workistratov@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3c/4f/4d62fef1f05544ddc3824fd10ed37f464341ae00da9449830965254e839f/tg_notification_bot-0.3.2.tar.gz",
"platform": null,
"description": "# Telegram Notification Bot \ud83e\udd16\r\n\r\n[](https://www.python.org/downloads/)\r\n[](https://badge.fury.io/py/tg-notification-bot)\r\n\r\nA modern, type-safe Python library for sending notifications through Telegram bots. Built with the latest aiogram 3.x\r\nand Pydantic 2.x for maximum reliability and developer experience.\r\n\r\n## \u2728 Features\r\n\r\n- \ud83d\udd12 **Type Safety**: Full type annotations with mypy support\r\n- \ud83d\ude80 **Modern**: Built on aiogram 3.x and Pydantic 2.x\r\n- \ud83d\udee1\ufe0f **Robust Error Handling**: Comprehensive exception handling with custom error types\r\n- \ud83d\udcdd **Validation**: Input validation using Pydantic models\r\n- \ud83c\udfaf **Multiple Formats**: Send text, photos, and documents\r\n- \ud83d\udd27 **Flexible Configuration**: Support for various chat ID formats\r\n- \ud83e\uddea **Well Tested**: Comprehensive test suite with high coverage\r\n- \ud83d\udce6 **Zero Dependencies**: Only requires aiogram and pydantic\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n```bash\r\nuv pip install tg-notification-bot\r\n```\r\n\r\nFor development:\r\n\r\n```bash\r\n# Using uv (recommended)\r\nuv add --dev tg-notification-bot\r\n```\r\n\r\n## \ud83d\udcd6 Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom tg_notification_bot import TelegramNotificationBot\r\n\r\n\r\nasync def main():\r\n # Initialize with token and chat ID\r\n bot = TelegramNotificationBot(\"YOUR_BOT_TOKEN\", \"YOUR_CHAT_ID\")\r\n\r\n # Send a simple message\r\n await bot.send_message(\"Hello, World! \ud83c\udf0d\")\r\n\r\n # Send a photo\r\n await bot.send_photo(\"path/to/photo.jpg\", caption=\"Check this out!\")\r\n\r\n # Send a document\r\n await bot.send_document(\"path/to/document.pdf\", caption=\"Important file\")\r\n\r\n # Don't forget to close the session\r\n await bot.close()\r\n\r\n\r\n# Run the example\r\nasyncio.run(main())\r\n```\r\n\r\n### Using Configuration Object\r\n\r\n```python\r\nimport asyncio\r\n\r\nfrom tg_notification_bot import TelegramNotificationBot, NotificationConfig\r\n\r\n\r\nasync def main():\r\n # Create configuration\r\n config = NotificationConfig(\r\n token=\"YOUR_BOT_TOKEN\",\r\n chat_id=\"YOUR_CHAT_ID\",\r\n parse_mode=\"Markdown\",\r\n disable_notification=True\r\n )\r\n\r\n # Initialize bot with config\r\n bot = TelegramNotificationBot(config)\r\n\r\n await bot.send_message(\"*Bold text* with _italic_\")\r\n await bot.close()\r\n\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Context Manager (Recommended)\r\n\r\n```python\r\nimport asyncio\r\nfrom tg_notification_bot import TelegramNotificationBot\r\n\r\n\r\nasync def main():\r\n async with TelegramNotificationBot(\"YOUR_BOT_TOKEN\", \"YOUR_CHAT_ID\") as bot:\r\n await bot.send_message(\"Message sent safely! \u2705\")\r\n # Session automatically closed\r\n\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## \ud83d\udd27 Advanced Usage\r\n\r\n### Structured Data with Pydantic Models\r\n\r\n```python\r\nimport asyncio\r\nfrom tg_notification_bot import (\r\n TelegramNotificationBot,\r\n MessageData,\r\n PhotoData,\r\n DocumentData\r\n)\r\n\r\n\r\nasync def main():\r\n async with TelegramNotificationBot(\"YOUR_BOT_TOKEN\", \"YOUR_CHAT_ID\") as bot:\r\n # Structured message\r\n message = MessageData(\r\n text=\"<b>Important</b> notification!\",\r\n parse_mode=\"HTML\",\r\n disable_notification=False\r\n )\r\n await bot.send_message(message)\r\n\r\n # Structured photo\r\n photo = PhotoData(\r\n photo=\"https://example.com/image.jpg\",\r\n caption=\"Remote image\",\r\n parse_mode=\"Markdown\"\r\n )\r\n await bot.send_photo(photo)\r\n\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### File Handling\r\n\r\n```python\r\nimport asyncio\r\nfrom pathlib import Path\r\nfrom io import BytesIO\r\nfrom tg_notification_bot import TelegramNotificationBot\r\n\r\n\r\nasync def main():\r\n async with TelegramNotificationBot(\"YOUR_BOT_TOKEN\", \"YOUR_CHAT_ID\") as bot:\r\n # Local file\r\n await bot.send_photo(Path(\"image.jpg\"))\r\n\r\n # URL\r\n await bot.send_photo(\"https://example.com/photo.jpg\")\r\n\r\n # File-like object\r\n buffer = BytesIO(b\"fake image data\")\r\n buffer.name = \"generated.jpg\"\r\n await bot.send_photo(buffer, caption=\"Generated image\")\r\n\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Error Handling\r\n\r\n```python\r\nimport asyncio\r\nfrom tg_notification_bot import (\r\n TelegramNotificationBot,\r\n ChatNotFoundError,\r\n BotBlockedError,\r\n RateLimitError,\r\n TelegramNotificationError\r\n)\r\n\r\n\r\nasync def main():\r\n async with TelegramNotificationBot(\"YOUR_BOT_TOKEN\", \"YOUR_CHAT_ID\") as bot:\r\n try:\r\n await bot.send_message(\"Test message\")\r\n except ChatNotFoundError as e:\r\n print(f\"Chat not found: {e.chat_id}\")\r\n except BotBlockedError as e:\r\n print(f\"Bot blocked in chat: {e.chat_id}\")\r\n except RateLimitError as e:\r\n print(f\"Rate limited. Retry after: {e.retry_after} seconds\")\r\n except TelegramNotificationError as e:\r\n print(f\"General error: {e}\")\r\n\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## \ud83d\udd10 Configuration\r\n\r\n### Environment Variables\r\n\r\n```bash\r\n# .env file\r\nTG_BOT_TOKEN=your_bot_token_here\r\nTG_CHAT_ID=your_chat_id_here\r\n```\r\n\r\n```python\r\nimport os\r\nfrom tg_notification_bot import TelegramNotificationBot\r\n\r\n# Load from environment\r\nbot = TelegramNotificationBot(\r\n token=os.getenv(\"TG_BOT_TOKEN\"),\r\n chat_id=os.getenv(\"TG_CHAT_ID\")\r\n)\r\n```\r\n\r\n### Chat ID Formats\r\n\r\nThe library supports various chat ID formats:\r\n\r\n- `123456789` - User ID\r\n- `-123456789` - Group chat ID\r\n- `-100123456789` - Supergroup/channel ID\r\n- `@username` - Public chat username\r\n\r\nThe bot automatically tries different formats if the initial one fails.\r\n\r\n## \ud83e\uddea Testing\r\n\r\nRun the test suite:\r\n\r\n```bash\r\n# Install development dependencies\r\nuv sync --dev\r\n\r\n# Run tests\r\nuv run pytest\r\n\r\n# Run tests with coverage\r\nuv run pytest --cov=tg_notification_bot --cov-report=html\r\n\r\n# Type checking\r\nuv run mypy tg_notification_bot\r\n\r\n# Linting and formatting with ruff\r\nuv run ruff check tg_notification_bot\r\nuv run ruff format --check tg_notification_bot\r\n```\r\n\r\n## \ud83d\udcdd API Reference\r\n\r\n### Classes\r\n\r\n#### `TelegramNotificationBot`\r\n\r\nMain bot class for sending notifications.\r\n\r\n**Constructor:**\r\n\r\n- `TelegramNotificationBot(token: NotificationConfig | str, chat_id: str | int = None)`\r\n\r\n**Methods:**\r\n\r\n- `send_message(message: str | MessageData, chat_id: str | int = None) -> None`\r\n- `send_photo(photo: str | Path | IO | PhotoData, caption: str = None, chat_id: str | int = None) -> None`\r\n- `send_document(document: str | Path | IO | DocumentData, caption: str = None, chat_id: str | int = None) -> None`\r\n- `close() -> None`\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- [aiogram](https://github.com/aiogram/aiogram) - Modern Telegram Bot API framework\r\n- [pydantic](https://github.com/pydantic/pydantic) - Data validation using Python type hints\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Modern Telegram notification bot library for Python projects",
"version": "0.3.2",
"project_urls": {
"Documentation": "https://github.com/AI-Stratov/tg-notification-bot#readme",
"Homepage": "https://github.com/AI-Stratov/tg-notification-bot",
"Issues": "https://github.com/AI-Stratov/tg-notification-bot/issues",
"Repository": "https://github.com/AI-Stratov/tg-notification-bot"
},
"split_keywords": [
"telegram",
" bot",
" notifications",
" aiogram"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "68b10df6734ee5892c834865032e1092a829c364d30e7e2dfcda64ed824b11fb",
"md5": "45c44b3eb3a206cb8a4c2e0241c80f62",
"sha256": "519400b3e94740308c63e0961699c13ef10c96d744380b4857657d42f5ca0a49"
},
"downloads": -1,
"filename": "tg_notification_bot-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45c44b3eb3a206cb8a4c2e0241c80f62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8040,
"upload_time": "2025-08-26T21:21:44",
"upload_time_iso_8601": "2025-08-26T21:21:44.734733Z",
"url": "https://files.pythonhosted.org/packages/68/b1/0df6734ee5892c834865032e1092a829c364d30e7e2dfcda64ed824b11fb/tg_notification_bot-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3c4f4d62fef1f05544ddc3824fd10ed37f464341ae00da9449830965254e839f",
"md5": "a810afecc8f7c71d42486aa6be164b7b",
"sha256": "a1f337c8b049dea1b248cab6947e3cca3e62b0c8ee0b1a3ecd95e8af8beba745"
},
"downloads": -1,
"filename": "tg_notification_bot-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "a810afecc8f7c71d42486aa6be164b7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12114,
"upload_time": "2025-08-26T21:21:45",
"upload_time_iso_8601": "2025-08-26T21:21:45.922203Z",
"url": "https://files.pythonhosted.org/packages/3c/4f/4d62fef1f05544ddc3824fd10ed37f464341ae00da9449830965254e839f/tg_notification_bot-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 21:21:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AI-Stratov",
"github_project": "tg-notification-bot#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tg-notification-bot"
}
JSON
