botapi-py 1.1.1__tar.gz → 1.3.0__tar.gz

{botapi_py-1.1.1 → botapi_py-1.3.0}/PKG-INFO

@@ -1,8 +1,10 @@
 Metadata-Version: 2.3
 Name: botapi-py
-Version: 1.1.1
+Version: 1.3.0
 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.1.1 → botapi_py-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "botapi-py"
-version = "1.1.1"
+version = "1.3.0"
 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.1.1 → botapi_py-1.3.0}/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.1.1 → botapi_py-1.3.0}/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.1.1 → botapi_py-1.3.0}/src/botapi/api.py

@@ -1,4 +1,6 @@
-# This is an autogenerated file. Do not edit this file directly.
+# WARNING!
+# This is an autogenerated file.
+# Do NOT edit this file directly, your changes will be overwritten.
 
 from __future__ import annotations
 
@@ -15,10 +17,14 @@ from .types import (
 	Message,
 	MessageId,
 	InaccessibleMessage,
+	MaybeInaccessibleMessage,
+	MaybeInaccessibleMessageAdapter,
 	MessageEntity,
 	TextQuote,
 	ExternalReplyInfo,
 	ReplyParameters,
+	MessageOrigin,
+	MessageOriginAdapter,
 	MessageOriginUser,
 	MessageOriginHiddenUser,
 	MessageOriginChat,
@@ -32,6 +38,8 @@ from .types import (
 	VideoNote,
 	Voice,
 	PaidMediaInfo,
+	PaidMedia,
+	PaidMediaAdapter,
 	PaidMediaPreview,
 	PaidMediaPhoto,
 	PaidMediaVideo,
@@ -53,9 +61,13 @@ from .types import (
 	ProximityAlertTriggered,
 	MessageAutoDeleteTimerChanged,
 	ChatBoostAdded,
+	BackgroundFill,
+	BackgroundFillAdapter,
 	BackgroundFillSolid,
 	BackgroundFillGradient,
 	BackgroundFillFreeformGradient,
+	BackgroundType,
+	BackgroundTypeAdapter,
 	BackgroundTypeFill,
 	BackgroundTypeWallpaper,
 	BackgroundTypePattern,
@@ -111,6 +123,8 @@ from .types import (
 	ChatInviteLink,
 	ChatAdministratorRights,
 	ChatMemberUpdated,
+	ChatMember,
+	ChatMemberAdapter,
 	ChatMemberOwner,
 	ChatMemberAdministrator,
 	ChatMemberMember,
@@ -126,6 +140,8 @@ from .types import (
 	BusinessOpeningHours,
 	StoryAreaPosition,
 	LocationAddress,
+	StoryAreaType,
+	StoryAreaTypeAdapter,
 	StoryAreaTypeLocation,
 	StoryAreaTypeSuggestedReaction,
 	StoryAreaTypeLink,
@@ -133,6 +149,8 @@ from .types import (
 	StoryAreaTypeUniqueGift,
 	StoryArea,
 	ChatLocation,
+	ReactionType,
+	ReactionTypeAdapter,
 	ReactionTypeEmoji,
 	ReactionTypeCustomEmoji,
 	ReactionTypePaid,
@@ -149,12 +167,16 @@ from .types import (
 	UniqueGift,
 	GiftInfo,
 	UniqueGiftInfo,
+	OwnedGift,
+	OwnedGiftAdapter,
 	OwnedGiftRegular,
 	OwnedGiftUnique,
 	OwnedGifts,
 	AcceptedGiftTypes,
 	StarAmount,
 	BotCommand,
+	BotCommandScope,
+	BotCommandScopeAdapter,
 	BotCommandScopeDefault,
 	BotCommandScopeAllPrivateChats,
 	BotCommandScopeAllGroupChats,
@@ -165,9 +187,13 @@ from .types import (
 	BotName,
 	BotDescription,
 	BotShortDescription,
+	MenuButton,
+	MenuButtonAdapter,
 	MenuButtonCommands,
 	MenuButtonWebApp,
 	MenuButtonDefault,
+	ChatBoostSource,
+	ChatBoostSourceAdapter,
 	ChatBoostSourcePremium,
 	ChatBoostSourceGiftCode,
 	ChatBoostSourceGiveaway,
@@ -179,16 +205,24 @@ from .types import (
 	BusinessConnection,
 	BusinessMessagesDeleted,
 	ResponseParameters,
+	InputMedia,
+	InputMediaAdapter,
 	InputMediaPhoto,
 	InputMediaVideo,
 	InputMediaAnimation,
 	InputMediaAudio,
 	InputMediaDocument,
 	InputFile,
+	InputPaidMedia,
+	InputPaidMediaAdapter,
 	InputPaidMediaPhoto,
 	InputPaidMediaVideo,
+	InputProfilePhoto,
+	InputProfilePhotoAdapter,
 	InputProfilePhotoStatic,
 	InputProfilePhotoAnimated,
+	InputStoryContent,
+	InputStoryContentAdapter,
 	InputStoryContentPhoto,
 	InputStoryContentVideo,
 	Sticker,
@@ -197,6 +231,8 @@ from .types import (
 	InputSticker,
 	InlineQuery,
 	InlineQueryResultsButton,
+	InlineQueryResult,
+	InlineQueryResultAdapter,
 	InlineQueryResultArticle,
 	InlineQueryResultPhoto,
 	InlineQueryResultGif,
@@ -217,6 +253,8 @@ from .types import (
 	InlineQueryResultCachedVideo,
 	InlineQueryResultCachedVoice,
 	InlineQueryResultCachedAudio,
+	InputMessageContent,
+	InputMessageContentAdapter,
 	InputTextMessageContent,
 	InputLocationMessageContent,
 	InputVenueMessageContent,
@@ -235,10 +273,14 @@ from .types import (
 	ShippingQuery,
 	PreCheckoutQuery,
 	PaidMediaPurchased,
+	RevenueWithdrawalState,
+	RevenueWithdrawalStateAdapter,
 	RevenueWithdrawalStatePending,
 	RevenueWithdrawalStateSucceeded,
 	RevenueWithdrawalStateFailed,
 	AffiliateInfo,
+	TransactionPartner,
+	TransactionPartnerAdapter,
 	TransactionPartnerUser,
 	TransactionPartnerChat,
 	TransactionPartnerAffiliateProgram,
@@ -252,6 +294,8 @@ from .types import (
 	PassportFile,
 	EncryptedPassportElement,
 	EncryptedCredentials,
+	PassportElementError,
+	PassportElementErrorAdapter,
 	PassportElementErrorDataField,
 	PassportElementErrorFrontSide,
 	PassportElementErrorReverseSide,
@@ -264,48 +308,6 @@ from .types import (
 	Game,
 	CallbackGame,
 	GameHighScore,
-	MaybeInaccessibleMessage,
-	MaybeInaccessibleMessageAdapter,
-	MessageOrigin,
-	MessageOriginAdapter,
-	PaidMedia,
-	PaidMediaAdapter,
-	BackgroundFill,
-	BackgroundFillAdapter,
-	BackgroundType,
-	BackgroundTypeAdapter,
-	ChatMember,
-	ChatMemberAdapter,
-	StoryAreaType,
-	StoryAreaTypeAdapter,
-	ReactionType,
-	ReactionTypeAdapter,
-	OwnedGift,
-	OwnedGiftAdapter,
-	BotCommandScope,
-	BotCommandScopeAdapter,
-	MenuButton,
-	MenuButtonAdapter,
-	ChatBoostSource,
-	ChatBoostSourceAdapter,
-	InputMedia,
-	InputMediaAdapter,
-	InputPaidMedia,
-	InputPaidMediaAdapter,
-	InputProfilePhoto,
-	InputProfilePhotoAdapter,
-	InputStoryContent,
-	InputStoryContentAdapter,
-	InlineQueryResult,
-	InlineQueryResultAdapter,
-	InputMessageContent,
-	InputMessageContentAdapter,
-	RevenueWithdrawalState,
-	RevenueWithdrawalStateAdapter,
-	TransactionPartner,
-	TransactionPartnerAdapter,
-	PassportElementError,
-	PassportElementErrorAdapter,
 	IntAdapter,
 	StrAdapter,
 	FloatAdapter,

botapi_py-1.3.0/src/botapi/boilerplate.py

@@ -0,0 +1,20 @@
+import enum
+
+from typing import TypeVar, Callable
+
+# Enums
+E = TypeVar('E', bound=enum.Enum)
+
+def extend_enum(*sources: type[E]) -> Callable[..., type[E]]:
+	'''
+	Decorator that extends an Enum class with members
+	from one or more source Enum classes.
+	'''
+	def decorator(target: type[E]) -> type[E]:
+		for source in sources:
+			for member in source:
+				if member.name not in target.__members__:
+					target._member_map_[member.name] = member
+		return target
+	return decorator
+	

botapi_py-1.3.0/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.0/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.0/src/botapi/dispatchers/redis_pubsub_handler.py

@@ -0,0 +1,200 @@
+import asyncio
+import json
+import logging
+import signal
+from typing import Any, Callable, Coroutine, TypeAlias
+
+import pydantic
+from botapi.types import Update
+
+logger = logging.getLogger(__name__)
+
+try:
+	import redis.asyncio as redis
+	from redis.asyncio.client import PubSub
+except ImportError as e:
+	logger.error(
+		'The Redis python library is not installed. Please install it to use this feature.'
+	)
+	raise e
+	
+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.
+		'''
+		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()
+