botapi-py 1.3.3__tar.gz → 1.4.1__tar.gz

{botapi_py-1.3.3 → botapi_py-1.4.1}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.3
 Name: botapi-py
-Version: 1.3.3
-Summary: A simple and flexible Python library to conveniently build Telegram bots using the Bot API.
+Version: 1.4.1
+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.3.3 → botapi_py-1.4.1}/pyproject.toml

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

botapi_py-1.4.1/src/botapi/__init__.py

@@ -0,0 +1,4 @@
+from . import enums, errors, types, utils, dispatchers
+from .methods import Bot
+
+__all__ = ['Bot', 'types', 'enums', 'utils', 'errors', 'dispatchers']

botapi_py-1.4.1/src/botapi/__init__.pyi

@@ -0,0 +1,4 @@
+from . import enums, errors, types, utils, dispatchers
+from .methods import Bot
+
+__all__ = ['Bot', 'types', 'enums', 'utils', 'errors', 'dispatchers']

{botapi_py-1.3.3 → botapi_py-1.4.1}/src/botapi/core.py

@@ -20,7 +20,7 @@ MultipartFile: TypeAlias = tuple[
 MultipartFiles: TypeAlias = dict[str, MultipartFile]
 
 
-class BaseBotAPI:
+class BaseBot:
 	def __init__(
 		self,
 		token: str,

{botapi_py-1.3.3 → botapi_py-1.4.1}/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.1/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.1/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.3.3 → botapi_py-1.4.1}/src/botapi/dispatchers/get_updates_handler.py

@@ -1,23 +1,26 @@
+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.api.BotAPI'
+	bot: botapi.methods.Bot
 	reconnect_delay: float
 	allowed_updates: list[str]
 	offset: int
@@ -25,7 +28,7 @@ class GetUpdatesAsyncDispatcher:
 	def __init__(
 		self,
 		update_handler: UpdateHandler,
-		bot: 'botapi.api.BotAPI',
+		bot: botapi.methods.Bot,
 		allowed_updates: list[str], # botapi.enums.UpdateType
 		reconnect_delay: float = 5,
 		shutdown_wait_timeout: float = 3
@@ -37,7 +40,7 @@ class GetUpdatesAsyncDispatcher:
 		Args:
 			update_handler (UpdateHandler):
 				Async function to handle received messages.
-			bot (botapi.api.BotAPI):
+			bot (botapi.Bot):
 				A `Bot` instance.
 			allowed_updates (list[botapi.enums.UpdateType]):
 				List of allowed update types.
@@ -53,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:
 		'''
@@ -73,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)
 		
@@ -153,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.3.3 → botapi_py-1.4.1}/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.de_json(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.3.3/src/botapi/api.py → botapi_py-1.4.1/src/botapi/methods.py

@@ -314,7 +314,7 @@ from .types import (
 	BoolAdapter,
 )
 
-class BotAPI(core.BaseBotAPI):
+class Bot(core.BaseBot):
 	'''
 	Creates an instance of a new Bot API client.
 

{botapi_py-1.3.3 → botapi_py-1.4.1}/src/botapi/types.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Union, Optional, Literal, List, Any
 from . import enums
 
 if TYPE_CHECKING:
-	from . import api
+	from . import methods
 
 class MaybeInaccessibleMessage(BaseModel, frozen=True):
 	message_id: int
@@ -127,15 +127,118 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 	web_app_data: Optional[WebAppData] = Field(default=None)
 	reply_markup: Optional[InlineKeyboardMarkup] = Field(default=None)
 	
-	async def delete(self, bot: api.BotAPI) -> bool:
+	async def delete(
+		self,
+		bot: methods.Bot
+	) -> bool:
+		'''
+		Deletes this message.
+		Shortcut for `bot.delete_message`.
+		'''
 		return await bot.delete_message(
 			chat_id=self.chat.id,
 			message_id=self.message_id
 		)
 	
+	async def pin(
+		self,
+		bot: methods.Bot,
+		disable_notification: bool | None = None,
+	) -> bool:
+		'''
+		Pins this message in the chat.
+		Shortcut for `bot.pin_chat_message`.
+		'''
+		return await bot.pin_chat_message(
+			chat_id=self.chat.id,
+			message_id=self.message_id,
+			disable_notification=disable_notification
+		)
+	
+	async def unpin(
+		self,
+		bot: methods.Bot
+	) -> bool:
+		'''
+		Unpins this message in the chat.
+		Shortcut for `bot.unpin_chat_message`.
+		'''
+		return await bot.unpin_chat_message(
+			chat_id=self.chat.id,
+			message_id=self.message_id
+		)
+	
+	async def forward(
+		self,
+		bot: methods.Bot,
+		chat_id: int | str,
+		disable_notification: bool | None = None,
+		protect_content: bool | None = None,
+		message_thread_id: int | None = None,
+		direct_messages_topic_id: int | None = None,
+		video_start_timestamp: int | None = None,
+		# suggested_post_parameters: SuggestedPostParameters | None = None,
+	) -> Message:
+		'''
+		Forwards this message to another chat.
+		Shortcut for `bot.forward_message`.
+		'''
+		return await bot.forward_message(
+			chat_id=chat_id,
+			from_chat_id=self.chat.id,
+			message_id=self.message_id,
+			message_thread_id=message_thread_id,
+			direct_messages_topic_id=direct_messages_topic_id,
+			video_start_timestamp=video_start_timestamp,
+			disable_notification=disable_notification,
+			protect_content=protect_content,
+			# suggested_post_parameters=suggested_post_parameters
+		)
+	
+	async def copy_to(
+		self,
+		bot: methods.Bot,
+		chat_id: int | str,
+		message_thread_id: int | None = None,
+		direct_messages_topic_id: int | None = None,
+		video_start_timestamp: int | None = None,
+		# caption: str | None = None,
+		# parse_mode: str | None = 'HTML',
+		# caption_entities: List[MessageEntity] | None = None,
+		# show_caption_above_media: bool | None = None,
+		disable_notification: bool | None = None,
+		protect_content: bool | None = None,
+		# allow_paid_broadcast: bool | None = None,
+		# suggested_post_parameters: SuggestedPostParameters | None = None,
+		# reply_parameters: ReplyParameters | None = None,
+		# reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply | None = None
+	) -> MessageId:
+		'''
+		Copies this message to another chat.
+		Shortcut for `bot.copy_message`.
+		'''
+		return await bot.copy_message(
+			chat_id=chat_id,
+			from_chat_id=self.chat.id,
+			message_id=self.message_id,
+			message_thread_id=message_thread_id,
+			direct_messages_topic_id=direct_messages_topic_id,
+			video_start_timestamp=video_start_timestamp,
+			# caption=caption,
+			# parse_mode=parse_mode,
+			# caption_entities=caption_entities,
+			# show_caption_above_media=show_caption_above_media,
+			disable_notification=disable_notification,
+			protect_content=protect_content,
+			# allow_paid_broadcast=allow_paid_broadcast,
+			# suggested_post_parameters=suggested_post_parameters,
+			# reply_parameters=reply_parameters,
+			# reply_markup=reply_markup
+		)
+	
 	async def edit_text(
 		self,
-		bot: api.BotAPI,
+		bot: methods.Bot,
 		text: str,
 		# inline_message_id: Optional[str] = None,
 		parse_mode: str | None = 'HTML',
@@ -143,6 +246,11 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 		link_preview_options: LinkPreviewOptions | None = None,
 		reply_markup: InlineKeyboardMarkup | None = None,
 	) -> Message | bool:
+		'''
+		Edits the text of this message.
+		Shortcut for `bot.edit_message_text`.
+		You can pass **either** `parse_mode` or `entities` to format the message text.
+		'''
 		return await bot.edit_message_text(
 			chat_id=self.chat.id,
 			message_id=self.message_id,
@@ -157,10 +265,14 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 	
 	async def edit_reply_markup(
 		self,
-		bot: api.BotAPI,
+		bot: methods.Bot,
 		# inline_message_id: Optional[str] = None,
 		reply_markup: InlineKeyboardMarkup | None = None,
 	) -> Message | bool:
+		'''
+		Edits the reply markup (inline keyboard) of this message.
+		Shortcut for `bot.edit_message_reply_markup`.
+		'''
 		return await bot.edit_message_reply_markup(
 			chat_id=self.chat.id,
 			message_id=self.message_id,
@@ -171,7 +283,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 	
 	async def reply_text(
 		self,
-		bot: api.BotAPI,
+		bot: methods.Bot,
 		text: str,
 		parse_mode: str | None = 'HTML',
 		entities: list[MessageEntity] | None = None,
@@ -194,7 +306,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 	
 		You can pass **either** `reply_to_original_message` or `reply_parameters` to reply
 		to this message. If both are passed, `reply_parameters` will be used.
-		
+	
 		'''
 		if not reply_parameters and reply_to_original_message:
 			reply_parameters = ReplyParameters(
@@ -2093,9 +2205,12 @@ class Update(BaseModel, frozen=True):
 	removed_chat_boost: Optional[ChatBoostRemoved] = Field(default=None)
 	
 	@staticmethod
-	def de_json(
+	def from_dict(
 		json_data: dict[str, Any]
 	) -> Update:
+		'''
+		Converts a JSON dictionary to an `Update` object.
+		'''
 		return Update.model_validate(json_data)
 	 
 
@@ -2237,6 +2352,9 @@ class MessageEntity(BaseModel, frozen=True):
 	def from_dict(
 		json_data: list[dict[str, Any]]
 	) -> list[MessageEntity]:
+		'''
+		Converts a list of JSON dictionaries to a list of `MessageEntity` objects.
+		'''
 		return [MessageEntity.model_validate(item) for item in json_data]
 	 
 
@@ -3205,6 +3323,9 @@ class InlineKeyboardMarkup(BaseModel, frozen=True):
 	def from_dict(
 		json_data: list[list[dict[str, Any]]]
 	) -> InlineKeyboardMarkup:
+		'''
+		Converts a JSON dictionary to an `InlineKeyboardMarkup` object.
+		'''
 		keyboard = [
 			[
 				InlineKeyboardButton(**button) for button in row
@@ -3407,8 +3528,11 @@ class ChatJoinRequest(BaseModel, frozen=True):
 	
 	async def approve(
 		self,
-		bot: api.BotAPI
+		bot: methods.Bot
 	) -> bool:
+		'''
+		Approves this chat join request.
+		'''
 		return await bot.approve_chat_join_request(
 			chat_id=self.chat.id,
 			user_id=self.from_user.id
@@ -3416,8 +3540,11 @@ class ChatJoinRequest(BaseModel, frozen=True):
 	
 	async def decline(
 		self,
-		bot: api.BotAPI
+		bot: methods.Bot
 	) -> bool:
+		'''
+		Declines this chat join request.
+		'''
 		return await bot.decline_chat_join_request(
 			chat_id=self.chat.id,
 			user_id=self.from_user.id

botapi_py-1.3.3/src/botapi/__init__.py

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

botapi_py-1.3.3/src/botapi/__init__.pyi

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