botapi-py 1.4.0__tar.gz → 1.4.2__tar.gz

{botapi_py-1.4.0 → botapi_py-1.4.2}/PKG-INFO

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

{botapi_py-1.4.0 → botapi_py-1.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "botapi-py"
-version = "1.4.0"
+version = "1.4.2"
 description = "A simple and flexible Python library to conveniently build fast Telegram bots using the Bot API."
 # readme = "README.md"
 # authors = [
@@ -17,6 +17,7 @@ dependencies = [
 
 [project.optional-dependencies]
 redis = [
+    "orjson>=3.11.3",
     "redis>=6.4.0",
 ]
 

{botapi_py-1.4.0 → botapi_py-1.4.2}/src/botapi/dispatchers/__init__.py

@@ -1,10 +1,14 @@
+from .common import UpdateHandler
+
 from .get_updates_handler import GetUpdatesAsyncDispatcher
 try:
+	# Fails at runtime if redis-py is not installed
 	from .redis_pubsub_handler import RedisPubSubAsyncDispatcher
 except ImportError:
 	pass
 
 __all__ = [
+	'UpdateHandler',
 	'GetUpdatesAsyncDispatcher',
 	'RedisPubSubAsyncDispatcher',
 ]

botapi_py-1.4.2/src/botapi/dispatchers/__init__.pyi

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

botapi_py-1.4.2/src/botapi/dispatchers/common.py

@@ -0,0 +1,62 @@
+from abc import ABC
+from typing import Any, Callable, Coroutine, TypeAlias, Union
+
+from botapi.types import Update
+
+UpdateHandler1: TypeAlias = Callable[
+	[Update],
+	Coroutine[Any, Any, None]
+]
+'''
+Represents an async update handler function.
+It has the following signature:
+- `async def handler(update: Update) -> None: ...`
+'''
+
+UpdateHandler2: TypeAlias = Callable[
+	[Update, str],
+	Coroutine[Any, Any, None]
+]
+'''
+Represents an async update handler function.
+It has the following signature:
+- `async def handler(update: Update, bot_token: str) -> None: ...`
+'''
+
+UpdateHandler: TypeAlias = Union[
+	UpdateHandler1,
+	UpdateHandler2
+]
+'''
+Represents an async update handler function.
+
+It can have one of the following signatures:
+- `async def handler(update: Update) -> None: ...`
+- `async def handler(update: Update, bot_token: str) -> None: ...`
+
+The second signature is especially useful when the dispatcher
+is used to handle incoming updates from multiple bots.
+'''
+
+class BaseAsyncDispatcher(ABC):
+	'''
+	Abstract base class for all async update dispatchers.
+	'''
+	
+	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 = Dispatcher(
+			...
+		)
+		await dispatcher.run_forever()
+		```
+		'''
+		raise NotImplementedError()
+		

{botapi_py-1.4.0 → botapi_py-1.4.2}/src/botapi/dispatchers/get_updates_handler.py

@@ -1,22 +1,23 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 import logging
 import signal
-from typing import Any, Callable, Coroutine, TypeAlias
+from typing import override
 
 import httpx
 
 import botapi
 from botapi.types import Update
 
-logger = logging.getLogger(__name__)
-
-UpdateHandler: TypeAlias = Callable[[Update], Coroutine[Any, Any, None]]
+from .common import BaseAsyncDispatcher, UpdateHandler
 
+logger = logging.getLogger(__name__)
 
-class GetUpdatesAsyncDispatcher:
+class GetUpdatesAsyncDispatcher(BaseAsyncDispatcher):
 	update_handler: UpdateHandler
+	update_handler_argcount: int
 	tasks_shutdown_timeout: float
 	tasks: set[asyncio.Task] # prevent gc from collecting tasks before they finish
 	bot: botapi.methods.Bot
@@ -55,6 +56,7 @@ class GetUpdatesAsyncDispatcher:
 		self.shutdown_wait_timeout = shutdown_wait_timeout
 		self.offset = -1
 		self.tasks = set()
+		self.update_handler_argcount = len(inspect.getfullargspec(update_handler).args)
 		
 	def _task_done_callback(self, task: asyncio.Task) -> None:
 		'''
@@ -75,7 +77,13 @@ class GetUpdatesAsyncDispatcher:
 		'''
 		Dispatches the update to the registered handler, in a new task.
 		'''
-		task = asyncio.create_task(self.update_handler(update))
+		if self.update_handler_argcount == 1:
+			coro = self.update_handler(update) # pyright: ignore[reportCallIssue]
+		else:
+			coro = self.update_handler(update, self.bot.token) # pyright: ignore[reportCallIssue]
+			
+		task = asyncio.create_task(coro)
+		
 		self.tasks.add(task)
 		task.add_done_callback(self._task_done_callback)
 		
@@ -155,6 +163,7 @@ class GetUpdatesAsyncDispatcher:
 				task_to_cancel.cancel
 			)
 			
+	@override
 	async def run_forever(self) -> None:
 		'''
 		Waits for incoming updates forever, and dispatches them to the registered handler.

{botapi_py-1.4.0 → botapi_py-1.4.2}/src/botapi/dispatchers/redis_pubsub_handler.py

@@ -1,12 +1,19 @@
+from __future__ import annotations
+
 import asyncio
+import inspect
 import json
 import logging
 import signal
-from typing import Any, Callable, Coroutine, TypeAlias
+from typing import override
 
+import orjson
 import pydantic
+
 from botapi.types import Update
 
+from .common import BaseAsyncDispatcher, UpdateHandler
+
 try:
 	import redis.asyncio as redis
 	from redis.asyncio.client import PubSub
@@ -17,21 +24,22 @@ except ImportError as e:
 	
 logger = logging.getLogger(__name__)
 
-UpdateHandler: TypeAlias = Callable[[Update], Coroutine[Any, Any, None]]
-
 
-class RedisPubSubAsyncDispatcher:
+class RedisPubSubAsyncDispatcher(BaseAsyncDispatcher):
 	update_handler: UpdateHandler
+	update_handler_argcount: int
 	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
+	bot_token_json_key: str
 	
 	def __init__(
 		self,
 		update_handler: UpdateHandler,
+		bot_token_json_key: str,
 		pubsub_channel: str,
 		redis_client: redis.Redis,
 		redis_reconnect_delay: float = 5,
@@ -41,9 +49,20 @@ class RedisPubSubAsyncDispatcher:
 		Dispatcher that receives updates from a Redis PUB/SUB
 		and dispatches them to a registered async handler.
 		
+		This dispatcher is atypical but very useful, especially when you need to handle
+		updates coming from a lot of different bots AND from many different projects.
+		
+		**NOTE:**
+		This dispatcher assumes that the bot token is part of the update JSON payload itself
+		inside the `bot_token_json_key` key (see constructor), so either:
+		- the software handling the `PUBLISH` must manipulate the JSON accordingly, or
+		- a custom Bot API Server must do this.
+		
 		Args:
 			update_handler (UpdateHandler):
 				Async function to handle received messages.
+			bot_token_json_key (str):
+				Name of the JSON key in the update payload that contains the bot token.
 			redis_client (redis.Redis):
 				Redis client instance.
 			pubsub_channel (str):
@@ -56,13 +75,15 @@ class RedisPubSubAsyncDispatcher:
 		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.bot_token_json_key = bot_token_json_key
+		self.redis_client = redis_client
 		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)
+		self.update_handler_argcount = len(inspect.getfullargspec(update_handler).args)
 		
 	def _task_done_callback(self, task: asyncio.Task) -> None:
 		'''
@@ -79,13 +100,21 @@ class RedisPubSubAsyncDispatcher:
 		finally:
 			self.tasks.discard(task)
 			
-	async def _message_to_update(self, message: str) -> Update:
+	async def _message_to_update_and_token(self, message: str) -> tuple[Update, str]:
 		'''
-		Converts raw message (containing a JSON) into a Python dict (with json),
-		then validated it and loads it into an Update object with Pydantic.
+		Converts raw message (containing a JSON) into a Python dict, then:
+		- extracts the bot token from the specified `self.bot_token_json_key` key
+		- validates the update into an `Update` object.
 		'''
-		data = json.loads(message)
-		return Update.from_dict(data)
+		data: dict = orjson.loads(message)
+		
+		if self.bot_token_json_key not in data:
+			err = f'Missing bot token key "{self.bot_token_json_key}" in the update JSON payload'
+			raise KeyError(err)
+			
+		bot_token = data.pop(self.bot_token_json_key)
+		
+		return Update.from_dict(data), bot_token
 		
 	async def _dispatch(self, message: str) -> None:
 		'''
@@ -93,13 +122,19 @@ class RedisPubSubAsyncDispatcher:
 		then dispatch it, to the registered handler, in a new task.
 		'''
 		try:
-			update = await self._message_to_update(message)
+			update, bot_token = await self._message_to_update_and_token(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))
+			if self.update_handler_argcount == 1:
+				coro = self.update_handler(update) # pyright: ignore[reportCallIssue]
+			else:
+				coro = self.update_handler(update, bot_token) # pyright: ignore[reportCallIssue]
+				
+			task = asyncio.create_task(coro)
+			
 			self.tasks.add(task)
 			task.add_done_callback(self._task_done_callback)
 			
@@ -171,6 +206,7 @@ class RedisPubSubAsyncDispatcher:
 				task_to_cancel.cancel
 			)
 			
+	@override
 	async def run_forever(self) -> None:
 		'''
 		Wait for incoming updates forever. This method **is blocking**.

{botapi_py-1.4.0 → botapi_py-1.4.2}/src/botapi/enums.py

@@ -14,6 +14,8 @@ class UpdateType(enum.StrEnum):
 	
 	You can use these to filter updates, using the `allowed_updates`
 	parameter in `getUpdates` and `setWebhook` methods.
+	
+	Source: https://github.com/tdlib/telegram-bot-api/blob/3b6a0b769c4a7fbe064087a4ad9fe6b1dbda498f/telegram-bot-api/Client.cpp#L15491
 	'''
 	MESSAGE = 'message'
 	EDITED_MESSAGE = 'edited_message'
@@ -22,12 +24,24 @@ class UpdateType(enum.StrEnum):
 	INLINE_QUERY = 'inline_query'
 	CHOSEN_INLINE_RESULT = 'chosen_inline_result'
 	CALLBACK_QUERY = 'callback_query'
+	CUSTOM_EVENT = 'custom_event'
+	CUSTOM_QUERY = 'custom_query'
 	SHIPPING_QUERY = 'shipping_query'
 	PRE_CHECKOUT_QUERY = 'pre_checkout_query'
 	POLL = 'poll'
 	POLL_ANSWER = 'poll_answer'
-	CHAT_MEMBER_UPDATED = 'chat_member_updated'
+	MY_CHAT_MEMBER = 'my_chat_member'
+	CHAT_MEMBER = 'chat_member'
 	CHAT_JOIN_REQUEST = 'chat_join_request'
+	CHAT_BOOST = 'chat_boost'
+	REMOVED_CHAT_BOOST = 'removed_chat_boost'
+	MESSAGE_REACTION = 'message_reaction'
+	MESSAGE_REACTION_COUNT = 'message_reaction_count'
+	BUSINESS_CONNECTION = 'business_connection'
+	BUSINESS_MESSAGE = 'business_message'
+	EDITED_BUSINESS_MESSAGE = 'edited_business_message'
+	DELETED_BUSINESS_MESSAGES = 'deleted_business_messages'
+	PURCHASED_PAID_MEDIA = 'purchased_paid_media'
 	
 class MediaType(enum.StrEnum):
 	'''