# snotify
Lightweight notification manager with support for Telegram, email, and custom channels. Supports both synchronous and asynchronous operations.
## Description
`snotify` is a library for managing notifications that allows sending messages through various channels such as Telegram, email, and custom channels. It supports both synchronous and asynchronous operations, and includes a fallback mechanism that allows sending messages through alternative channels in case the primary one fails.
## Installation
Install the library using pip:
```bash
pip install snotify
```
## Usage Example
### Configuring Logging
```python
from snotify import configure_logging
import logging
# Enable debug logging
configure_logging(logging.DEBUG)
# Or use INFO level (default)
configure_logging(logging.INFO)
# To disable logging completely
logging.disable(logging.CRITICAL)
```
### Synchronous Usage
```python
from snotify import Notifier, TelegramChannel, EmailChannel
# Create an instance of synchronous Notifier
notifier = Notifier()
# Add a Telegram channel
telegram_channel = TelegramChannel(bot_token="your_bot_token", recipients=["1234567890"])
notifier.add_channel(telegram_channel)
# Send a notification synchronously
notifier.send("Your message") # This will block until the message is sent
```
### Asynchronous Usage
```python
from snotify import ANotifier, TelegramChannel, EmailChannel
import asyncio
async def send_notification():
# Create an instance of asynchronous Notifier
notifier = ANotifier()
# Add a Telegram channel
telegram_channel = TelegramChannel(bot_token="your_bot_token", recipients=["1234567890"])
notifier.add_channel(telegram_channel)
# Send a notification asynchronously
await notifier.send("Your message")
# Run the async function
asyncio.run(send_notification())
```
### Using Fallback Mechanism (works in both sync and async modes)
```python
# Add an Email channel
email_channel = EmailChannel(
smtp_server="smtp.example.com",
smtp_port=587,
smtp_user="your_user",
smtp_password="your_password",
recipients=['test@example.com']
)
notifier.add_channel(email_channel)
# Set fallback order
notifier.set_fallback_order(["telegram", "email"])
# Send a notification with fallback
notifier.send("Your message with fallback") # For synchronous usage
# or
await notifier.send("Your message with fallback") # For asynchronous usage
```
### Creating and Using a Custom Channel
To create a custom channel, you need to extend the `BaseChannel` class and implement the `send` and `validate_config` methods. Here's a basic example:
```python
from snotify.channels.base import BaseChannel, BaseRecipient
import logging
class CustomRecipientTypeError(TypeError):
"""Custom exception for invalid recipient types."""
pass
class CustomChannel(BaseChannel):
def __init__(self, custom_param, recipients):
super().__init__(recipients)
self.custom_param = custom_param
async def send(self, message, recipients=None):
logger = logging.getLogger(__name__)
recipients_to_use = recipients if recipients is not None else self.recipients
for recipient in recipients_to_use:
if isinstance(recipient, str):
recipient = CustomRecipient(name=recipient, chat_id=recipient)
# Implement your custom sending logic here
logger.info(f"Sending message to {recipient.get_recipient_name()} via custom channel")
def validate_config(self):
if not self.custom_param:
raise ValueError("Custom parameter is required")
for recipient in self.recipients:
if not isinstance(recipient, CustomRecipient) and not isinstance(
recipient, str
):
raise CustomRecipientTypeError(
f"The {
recipient} recipient must be either str or CustomRecipient"
)
# Add a custom channel
custom_channel = CustomChannel(custom_param="value", recipients=[...])
notifier.add_channel(custom_channel)
# Send a notification using the custom channel
await notifier.send("Your custom message")
```
## Features
- **Flexible operation modes**: Support for both synchronous and asynchronous operations
- **Support for multiple channels**: Telegram, Email, and Custom channels
- **Fallback mechanism**: ability to specify the order of channels for sending messages in case of failure
- **Easy setup and use**
## Requirements
To use `snotify`, you need the following Python packages:
- **Runtime Requirements**: These are the packages required to run the library.
- `aiohttp>=3.7.4`: Asynchronous HTTP client/server framework.
- `aiosmtplib>=1.1.6`: Asynchronous SMTP client for sending emails.
- **Development Requirements**: These are additional packages needed for development and testing.
- `pre-commit>=2.13.0`: A framework for managing and maintaining multi-language pre-commit hooks.
- `pytest>=6.2.4`: A framework that makes building simple and scalable test cases easy.
- `pytest-asyncio>=0.14.0`: A `pytest` plugin for testing asyncio code.
- `python-dotenv>=0.17.0`: Reads key-value pairs from a `.env` file and can set them as environment variables.
- `setuptools>=52.0.0`: A package development and distribution library.
These dependencies are listed in the `requirements.txt` and `requirements-dev.txt` files, respectively. You can install them using pip:
```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```
## License
MIT License. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/swtormy/snotify",
"name": "snotify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "notifications telegram, webhook, email",
"author": "Konstantin Vasilev",
"author_email": "swtormy@yahoo.com",
"download_url": "https://files.pythonhosted.org/packages/4e/6e/5c41d70736c8a51979af809c1cd5c6a7c4f1a574aedce44d62624ae65b21/snotify-0.2.1.tar.gz",
"platform": null,
"description": "# snotify\r\n\r\nLightweight notification manager with support for Telegram, email, and custom channels. Supports both synchronous and asynchronous operations.\r\n\r\n## Description\r\n\r\n`snotify` is a library for managing notifications that allows sending messages through various channels such as Telegram, email, and custom channels. It supports both synchronous and asynchronous operations, and includes a fallback mechanism that allows sending messages through alternative channels in case the primary one fails.\r\n\r\n## Installation\r\n\r\nInstall the library using pip:\r\n\r\n```bash\r\npip install snotify\r\n```\r\n\r\n## Usage Example\r\n\r\n### Configuring Logging\r\n\r\n```python\r\nfrom snotify import configure_logging\r\nimport logging\r\n\r\n# Enable debug logging\r\nconfigure_logging(logging.DEBUG)\r\n\r\n# Or use INFO level (default)\r\nconfigure_logging(logging.INFO)\r\n\r\n# To disable logging completely\r\nlogging.disable(logging.CRITICAL)\r\n```\r\n\r\n### Synchronous Usage\r\n\r\n```python\r\nfrom snotify import Notifier, TelegramChannel, EmailChannel\r\n\r\n# Create an instance of synchronous Notifier\r\nnotifier = Notifier()\r\n\r\n# Add a Telegram channel\r\ntelegram_channel = TelegramChannel(bot_token=\"your_bot_token\", recipients=[\"1234567890\"])\r\nnotifier.add_channel(telegram_channel)\r\n\r\n# Send a notification synchronously\r\nnotifier.send(\"Your message\") # This will block until the message is sent\r\n```\r\n\r\n### Asynchronous Usage\r\n\r\n```python\r\nfrom snotify import ANotifier, TelegramChannel, EmailChannel\r\nimport asyncio\r\n\r\nasync def send_notification():\r\n # Create an instance of asynchronous Notifier\r\n notifier = ANotifier()\r\n\r\n # Add a Telegram channel\r\n telegram_channel = TelegramChannel(bot_token=\"your_bot_token\", recipients=[\"1234567890\"])\r\n notifier.add_channel(telegram_channel)\r\n\r\n # Send a notification asynchronously\r\n await notifier.send(\"Your message\")\r\n\r\n# Run the async function\r\nasyncio.run(send_notification())\r\n```\r\n\r\n### Using Fallback Mechanism (works in both sync and async modes)\r\n\r\n```python\r\n# Add an Email channel\r\nemail_channel = EmailChannel(\r\n smtp_server=\"smtp.example.com\",\r\n smtp_port=587,\r\n smtp_user=\"your_user\",\r\n smtp_password=\"your_password\",\r\n recipients=['test@example.com']\r\n)\r\nnotifier.add_channel(email_channel)\r\n\r\n# Set fallback order\r\nnotifier.set_fallback_order([\"telegram\", \"email\"])\r\n\r\n# Send a notification with fallback\r\nnotifier.send(\"Your message with fallback\") # For synchronous usage\r\n# or\r\nawait notifier.send(\"Your message with fallback\") # For asynchronous usage\r\n```\r\n\r\n### Creating and Using a Custom Channel\r\n\r\nTo create a custom channel, you need to extend the `BaseChannel` class and implement the `send` and `validate_config` methods. Here's a basic example:\r\n\r\n```python\r\nfrom snotify.channels.base import BaseChannel, BaseRecipient\r\nimport logging\r\n\r\nclass CustomRecipientTypeError(TypeError):\r\n \"\"\"Custom exception for invalid recipient types.\"\"\"\r\n pass\r\n\r\nclass CustomChannel(BaseChannel):\r\n def __init__(self, custom_param, recipients):\r\n super().__init__(recipients)\r\n self.custom_param = custom_param\r\n\r\n async def send(self, message, recipients=None):\r\n logger = logging.getLogger(__name__)\r\n recipients_to_use = recipients if recipients is not None else self.recipients\r\n for recipient in recipients_to_use:\r\n if isinstance(recipient, str):\r\n recipient = CustomRecipient(name=recipient, chat_id=recipient)\r\n # Implement your custom sending logic here\r\n logger.info(f\"Sending message to {recipient.get_recipient_name()} via custom channel\")\r\n\r\n def validate_config(self):\r\n if not self.custom_param:\r\n raise ValueError(\"Custom parameter is required\")\r\n for recipient in self.recipients:\r\n if not isinstance(recipient, CustomRecipient) and not isinstance(\r\n recipient, str\r\n ):\r\n raise CustomRecipientTypeError(\r\n f\"The {\r\n recipient} recipient must be either str or CustomRecipient\"\r\n )\r\n\r\n# Add a custom channel\r\ncustom_channel = CustomChannel(custom_param=\"value\", recipients=[...])\r\nnotifier.add_channel(custom_channel)\r\n\r\n# Send a notification using the custom channel\r\nawait notifier.send(\"Your custom message\")\r\n```\r\n\r\n## Features\r\n\r\n- **Flexible operation modes**: Support for both synchronous and asynchronous operations\r\n- **Support for multiple channels**: Telegram, Email, and Custom channels\r\n- **Fallback mechanism**: ability to specify the order of channels for sending messages in case of failure\r\n- **Easy setup and use**\r\n\r\n## Requirements\r\n\r\nTo use `snotify`, you need the following Python packages:\r\n\r\n- **Runtime Requirements**: These are the packages required to run the library.\r\n - `aiohttp>=3.7.4`: Asynchronous HTTP client/server framework.\r\n - `aiosmtplib>=1.1.6`: Asynchronous SMTP client for sending emails.\r\n\r\n- **Development Requirements**: These are additional packages needed for development and testing.\r\n - `pre-commit>=2.13.0`: A framework for managing and maintaining multi-language pre-commit hooks.\r\n - `pytest>=6.2.4`: A framework that makes building simple and scalable test cases easy.\r\n - `pytest-asyncio>=0.14.0`: A `pytest` plugin for testing asyncio code.\r\n - `python-dotenv>=0.17.0`: Reads key-value pairs from a `.env` file and can set them as environment variables.\r\n - `setuptools>=52.0.0`: A package development and distribution library.\r\n\r\nThese dependencies are listed in the `requirements.txt` and `requirements-dev.txt` files, respectively. You can install them using pip:\r\n\r\n```bash\r\npip install -r requirements.txt\r\npip install -r requirements-dev.txt\r\n```\r\n\r\n## License\r\n\r\nMIT License. See the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight notification manager for Telegram, Webhook, Email and Custom channels",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/swtormy/snotify#readme",
"Homepage": "https://github.com/swtormy/snotify",
"Source": "https://github.com/swtormy/snotify",
"Tracker": "https://github.com/swtormy/snotify/issues"
},
"split_keywords": [
"notifications telegram",
" webhook",
" email"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dc5afbe6d807c120fe230aa8cfcb0cb2a266060e5212da9b2689b7487296072c",
"md5": "bb05c7e4a66f3ab74e2258ed397beb61",
"sha256": "8222730d6ede181c244ab05bd8879fe0c933d8f8c56409266a5617ff9184b564"
},
"downloads": -1,
"filename": "snotify-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb05c7e4a66f3ab74e2258ed397beb61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13778,
"upload_time": "2024-12-25T19:06:13",
"upload_time_iso_8601": "2024-12-25T19:06:13.205614Z",
"url": "https://files.pythonhosted.org/packages/dc/5a/fbe6d807c120fe230aa8cfcb0cb2a266060e5212da9b2689b7487296072c/snotify-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e6e5c41d70736c8a51979af809c1cd5c6a7c4f1a574aedce44d62624ae65b21",
"md5": "e6d421aa2dda8a1ee453796c3df8b645",
"sha256": "c393275e2b83f91b13e0ae1cfa49785c2cfcce6e32f443d12ccf3fd4bbe7a18d"
},
"downloads": -1,
"filename": "snotify-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e6d421aa2dda8a1ee453796c3df8b645",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11790,
"upload_time": "2024-12-25T19:06:15",
"upload_time_iso_8601": "2024-12-25T19:06:15.525638Z",
"url": "https://files.pythonhosted.org/packages/4e/6e/5c41d70736c8a51979af809c1cd5c6a7c4f1a574aedce44d62624ae65b21/snotify-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-25 19:06:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "swtormy",
"github_project": "snotify",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.11.6"
]
]
},
{
"name": "aiosmtplib",
"specs": [
[
">=",
"3.0.2"
]
]
}
],
"lcname": "snotify"
}
JSON
