Xtao-Labs/MTPyroger
3
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add examples to all available methods

Browse Source
This commit is contained in:
Dan 2019-07-25 11:22:14 +02:00
parent fe2ccc6036
commit 2dec2442e5
92 changed files with 876 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
pyrogram/client/methods/bots/answer_callback_query.py
View File

@ -56,8 +56,14 @@ class AnswerCallbackQuery(BaseClient):
Returns:
``bool``: True, on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Answer without alert
app.answer_callback_query(query_id, text=text)
# Answer with alert
app.answer_callback_query(query_id, text=text, show_alert=True)
"""
return self.send(
functions.messages.SetBotCallbackAnswer(

13
pyrogram/client/methods/bots/answer_inline_query.py
View File

@ -81,8 +81,17 @@ class AnswerInlineQuery(BaseClient):
Returns:
``bool``: True, on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InlineQueryResultArticle, InputTextMessageContent
app.answer_inline_query(
inline_query_id,
results=[
InlineQueryResultArticle(
"Title",
InputTextMessageContent("Message content"))])
"""
return self.send(
functions.messages.SetInlineBotResults(

7
pyrogram/client/methods/bots/get_game_high_scores.py
View File

@ -51,8 +51,11 @@ class GetGameHighScores(BaseClient):
Returns:
List of :obj:`GameHighScore`: On success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
scores = app.get_game_high_scores(user_id, chat_id, message_id)
print(scores)
"""
# TODO: inline_message_id

12
pyrogram/client/methods/bots/get_inline_bot_results.py
View File

@ -27,7 +27,7 @@ class GetInlineBotResults(BaseClient):
def get_inline_bot_results(
self,
bot: Union[int, str],
query: str,
query: str = "",
offset: str = "",
latitude: float = None,
longitude: float = None
@ -40,8 +40,9 @@ class GetInlineBotResults(BaseClient):
Unique identifier of the inline bot you want to get results from. You can specify
a @username (str) or a bot ID (int).
query (``str``):
query (``str``, *optional*):
Text of the query (up to 512 characters).
Defaults to "" (empty string).
offset (``str``, *optional*):
Offset of the results to be returned.
@ -58,8 +59,13 @@ class GetInlineBotResults(BaseClient):
:obj:`BotResults <pyrogram.api.types.messages.BotResults>`: On Success.
Raises:
RPCError: In case of a Telegram RPC error.
TimeoutError: In case the bot fails to answer within 10 seconds.
Example:
.. code-block:: python
results = app.get_inline_bot_results("pyrogrambot")
print(results)
"""
# TODO: Don't return the raw type

6
pyrogram/client/methods/bots/request_callback_answer.py
View File

@ -53,8 +53,12 @@ class RequestCallbackAnswer(BaseClient):
or as an alert.
Raises:
RPCError: In case of a Telegram RPC error.
TimeoutError: In case the bot fails to answer within 10 seconds.
Example:
.. code-block:: python
app.request_callback_answer(chat_id, message_id, "callback_data")
"""
# Telegram only wants bytes, but we are allowed to pass strings too.

6
pyrogram/client/methods/bots/send_game.py
View File

@ -62,8 +62,10 @@ class SendGame(BaseClient):
Returns:
:obj:`Message`: On success, the sent game message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_game(chat_id, "gamename")
"""
r = self.send(
functions.messages.SendMedia(

6
pyrogram/client/methods/bots/send_inline_bot_result.py
View File

@ -60,8 +60,10 @@ class SendInlineBotResult(BaseClient):
Returns:
:obj:`Message`: On success, the sent inline result message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_inline_bot_result(chat_id, query_id, result_id)
"""
return self.send(
functions.messages.SendInlineBotResult(

10
pyrogram/client/methods/bots/set_game_score.py
View File

@ -66,8 +66,14 @@ class SetGameScore(BaseClient):
:obj:`Message` | ``bool``: On success, if the message was sent by the bot, the edited message is returned,
True otherwise.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Set new score
app.set_game_score(user_id, 1000)
# Force set new score
app.set_game_score(user_id, 25, force=True)
"""
r = self.send(
functions.messages.SetGameScore(

12
pyrogram/client/methods/chats/add_chat_members.py
View File

@ -47,6 +47,18 @@ class AddChatMembers(BaseClient):
Returns:
``bool``: On success, True is returned.
Example:
.. code-block:: python
# Add one member to a group or channel
app.add_chat_members(chat_id, user_id)
# Add multiple members to a group or channel
app.add_chat_members(chat_id, [user_id1, user_id2, user_id3])
# Change forward_limit (for basic groups only)
app.add_chat_members(chat_id, user_id, forward_limit=25)
"""
peer = self.resolve_peer(chat_id)

10
pyrogram/client/methods/chats/archive_chats.py
View File

@ -37,8 +37,14 @@ class ArchiveChats(BaseClient):
Returns:
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Archive chat
app.archive_chats(chat_id)
# Archive multiple chats at once
app.archive_chats([chat_id1, chat_id2, chat_id3])
"""
if not isinstance(chat_ids, list):

5
pyrogram/client/methods/chats/create_channel.py
View File

@ -38,6 +38,11 @@ class CreateChannel(BaseClient):
Returns:
:obj:`Chat`: On success, a chat object is returned.
Example:
.. code-block:: python
app.create_channel("Channel Title", "Channel Description")
"""
r = self.send(
functions.channels.CreateChannel(

5
pyrogram/client/methods/chats/create_group.py
View File

@ -46,6 +46,11 @@ class CreateGroup(BaseClient):
Returns:
:obj:`Chat`: On success, a chat object is returned.
Example:
.. code-block:: python
app.create_group("Group Title", user_id)
"""
if not isinstance(users, list):
users = [users]

5
pyrogram/client/methods/chats/create_supergroup.py
View File

@ -42,6 +42,11 @@ class CreateSupergroup(BaseClient):
Returns:
:obj:`Chat`: On success, a chat object is returned.
Example:
.. code-block:: python
app.create_supergroup("Supergroup Title", "Supergroup Description")
"""
r = self.send(
functions.channels.CreateChannel(

5
pyrogram/client/methods/chats/delete_channel.py
View File

@ -33,6 +33,11 @@ class DeleteChannel(BaseClient):
Returns:
``bool``: On success, True is returned.
Example:
.. code-block:: python
app.delete_channel(channel_id)
"""
self.send(
functions.channels.DeleteChannel(

14
pyrogram/client/methods/chats/delete_chat_photo.py
View File

@ -28,12 +28,8 @@ class DeleteChatPhoto(BaseClient):
chat_id: Union[int, str]
) -> bool:
"""Delete a chat photo.
Photos can't be changed for private chats.
You must be an administrator in the chat for this to work and must have the appropriate admin rights.
Note:
In regular groups (non-supergroups), this method will only work if the "All Members Are Admins"
setting is off.
You must be an administrator in the chat for this to work and must have the appropriate admin rights.
Parameters:
chat_id (``int`` | ``str``):
@ -43,8 +39,12 @@ class DeleteChatPhoto(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
``ValueError`` if a chat_id belongs to user.
ValueError: if a chat_id belongs to user.
Example:
.. code-block:: python
app.delete_chat_photo(chat_id)
"""
peer = self.resolve_peer(chat_id)

5
pyrogram/client/methods/chats/delete_supergroup.py
View File

@ -33,6 +33,11 @@ class DeleteSupergroup(BaseClient):
Returns:
``bool``: On success, True is returned.
Example:
.. code-block:: python
app.delete_supergroup(supergroup_id)
"""
self.send(
functions.channels.DeleteChannel(

7
pyrogram/client/methods/chats/export_chat_invite_link.py
View File

@ -47,8 +47,13 @@ class ExportChatInviteLink(BaseClient):
``str``: On success, the exported invite link is returned.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case the chat_id belongs to a user.
Example:
.. code-block:: python
link = app.export_chat_invite_link(chat_id)
print(link)
"""
peer = self.resolve_peer(chat_id)

7
pyrogram/client/methods/chats/get_chat.py
View File

@ -44,8 +44,13 @@ class GetChat(BaseClient):
otherwise, a chat preview object is returned.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case the chat invite link points to a chat you haven't joined yet.
Example:
.. code-block:: python
chat = app.get_chat("pyrogram")
print(chat)
"""
match = self.INVITE_LINK_RE.match(str(chat_id))

7
pyrogram/client/methods/chats/get_chat_member.py
View File

@ -44,8 +44,11 @@ class GetChatMember(BaseClient):
Returns:
:obj:`ChatMember`: On success, a chat member is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
dan = app.get_chat_member("pyrogramchat", "haskell")
print(dan)
"""
chat = self.resolve_peer(chat_id)
user = self.resolve_peer(user_id)

13
pyrogram/client/methods/chats/get_chat_members.py
View File

@ -91,8 +91,19 @@ class GetChatMembers(BaseClient):
List of :obj:`ChatMember`: On success, a list of chat members is returned.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case you used an invalid filter or a chat id that belongs to a user.
Example:
.. code-block:: python
# Get first 200 recent members
app.get_chat_members("pyrogramchat")
# Get all administrators
app.get_chat_members("pyrogramchat", filter="administrators")
# Get all bots
app.get_chat_members("pyrogramchat", filter="bots")
"""
peer = self.resolve_peer(chat_id)

7
pyrogram/client/methods/chats/get_chat_members_count.py
View File

@ -37,8 +37,13 @@ class GetChatMembersCount(BaseClient):
``int``: On success, the chat members count is returned.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case a chat id belongs to user.
Example:
.. code-block:: python
count = app.get_chat_members_count("pyrogramchat")
print(count)
"""
peer = self.resolve_peer(chat_id)

10
pyrogram/client/methods/chats/get_dialogs.py
View File

@ -56,8 +56,14 @@ class GetDialogs(BaseClient):
Returns:
List of :obj:`Dialog`: On success, a list of dialogs is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Get first 100 dialogs
app.get_dialogs()
# Get pinned dialogs
app.get_dialogs(pinned_only=True)
"""
while True:

7
pyrogram/client/methods/chats/get_dialogs_count.py
View File

@ -31,8 +31,11 @@ class GetDialogsCount(BaseClient):
Returns:
``int``: On success, the dialogs count is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
count = app.get_dialogs_count()
print(count)
"""
if pinned_only:

16
pyrogram/client/methods/chats/iter_chat_members.py
View File

@ -77,8 +77,20 @@ class IterChatMembers(BaseClient):
Returns:
``Generator``: A generator yielding :obj:`ChatMember` objects.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Iterate though all chat members
for member in app.iter_chat_members("pyrogramchat"):
print(member.user.first_name)
# Iterate though all administrators
for member in app.iter_chat_members("pyrogramchat", filter="administrators"):
print(member.user.first_name)
# Iterate though all bots
for member in app.iter_chat_members("pyrogramchat", filter="bots"):
print(member.user.first_name)
"""
current = 0
yielded = set()

8
pyrogram/client/methods/chats/iter_dialogs.py
View File

@ -46,8 +46,12 @@ class IterDialogs(BaseClient):
Returns:
``Generator``: A generator yielding :obj:`Dialog` objects.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Iterate through all dialogs
for dialog in app.iter_dialogs():
print(dialog.chat.first_name or dialog.chat.title)
"""
current = 0
total = limit or (1 << 31) - 1

10
pyrogram/client/methods/chats/join_chat.py
View File

@ -36,8 +36,14 @@ class JoinChat(BaseClient):
Returns:
:obj:`Chat`: On success, a chat object is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Join chat via username
app.join_chat("pyrogram")
# Join chat via invite link
app.join_chat("https://t.me/joinchat/AAAAAE0QmSW3IUmm3UFR7A")
"""
match = self.INVITE_LINK_RE.match(chat_id)

12
pyrogram/client/methods/chats/kick_chat_member.py
View File

@ -57,8 +57,16 @@ class KickChatMember(BaseClient):
:obj:`Message` | ``bool``: On success, a service message will be returned (when applicable), otherwise, in
case a message object couldn't be returned, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from time import time
# Ban chat member forever
app.kick_chat_member(chat_id, user_id)
# Kick chat member and automatically unban after 24h
app.kick_chat_member(chat_id, user_id, int(time.time() + 86400))
"""
chat_peer = self.resolve_peer(chat_id)
user_peer = self.resolve_peer(user_id)

11
pyrogram/client/methods/chats/leave_chat.py
View File

@ -37,9 +37,16 @@ class LeaveChat(BaseClient):
delete (``bool``, *optional*):
Deletes the group chat dialog after leaving (for simple group chats, not supergroups).
Defaults to False.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Leave chat or channel
app.leave_chat(chat_id)
# Leave basic chat and also delete the dialog
app.leave_chat(chat_id, delete=True)
"""
peer = self.resolve_peer(chat_id)

10
pyrogram/client/methods/chats/pin_chat_message.py
View File

@ -47,8 +47,14 @@ class PinChatMessage(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Pin with notification
app.pin_chat_message(chat_id, message_id)
# Pin without notification
app.pin_chat_message(chat_id, message_id, disable_notification=True)
"""
self.send(
functions.messages.UpdatePinnedMessage(

7
pyrogram/client/methods/chats/promote_chat_member.py
View File

@ -78,8 +78,11 @@ class PromoteChatMember(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Promote chat member to supergroup admin
app.promote_chat_member(chat_id, user_id)
"""
self.send(
functions.channels.EditAdmin(

10
pyrogram/client/methods/chats/restrict_chat.py
View File

@ -72,8 +72,14 @@ class RestrictChat(BaseClient):
Returns:
:obj:`Chat`: On success, a chat object is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Completely restrict chat
app.restrict_chat(chat_id)
# All chat members can only send text messages
app.restrict_chat(chat_id, can_send_messages=True)
"""
send_messages = True
send_media = True

15
pyrogram/client/methods/chats/restrict_chat_member.py
View File

@ -85,8 +85,19 @@ class RestrictChatMember(BaseClient):
Returns:
:obj:`Chat`: On success, a chat object is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from time import time
# Completely restrict chat member forever
app.restrict_chat_member(chat_id, user_id)
# Chat member can't send messages for 24h
app.restrict_chat_member(chat_id, user_id, int(time.time() + 86400))
# Chat member can only send text messages
app.restrict_chat_member(chat_id, user_id, can_send_messages=True)
"""
send_messages = True
send_media = True

8
pyrogram/client/methods/chats/set_chat_description.py
View File

@ -42,8 +42,12 @@ class SetChatDescription(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
``ValueError`` if a chat_id doesn't belong to a supergroup or a channel.
ValueError: if a chat_id doesn't belong to a supergroup or a channel.
Example:
.. code-block:: python
app.set_chat_description(chat_id, "New Description")
"""
peer = self.resolve_peer(chat_id)

28
pyrogram/client/methods/chats/set_chat_photo.py
View File

@ -17,12 +17,11 @@
# along with Pyrogram. If not, see <http://www.gnu.org/licenses/>.
import os
from base64 import b64decode
from struct import unpack
from typing import Union
from pyrogram.api import functions, types
from ...ext import BaseClient
from ...ext import BaseClient, utils
class SetChatPhoto(BaseClient):
@ -32,38 +31,43 @@ class SetChatPhoto(BaseClient):
photo: str
) -> bool:
"""Set a new profile photo for the chat.
Photos can't be changed for private chats.
You must be an administrator in the chat for this to work and must have the appropriate admin rights.
Note:
In regular groups (non-supergroups), this method will only work if the "All Members Are Admins"
setting is off.
You must be an administrator in the chat for this to work and must have the appropriate admin rights.
Parameters:
chat_id (``int`` | ``str``):
Unique identifier (int) or username (str) of the target chat.
photo (``str``):
New chat photo. You can pass a :obj:`Photo` id or a file path to upload a new photo.
New chat photo. You can pass a :obj:`Photo` file_id or a file path to upload a new photo from your local
machine.
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: if a chat_id belongs to user.
Example:
.. code-block:: python
# Set chat photo using a local file
app.set_chat_photo(chat_id, "photo.jpg")
# Set chat photo using an exiting Photo file_id
app.set_chat_photo(chat_id, photo.file_id)
"""
peer = self.resolve_peer(chat_id)
if os.path.exists(photo):
photo = types.InputChatUploadedPhoto(file=self.save_file(photo))
else:
s = unpack("<qq", b64decode(photo + "=" * (-len(photo) % 4), "-_"))
unpacked = unpack("<iiqqc", utils.decode(photo))
photo = types.InputChatPhoto(
id=types.InputPhoto(
id=s[0],
access_hash=s[1],
id=unpacked[2],
access_hash=unpacked[3],
file_reference=b""
)
)

6
pyrogram/client/methods/chats/set_chat_title.py
View File

@ -47,8 +47,12 @@ class SetChatTitle(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case a chat id belongs to user.
Example:
.. code-block:: python
app.set_chat_title(chat_id, "New Title")
"""
peer = self.resolve_peer(chat_id)

10
pyrogram/client/methods/chats/unarchive_chats.py
View File

@ -37,8 +37,14 @@ class UnarchiveChats(BaseClient):
Returns:
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Unarchive chat
app.unarchive_chats(chat_id)
# Unarchive multiple chats at once
app.unarchive_chats([chat_id1, chat_id2, chat_id3])
"""
if not isinstance(chat_ids, list):

7
pyrogram/client/methods/chats/unban_chat_member.py
View File

@ -43,8 +43,11 @@ class UnbanChatMember(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Unban chat member right now
app.unban_chat_member(chat_id, user_id)
"""
self.send(
functions.channels.EditBanned(

6
pyrogram/client/methods/chats/unpin_chat_message.py
View File

@ -38,8 +38,10 @@ class UnpinChatMessage(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.unpin_chat_message(chat_id)
"""
self.send(
functions.messages.UpdatePinnedMessage(

6
pyrogram/client/methods/chats/update_chat_username.py
View File

@ -42,8 +42,12 @@ class UpdateChatUsername(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case a chat id belongs to a user or chat.
Example:
.. code-block:: python
app.update_chat_username(chat_id, "new_username")
"""
peer = self.resolve_peer(chat_id)

11
pyrogram/client/methods/contacts/add_contacts.py
View File

@ -37,8 +37,15 @@ class AddContacts(BaseClient):
Returns:
:obj:`types.contacts.ImportedContacts`
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InputPhoneContact
app.add_contacts([
InputPhoneContact("39123456789", "Foo"),
InputPhoneContact("38987654321", "Bar"),
InputPhoneContact("01234567891", "Baz")])
"""
imported_contacts = self.send(
functions.contacts.ImportContacts(

6
pyrogram/client/methods/contacts/delete_contacts.py
View File

@ -38,8 +38,10 @@ class DeleteContacts(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.delete_contacts([user_id1, user_id2, user_id3])
"""
contacts = []

8
pyrogram/client/methods/contacts/get_contacts.py
View File

@ -30,14 +30,16 @@ log = logging.getLogger(__name__)
class GetContacts(BaseClient):
def get_contacts(self) -> List["pyrogram.User"]:
# TODO: Create a Users object and return that
"""Get contacts from your Telegram address book.
Returns:
List of :obj:`User`: On success, a list of users is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
contacts = app.get_contacts()
print(contacts)
"""
while True:
try:

7
pyrogram/client/methods/contacts/get_contacts_count.py
View File

@ -27,8 +27,11 @@ class GetContactsCount(BaseClient):
Returns:
``int``: On success, the contacts count is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
count = app.get_contacts_count()
print(count)
"""
return len(self.send(functions.contacts.GetContacts(hash=0)).contacts)

13
pyrogram/client/methods/messages/delete_messages.py
View File

@ -50,8 +50,17 @@ class DeleteMessages(BaseClient):
Returns:
``bool``: True on success, False otherwise.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Delete one message
app.delete_messages(chat_id, message_id)
# Delete multiple messages at once
app.delete_messages(chat_id, list_of_message_ids)
# Delete messages only on your side (without revoking)
app.delete_messages(chat_id, message_id, revoke=False)
"""
peer = self.resolve_peer(chat_id)
message_ids = list(message_ids) if not isinstance(message_ids, int) else [message_ids]

33
pyrogram/client/methods/messages/download_media.py
View File

@ -57,24 +57,23 @@ class DownloadMedia(BaseClient):
Blocks the code execution until the file has been downloaded.
Defaults to True.
progress (``callable``):
Pass a callback function to view the download progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
progress (``callable``, *optional*):
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes downloaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -85,8 +84,16 @@ class DownloadMedia(BaseClient):
the download failed or was deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: if the message doesn't contain any downloadable media
Example:
.. code-block:: python
# Download from Message
app.download_media(message)
# Download from file id
app.download_media("CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
"""
error_message = "This message doesn't contain any downloadable media"
available_media = ("audio", "document", "photo", "sticker", "animation", "video", "voice", "video_note")

9
pyrogram/client/methods/messages/edit_inline_caption.py
View File

@ -30,7 +30,7 @@ class EditInlineCaption(BaseClient):
parse_mode: Union[str, None] = object,
reply_markup: "pyrogram.InlineKeyboardMarkup" = None
) -> bool:
"""Edit the caption of **inline** media messages.
"""Edit the caption of inline media messages.
Parameters:
inline_message_id (``str``):
@ -52,8 +52,11 @@ class EditInlineCaption(BaseClient):
Returns:
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Bots only
app.edit_inline_caption(inline_message_id, "new media caption")
"""
return self.edit_inline_text(
inline_message_id=inline_message_id,

19
pyrogram/client/methods/messages/edit_inline_media.py
View File

@ -33,7 +33,7 @@ class EditInlineMedia(BaseClient):
media: InputMedia,
reply_markup: "pyrogram.InlineKeyboardMarkup" = None
) -> bool:
"""Edit **inline** animation, audio, document, photo or video messages.
"""Edit inline animation, audio, document, photo or video messages.
When the inline message is edited, a new file can't be uploaded. Use a previously uploaded file via its file_id
or specify a URL.
@ -52,8 +52,21 @@ class EditInlineMedia(BaseClient):
Returns:
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InputMediaPhoto, InputMediaVideo, InputMediaAudio
# Bots only
# Replace the current media with a local photo
app.edit_inline_media(inline_message_id, InputMediaPhoto("new_photo.jpg"))
# Replace the current media with a local video
app.edit_inline_media(inline_message_id, InputMediaVideo("new_video.mp4"))
# Replace the current media with a local audio
app.edit_inline_media(inline_message_id, InputMediaAudio("new_audio.mp3"))
"""
caption = media.caption
parse_mode = media.parse_mode

14
pyrogram/client/methods/messages/edit_inline_reply_markup.py
View File

@ -27,7 +27,7 @@ class EditInlineReplyMarkup(BaseClient):
inline_message_id: str,
reply_markup: "pyrogram.InlineKeyboardMarkup" = None
) -> bool:
"""Edit only the reply markup of **inline** messages sent via the bot (for inline bots).
"""Edit only the reply markup of inline messages sent via the bot (for inline bots).
Parameters:
inline_message_id (``str``):
@ -39,8 +39,16 @@ class EditInlineReplyMarkup(BaseClient):
Returns:
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InlineKeyboardMarkup, InlineKeyboardButton
# Bots only
app.edit_inline_reply_markup(
inline_message_id,
InlineKeyboardMarkup([[
InlineKeyboardButton("New button", callback_data="new_data")]]))
"""
return self.send(
functions.messages.EditInlineBotMessage(

16
pyrogram/client/methods/messages/edit_inline_text.py
View File

@ -32,7 +32,7 @@ class EditInlineText(BaseClient):
disable_web_page_preview: bool = None,
reply_markup: "pyrogram.InlineKeyboardMarkup" = None
) -> bool:
"""Edit the text of **inline** messages.
"""Edit the text of inline messages.
Parameters:
inline_message_id (``str``):
@ -57,8 +57,18 @@ class EditInlineText(BaseClient):
Returns:
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Bots only
# Simple edit text
app.edit_inline_text(inline_message_id, "new text")
# Take the same text message, remove the web page preview only
app.edit_inline_text(
inline_message_id, message.text,
disable_web_page_preview=True)
"""
return self.send(

6
pyrogram/client/methods/messages/edit_message_caption.py
View File

@ -58,8 +58,10 @@ class EditMessageCaption(BaseClient):
Returns:
:obj:`Message`: On success, the edited message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.edit_message_caption(chat_id, message_id, "new media caption")
"""
return self.edit_message_text(
chat_id=chat_id,

15
pyrogram/client/methods/messages/edit_message_media.py
View File

@ -60,8 +60,19 @@ class EditMessageMedia(BaseClient):
Returns:
:obj:`Message`: On success, the edited message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InputMediaPhoto, InputMediaVideo, InputMediaAudio
# Replace the current media with a local photo
app.edit_message_media(chat_id, message_id, InputMediaPhoto("new_photo.jpg"))
# Replace the current media with a local video
app.edit_message_media(chat_id, message_id, InputMediaVideo("new_video.mp4"))
# Replace the current media with a local audio
app.edit_message_media(chat_id, message_id, InputMediaAudio("new_audio.mp3"))
"""
caption = media.caption
parse_mode = media.parse_mode

12
pyrogram/client/methods/messages/edit_message_reply_markup.py
View File

@ -47,8 +47,16 @@ class EditMessageReplyMarkup(BaseClient):
Returns:
:obj:`Message`: On success, the edited message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InlineKeyboardMarkup, InlineKeyboardButton
# Bots only
app.edit_message_reply_markup(
chat_id, message_id,
InlineKeyboardMarkup([[
InlineKeyboardButton("New button", callback_data="new_data")]]))
"""
r = self.send(
functions.messages.EditMessage(

12
pyrogram/client/methods/messages/edit_message_text.py
View File

@ -63,8 +63,16 @@ class EditMessageText(BaseClient):
Returns:
:obj:`Message`: On success, the edited message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Simple edit text
app.edit_message_text(chat_id, message_id, "new text")
# Take the same text message, remove the web page preview only
app.edit_message_text(
chat_id, message_id, message.text,
disable_web_page_preview=True)
"""
r = self.send(

17
pyrogram/client/methods/messages/forward_messages.py
View File

@ -55,7 +55,8 @@ class ForwardMessages(BaseClient):
Users will receive a notification with no sound.
as_copy (``bool``, *optional*):
Pass True to forward messages without the forward header (i.e.: send a copy of the message content).
Pass True to forward messages without the forward header (i.e.: send a copy of the message content so
that it appears as originally sent by you).
Defaults to False.
remove_caption (``bool``, *optional*):
@ -68,8 +69,18 @@ class ForwardMessages(BaseClient):
is returned, otherwise, in case *message_ids* was an iterable, the returned value will be a list of
messages, even if such iterable contained just a single element.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
:emphasize-lines: 2,5,8
# Forward a single message
app.forward_messages("me", "pyrogram", 20)
# Forward multiple messages at once
app.forward_messages("me", "pyrogram", [3, 20, 27])
# Forward messages as copy
app.forward_messages("me", "pyrogram", 20, as_copy=True)
"""
is_iterable = not isinstance(message_ids, int)

13
pyrogram/client/methods/messages/get_history.py
View File

@ -70,8 +70,17 @@ class GetHistory(BaseClient):
Returns:
List of :obj:`Message` - On success, a list of the retrieved messages is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Get the last 100 messages of a chat
app.get_history("pyrogramchat")
# Get the last 3 messages of a chat
app.get_history("pyrogramchat", limit=3)
# Get 3 messages after skipping the first 5
app.get_history("pyrogramchat", offset=5, limit=3)
"""
offset_id = offset_id or (1 if reverse else 0)

6
pyrogram/client/methods/messages/get_history_count.py
View File

@ -45,8 +45,10 @@ class GetHistoryCount(BaseClient):
Returns:
``int``: On success, the chat history count is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.get_history_count("pyrogramchat")
"""
r = self.send(

19
pyrogram/client/methods/messages/get_messages.py
View File

@ -64,8 +64,25 @@ class GetMessages(BaseClient):
returned, otherwise, in case *message_ids* was an iterable, the returned value will be a list of messages,
even if such iterable contained just a single element.
Example:
.. code-block:: python
# Get one message
app.get_messages("pyrogramchat", 51110)
# Get more than one message (list of messages)
app.get_messages("pyrogramchat", [44625, 51110])
# Get message by ignoring any replied-to message
app.get_messages(chat_id, message_id, replies=0)
# Get message with all chained replied-to messages
app.get_messages(chat_id, message_id, replies=-1)
# Get the replied-to message of a message
app.get_messages(chat_id, reply_to_message_ids=message_id)
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case of invalid arguments.
"""
ids, ids_type = (

7
pyrogram/client/methods/messages/iter_history.py
View File

@ -64,8 +64,11 @@ class IterHistory(BaseClient):
Returns:
``Generator``: A generator yielding :obj:`Message` objects.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
for message in app.iter_history("pyrogram"):
print(message.text)
"""
offset_id = offset_id or (1 if reverse else 0)
current = 0

10
pyrogram/client/methods/messages/read_history.py
View File

@ -43,8 +43,14 @@ class ReadHistory(BaseClient):
Returns:
``bool`` - On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Mark the whole chat as read
app.read_history("pyrogramlounge")
# Mark messages as read only up to the given message id
app.read_history("pyrogramlounge", 123456)
"""
peer = self.resolve_peer(chat_id)

6
pyrogram/client/methods/messages/retract_vote.py
View File

@ -43,8 +43,10 @@ class RetractVote(BaseClient):
Returns:
:obj:`Poll`: On success, the poll with the retracted vote is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.retract_vote(chat_id, message_id)
"""
r = self.send(
functions.messages.SendVote(

27
pyrogram/client/methods/messages/send_animated_sticker.py
View File

@ -67,23 +67,22 @@ class SendAnimatedSticker(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -92,8 +91,12 @@ class SendAnimatedSticker(BaseClient):
Returns:
:obj:`Message` | ``None``: On success, the sent animated sticker message is returned, otherwise, in case the
upload is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send animated sticker by uploading from local file
app.send_animated_sticker("me", "animated_sticker.tgs")
"""
file = None

40
pyrogram/client/methods/messages/send_animation.py
View File

@ -66,7 +66,7 @@ class SendAnimation(BaseClient):
Animation caption, 0-1024 characters.
unsave (``bool``, *optional*):
By default, the server will save into your own collection any new animation GIF you send.
By default, the server will save into your own collection any new animation you send.
Pass True to automatically unsave the sent animation. Defaults to False.
parse_mode (``str``, *optional*):
@ -103,23 +103,22 @@ class SendAnimation(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -129,8 +128,23 @@ class SendAnimation(BaseClient):
:obj:`Message` | ``None``: On success, the sent animation message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send animation by uploading from local file
app.send_animation("me", "animation.gif")
# Add caption to the animation
app.send_animation("me", "animation.gif", caption="cat")
# Unsave the animation once is sent
app.send_animation("me", "animation.gif", unsave=True)
# Keep track of the progress while uploading
def progress(current, total):
print("{:.1f}%".format(current * 100 / total))
app.send_animation("me", "animation.gif", progress=progress)
"""
file = None

41
pyrogram/client/methods/messages/send_audio.py
View File

@ -100,23 +100,22 @@ class SendAudio(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -126,8 +125,26 @@ class SendAudio(BaseClient):
:obj:`Message` | ``None``: On success, the sent audio message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
:emphasize-lines: 2,5,8-10,13-16
# Send audio file by uploading from file
app.send_audio("me", "audio.mp3")
# Add caption to the audio
app.send_audio("me", "audio.mp3", caption="shoegaze")
# Set audio metadata
app.send_audio(
"me", "audio.mp3",
title="Printemps émeraude", performer="Alcest", duration=440)
# Keep track of the progress while uploading
def progress(current, total):
print("{:.1f}%".format(current * 100 / total))
app.send_audio("me", "audio.mp3", progress=progress)
"""
file = None

6
pyrogram/client/methods/messages/send_cached_media.py
View File

@ -79,8 +79,10 @@ class SendCachedMedia(BaseClient):
Returns:
:obj:`Message`: On success, the sent media message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_cached_media("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
"""
r = self.send(

18
pyrogram/client/methods/messages/send_chat_action.py
View File

@ -64,8 +64,22 @@ class SendChatAction(BaseClient):
``bool``: On success, True is returned.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case the provided string is not a valid ChatAction.
ValueError: In case the provided string is not a valid chat action.
Example:
.. code-block:: python
# Send "typing" chat action
app.send_chat_action(chat_id, "typing")
# Send "upload_video" chat action
app.send_chat_action(chat_id, "upload_video")
# Send "playing" chat action
app.send_chat_action(chat_id, "playing")
# Cancel any current chat action
app.send_chat_action(chat_id, "cancel")
"""
try:

6
pyrogram/client/methods/messages/send_contact.py
View File

@ -74,8 +74,10 @@ class SendContact(BaseClient):
Returns:
:obj:`Message`: On success, the sent contact message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_contact("me", "+39 123 456 7890", "Dan")
"""
r = self.send(
functions.messages.SendMedia(

35
pyrogram/client/methods/messages/send_document.py
View File

@ -86,23 +86,22 @@ class SendDocument(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -112,8 +111,20 @@ class SendDocument(BaseClient):
:obj:`Message` | ``None``: On success, the sent document message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send document by uploading from local file
app.send_document("me", "document.zip")
# Add caption to the document file
app.send_document("me", "document.zip", caption="archive")
# Keep track of the progress while uploading
def progress(current, total):
print("{:.1f}%".format(current * 100 / total))
app.send_document("me", "document.zip", progress=progress)
"""
file = None

6
pyrogram/client/methods/messages/send_location.py
View File

@ -66,8 +66,10 @@ class SendLocation(BaseClient):
Returns:
:obj:`Message`: On success, the sent location message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_location("me", 51.500729, -0.124583)
"""
r = self.send(
functions.messages.SendMedia(

15
pyrogram/client/methods/messages/send_media_group.py
View File

@ -59,8 +59,19 @@ class SendMediaGroup(BaseClient):
Returns:
List of :obj:`Message`: On success, a list of the sent messages is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
from pyrogram import InputMediaPhoto, InputMediaVideo
app.send_media_group(
"me",
[
InputMediaPhoto("photo1.jpg"),
InputMediaPhoto("photo2.jpg", caption="photo caption"),
InputMediaVideo("video.mp4", caption="a video")
]
)
"""
multi_media = []

39
pyrogram/client/methods/messages/send_message.py
View File

@ -74,9 +74,44 @@ class SendMessage(BaseClient):
Returns:
:obj:`Message`: On success, the sent text message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
:emphasize-lines: 2,5,8,11,21-23,26-33
# Simple example
app.send_message("haskell", "Thanks for creating **Pyrogram**!")
# Disable web page previews
app.send_message("me", "https://docs.pyrogram.org", disable_web_page_preview=True)
# Reply to a message using its id
app.send_message("me", "this is a reply", reply_to_message_id=12345)
# Force HTML-only styles for this request only
app.send_message("me", "**not bold**, <i>italic<i>", parse_mode="html")
##
# For bots only, send messages with keyboards attached
##
from pyrogram import (
ReplyKeyboardMarkup, InlineKeyboardMarkup, InlineKeyboardButton)
# Send a normal keyboard
app.send_message(
chat_id, "Look at that button!",
reply_markup=ReplyKeyboardMarkup([["Nice!"]]))
# Send an inline keyboard
app.send_message(
chat_id, "These are inline buttons",
reply_markup=InlineKeyboardMarkup(
[
[InlineKeyboardButton("Data", callback_data="hidden_callback_data")],
[InlineKeyboardButton("Docs", url="https://docs.pyrogram.org")]
]))
"""
message, entities = self.parser.parse(text, parse_mode).values()
r = self.send(

35
pyrogram/client/methods/messages/send_photo.py
View File

@ -85,23 +85,22 @@ class SendPhoto(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -111,8 +110,20 @@ class SendPhoto(BaseClient):
:obj:`Message` | ``None``: On success, the sent photo message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send photo by uploading from local file
app.send_photo("me", "photo.jpg")
# Send photo by uploading from URL
app.send_photo("me", "https://i.imgur.com/BQBTP7d.png")
# Add caption to a photo
app.send_photo("me", "photo.jpg", caption="Holidays!")
# Send self-destructing photo
app.send_photo("me", "photo.jpg", ttl_seconds=10)
"""
file = None

6
pyrogram/client/methods/messages/send_poll.py
View File

@ -66,8 +66,10 @@ class SendPoll(BaseClient):
Returns:
:obj:`Message`: On success, the sent poll message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_poll(chat_id, "Is this a poll question?", ["Yes", "No", "Maybe"])
"""
r = self.send(
functions.messages.SendMedia(

30
pyrogram/client/methods/messages/send_sticker.py
View File

@ -67,23 +67,22 @@ class SendSticker(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -92,8 +91,15 @@ class SendSticker(BaseClient):
Returns:
:obj:`Message` | ``None``: On success, the sent sticker message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send sticker by uploading from local file
app.send_sticker("me", "sticker.webp")
# Send sticker using file_id
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
"""
file = None

8
pyrogram/client/methods/messages/send_venue.py
View File

@ -83,8 +83,12 @@ class SendVenue(BaseClient):
Returns:
:obj:`Message`: On success, the sent venue message is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.send_venue(
"me", 51.500729, -0.124583,
"Elizabeth Tower", "Westminster, London SW1A 0AA, UK")
"""
r = self.send(
functions.messages.SendMedia(

35
pyrogram/client/methods/messages/send_video.py
View File

@ -103,23 +103,22 @@ class SendVideo(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -129,8 +128,20 @@ class SendVideo(BaseClient):
:obj:`Message` | ``None``: On success, the sent video message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send video by uploading from local file
app.send_video("me", "video.mp4")
# Add caption to the video
app.send_video("me", "video.mp4", caption="recording")
# Keep track of the progress while uploading
def progress(current, total):
print("{:.1f}%".format(current * 100 / total))
app.send_video("me", "video.mp4", progress=progress)
"""
file = None

29
pyrogram/client/methods/messages/send_video_note.py
View File

@ -82,23 +82,22 @@ class SendVideoNote(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -108,8 +107,14 @@ class SendVideoNote(BaseClient):
:obj:`Message` | ``None``: On success, the sent video note message is returned, otherwise, in case the
upload is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send video note by uploading from local file
app.send_video_note("me", "video_note.mp4")
# Set video note length
app.send_video_note("me", "video_note.mp4", length=25)
"""
file = None

32
pyrogram/client/methods/messages/send_voice.py
View File

@ -83,23 +83,22 @@ class SendVoice(BaseClient):
instructions to remove reply keyboard or to force a reply from the user.
progress (``callable``, *optional*):
Pass a callback function to view the upload progress.
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
below for a detailed description).
Pass a callback function to view the file transmission progress.
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
detailed description) and will be called back each time a new file chunk has been successfully
transmitted.
progress_args (``tuple``, *optional*):
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
a chat_id and a message_id in order to edit a message with the updated progress.
Extra custom arguments for the progress callback function.
You can pass anything you need to be available in the progress callback scope; for example, a Message
object or a Client instance in order to edit the message with the updated progress status.
Other Parameters:
client (:obj:`Client`):
The Client itself, useful when you want to call other API methods inside the callback function.
current (``int``):
The amount of bytes uploaded so far.
The amount of bytes transmitted so far.
total (``int``):
The size of the file.
The total size of the file.
*args (``tuple``, *optional*):
Extra custom arguments as defined in the *progress_args* parameter.
@ -109,8 +108,17 @@ class SendVoice(BaseClient):
:obj:`Message` | ``None``: On success, the sent voice message is returned, otherwise, in case the upload
is deliberately stopped with :meth:`~Client.stop_transmission`, None is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Send voice note by uploading from local file
app.send_voice("me", "voice.ogg")
# Add caption to the voice note
app.send_voice("me", "voice.ogg", caption="voice note")
# Set voice note duration
app.send_voice("me", "voice.ogg", duration=20)
"""
file = None

6
pyrogram/client/methods/messages/stop_poll.py
View File

@ -49,8 +49,10 @@ class StopPoll(BaseClient):
Returns:
:obj:`Poll`: On success, the stopped poll with the final results is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.stop_poll(chat_id, message_id)
"""
poll = self.get_messages(chat_id, message_id).poll

6
pyrogram/client/methods/messages/vote_poll.py
View File

@ -47,8 +47,10 @@ class VotePoll(BaseClient):
Returns:
:obj:`Poll` - On success, the poll with the chosen option is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.vote_poll(chat_id, message_id, 6)
"""
poll = self.get_messages(chat_id, message_id).poll

10
pyrogram/client/methods/password/change_cloud_password.py
View File

@ -46,8 +46,16 @@ class ChangeCloudPassword(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case there is no cloud password to change.
Example:
.. code-block:: python
# Change password only
app.change_cloud_password("current_password", "new_password")
# Change password and hint
app.change_cloud_password("current_password", "new_password", new_hint="hint")
"""
r = self.send(functions.account.GetPassword())

13
pyrogram/client/methods/password/enable_cloud_password.py
View File

@ -48,8 +48,19 @@ class EnableCloudPassword(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case there is already a cloud password enabled.
Example:
.. code-block:: python
# Enable password without hint and email
app.enable_cloud_password("password")
# Enable password with hint and without email
app.enable_cloud_password("password", hint="hint")
# Enable password with hint and email
app.enable_cloud_password("password", hint="hint", email="user@email.com")
"""
r = self.send(functions.account.GetPassword())

6
pyrogram/client/methods/password/remove_cloud_password.py
View File

@ -36,8 +36,12 @@ class RemoveCloudPassword(BaseClient):
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
ValueError: In case there is no cloud password to remove.
Example:
.. code-block:: python
app.remove_cloud_password("password")
"""
r = self.send(functions.account.GetPassword())

12
pyrogram/client/methods/users/block_user.py
View File

@ -30,11 +30,19 @@ class BlockUser(BaseClient):
) -> bool:
"""Block a user.
Parameters:
user_id (``int`` | ``str``)::
Unique identifier (int) or username (str) of the target user.
For you yourself you can simply use "me" or "self".
For a contact that exists in your Telegram address book you can use his phone number (str).
Returns:
``bool``: True on success
Raises:
RPCError: In case of Telegram RPC Error.
Example:
.. code-block:: python
app.block_user(user_id)
"""
return bool(
self.send(

13
pyrogram/client/methods/users/delete_profile_photos.py
View File

@ -40,8 +40,17 @@ class DeleteProfilePhotos(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Get the photos to be deleted
photos = app.get_profile_photos("me")
# Delete one photo
app.delete_profile_photos(photos[0].file_id)
# Delete the rest of the photos
app.delete_profile_photos([p.file_id for p in photos[1:]])
"""
photo_ids = photo_ids if isinstance(photo_ids, list) else [photo_ids]
input_photos = []

9
pyrogram/client/methods/users/get_me.py
View File

@ -26,10 +26,13 @@ class GetMe(BaseClient):
"""Get your own user identity.
Returns:
:obj:`User`: Basic information about the user or bot.
:obj:`User`: Information about the own logged in user/bot.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
me = app.get_me()
print(me)
"""
return pyrogram.User._parse(
self,

13
pyrogram/client/methods/users/get_profile_photos.py
View File

@ -51,8 +51,17 @@ class GetProfilePhotos(BaseClient):
Returns:
List of :obj:`Photo`: On success, a list of profile photos is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Get the first 100 profile photos of a user
app.get_profile_photos("haskell")
# Get only the first profile photo of a user
app.get_profile_photos("haskell", limit=1)
# Get 3 profile photos of a user, skip the first 5
app.get_profile_photos("haskell", limit=3, offset=5)
"""
peer_id = self.resolve_peer(chat_id)

7
pyrogram/client/methods/users/get_profile_photos_count.py
View File

@ -36,8 +36,11 @@ class GetProfilePhotosCount(BaseClient):
Returns:
``int``: On success, the user profile photos count is returned.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
count = app.get_profile_photos_count("haskell")
print(count)
"""
peer_id = self.resolve_peer(chat_id)

11
pyrogram/client/methods/users/get_users.py
View File

@ -24,7 +24,6 @@ from ...ext import BaseClient
class GetUsers(BaseClient):
# TODO: Add Users type and use that
def get_users(
self,
user_ids: Union[Iterable[Union[int, str]], int, str]
@ -43,8 +42,14 @@ class GetUsers(BaseClient):
returned, otherwise, in case *user_ids* was an iterable a list of users is returned, even if the iterable
contained one item only.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
# Get information about one user
app.get_users("haskell")
# Get information about multiple users at once
app.get_users([user1, user2, user3])
"""
is_iterable = not isinstance(user_ids, (int, str))
user_ids = list(user_ids) if is_iterable else [user_ids]

7
pyrogram/client/methods/users/iter_profile_photos.py
View File

@ -51,8 +51,11 @@ class IterProfilePhotos(BaseClient):
Returns:
``Generator``: A generator yielding :obj:`Photo` objects.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
for photo in app.iter_profile_photos("haskell"):
print(photo.file_id)
"""
current = 0
total = limit or (1 << 31)

6
pyrogram/client/methods/users/set_profile_photo.py
View File

@ -38,8 +38,10 @@ class SetProfilePhoto(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.set_profile_photo("new_photo.jpg")
"""
return bool(

12
pyrogram/client/methods/users/unblock_user.py
View File

@ -30,11 +30,19 @@ class UnblockUser(BaseClient):
) -> bool:
"""Unblock a user.
Parameters:
user_id (``int`` | ``str``)::
Unique identifier (int) or username (str) of the target user.
For you yourself you can simply use "me" or "self".
For a contact that exists in your Telegram address book you can use his phone number (str).
Returns:
``bool``: True on success
Raises:
RPCError: In case of Telegram RPC Error.
Example:
.. code-block:: python
app.unblock_user(user_id)
"""
return bool(
self.send(

6
pyrogram/client/methods/users/update_username.py
View File

@ -40,8 +40,10 @@ class UpdateUsername(BaseClient):
Returns:
``bool``: True on success.
Raises:
RPCError: In case of a Telegram RPC error.
Example:
.. code-block:: python
app.update_username("new_username")
"""
return bool(