botapi-py 1.4.11__tar.gz → 1.4.13__tar.gz

{botapi_py-1.4.11 → botapi_py-1.4.13}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "botapi-py"
-version = "1.4.11"
+version = "1.4.13"
 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.11 → botapi_py-1.4.13}/src/botapi/shortcuts.py

@@ -18,7 +18,7 @@ class BotShortcuts:
 		self,
 		chat_id: Union[int, str],
 		media: Union[types.InputFile, str, None],
-		file_type: Optional[enums.MediaType],
+		file_type: Optional[enums.MediaType | str],
 		caption: Optional[str] = None,
 		parse_mode: Optional[enums.ParseMode] = enums.ParseMode.HTML,
 		caption_entities: Optional[List[types.MessageEntity]] = None,

{botapi_py-1.4.11 → botapi_py-1.4.13}/src/botapi/types.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 from pydantic import BaseModel, Field, TypeAdapter
-from typing import TYPE_CHECKING, Union, Optional, Literal, List, Any
+from typing import TYPE_CHECKING, Union, Optional, Literal, List, Any, overload
 
 from . import enums
 
@@ -3200,7 +3200,51 @@ class File(BaseModel, frozen=True):
 	file_id: str
 	file_unique_id: str
 	file_size: Optional[int] = Field(default=None)
-	file_path: Optional[str] = Field(default=None) 
+	file_path: Optional[str] = Field(default=None)
+	
+	@overload
+	async def download(
+		self,
+		bot: methods.Bot,
+		destination_path: str
+	) -> None: ...
+	
+	@overload
+	async def download(
+		self,
+		bot: methods.Bot,
+		destination_path: None = None
+	) -> bytes: ...
+	
+	async def download(
+		self,
+		bot: methods.Bot,
+		destination_path: Optional[str] = None
+	) -> bytes | None:
+		'''
+		Convenience method to download a file from Telegram servers.
+	
+		: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.
+		'''
+		file_path = self.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 = bot._compose_api_file_url(file_path=file_path) # pyright: ignore[reportPrivateUsage]
+	
+		response = await bot.session.get(url)
+		content = response.content
+	
+		if destination_path:
+			with open(destination_path, 'wb') as f:
+				f.write(content)
+			return None
+	
+		return content
+	 
 
 class WebAppInfo(BaseModel, frozen=True):
 	'''