botapi-py 1.4.6__tar.gz → 1.4.8__tar.gz

{botapi_py-1.4.6 → botapi_py-1.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: botapi-py
-Version: 1.4.6
+Version: 1.4.8
 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

{botapi_py-1.4.6 → botapi_py-1.4.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "botapi-py"
-version = "1.4.6"
+version = "1.4.8"
 description = "A simple and flexible Python library to conveniently build fast Telegram bots using the Bot API."
 # readme = "README.md"
 # authors = [

{botapi_py-1.4.6 → botapi_py-1.4.8}/src/botapi/methods.py

@@ -10,6 +10,8 @@ from . import core
 
 from . import enums
 
+from .shortcuts import BotShortcuts
+
 from .types import (
 	Update,
 	WebhookInfo,
@@ -319,7 +321,7 @@ from .types import (
 	BoolAdapter,
 )
 
-class Bot(core.BaseBot):
+class Bot(core.BaseBot, BotShortcuts):
 	'''
 	Creates an instance of a new Bot API client.
 

botapi_py-1.4.8/src/botapi/shortcuts.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from typing import Optional, Union, List, cast
+
+from . import enums
+from . import types
+
+from . import methods
+
+
+class BotShortcuts:
+	'''
+	Mixin class containing shortcut bound methods for the `Bot` class.
+	These methods provide convenient wrappers around standard API methods.
+	'''
+	
+	async def send_media(
+		self,
+		chat_id: Union[int, str],
+		media: Union[types.InputFile, str],
+		file_type: enums.MediaType,
+		caption: Optional[str] = None,
+		parse_mode: Optional[enums.ParseMode] = enums.ParseMode.HTML,
+		caption_entities: Optional[List[types.MessageEntity]] = None,
+		show_caption_above_media: Optional[bool] = None,
+		has_spoiler: Optional[bool] = None,
+		disable_notification: Optional[bool] = None,
+		protect_content: Optional[bool] = None,
+		reply_parameters: Optional[types.ReplyParameters] = None,
+		reply_markup: Optional[Union[types.InlineKeyboardMarkup, types.ReplyKeyboardMarkup, types.ReplyKeyboardRemove, types.ForceReply]] = None,
+		message_effect_id: Optional[str] = None,
+		allow_paid_broadcast: Optional[bool] = None,
+		business_connection_id: Optional[str] = None,
+		message_thread_id: Optional[int] = None,
+		disable_content_type_detection: Optional[bool] = None, # Documents only
+	) -> types.Message:
+		'''
+		Method that sends common types of media by automatically routing to the correct `send_<type>` method.
+		
+		:param chat_id: Unique identifier for the target chat or username of the target channel.
+		:param media: File to send. Pass a file_id as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data.
+		:param file_type: The type of media to send. Use `enums.MediaType`.
+		:param caption: Media caption, 0-1024 characters.
+		:param parse_mode: Mode for parsing entities in the media caption.
+		:param caption_entities: A JSON-serialized list of special entities that appear in the caption, which can be specified instead of parse_mode.
+		:param show_caption_above_media: Pass True, if the caption must be shown above the message media.
+		:param has_spoiler: Pass True if the media needs to be covered with a spoiler animation.
+		:param disable_notification: Sends the message silently. Users will receive a notification with no sound.
+		:param protect_content: Protects the contents of the sent message from forwarding and saving.
+		:param reply_parameters: Description of the message to reply to.
+		:param reply_markup: Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user.
+		:param message_effect_id: Unique identifier of the message effect to be added to the message.
+		:param allow_paid_broadcast: Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance.
+		:param business_connection_id: Unique identifier of the business connection on behalf of which the message will be sent.
+		:param message_thread_id: Unique identifier for the target message thread (topic) of the forum; for forum supergroups only.
+		:param disable_content_type_detection: Disables automatic server-side content type detection.
+		:return: On success, the sent Message is returned.
+		'''
+		self = cast(methods.Bot, self)
+		
+		match file_type:
+			
+			case enums.MediaType.PHOTO:
+				return await self.send_photo(
+					chat_id=chat_id,
+					photo=media,
+					caption=caption,
+					parse_mode=parse_mode,
+					caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					has_spoiler=has_spoiler,
+					show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.VIDEO:
+				return await self.send_video(
+					chat_id=chat_id,
+					video=media,
+					caption=caption,
+					parse_mode=parse_mode,
+					caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					has_spoiler=has_spoiler,
+					show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.ANIMATION:
+				return await self.send_animation(
+					chat_id=chat_id,
+					animation=media,
+					caption=caption,
+					parse_mode=parse_mode,
+					caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					has_spoiler=has_spoiler,
+					show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.AUDIO:
+				return await self.send_audio(
+					chat_id=chat_id,
+					audio=media,
+					caption=caption,
+					parse_mode=parse_mode,
+					caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					# has_spoiler=has_spoiler,
+					# show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.DOCUMENT:
+				return await self.send_document(
+					chat_id=chat_id,
+					document=media,
+					caption=caption,
+					parse_mode=parse_mode,
+					caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					# has_spoiler=has_spoiler,
+					# show_caption_above_media=show_caption_above_media,
+					disable_content_type_detection=disable_content_type_detection
+				)
+				
+			case enums.MediaType.VOICE:
+				return await self.send_voice(
+					chat_id=chat_id,
+					voice=media,
+					caption=caption,
+					parse_mode=parse_mode,
+					caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					# has_spoiler=has_spoiler,
+					# show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.VIDEO_NOTE:
+				return await self.send_video_note(
+					chat_id=chat_id,
+					video_note=media,
+					# caption=caption,
+					# parse_mode=parse_mode,
+					# caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					# has_spoiler=has_spoiler,
+					# show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.STICKER:
+				return await self.send_sticker(
+					chat_id=chat_id,
+					sticker=media,
+					# caption=caption,
+					# parse_mode=parse_mode,
+					# caption_entities=caption_entities,
+					disable_notification=disable_notification,
+					protect_content=protect_content,
+					reply_parameters=reply_parameters,
+					reply_markup=reply_markup,
+					message_effect_id=message_effect_id,
+					allow_paid_broadcast=allow_paid_broadcast,
+					business_connection_id=business_connection_id,
+					message_thread_id=message_thread_id,
+					# has_spoiler=has_spoiler,
+					# show_caption_above_media=show_caption_above_media
+				)
+				
+			case enums.MediaType.STORY, enums.MediaType.PAID_MEDIA:
+				raise ValueError(f'Unsupported media type: {file_type}')
+				
+			case _:
+				raise ValueError(f'Unknown media type: {file_type}')
+				

{botapi_py-1.4.6 → botapi_py-1.4.8}/src/botapi/types.py

@@ -178,6 +178,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 		message_thread_id: Optional[int] = None,
 		direct_messages_topic_id: Optional[int] = None,
 		video_start_timestamp: Optional[int] = None,
+		message_effect_id: Optional[str] = None,
 		# suggested_post_parameters: Optional[SuggestedPostParameters] = None,
 	) -> Message:
 		'''
@@ -193,6 +194,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 			video_start_timestamp=video_start_timestamp,
 			disable_notification=disable_notification,
 			protect_content=protect_content,
+			message_effect_id=message_effect_id,
 			# suggested_post_parameters=suggested_post_parameters
 		)
 	
@@ -210,6 +212,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 		disable_notification: Optional[bool] = None,
 		protect_content: Optional[bool] = None,
 		# allow_paid_broadcast: Optional[bool] = None,
+		message_effect_id: Optional[str] = None,
 		# suggested_post_parameters: Optional[SuggestedPostParameters] = None,
 		# reply_parameters: Optional[ReplyParameters] = None,
 		# reply_markup: Optional[Union[InlineKeyboardMarkup, ReplyKeyboardMarkup, ReplyKeyboardRemove, ForceReply]] = None
@@ -232,6 +235,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 			disable_notification=disable_notification,
 			protect_content=protect_content,
 			# allow_paid_broadcast=allow_paid_broadcast,
+			message_effect_id=message_effect_id,
 			# suggested_post_parameters=suggested_post_parameters,
 			# reply_parameters=reply_parameters,
 			# reply_markup=reply_markup
@@ -338,19 +342,7 @@ class Message(MaybeInaccessibleMessage, frozen=True):
 		)
 	
 	@property
-	def media(self) -> Union[
-		Animation,
-		Audio,
-		Document,
-		list[PhotoSize],
-		Sticker,
-		Video,
-		VideoNote,
-		Voice,
-		Story,
-		PaidMedia,
-		None
-	]:
+	def media(self) -> Optional[MediaTypeUnion]:
 		'''
 		Actual multimedia content of this message.
 	
@@ -4525,3 +4517,5 @@ IntAdapter = TypeAdapter[int](int)
 StrAdapter = TypeAdapter[str](str)
 FloatAdapter = TypeAdapter[float](float)
 BoolAdapter = TypeAdapter[bool](bool)
+
+MediaTypeUnion = Union[Animation, Audio, Document, List[PhotoSize], Sticker, Video, VideoNote, Voice, Story, PaidMedia]