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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: botapi-py
-Version: 1.3.2
-Summary: A simple and flexible Python library to conveniently build Telegram bots using the Bot API.
+Version: 1.4.0
+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: redis>=6.4.0 ; extra == 'redis'

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

@@ -1,7 +1,7 @@
 [project]
 name = "botapi-py"
-version = "1.3.2"
-description = "A simple and flexible Python library to conveniently build Telegram bots using the Bot API."
+version = "1.4.0"
+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" }

botapi_py-1.4.0/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.0/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.2 → botapi_py-1.4.0}/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.2 → botapi_py-1.4.0}/src/botapi/dispatchers/get_updates_handler.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 import logging
 import signal
@@ -17,7 +19,7 @@ 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
+	bot: botapi.methods.Bot
 	reconnect_delay: float
 	allowed_updates: list[str]
 	offset: int
@@ -25,7 +27,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 +39,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.

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

@@ -85,7 +85,7 @@ class RedisPubSubAsyncDispatcher:
 		then validated it and loads it into an Update object with Pydantic.
 		'''
 		data = json.loads(message)
-		return Update.de_json(data)
+		return Update.from_dict(data)
 		
 	async def _dispatch(self, message: str) -> None:
 		'''

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

@@ -1,4 +1,6 @@
 import enum
+from typing import Union
+
 
 class ChatType(enum.StrEnum):
 	PRIVATE = 'private'
@@ -100,11 +102,9 @@ class ServiceMessage(enum.StrEnum):
 	WEB_APP_DATA = 'web_app_data'
 	SUGGESTED_POST = 'suggested_post_info'
 	
-# @boilerplate.extend_enum(MediaType, ServiceMessage)
-class MessageType(enum.StrEnum):
+class OtherMessageType(enum.StrEnum):
 	'''
-	The content of this message.
-	All of these fields should be mutually exclusive.
+	The type of this message (that does NOT contain multimedia or service content).
 	'''
 	TEXT = 'text'
 	CHECKLIST = 'checklist'
@@ -116,68 +116,17 @@ class MessageType(enum.StrEnum):
 	LOCATION = 'location'
 	CONTACT = 'contact'
 	
-	# MediaType - Python sucks.
-	ANIMATION = 'animation'
-	AUDIO = 'audio'
-	DOCUMENT = 'document'
-	PHOTO = 'photo'
-	STICKER = 'sticker'
-	VIDEO = 'video'
-	VIDEO_NOTE = 'video_note'
-	VOICE = 'voice'
-	STORY = 'story'
-	PAID_MEDIA = 'paid_media'
-	
-	# ServiceMessage - Python sucks.
-	NEW_CHAT_MEMBERS = 'new_chat_members'
-	LEFT_CHAT_MEMBER = 'left_chat_member'
-	NEW_CHAT_TITLE = 'new_chat_title'
-	NEW_CHAT_PHOTO = 'new_chat_photo'
-	DELETE_CHAT_PHOTO = 'delete_chat_photo'
-	GROUP_CHAT_CREATED = 'group_chat_created'
-	SUPERGROUP_CHAT_CREATED = 'supergroup_chat_created'
-	CHANNEL_CHAT_CREATED = 'channel_chat_created'
-	MESSAGE_AUTO_DELETE_TIMER_CHANGED = 'message_auto_delete_timer_changed'
-	MIGRATE_TO_CHAT_ID = 'migrate_to_chat_id'
-	MIGRATE_FROM_CHAT_ID = 'migrate_from_chat_id'
-	PINNED_MESSAGE = 'pinned_message'
-	SUCCESSFUL_PAYMENT = 'successful_payment'
-	REFUNDED_PAYMENT = 'refunded_payment'
-	USERS_SHARED = 'users_shared'
-	CHAT_SHARED = 'chat_shared'
-	GIFT = 'gift'
-	UNIQUE_GIFT = 'unique_gift'
-	CONNECTED_WEBSITE = 'connected_website'
-	WRITE_ACCESS_ALLOWED = 'write_access_allowed'
-	PASSPORT_DATA = 'passport_data'
-	PROXIMITY_ALERT_TRIGGERED = 'proximity_alert_triggered'
-	BOOST_ADDED = 'boost_added'
-	CHAT_BACKGROUND_SET = 'chat_background_set'
-	CHECKLIST_TASKS_DONE = 'checklist_tasks_done'
-	CHECKLIST_TASKS_ADDED = 'checklist_tasks_added'
-	DIRECT_MESSAGE_PRICE_CHANGED = 'direct_message_price_changed'
-	FORUM_TOPIC_CREATED = 'forum_topic_created'
-	FORUM_TOPIC_EDITED = 'forum_topic_edited'
-	FORUM_TOPIC_CLOSED = 'forum_topic_closed'
-	FORUM_TOPIC_REOPENED = 'forum_topic_reopened'
-	GENERAL_FORUM_TOPIC_HIDDEN = 'general_forum_topic_hidden'
-	GENERAL_FORUM_TOPIC_UNHIDDEN = 'general_forum_topic_unhidden'
-	GIVEAWAY = 'giveaway'
-	GIVEAWAY_CREATED = 'giveaway_created'
-	GIVEAWAY_WINNERS = 'giveaway_winners'
-	GIVEAWAY_COMPLETED = 'giveaway_completed'
-	PAID_MESSAGE_PRICE_CHANGED = 'paid_message_price_changed'
-	SUGGESTED_POST_APPROVED = 'suggested_post_approved'
-	SUGGESTED_POST_APPROVAL_FAILED = 'suggested_post_approval_failed'
-	SUGGESTED_POST_DECLINED = 'suggested_post_declined'
-	SUGGESTED_POST_PAID = 'suggested_post_paid'
-	SUGGESTED_POST_REFUNDED = 'suggested_post_refunded'
-	VIDEO_CHAT_SCHEDULED = 'video_chat_scheduled'
-	VIDEO_CHAT_STARTED = 'video_chat_started'
-	VIDEO_CHAT_ENDED = 'video_chat_ended'
-	VIDEO_CHAT_PARTICIPANTS_INVITED = 'video_chat_participants_invited'
-	WEB_APP_DATA = 'web_app_data'
-	SUGGESTED_POST = 'suggested_post_info'
+MessageType = Union[
+	MediaType,
+	ServiceMessage,
+	OtherMessageType
+]
+'''
+The type of the **actual** message content.
+
+All of the fields are mutually exclusive, since a message
+can only be of one 'type' at a time.
+'''
 	
 class ChatMemberStatus(enum.StrEnum):
 	'''

botapi_py-1.3.2/src/botapi/api.py → botapi_py-1.4.0/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.2 → botapi_py-1.4.0}/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.2/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.2/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']