botapi-py 1.2.1__tar.gz → 1.3.1__tar.gz

{botapi_py-1.2.1 → botapi_py-1.3.1}/PKG-INFO

@@ -1,8 +1,10 @@
 Metadata-Version: 2.3
 Name: botapi-py
-Version: 1.2.1
+Version: 1.3.1
 Summary: A simple and flexible Python library to conveniently build Telegram bots using the Bot API.
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.12.0
+Requires-Dist: redis>=6.4.0 ; extra == 'redis'
 Requires-Python: >=3.12
 Project-URL: Telegram BotAPI Docs, https://core.telegram.org/bots/api
+Provides-Extra: redis

{botapi_py-1.2.1 → botapi_py-1.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "botapi-py"
-version = "1.2.1"
+version = "1.3.1"
 description = "A simple and flexible Python library to conveniently build Telegram bots using the Bot API."
 # readme = "README.md"
 # authors = [
@@ -15,6 +15,11 @@ dependencies = [
 [project.urls]
 "Telegram BotAPI Docs" = "https://core.telegram.org/bots/api"
 
+[project.optional-dependencies]
+redis = [
+    "redis>=6.4.0",
+]
+
 [build-system]
 requires = ["uv_build>=0.9.0,<0.10.0"]
 build-backend = "uv_build"

{botapi_py-1.2.1 → botapi_py-1.3.1}/src/botapi/__init__.py

@@ -1,4 +1,4 @@
-from . import core, enums, errors, types, utils
+from . import core, enums, errors, types, utils, dispatchers
 from .api import BotAPI
 
-__all__ = ['BotAPI', 'types', 'enums', 'utils', 'errors', 'core']
+__all__ = ['BotAPI', 'types', 'enums', 'utils', 'errors', 'core', 'dispatchers']

{botapi_py-1.2.1 → botapi_py-1.3.1}/src/botapi/__init__.pyi

@@ -1,4 +1,4 @@
-from . import core, enums, errors, types, utils
+from . import core, enums, errors, types, utils, dispatchers
 from .api import BotAPI
 
-__all__ = ['BotAPI', 'types', 'enums', 'utils', 'errors', 'core']
+__all__ = ['BotAPI', 'types', 'enums', 'utils', 'errors', 'core', 'dispatchers']

botapi_py-1.3.1/src/botapi/dispatchers/__init__.py

@@ -0,0 +1,7 @@
+from .get_updates_handler import GetUpdatesAsyncDispatcher
+from .redis_pubsub_handler import RedisPubSubAsyncDispatcher
+
+__all__ = [
+	'GetUpdatesAsyncDispatcher',
+	'RedisPubSubAsyncDispatcher',
+]

botapi_py-1.3.1/src/botapi/dispatchers/get_updates_handler.py

@@ -0,0 +1,188 @@
+import asyncio
+import logging
+import signal
+from typing import Any, Callable, Coroutine, TypeAlias
+
+import httpx
+
+import botapi
+from botapi.types import Update
+
+logger = logging.getLogger(__name__)
+
+UpdateHandler: TypeAlias = Callable[[Update], Coroutine[Any, Any, None]]
+
+
+class GetUpdatesAsyncDispatcher:
+	update_handler: UpdateHandler
+	tasks_shutdown_timeout: float
+	tasks: set[asyncio.Task] # prevent gc from collecting tasks before they finish
+	bot: botapi.api.BotAPI
+	reconnect_delay: float
+	allowed_updates: list[str]
+	offset: int
+	
+	def __init__(
+		self,
+		update_handler: UpdateHandler,
+		bot: botapi.api.BotAPI,
+		allowed_updates: list[str], # botapi.enums.UpdateType
+		reconnect_delay: float = 5,
+		shutdown_wait_timeout: float = 3
+	) -> None:
+		'''
+		Dispatcher that receives updates with long polling (`getUpdates`)
+		and dispatches them to a registered async handler.
+		
+		Args:
+			update_handler (UpdateHandler):
+				Async function to handle received messages.
+			bot (botapi.api.BotAPI):
+				A `Bot` instance.
+			allowed_updates (list[botapi.enums.UpdateType]):
+				List of allowed update types.
+			reconnect_delay (float, optional):
+				Delay in seconds before retrying after a failed request.
+			shutdown_wait_timeout (float, optional):
+				Timeout in seconds to wait for pending tasks to complete on shutdown.
+		'''
+		self.bot = bot
+		self.update_handler = update_handler
+		self.allowed_updates = allowed_updates
+		self.reconnect_delay = reconnect_delay
+		self.shutdown_wait_timeout = shutdown_wait_timeout
+		self.offset = -1
+		self.tasks = set()
+		
+	def _task_done_callback(self, task: asyncio.Task) -> None:
+		'''
+		Callback that is called by the event loop when an update_handler task is done.
+		
+		This catches and logs unhandled exceptions, so that they don't pass silently.
+		Also, it removes the completed task from the `tasks` set.
+		'''
+		try:
+			task.result()
+		except Exception:
+			logger.exception('Exception in handler')
+			
+		finally:
+			self.tasks.discard(task)
+			
+	async def _dispatch(self, update: Update) -> None:
+		'''
+		Dispatches the update to the registered handler, in a new task.
+		'''
+		task = asyncio.create_task(self.update_handler(update))
+		self.tasks.add(task)
+		task.add_done_callback(self._task_done_callback)
+		
+	async def _shutdown(self) -> None:
+		'''
+		Wait for pending/running tasks to complete (with a timeout),
+		then exits.
+		'''
+		if self.tasks:
+			logger.info('Waiting for %d tasks to complete...', len(self.tasks))
+			try:
+				await asyncio.wait_for(
+					asyncio.gather(*self.tasks, return_exceptions=True),
+					timeout=self.shutdown_wait_timeout
+				)
+			except asyncio.TimeoutError:
+				logger.warning('Some tasks were still running after timeout, CancelledError was raised.')
+				
+	async def _listen_forever(self) -> None:
+		'''
+		Listen for incoming updates forever, with long polling.
+		In case of connection errors, it will retry after a delay.
+		'''
+		GET_UPDATES_TIMEOUT = int(self.bot.session.timeout.read or 60) - 10 # 10 seconds less than the read timeout
+		
+		self.offset = -1
+		
+		while True:
+			try:
+				result = await self.bot.get_updates(
+					offset=self.offset,
+					limit=100,
+					timeout=GET_UPDATES_TIMEOUT,
+					allowed_updates=self.allowed_updates,
+				)
+				
+				if result:
+					self.offset = result[-1].update_id + 1 # next update offset
+					
+					for update in result:
+						try:
+							await self._dispatch(update)
+						except Exception:
+							logger.exception('Exception raised in the dispatcher:')
+							
+							
+			except botapi.errors.BotAPIError as e:
+				# logger.exception('Bot API error:')
+				logger.error('Bot API error, retrying soon: %s', e)
+				await asyncio.sleep(delay=self.reconnect_delay)
+				#TODO manage specific error codes (like 409 Conflict or 401 Unauthorized)
+				
+			except httpx.RequestError as e:
+				# logger.exception('Request error:')
+				logger.error('Request error, retrying soon: %s', e)
+				await asyncio.sleep(delay=self.reconnect_delay)
+				
+			except asyncio.CancelledError:
+				logger.info('Received termination signal')
+				break
+				
+			except Exception: # catch-all for unexpected exceptions; NEVER let the bot crash!
+				logger.exception('Unexpected exception in listen_forever:')
+				await asyncio.sleep(delay=self.reconnect_delay)
+				
+	async def _register_signal_handlers(self, task_to_cancel: asyncio.Task) -> None:
+		'''
+		Register signal handlers for graceful shutdown on:
+		- SIGTERM
+		- SIGINT
+		'''
+		loop = asyncio.get_running_loop()
+		
+		for sig in (signal.SIGTERM, signal.SIGINT):
+			loop.add_signal_handler(
+				sig,
+				task_to_cancel.cancel
+			)
+			
+	async def run_forever(self) -> None:
+		'''
+		Waits for incoming updates forever, and dispatches them to the registered handler.
+		This method **is blocking**, it terminates on SIGINT/SIGTERM signals.
+		
+		This method automatically retries failed `getUpdates` requests after a short delay.
+		
+		Example:
+		```python
+		dispatcher = GetUpdatesAsyncDispatcher(
+			update_handler=handler,
+			bot=bot,
+			allowed_updates=[
+				botapi.enums.UpdateType.MESSAGE,
+				botapi.enums.UpdateType.EDITED_MESSAGE,
+				botapi.enums.UpdateType.CALLBACK_QUERY,
+				botapi.enums.UpdateType.CHAT_MEMBER_UPDATED,
+				botapi.enums.UpdateType.CHAT_JOIN_REQUEST,
+			]
+		)
+		await dispatcher.run_forever()
+		```
+		'''
+		task = asyncio.create_task(self._listen_forever())
+		
+		try:
+			await task
+		except asyncio.CancelledError:
+			logger.info('Received termination signal')
+		finally:
+			logger.warning('Shutting down...')
+			await self._shutdown()
+			

botapi_py-1.3.1/src/botapi/dispatchers/redis_pubsub_handler.py

@@ -0,0 +1,201 @@
+import asyncio
+import json
+import logging
+import signal
+from typing import Any, Callable, Coroutine, TypeAlias
+
+import pydantic
+from botapi.types import Update
+
+try:
+	import redis.asyncio as redis
+	from redis.asyncio.client import PubSub
+	_has_redis = True
+except ImportError:
+	_has_redis = False
+	
+logger = logging.getLogger(__name__)
+
+UpdateHandler: TypeAlias = Callable[[Update], Coroutine[Any, Any, None]]
+
+
+class RedisPubSubAsyncDispatcher:
+	update_handler: UpdateHandler
+	tasks_shutdown_timeout: float
+	tasks: set[asyncio.Task] # prevent gc from collecting tasks before they finish
+	redis_client: redis.Redis
+	redis_reconnect_delay: float
+	pubsub: PubSub
+	pubsub_channel: str
+	
+	def __init__(
+		self,
+		update_handler: UpdateHandler,
+		pubsub_channel: str,
+		redis_client: redis.Redis,
+		redis_reconnect_delay: float = 5,
+		shutdown_wait_timeout: float = 3
+	) -> None:
+		'''
+		Dispatcher that receives updates from a Redis PUB/SUB
+		and dispatches them to a registered async handler.
+		
+		Args:
+			update_handler (UpdateHandler):
+				Async function to handle received messages.
+			redis_client (redis.Redis):
+				Redis client instance.
+			pubsub_channel (str):
+				Name of the Redis PUB/SUB channel to subscribe to.
+			redis_reconnect_delay (float, optional):
+				Delay in seconds before retrying connection on failure.
+			shutdown_wait_timeout (float, optional):
+				Timeout in seconds to wait for pending tasks to complete on shutdown.
+		'''
+		if not _has_redis:
+			raise ImportError('redis-py is not installed. Install `botapi-py[redis]` to use this dispatcher.')
+			
+		self.redis_client = redis_client
+		self.update_handler = update_handler
+		self.pubsub_channel = pubsub_channel
+		self.redis_reconnect_delay = redis_reconnect_delay
+		self.shutdown_wait_timeout = shutdown_wait_timeout
+		self.tasks = set()
+		self.pubsub = self.redis_client.pubsub(ignore_subscribe_messages=True)
+		
+	def _task_done_callback(self, task: asyncio.Task) -> None:
+		'''
+		Callback that is called by the event loop when an update_handler task is done.
+		
+		This catches and logs unhandled exceptions, so that they don't pass silently.
+		Also, it removes the completed task from the `tasks` set.
+		'''
+		try:
+			task.result()
+		except Exception:
+			logger.exception('Exception in handler')
+			
+		finally:
+			self.tasks.discard(task)
+			
+	async def _message_to_update(self, message: str) -> Update:
+		'''
+		Converts raw message (containing a JSON) into a Python dict (with json),
+		then validated it and loads it into an Update object with Pydantic.
+		'''
+		data = json.loads(message)
+		return Update.de_json(data)
+		
+	async def _dispatch(self, message: str) -> None:
+		'''
+		Converts raw message (containing a JSON) into a Python dict,
+		then dispatch it, to the registered handler, in a new task.
+		'''
+		try:
+			update = await self._message_to_update(message)
+		except json.JSONDecodeError:
+			logger.exception('Failed to decode JSON:')
+		except pydantic.ValidationError:
+			logger.exception('Failed pydantic validation:')
+		else:
+			task = asyncio.create_task(self.update_handler(update))
+			self.tasks.add(task)
+			task.add_done_callback(self._task_done_callback)
+			
+	async def _shutdown(self) -> None:
+		'''
+		Wait for pending/running tasks to complete (with a timeout),
+		then close the Redis connection.
+		'''
+		if self.tasks:
+			logger.info('Waiting for %d tasks to complete...', len(self.tasks))
+			try:
+				await asyncio.wait_for(
+					asyncio.gather(*self.tasks, return_exceptions=True),
+					timeout=self.shutdown_wait_timeout
+				)
+			except asyncio.TimeoutError:
+				logger.warning('Some tasks were still running after timeout, CancelledError was raised.')
+				
+		try:
+			await self.redis_client.aclose()
+		except Exception:
+			logger.exception('Exception while closing Redis connection:')
+			
+	async def _listen_forever(self) -> None:
+		'''
+		Listen for messages coming from the PUBSUB channel forever.
+		In case of connection errors, it will retry after a delay.
+		'''
+		while True:
+			try:
+				logger.info('Subscribing to channel %s...', self.pubsub_channel)
+				await self.pubsub.subscribe(self.pubsub_channel)
+				
+				logger.info('Subscribed to %s. Waiting for messages...', self.pubsub_channel)
+				
+				async for message in self.pubsub.listen():
+					if message['type'] == 'message':
+						try:
+							await self._dispatch(message['data'])
+						except Exception:
+							logger.exception('Exception raised in the dispatcher:')
+							
+			except redis.ConnectionError as e:
+				# logger.exception('Connection error, attempting to reconnect:')
+				logger.error('Connection error, attempting to reconnect: %s', e)
+				await asyncio.sleep(delay=self.redis_reconnect_delay)
+				
+				# await self.pubsub.unsubscribe()
+				
+			except asyncio.CancelledError:
+				logger.info('Received termination signal')
+				break
+				
+			except Exception: # catch-all for unexpected exceptions; NEVER let the bot crash!
+				logger.exception('Unexpected exception in listen_forever:')
+				await asyncio.sleep(delay=self.redis_reconnect_delay)
+				
+	async def _register_signal_handlers(self, task_to_cancel: asyncio.Task) -> None:
+		'''
+		Register signal handlers for graceful shutdown on:
+		- SIGTERM
+		- SIGINT
+		'''
+		loop = asyncio.get_running_loop()
+		
+		for sig in (signal.SIGTERM, signal.SIGINT):
+			loop.add_signal_handler(
+				sig,
+				task_to_cancel.cancel
+			)
+			
+	async def run_forever(self) -> None:
+		'''
+		Wait for incoming updates forever. This method **is blocking**.
+		Retries automatically after Redis connection errors, terminates on SIGINT/SIGTERM.
+		
+		Example:
+		```python
+		redis_client = redis.Redis(
+			host='localhost',
+			port=6379
+		)
+		dispatcher = RedisPubSubAsyncDispatcher(
+			update_handler=handler,
+			pubsub_channel='my_channel',
+			redis_client=redis_client
+		)
+		await dispatcher.run_forever()
+		```
+		'''
+		task = asyncio.create_task(self._listen_forever())
+		
+		try:
+			await task
+		except asyncio.CancelledError:
+			logger.info('Received termination signal')
+		finally:
+			logger.warning('Shutting down...')
+			await self._shutdown()
+