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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: botapi-py
-Version: 1.4.8
+Version: 1.4.10
 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.8 → botapi_py-1.4.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "botapi-py"
-version = "1.4.8"
+version = "1.4.10"
 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.8 → botapi_py-1.4.10}/src/botapi/core.py

@@ -49,7 +49,19 @@ class BaseBot:
 			url += 'test/'
 		url += method
 		return url
-
+		
+	def _compose_api_file_url(self, file_path: str) -> str:
+		'''
+		Composes the URL for file downloads from the Telegram Bot API.
+		'''
+		# https://api.telegram.org/file/bot<token>/<file_path>
+		# https://api.telegram.org/file/bot<token>/test/<file_path>
+		url = f'{self.api_url}/file/bot{self.token}/'
+		if self.test_server:
+			url += 'test/'
+		url += file_path
+		return url
+		
 	def _convert_data(self, data: dict[str, Any]) -> tuple[dict[str, Any], MultipartFiles]:
 		new_data: dict[str, Any] = {}
 		files: MultipartFiles = {} # (filename, file_content, mime_type)

{botapi_py-1.4.8 → botapi_py-1.4.10}/src/botapi/shortcuts.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Optional, Union, List, cast
+from typing import Optional, Union, List, cast, overload
 
 from . import enums
 from . import types
@@ -17,8 +17,8 @@ class BotShortcuts:
 	async def send_media(
 		self,
 		chat_id: Union[int, str],
-		media: Union[types.InputFile, str],
-		file_type: enums.MediaType,
+		media: Union[types.InputFile, str, None],
+		file_type: Optional[enums.MediaType],
 		caption: Optional[str] = None,
 		parse_mode: Optional[enums.ParseMode] = enums.ParseMode.HTML,
 		caption_entities: Optional[List[types.MessageEntity]] = None,
@@ -36,6 +36,7 @@ class BotShortcuts:
 	) -> types.Message:
 		'''
 		Method that sends common types of media by automatically routing to the correct `send_<type>` method.
+		Also supports send_message with text only for convenience.
 		
 		: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.
@@ -58,6 +59,29 @@ class BotShortcuts:
 		'''
 		self = cast(methods.Bot, self)
 		
+		# Plain text message
+		if not media or not file_type:
+			if not caption:
+				raise ValueError('Either media or caption must be provided.')
+				
+			return await self.send_message(
+				chat_id=chat_id,
+				# =media,
+				text=caption,
+				parse_mode=parse_mode,
+				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
+			)
+			
 		match file_type:
 			
 			case enums.MediaType.PHOTO:
@@ -219,3 +243,51 @@ class BotShortcuts:
 			case _:
 				raise ValueError(f'Unknown media type: {file_type}')
 				
+	@overload
+	async def download_file(
+		self,
+		file: types.File,
+		destination_path: str
+	) -> None: ...
+	
+	@overload
+	async def download_file(
+		self,
+		file: types.File,
+		destination_path: None = None
+	) -> bytes: ...
+	
+	async def download_file(
+		self,
+		file: types.File,
+		destination_path: Optional[str] = None
+	) -> bytes | None:
+		'''
+		Convenience method to download a file from Telegram servers.
+		
+		Call this method with a `File` object obtained via `get_file`.
+		
+		:param file: File object to download.
+		:param destination_path: Optional path to save the downloaded file. If not provided, the file content will be returned as bytes.
+		:return: The file content as bytes if destination_path is not provided, otherwise None.
+		'''
+		self = cast(methods.Bot, self)
+		
+		file_path = file.file_path
+		if not file_path:
+			raise ValueError('The file does not have a valid file_path to download.')
+			
+		# https://api.telegram.org/file/bot<token>/<file_path>
+		# https://api.telegram.org/file/bot<token>/test/<file_path>
+		url = self._compose_api_file_url(file_path=file_path) # pyright: ignore[reportPrivateUsage]
+		
+		response = await self.session.get(url)
+		content = response.content
+		
+		if destination_path:
+			with open(destination_path, 'wb') as f:
+				f.write(content)
+			return None
+			
+		return content
+