mir/pyrogram
2
0
Fork 0
mirror of https://github.com/pyrogram/pyrogram synced 2025-08-22 18:07:21 +00:00
Code Issues Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Dan 2019-05-28 16:41:55 +02:00
parent 87ad981420
commit e94dcd3b0b
28 changed files with 536 additions and 551 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/sitemap.py
View File

@ -23,11 +23,11 @@ canonical = "https://docs.pyrogram.org/"
dirs = {
".": ("weekly", 1.0),
"intro": ("weekly", 0.8),
"start": ("weekly", 0.8),
"api": ("weekly", 0.6),
"topics": ("weekly", 0.6),
"telegram": ("weekly", 0.4)
"intro": ("weekly", 0.9),
"start": ("weekly", 0.9),
"api": ("weekly", 0.8),
"topics": ("weekly", 0.8),
"telegram": ("weekly", 0.6)
}

102
docs/source/api/bound-methods.rst
View File

@ -22,43 +22,65 @@ some of the required arguments.
.. currentmodule:: pyrogram
- Message_
- CallbackQuery_
- InlineQuery_
.. _Message:
Index
-----
Message
^^^^^^^
.. hlist::
:columns: 3
- :meth:`~Message.click`
- :meth:`~Message.delete`
- :meth:`~Message.download`
- :meth:`~Message.edit`
- :meth:`~Message.edit_caption`
- :meth:`~Message.edit_media`
- :meth:`~Message.edit_reply_markup`
- :meth:`~Message.forward`
- :meth:`~Message.pin`
- :meth:`~Message.reply`
- :meth:`~Message.reply_animation`
- :meth:`~Message.reply_audio`
- :meth:`~Message.reply_cached_media`
- :meth:`~Message.reply_chat_action`
- :meth:`~Message.reply_contact`
- :meth:`~Message.reply_document`
- :meth:`~Message.reply_game`
- :meth:`~Message.reply_inline_bot_result`
- :meth:`~Message.reply_location`
- :meth:`~Message.reply_media_group`
- :meth:`~Message.reply_photo`
- :meth:`~Message.reply_poll`
- :meth:`~Message.reply_sticker`
- :meth:`~Message.reply_venue`
- :meth:`~Message.reply_video`
- :meth:`~Message.reply_video_note`
- :meth:`~Message.reply_voice`
CallbackQuery
^^^^^^^^^^^^^
.. hlist::
:columns: 2
- :meth:`~CallbackQuery.answer`
InlineQuery
^^^^^^^^^^^
.. hlist::
:columns: 2
- :meth:`~InlineQuery.answer`
-----
Details
-------
- :meth:`Message.click()`
- :meth:`Message.delete()`
- :meth:`Message.download()`
- :meth:`Message.edit()`
- :meth:`Message.edit_caption()`
- :meth:`Message.edit_media()`
- :meth:`Message.edit_reply_markup()`
- :meth:`Message.forward()`
- :meth:`Message.pin()`
- :meth:`Message.reply()`
- :meth:`Message.reply_animation()`
- :meth:`Message.reply_audio()`
- :meth:`Message.reply_cached_media()`
- :meth:`Message.reply_chat_action()`
- :meth:`Message.reply_contact()`
- :meth:`Message.reply_document()`
- :meth:`Message.reply_game()`
- :meth:`Message.reply_inline_bot_result()`
- :meth:`Message.reply_location()`
- :meth:`Message.reply_media_group()`
- :meth:`Message.reply_photo()`
- :meth:`Message.reply_poll()`
- :meth:`Message.reply_sticker()`
- :meth:`Message.reply_venue()`
- :meth:`Message.reply_video()`
- :meth:`Message.reply_video_note()`
- :meth:`Message.reply_voice()`
.. Message
.. automethod:: Message.click()
.. automethod:: Message.delete()
.. automethod:: Message.download()
@ -87,16 +109,8 @@ Message
.. automethod:: Message.reply_video_note()
.. automethod:: Message.reply_voice()
.. _CallbackQuery:
CallbackQuery
-------------
.. CallbackQuery
.. automethod:: CallbackQuery.answer()
.. _InlineQuery:
InlineQuery
-----------
.. automethod:: InlineQuery.answer()
.. InlineQuery
.. automethod:: InlineQuery.answer()

57
docs/source/api/decorators.rst
View File

@ -1,13 +1,13 @@
Decorators
==========
While still being methods bound to the :obj:`Client <pyrogram.Client>` class, decorators are of a special kind and thus deserve a
dedicated page.
While still being methods bound to the :class:`~pyrogram.Client` class, decorators are of a special kind and thus
deserve a dedicated page.
Decorators are able to register callback functions for handling updates in a much easier and cleaner way compared to
`Handlers <Handlers.html>`_; they do so by instantiating the correct handler and calling
:meth:`add_handler() <pyrogram.Client.add_handler>`, automatically. All you need to do is adding the decorators on top
of your functions.
:doc:`Handlers <handlers>`; they do so by instantiating the correct handler and calling
:meth:`~pyrogram.Client.add_handler`, automatically. All you need to do is adding the decorators on top of your
functions.
.. code-block:: python
:emphasize-lines: 6
@ -24,25 +24,34 @@ of your functions.
app.run()
.. currentmodule:: pyrogram.Client
.. currentmodule:: pyrogram
.. autosummary::
:nosignatures:
Index
-----
on_message
on_callback_query
on_inline_query
on_deleted_messages
on_user_status
on_poll
on_disconnect
on_raw_update
.. hlist::
:columns: 3
.. automethod:: pyrogram.Client.on_message()
.. automethod:: pyrogram.Client.on_callback_query()
.. automethod:: pyrogram.Client.on_inline_query()
.. automethod:: pyrogram.Client.on_deleted_messages()
.. automethod:: pyrogram.Client.on_user_status()
.. automethod:: pyrogram.Client.on_poll()
.. automethod:: pyrogram.Client.on_disconnect()
.. automethod:: pyrogram.Client.on_raw_update()
- :meth:`~Client.on_message`
- :meth:`~Client.on_callback_query`
- :meth:`~Client.on_inline_query`
- :meth:`~Client.on_deleted_messages`
- :meth:`~Client.on_user_status`
- :meth:`~Client.on_poll`
- :meth:`~Client.on_disconnect`
- :meth:`~Client.on_raw_update`
-----
Details
-------
.. Decorators
.. autodecorator:: pyrogram.Client.on_message()
.. autodecorator:: pyrogram.Client.on_callback_query()
.. autodecorator:: pyrogram.Client.on_inline_query()
.. autodecorator:: pyrogram.Client.on_deleted_messages()
.. autodecorator:: pyrogram.Client.on_user_status()
.. autodecorator:: pyrogram.Client.on_poll()
.. autodecorator:: pyrogram.Client.on_disconnect()
.. autodecorator:: pyrogram.Client.on_raw_update()

33
docs/source/api/handlers.rst
View File

@ -3,8 +3,8 @@ Update Handlers
Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions.
For a much more convenient way of registering callback functions have a look at `Decorators <Decorators.html>`_ instead.
In case you decided to manually create a handler, use :meth:`add_handler() <pyrogram.Client.add_handler>` to register
For a much more convenient way of registering callback functions have a look at :doc:`Decorators <decorators>` instead.
In case you decided to manually create a handler, use :class:`~pyrogram.Client.add_handler` to register
it.
.. code-block:: python
@ -25,18 +25,27 @@ it.
.. currentmodule:: pyrogram
.. autosummary::
:nosignatures:
Index
-----
MessageHandler
DeletedMessagesHandler
CallbackQueryHandler
InlineQueryHandler
UserStatusHandler
PollHandler
DisconnectHandler
RawUpdateHandler
.. hlist::
:columns: 3
- :class:`MessageHandler`
- :class:`DeletedMessagesHandler`
- :class:`CallbackQueryHandler`
- :class:`InlineQueryHandler`
- :class:`UserStatusHandler`
- :class:`PollHandler`
- :class:`DisconnectHandler`
- :class:`RawUpdateHandler`
-----
Details
-------
.. Handlers
.. autoclass:: MessageHandler()
.. autoclass:: DeletedMessagesHandler()
.. autoclass:: CallbackQueryHandler()

414
docs/source/api/methods.rst
View File

@ -1,7 +1,7 @@
Available Methods
=================
All Pyrogram methods listed here are bound to a :obj:`Client <pyrogram.Client>` instance.
All Pyrogram methods listed here are bound to a :class:`~pyrogram.Client` instance.
.. code-block:: python
:emphasize-lines: 6
@ -13,253 +13,249 @@ All Pyrogram methods listed here are bound to a :obj:`Client <pyrogram.Client>`
with app:
app.send_message("haskell", "hi")
.. currentmodule:: pyrogram.Client
.. currentmodule:: pyrogram
Index
-----
Utilities
---------
^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 4
start
stop
restart
idle
run
add_handler
remove_handler
send
resolve_peer
save_file
stop_transmission
- :meth:`~Client.start`
- :meth:`~Client.stop`
- :meth:`~Client.restart`
- :meth:`~Client.idle`
- :meth:`~Client.run`
- :meth:`~Client.add_handler`
- :meth:`~Client.remove_handler`
- :meth:`~Client.send`
- :meth:`~Client.resolve_peer`
- :meth:`~Client.save_file`
- :meth:`~Client.stop_transmission`
Messages
--------
^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
send_message
forward_messages
send_photo
send_audio
send_document
send_sticker
send_video
send_animation
send_voice
send_video_note
send_media_group
send_location
send_venue
send_contact
send_cached_media
send_chat_action
edit_message_text
edit_message_caption
edit_message_reply_markup
edit_message_media
delete_messages
get_messages
get_history
get_history_count
iter_history
send_poll
vote_poll
stop_poll
retract_vote
download_media
- :meth:`~Client.send_message`
- :meth:`~Client.forward_messages`
- :meth:`~Client.send_photo`
- :meth:`~Client.send_audio`
- :meth:`~Client.send_document`
- :meth:`~Client.send_sticker`
- :meth:`~Client.send_video`
- :meth:`~Client.send_animation`
- :meth:`~Client.send_voice`
- :meth:`~Client.send_video_note`
- :meth:`~Client.send_media_group`
- :meth:`~Client.send_location`
- :meth:`~Client.send_venue`
- :meth:`~Client.send_contact`
- :meth:`~Client.send_cached_media`
- :meth:`~Client.send_chat_action`
- :meth:`~Client.edit_message_text`
- :meth:`~Client.edit_message_caption`
- :meth:`~Client.edit_message_reply_markup`
- :meth:`~Client.edit_message_media`
- :meth:`~Client.delete_messages`
- :meth:`~Client.get_messages`
- :meth:`~Client.get_history`
- :meth:`~Client.get_history_count`
- :meth:`~Client.iter_history`
- :meth:`~Client.send_poll`
- :meth:`~Client.vote_poll`
- :meth:`~Client.stop_poll`
- :meth:`~Client.retract_vote`
- :meth:`~Client.download_media`
Chats
-----
^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
join_chat
leave_chat
kick_chat_member
unban_chat_member
restrict_chat_member
promote_chat_member
export_chat_invite_link
set_chat_photo
delete_chat_photo
set_chat_title
set_chat_description
pin_chat_message
unpin_chat_message
get_chat
get_chat_member
get_chat_members
get_chat_members_count
iter_chat_members
get_dialogs
iter_dialogs
get_dialogs_count
restrict_chat
update_chat_username
- :meth:`~Client.join_chat`
- :meth:`~Client.leave_chat`
- :meth:`~Client.kick_chat_member`
- :meth:`~Client.unban_chat_member`
- :meth:`~Client.restrict_chat_member`
- :meth:`~Client.promote_chat_member`
- :meth:`~Client.export_chat_invite_link`
- :meth:`~Client.set_chat_photo`
- :meth:`~Client.delete_chat_photo`
- :meth:`~Client.set_chat_title`
- :meth:`~Client.set_chat_description`
- :meth:`~Client.pin_chat_message`
- :meth:`~Client.unpin_chat_message`
- :meth:`~Client.get_chat`
- :meth:`~Client.get_chat_member`
- :meth:`~Client.get_chat_members`
- :meth:`~Client.get_chat_members_count`
- :meth:`~Client.iter_chat_members`
- :meth:`~Client.get_dialogs`
- :meth:`~Client.iter_dialogs`
- :meth:`~Client.get_dialogs_count`
- :meth:`~Client.restrict_chat`
- :meth:`~Client.update_chat_username`
Users
-----
^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 2
get_me
get_users
get_user_profile_photos
get_user_profile_photos_count
set_user_profile_photo
delete_user_profile_photos
update_username
- :meth:`~Client.get_me`
- :meth:`~Client.get_users`
- :meth:`~Client.get_user_profile_photos`
- :meth:`~Client.get_user_profile_photos_count`
- :meth:`~Client.set_user_profile_photo`
- :meth:`~Client.delete_user_profile_photos`
- :meth:`~Client.update_username`
- :meth:`~Client.get_user_dc`
Contacts
--------
^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
add_contacts
get_contacts
get_contacts_count
delete_contacts
- :meth:`~Client.add_contacts`
- :meth:`~Client.get_contacts`
- :meth:`~Client.get_contacts_count`
- :meth:`~Client.delete_contacts`
Password
--------
^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
enable_cloud_password
change_cloud_password
remove_cloud_password
- :meth:`~Client.enable_cloud_password`
- :meth:`~Client.change_cloud_password`
- :meth:`~Client.remove_cloud_password`
Bots
----
^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
get_inline_bot_results
send_inline_bot_result
answer_callback_query
answer_inline_query
request_callback_answer
send_game
set_game_score
get_game_high_scores
- :meth:`~Client.get_inline_bot_results`
- :meth:`~Client.send_inline_bot_result`
- :meth:`~Client.answer_callback_query`
- :meth:`~Client.answer_inline_query`
- :meth:`~Client.request_callback_answer`
- :meth:`~Client.send_game`
- :meth:`~Client.set_game_score`
- :meth:`~Client.get_game_high_scores`
-----
Details
-------
.. Utilities
---------
.. automethod:: pyrogram.Client.start()
.. automethod:: pyrogram.Client.stop()
.. automethod:: pyrogram.Client.restart()
.. automethod:: pyrogram.Client.idle()
.. automethod:: pyrogram.Client.run()
.. automethod:: pyrogram.Client.add_handler()
.. automethod:: pyrogram.Client.remove_handler()
.. automethod:: pyrogram.Client.send()
.. automethod:: pyrogram.Client.resolve_peer()
.. automethod:: pyrogram.Client.save_file()
.. automethod:: pyrogram.Client.stop_transmission()
.. automethod:: Client.start()
.. automethod:: Client.stop()
.. automethod:: Client.restart()
.. automethod:: Client.idle()
.. automethod:: Client.run()
.. automethod:: Client.add_handler()
.. automethod:: Client.remove_handler()
.. automethod:: Client.send()
.. automethod:: Client.resolve_peer()
.. automethod:: Client.save_file()
.. automethod:: Client.stop_transmission()
.. Messages
--------
.. automethod:: pyrogram.Client.send_message()
.. automethod:: pyrogram.Client.forward_messages()
.. automethod:: pyrogram.Client.send_photo()
.. automethod:: pyrogram.Client.send_audio()
.. automethod:: pyrogram.Client.send_document()
.. automethod:: pyrogram.Client.send_sticker()
.. automethod:: pyrogram.Client.send_video()
.. automethod:: pyrogram.Client.send_animation()
.. automethod:: pyrogram.Client.send_voice()
.. automethod:: pyrogram.Client.send_video_note()
.. automethod:: pyrogram.Client.send_media_group()
.. automethod:: pyrogram.Client.send_location()
.. automethod:: pyrogram.Client.send_venue()
.. automethod:: pyrogram.Client.send_contact()
.. automethod:: pyrogram.Client.send_cached_media()
.. automethod:: pyrogram.Client.send_chat_action()
.. automethod:: pyrogram.Client.edit_message_text()
.. automethod:: pyrogram.Client.edit_message_caption()
.. automethod:: pyrogram.Client.edit_message_reply_markup()
.. automethod:: pyrogram.Client.edit_message_media()
.. automethod:: pyrogram.Client.delete_messages()
.. automethod:: pyrogram.Client.get_messages()
.. automethod:: pyrogram.Client.get_history()
.. automethod:: pyrogram.Client.get_history_count()
.. automethod:: pyrogram.Client.iter_history()
.. automethod:: pyrogram.Client.send_poll()
.. automethod:: pyrogram.Client.vote_poll()
.. automethod:: pyrogram.Client.stop_poll()
.. automethod:: pyrogram.Client.retract_vote()
.. automethod:: pyrogram.Client.download_media()
.. automethod:: Client.send_message()
.. automethod:: Client.forward_messages()
.. automethod:: Client.send_photo()
.. automethod:: Client.send_audio()
.. automethod:: Client.send_document()
.. automethod:: Client.send_sticker()
.. automethod:: Client.send_video()
.. automethod:: Client.send_animation()
.. automethod:: Client.send_voice()
.. automethod:: Client.send_video_note()
.. automethod:: Client.send_media_group()
.. automethod:: Client.send_location()
.. automethod:: Client.send_venue()
.. automethod:: Client.send_contact()
.. automethod:: Client.send_cached_media()
.. automethod:: Client.send_chat_action()
.. automethod:: Client.edit_message_text()
.. automethod:: Client.edit_message_caption()
.. automethod:: Client.edit_message_reply_markup()
.. automethod:: Client.edit_message_media()
.. automethod:: Client.delete_messages()
.. automethod:: Client.get_messages()
.. automethod:: Client.get_history()
.. automethod:: Client.get_history_count()
.. automethod:: Client.iter_history()
.. automethod:: Client.send_poll()
.. automethod:: Client.vote_poll()
.. automethod:: Client.stop_poll()
.. automethod:: Client.retract_vote()
.. automethod:: Client.download_media()
.. Chats
-----
.. automethod:: pyrogram.Client.join_chat()
.. automethod:: pyrogram.Client.leave_chat()
.. automethod:: pyrogram.Client.kick_chat_member()
.. automethod:: pyrogram.Client.unban_chat_member()
.. automethod:: pyrogram.Client.restrict_chat_member()
.. automethod:: pyrogram.Client.promote_chat_member()
.. automethod:: pyrogram.Client.export_chat_invite_link()
.. automethod:: pyrogram.Client.set_chat_photo()
.. automethod:: pyrogram.Client.delete_chat_photo()
.. automethod:: pyrogram.Client.set_chat_title()
.. automethod:: pyrogram.Client.set_chat_description()
.. automethod:: pyrogram.Client.pin_chat_message()
.. automethod:: pyrogram.Client.unpin_chat_message()
.. automethod:: pyrogram.Client.get_chat()
.. automethod:: pyrogram.Client.get_chat_member()
.. automethod:: pyrogram.Client.get_chat_members()
.. automethod:: pyrogram.Client.get_chat_members_count()
.. automethod:: pyrogram.Client.iter_chat_members()
.. automethod:: pyrogram.Client.get_dialogs()
.. automethod:: pyrogram.Client.iter_dialogs()
.. automethod:: pyrogram.Client.get_dialogs_count()
.. automethod:: pyrogram.Client.restrict_chat()
.. automethod:: pyrogram.Client.update_chat_username()
.. automethod:: Client.join_chat()
.. automethod:: Client.leave_chat()
.. automethod:: Client.kick_chat_member()
.. automethod:: Client.unban_chat_member()
.. automethod:: Client.restrict_chat_member()
.. automethod:: Client.promote_chat_member()
.. automethod:: Client.export_chat_invite_link()
.. automethod:: Client.set_chat_photo()
.. automethod:: Client.delete_chat_photo()
.. automethod:: Client.set_chat_title()
.. automethod:: Client.set_chat_description()
.. automethod:: Client.pin_chat_message()
.. automethod:: Client.unpin_chat_message()
.. automethod:: Client.get_chat()
.. automethod:: Client.get_chat_member()
.. automethod:: Client.get_chat_members()
.. automethod:: Client.get_chat_members_count()
.. automethod:: Client.iter_chat_members()
.. automethod:: Client.get_dialogs()
.. automethod:: Client.iter_dialogs()
.. automethod:: Client.get_dialogs_count()
.. automethod:: Client.restrict_chat()
.. automethod:: Client.update_chat_username()
.. Users
-----
.. automethod:: pyrogram.Client.get_me()
.. automethod:: pyrogram.Client.get_users()
.. automethod:: pyrogram.Client.get_user_profile_photos()
.. automethod:: pyrogram.Client.get_user_profile_photos_count()
.. automethod:: pyrogram.Client.set_user_profile_photo()
.. automethod:: pyrogram.Client.delete_user_profile_photos()
.. automethod:: pyrogram.Client.update_username()
.. automethod:: Client.get_me()
.. automethod:: Client.get_users()
.. automethod:: Client.get_user_profile_photos()
.. automethod:: Client.get_user_profile_photos_count()
.. automethod:: Client.set_user_profile_photo()
.. automethod:: Client.delete_user_profile_photos()
.. automethod:: Client.update_username()
.. automethod:: Client.get_user_dc()
.. Contacts
--------
.. automethod:: pyrogram.Client.add_contacts()
.. automethod:: pyrogram.Client.get_contacts()
.. automethod:: pyrogram.Client.get_contacts_count()
.. automethod:: pyrogram.Client.delete_contacts()
.. automethod:: Client.add_contacts()
.. automethod:: Client.get_contacts()
.. automethod:: Client.get_contacts_count()
.. automethod:: Client.delete_contacts()
.. Password
--------
.. automethod:: pyrogram.Client.enable_cloud_password()
.. automethod:: pyrogram.Client.change_cloud_password()
.. automethod:: pyrogram.Client.remove_cloud_password()
.. automethod:: Client.enable_cloud_password()
.. automethod:: Client.change_cloud_password()
.. automethod:: Client.remove_cloud_password()
.. Bots
----
.. automethod:: pyrogram.Client.get_inline_bot_results()
.. automethod:: pyrogram.Client.send_inline_bot_result()
.. automethod:: pyrogram.Client.answer_callback_query()
.. automethod:: pyrogram.Client.answer_inline_query()
.. automethod:: pyrogram.Client.request_callback_answer()
.. automethod:: pyrogram.Client.send_game()
.. automethod:: pyrogram.Client.set_game_score()
.. automethod:: pyrogram.Client.get_game_high_scores()
.. automethod:: Client.get_inline_bot_results()
.. automethod:: Client.send_inline_bot_result()
.. automethod:: Client.answer_callback_query()
.. automethod:: Client.answer_inline_query()
.. automethod:: Client.request_callback_answer()
.. automethod:: Client.send_game()
.. automethod:: Client.set_game_score()
.. automethod:: Client.get_game_high_scores()

158
docs/source/api/types.rst
View File

@ -15,102 +15,108 @@ All Pyrogram types listed here are accessible through the main package directly.
.. currentmodule:: pyrogram
Index
-----
Users & Chats
-------------
^^^^^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 5
User
UserStatus
Chat
ChatPreview
ChatPhoto
ChatMember
ChatMembers
ChatPermissions
Dialog
Dialogs
- :class:`User`
- :class:`UserStatus`
- :class:`Chat`
- :class:`ChatPreview`
- :class:`ChatPhoto`
- :class:`ChatMember`
- :class:`ChatMembers`
- :class:`ChatPermissions`
- :class:`Dialog`
- :class:`Dialogs`
Messages & Media
----------------
^^^^^^^^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 5
Message
Messages
MessageEntity
Photo
PhotoSize
UserProfilePhotos
Audio
Document
Animation
Video
Voice
VideoNote
Contact
Location
Venue
Sticker
Game
Poll
PollOption
- :class:`Message`
- :class:`Messages`
- :class:`MessageEntity`
- :class:`Photo`
- :class:`PhotoSize`
- :class:`UserProfilePhotos`
- :class:`Audio`
- :class:`Document`
- :class:`Animation`
- :class:`Video`
- :class:`Voice`
- :class:`VideoNote`
- :class:`Contact`
- :class:`Location`
- :class:`Venue`
- :class:`Sticker`
- :class:`Game`
- :class:`Poll`
- :class:`PollOption`
Keyboards
---------
^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 4
ReplyKeyboardMarkup
KeyboardButton
ReplyKeyboardRemove
InlineKeyboardMarkup
InlineKeyboardButton
ForceReply
CallbackQuery
GameHighScore
GameHighScores
CallbackGame
- :class:`ReplyKeyboardMarkup`
- :class:`KeyboardButton`
- :class:`ReplyKeyboardRemove`
- :class:`InlineKeyboardMarkup`
- :class:`InlineKeyboardButton`
- :class:`ForceReply`
- :class:`CallbackQuery`
- :class:`GameHighScore`
- :class:`GameHighScores`
- :class:`CallbackGame`
Input Media
-----------
^^^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 4
InputMedia
InputMediaPhoto
InputMediaVideo
InputMediaAudio
InputMediaAnimation
InputMediaDocument
InputPhoneContact
- :class:`InputMedia`
- :class:`InputMediaPhoto`
- :class:`InputMediaVideo`
- :class:`InputMediaAudio`
- :class:`InputMediaAnimation`
- :class:`InputMediaDocument`
- :class:`InputPhoneContact`
Inline Mode
------------
^^^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
InlineQuery
InlineQueryResult
InlineQueryResultArticle
- :class:`InlineQuery`
- :class:`InlineQueryResult`
- :class:`InlineQueryResultArticle`
InputMessageContent
-------------------
^^^^^^^^^^^^^^^^^^^
.. autosummary::
:nosignatures:
.. hlist::
:columns: 3
InputMessageContent
InputTextMessageContent
- :class:`InputMessageContent`
- :class:`InputTextMessageContent`
-----
Details
-------
.. User & Chats
------------
.. autoclass:: User()
.. autoclass:: UserStatus()
.. autoclass:: Chat()
@ -123,8 +129,6 @@ InputMessageContent
.. autoclass:: Dialogs()
.. Messages & Media
----------------
.. autoclass:: Message()
.. autoclass:: Messages()
.. autoclass:: MessageEntity()
@ -146,8 +150,6 @@ InputMessageContent
.. autoclass:: PollOption()
.. Keyboards
---------
.. autoclass:: ReplyKeyboardMarkup()
.. autoclass:: KeyboardButton()
.. autoclass:: ReplyKeyboardRemove()
@ -160,8 +162,6 @@ InputMessageContent
.. autoclass:: CallbackGame()
.. Input Media
-----------
.. autoclass:: InputMedia()
.. autoclass:: InputMediaPhoto()
.. autoclass:: InputMediaVideo()
@ -171,14 +171,10 @@ InputMessageContent
.. autoclass:: InputPhoneContact()
.. Inline Mode
-----------
.. autoclass:: InlineQuery()
.. autoclass:: InlineQueryResult()
.. autoclass:: InlineQueryResultArticle()
.. InputMessageContent
-------------------
.. autoclass:: InputMessageContent()
.. autoclass:: InputTextMessageContent()

4
docs/source/conf.py
View File

@ -43,7 +43,6 @@ autodoc_member_order = "bysource"
version = __version__
release = version
version_rst = ".. |version| replace:: {}".format(version)
templates_path = ["_templates"]
@ -61,7 +60,8 @@ html_theme_options = {
"collapse_navigation": True,
"sticky_navigation": False,
"logo_only": True,
"display_version": True
"display_version": True,
"style_external_links": True
}
html_logo = "_images/pyrogram.png"

42
docs/source/faq.rst
View File

@ -17,10 +17,9 @@ What is Pyrogram?
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
C. It enables you to easily create custom applications for both user and bot identities (bot API alternative) via the
`MTProto API`_ with the Python programming language.
:doc:`MTProto API <topics/mtproto-vs-botapi>` with the Python programming language.
.. _Telegram: https://telegram.org
.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
Where does the name come from?
------------------------------
@ -47,19 +46,17 @@ Why Pyrogram?
- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted.
- **Updated**, to make use of the latest Telegram API version and features.
- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed.
- **Pluggable**: The `Smart Plugin`_ system allows to write components with minimal boilerplate code.
- **Comprehensive**: Execute any `advanced action`_ an official client is able to do, and even more.
- **Pluggable**: The :doc:`Smart Plugin <topics/smart-plugins>` system allows to write components with minimal
boilerplate code.
- **Comprehensive**: Execute any :doc:`advanced action <topics/advanced-usage>` an official client is able to do, and
even more.
.. _TgCrypto: https://github.com/pyrogram/tgcrypto
.. _Smart Plugin: topics/smart-plugins
.. _advanced action: topics/advanced-usage
What can MTProto do more than the Bot API?
------------------------------------------
For a detailed answer, please refer to the `MTProto vs. Bot API`_ page.
.. _MTProto vs. Bot API: topics/mtproto-vs-botapi
For a detailed answer, please refer to the :doc:`MTProto vs. Bot API <topics/mtproto-vs-botapi>` page.
Why do I need an API key for bots?
----------------------------------
@ -97,9 +94,9 @@ Telegram is slowly changing some server's internals and it's doing it in such a
inevitably. Not only this, but it seems that the new, hypothetical, file ids could also possibly expire at anytime, thus
losing the *persistence* feature.
This change will most likely affect the official `Bot API <topics/mtproto-vs-botapi#what-is-the-bot-api>`_ too
(unless Telegram implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn
make use of) and we can expect a proper notice from Telegram.
This change will most likely affect the official :doc:`Bot API <topics/mtproto-vs-botapi>` too (unless Telegram
implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn make use of) and
we can expect a proper notice from Telegram.
Can I use multiple clients at once on the same account?
-------------------------------------------------------
@ -125,8 +122,8 @@ from the beginning every time, and use one separate session for each parallel cl
I started a client and nothing happens!
---------------------------------------
If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or
totally blocked in those countries.
If you are connecting from Russia, China or Iran :doc:`you need a proxy <topics/proxy>`, because Telegram could be
partially or totally blocked in those countries.
Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on
the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network
@ -146,8 +143,6 @@ fails or not:
- DC4: ``149.154.167.91``
- DC5: ``91.108.56.149``
.. _you need a proxy: topics/proxy
I keep getting PEER_ID_INVALID error!
-------------------------------------------
@ -182,20 +177,5 @@ recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_.
.. _@smstelegram: https://twitter.com/smstelegram
.. _this form: https://telegram.org/support
About the License
-----------------
.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
:align: left
Pyrogram is free software and is currently licensed under the terms of the
`GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it
provided that modifications are described and licensed for free under LGPLv3+.
In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or
different license, or even proprietary --- without being required to release the source code of your own applications.
However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license.
.. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser
.. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

14
docs/source/glossary.rst
View File

@ -18,7 +18,7 @@ general. Some words may as well link to dedicated articles in case the topic is
API key
A secret code used to authenticate and/or authorize a specific application to Telegram in order for it to
control how the API is being used, for example, to prevent abuses of the API.
`More on API keys <intro/setup#api-keys>`_.
:doc:`More on API keys <intro/setup>`.
DC
Also known as *data center*, is a place where lots of computer systems are housed and used together in order to
@ -30,21 +30,21 @@ general. Some words may as well link to dedicated articles in case the topic is
RPCError
An error caused by an RPC which must be returned in place of the successful result in order to let the caller
know something went wrong. `More on RPCError <start/errors>`_.
know something went wrong. :doc:`More on RPCError <start/errors>`.
MTProto
The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
`More on MTProto <topics/mtproto-vs-botapi>`_.
:doc:`More on MTProto <topics/mtproto-vs-botapi>`.
MTProto API
The Telegram main API Pyrogram makes use of, which is able to connect both users and normal bots to Telegram
using MTProto as application layer protocol and execute any method Telegram provides from its public TL-schema.
`More on MTProto API <topics/mtproto-vs-botapi#what-is-the-mtproto-api>`_.
:doc:`More on MTProto API <topics/mtproto-vs-botapi>`.
Bot API
The Telegram Bot API that is able to only connect normal bots only to Telegram using HTTP as application layer
protocol and allows to execute a sub-set of the main Telegram API.
`More on Bot API <topics/mtproto-vs-botapi#what-is-the-bot-api>`_.
:doc:`More on Bot API <topics/mtproto-vs-botapi>`.
Pyrogrammer
A developer that uses Pyrogram to build Telegram applications.
@ -65,11 +65,11 @@ general. Some words may as well link to dedicated articles in case the topic is
Handler
An object that wraps around a callback function that is *actually meant* to be registered into the framework,
which will then be able to handle a specific kind of events, such as a new incoming message, for example.
`More on Handlers <start/updates>`_.
:doc:`More on Handlers <start/updates>`.
Decorator
Also known as *function decorator*, in Python, is a callable object that is used to modify another function.
Decorators in Pyrogram are used to automatically register callback functions for handling updates.
`More on Decorators <start/updates#using-decorators>`_.
:doc:`More on Decorators <start/updates>`.
.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

51
docs/source/index.rst
View File

@ -42,10 +42,9 @@ Welcome to Pyrogram
**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
C. It enables you to easily create custom apps for both user and bot identities (bot API alternative) via the
`MTProto API`_.
:doc:`MTProto API <topics/mtproto-vs-botapi>`.
.. _Telegram: https://telegram.org
.. _MTProto API: topics/mtproto-vs-botapi#what-is-the-mtproto-api
How the Documentation is Organized
----------------------------------
@ -60,15 +59,10 @@ First Steps
.. hlist::
:columns: 2
- `Quick Start`_: Overview to get you started quickly.
- `Calling Methods`_: How to call Pyrogram's methods.
- `Handling Updates`_: How to handle Telegram updates.
- `Error Handling`_: How to handle API errors correctly.
.. _Quick Start: intro/quickstart
.. _Calling Methods: start/invoking
.. _Handling Updates: start/updates
.. _Error Handling: start/errors
- :doc:`Quick Start <intro/quickstart>`: Overview to get you started quickly.
- :doc:`Calling Methods <start/invoking>`: How to call Pyrogram's methods.
- :doc:`Handling Updates <start/updates>`: How to handle Telegram updates.
- :doc:`Error Handling <start/errors>`: How to handle API errors correctly.
API Reference
-------------
@ -76,15 +70,10 @@ API Reference
.. hlist::
:columns: 2
- `Pyrogram Client`_: Reference details about the Client class.
- `Available Methods`_: List of available high-level methods.
- `Available Types`_: List of available high-level types.
- `Bound Methods`_: List of convenient bound methods.
.. _Pyrogram Client: ./api/client
.. _Available Methods: api/methods
.. _Available Types: api/types
.. _Bound Methods: api/bound-methods
- :doc:`Pyrogram Client <api/client>`: Reference details about the Client class.
- :doc:`Available Methods <api/methods>`: List of available high-level methods.
- :doc:`Available Types <api/types>`: List of available high-level types.
- :doc:`Bound Methods <api/bound-methods>`: List of convenient bound methods.
Meta
----
@ -92,17 +81,12 @@ Meta
.. hlist::
:columns: 2
- `Pyrogram FAQ`_: Answers to common Pyrogram questions.
- `Pyrogram Glossary`_: List of words with brief explanations.
- `Release Notes`_: Release notes for Pyrogram releases.
- `Powered by Pyrogram`_: Collection of Pyrogram Projects.
- `Support Pyrogram`_: Ways to show your appreciation.
.. _Pyrogram FAQ: faq
.. _Pyrogram Glossary: glossary
.. _Release Notes: releases
.. _Powered by Pyrogram: powered-by
.. _Support Pyrogram: support-pyrogram
- :doc:`Pyrogram FAQ <faq>`: Answers to common Pyrogram questions.
- :doc:`Pyrogram Glossary <glossary>`: List of words with brief explanations.
- :doc:`Release Notes <releases>`: Release notes for Pyrogram releases.
- :doc:`Powered by Pyrogram <powered-by>`: Collection of Pyrogram Projects.
- :doc:`Support Pyrogram <support-pyrogram>`: Ways to show your appreciation.
- :doc:`About the License <license>`: Information about the Project license.
.. toctree::
:hidden:
@ -163,10 +147,13 @@ Meta
releases
powered-by
support-pyrogram
license
.. toctree::
:hidden:
:caption: Telegram API
telegram/functions/index
telegram/types/index
telegram/types/index
Last updated on |today|

3
docs/source/intro/install.rst
View File

@ -20,7 +20,7 @@ Install Pyrogram
$ pip3 install -U pyrogram
- or, with TgCrypto_ as extra requirement (recommended):
- or, with :doc:`TgCrypto <../topics/tgcrypto>` as extra requirement (recommended):
.. code-block:: text
@ -89,5 +89,4 @@ If no error shows up you are good to go.
>>> pyrogram.__version__
'|version|'
.. _TgCrypto: ../topics/tgcrypto
.. _`Github repo`: http://github.com/pyrogram/pyrogram

4
docs/source/intro/quickstart.rst
View File

@ -43,7 +43,7 @@ Enjoy the API
That was just a quick overview that barely scratched the surface!
In the next few pages of the introduction, we'll take a much more in-depth look of what we have just done above.
Feeling eager to continue? You can take a shortcut to `Calling Methods`_ and come back later to learn some more details.
Feeling eager to continue? You can take a shortcut to :doc:`Calling Methods <../start/invoking>` and come back later to
learn some more details.
.. _community: //t.me/Pyrogram
.. _Calling Methods: ../start/invoking

8
docs/source/intro/setup.rst
View File

@ -1,8 +1,8 @@
Project Setup
=============
We have just `installed Pyrogram`_. In this page we'll discuss what you need to do in order to set up a project with
the library. Let's see how it's done.
We have just :doc:`installed Pyrogram <install>`. In this page we'll discuss what you need to do in order to set up a
project with the library. Let's see how it's done.
API Keys
--------
@ -26,7 +26,7 @@ The very first step requires you to obtain a valid Telegram API key (API id/hash
Configuration
-------------
Having the API key from the `previous step <#api-keys>`_ in handy, we can now begin to configure a Pyrogram project.
Having the API key from the previous step in handy, we can now begin to configure a Pyrogram project.
There are two ways to do so, and you can choose what fits better for you:
- First option (recommended): create a new ``config.ini`` file at the root of your working directory, copy-paste the
@ -57,5 +57,3 @@ There are two ways to do so, and you can choose what fits better for you:
To keep code snippets clean and concise, from now on it is assumed you are making use of the ``config.ini`` file,
thus, the *api_id* and *api_hash* parameters usage won't be shown anymore.
.. _installed Pyrogram: install.html

15
docs/source/license.rst Normal file
View File

@ -0,0 +1,15 @@
About the License
=================
.. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
:align: left
Pyrogram is free software and is currently licensed under the terms of the
`GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it
provided that modifications are described and licensed for free under LGPLv3+.
In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or
different license, or even proprietary --- without being required to release the source code of your own applications.
However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license.
.. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser

9
docs/source/start/auth.rst
View File

@ -1,7 +1,7 @@
Authorization
=============
Once a `project is set up`_, you will still have to follow a few steps before you can actually use Pyrogram to make
Once a :doc:`project is set up <../intro/setup>`, you will still have to follow a few steps before you can actually use Pyrogram to make
API calls. This section provides all the information you need in order to authorize yourself as user or bot.
User Authorization
@ -9,8 +9,8 @@ User Authorization
In order to use the API, Telegram requires that users be authorized via their phone numbers.
Pyrogram automatically manages this process, all you need to do is create an instance of the
:class:`Client <pyrogram.Client>` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call
the :meth:`run() <pyrogram.Client.run>` method:
:class:`~pyrogram.Client` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call
the :meth:`~pyrogram.Client.run` method:
.. code-block:: python
@ -47,7 +47,7 @@ Bot Authorization
Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by
the `Bot Father`_. Bot tokens replace the users' phone numbers only — you still need to
`configure a Telegram API key <../intro/setup#configuration>`_ with Pyrogram, even when using bots.
:doc:`configure a Telegram API key <../intro/setup>` with Pyrogram, even when using bots.
The authorization process is automatically managed. All you need to do is choose a ``session_name`` (can be anything,
usually your bot username) and pass your bot token using the ``bot_token`` parameter. The session file will be named
@ -64,6 +64,5 @@ after the session name, which will be ``my_bot.session`` for the example below.
app.run()
.. _project is set up: ../intro/setup
.. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
.. _Bot Father: https://t.me/botfather

11
docs/source/start/invoking.rst
View File

@ -1,8 +1,8 @@
Calling Methods
===============
At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now aiming towards the
core of the library. It's time to start playing with the API!
At this point, we have successfully :doc:`installed Pyrogram <../intro/install>` and :doc:`authorized <auth>` our
account; we are now aiming towards the core of the library. It's time to start playing with the API!
Basic Usage
-----------
@ -63,8 +63,8 @@ Context Manager
---------------
You can also use Pyrogram's Client in a context manager with the ``with`` statement. The client will automatically
:meth:`start() <pyrogram.Client.start>` and :meth:`stop() <pyrogram.Client.stop>` gracefully, even in case of unhandled
exceptions in your code. The example above can be therefore rewritten in a much nicer way:
:meth:`~pyrogram.Client.start` and :meth:`~pyrogram.Client.stop` gracefully, even in case of unhandled exceptions in
your code. The example above can be therefore rewritten in a much nicer way:
.. code-block:: python
@ -79,6 +79,3 @@ exceptions in your code. The example above can be therefore rewritten in a much
app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")
More examples can be found on `GitHub <https://github.com/pyrogram/pyrogram/tree/develop/examples>`_.
.. _installed Pyrogram: ../intro/install.html
.. _authorized: ../intro/setup.html

38
docs/source/start/updates.rst
View File

@ -1,8 +1,8 @@
Handling Updates
================
Calling `API methods`_ sequentially is cool, but how to react when, for example, a new message arrives? This page deals
with updates and how to handle such events in Pyrogram. Let's have a look at how they work.
Calling :doc:`API methods <invoking>` sequentially is cool, but how to react when, for example, a new message arrives?
This page deals with updates and how to handle such events in Pyrogram. Let's have a look at how they work.
Defining Updates
----------------
@ -10,7 +10,7 @@ Defining Updates
First, let's define what are these updates. As hinted already, updates are simply events that happen in your Telegram
account (incoming messages, new members join, bot button presses, etc...), which are meant to notify you about a new
specific state that has changed. These updates are handled by registering one or more callback functions in your app
using `Handlers <../api/handlers>`_.
using :doc:`Handlers <../api/handlers>`.
Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback
function will be called back by the framework and its body executed.
@ -18,17 +18,16 @@ function will be called back by the framework and its body executed.
Registering a Handler
---------------------
To explain how handlers work let's have a look at the most used one, the
:obj:`MessageHandler <pyrogram.MessageHandler>`, which will be in charge for handling :obj:`Message <pyrogram.Message>`
updates coming from all around your chats. Every other handler shares the same setup logic; you should not have troubles
settings them up once you learn from this section.
To explain how handlers work let's have a look at the most used one, the :class:`~pyrogram.MessageHandler`, which will
be in charge for handling :class:`~pyrogram.Message` updates coming from all around your chats. Every other handler shares
the same setup logic; you should not have troubles settings them up once you learn from this section.
Using add_handler()
-------------------
The :meth:`add_handler() <pyrogram.Client.add_handler>` method takes any handler instance that wraps around your defined
callback function and registers it in your Client. Here's a full example that prints out the content of a message as
soon as it arrives:
The :meth:`~pyrogram.Client.add_handler` method takes any handler instance that wraps around your defined callback
function and registers it in your Client. Here's a full example that prints out the content of a message as soon as it
arrives:
.. code-block:: python
@ -55,24 +54,23 @@ call that function by passing the client instance and the new message instance a
def my_function(client, message):
print(message)
Second one: the :obj:`MessageHandler <pyrogram.MessageHandler>`. This object tells Pyrogram the function we defined
above must only handle updates that are in form of a :obj:`Message <pyrogram.Message>`:
Second one: the :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must only
handle updates that are in form of a :class:`~pyrogram.Message`:
.. code-block:: python
my_handler = MessageHandler(my_function)
Third: the method :meth:`add_handler() <pyrogram.Client.add_handler>`. This method is used to actually register the
handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal
dispatching phase begins.
Third: the method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let
Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase begins.
.. code-block:: python
app.add_handler(my_handler)
Last one, the :meth:`run() <pyrogram.Client.run>` method. What this does is simply call
:meth:`start() <pyrogram.Client.start>` and a special method :meth:`idle() <pyrogram.Client.idle>` that keeps your main
scripts alive until you press ``CTRL+C``; the client will be automatically stopped after that.
Last one, the :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and a
special method :meth:`~pyrogram.Client.idle` that keeps your main scripts alive until you press ``CTRL+C``; the client
will be automatically stopped after that.
.. code-block:: python
@ -82,7 +80,7 @@ Using Decorators
----------------
All of the above will become quite verbose, especially in case you have lots of handlers to register. A much nicer way
to do so is by decorating your callback function with the :meth:`on_message() <pyrogram.Client.on_message>` decorator.
to do so is by decorating your callback function with the :meth:`~pyrogram.Client.on_message` decorator.
.. code-block:: python
@ -108,5 +106,3 @@ to do so is by decorating your callback function with the :meth:`on_message() <p
In case, for some reason, you want to get your own function back after it has been decorated, you need to access
``my_function[0].callback``, that is, the *callback* field of the *handler* object which is the first element in the
tuple, accessed by bracket notation *[0]*.
.. _API methods: invoking

41
docs/source/topics/advanced-usage.rst
View File

@ -1,8 +1,9 @@
Advanced Usage
==============
Pyrogram's API, which consists of well documented convenience methods_ and facade types_, exists to provide a much
easier interface to the undocumented and often confusing Telegram API.
Pyrogram's API, which consists of well documented convenience :doc:`methods <../api/methods>` and facade
:doc:`types <../api/types>`, exists to provide a much easier interface to the undocumented and often confusing Telegram
API.
In this section, you'll be shown the alternative way of communicating with Telegram using Pyrogram: the main "raw"
Telegram API with its functions and types.
@ -11,7 +12,7 @@ Telegram Raw API
----------------
If you can't find a high-level method for your needs or if you want complete, low-level access to the whole
Telegram API, you have to use the raw :mod:`functions <pyrogram.api.functions>` and :mod:`types <pyrogram.api.types>`.
Telegram API, you have to use the raw :mod:`~pyrogram.api.functions` and :mod:`~pyrogram.api.types`.
As already hinted, raw functions and types can be really confusing, mainly because people don't realize soon enough they
accept *only* the right types and that all required parameters must be filled in. This section will therefore explain
@ -21,24 +22,25 @@ some pitfalls to take into consideration when working with the raw API.
Every available high-level methods in Pyrogram is built on top of these raw functions.
Nothing stops you from using the raw functions only, but they are rather complex and `plenty of them`_ are already
re-implemented by providing a much simpler and cleaner interface which is very similar to the Bot API (yet much more
powerful).
Nothing stops you from using the raw functions only, but they are rather complex and
:doc:`plenty of them <../api/methods>` are already re-implemented by providing a much simpler and cleaner interface
which is very similar to the Bot API (yet much more powerful).
If you think a raw function should be wrapped and added as a high-level method, feel free to ask in our Community_!
Invoking Functions
^^^^^^^^^^^^^^^^^^
Unlike the methods_ found in Pyrogram's API, which can be called in the usual simple way, functions to be invoked from
the raw Telegram API have a different way of usage and are more complex.
Unlike the :doc:`methods <../api/methods>` found in Pyrogram's API, which can be called in the usual simple way,
functions to be invoked from the raw Telegram API have a different way of usage and are more complex.
First of all, both `raw functions`_ and `raw types`_ live in their respective packages (and sub-packages):
``pyrogram.api.functions``, ``pyrogram.api.types``. They all exist as Python classes, meaning you need to create an
instance of each every time you need them and fill them in with the correct values using named arguments.
First of all, both :doc:`raw functions <../telegram/functions/index>` and :doc:`raw types <../telegram/types/index>` live in their
respective packages (and sub-packages): ``pyrogram.api.functions``, ``pyrogram.api.types``. They all exist as Python
classes, meaning you need to create an instance of each every time you need them and fill them in with the correct
values using named arguments.
Next, to actually invoke the raw function you have to use the :meth:`send() <pyrogram.Client.send>` method provided by
the Client class and pass the function object you created.
Next, to actually invoke the raw function you have to use the :meth:`~pyrogram.Client.send` method provided by the
Client class and pass the function object you created.
Here's some examples:
@ -101,12 +103,12 @@ sending messages with IDs only thanks to cached access hashes.
There are three different InputPeer types, one for each kind of Telegram entity.
Whenever an InputPeer is needed you must pass one of these:
- :obj:`InputPeerUser <../telegram/types/InputPeerUser>` - Users
- :obj:`InputPeerChat <../telegram/types/InputPeerChat>` - Basic Chats
- :obj:`InputPeerChannel <../telegram/types/InputPeerChannel>` - Either Channels or Supergroups
- :class:`~pyrogram.api.types.InputPeerUser` - Users
- :class:`~pyrogram.api.types.InputPeerChat` - Basic Chats
- :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups
But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides
:meth:`resolve_peer() <pyrogram.Client.resolve_peer>` as a convenience utility method that returns the correct InputPeer
:meth:`~pyrogram.Client.resolve_peer` as a convenience utility method that returns the correct InputPeer
by accepting a peer ID only.
Another thing to take into consideration about chat IDs is the way they are represented: they are all integers and
@ -125,9 +127,4 @@ For example, given the ID *123456789*, here's how Pyrogram can tell entities apa
So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an
high-level method.
.. _methods: ../api/methods
.. _types: ../api/types
.. _plenty of them: ../api/methods
.. _raw functions: ../telegram/functions
.. _raw types: ../telegram/types
.. _Community: https://t.me/Pyrogram

2
docs/source/topics/auto-auth.rst
View File

@ -3,7 +3,7 @@ Auto Authorization
Manually writing phone number, phone code and password on the terminal every time you want to login can be tedious.
Pyrogram is able to automate both **Log In** and **Sign Up** processes, all you need to do is pass the relevant
parameters when creating a new :class:`Client <pyrogram.Client>`.
parameters when creating a new :class:`~pyrogram.Client`.
.. note:: If you omit any of the optional parameter required for the authorization, Pyrogram will ask you to
manually write it. For instance, if you don't want to set a ``last_name`` when creating a new account you

5
docs/source/topics/bots-interaction.rst
View File

@ -7,8 +7,7 @@ Inline Bots
-----------
- If a bot accepts inline queries, you can call it by using
:meth:`get_inline_bot_results() <pyrogram.Client.get_inline_bot_results>` to get the list of its inline results
for a query:
:meth:`~pyrogram.Client.get_inline_bot_results` to get the list of its inline results for a query:
.. code-block:: python
@ -24,7 +23,7 @@ Inline Bots
results list.
- After you retrieved the bot results, you can use
:meth:`send_inline_bot_result() <pyrogram.Client.send_inline_bot_result>` to send a chosen result to any chat:
:meth:`~pyrogram.Client.send_inline_bot_result` to send a chosen result to any chat:
.. code-block:: python

24
docs/source/topics/filters.rst
View File

@ -4,7 +4,7 @@ Using Filters
So far we've seen how to register a callback function that executes every time a specific update comes from the server,
but there's much more than that to come.
Here we'll discuss about :class:`Filters <pyrogram.Filters>`. Filters enable a fine-grain control over what kind of
Here we'll discuss about :class:`~pyrogram.Filters`. Filters enable a fine-grain control over what kind of
updates are allowed or not to be passed in your callback functions, based on their inner details.
Single Filters
@ -12,7 +12,7 @@ Single Filters
Let's start right away with a simple example:
- This example will show you how to **only** handle messages containing an :obj:`Audio <pyrogram.Audio>` object and
- This example will show you how to **only** handle messages containing an :class:`~pyrogram.Audio` object and
ignore any other message. Filters are passed as the first argument of the decorator:
.. code-block:: python
@ -69,7 +69,7 @@ Here are some examples:
Advanced Filters
----------------
Some filters, like :meth:`command() <pyrogram.Filters.command>` or :meth:`regex() <pyrogram.Filters.regex>`
Some filters, like :meth:`~pyrogram.Filters.command` or :meth:`~pyrogram.Filters.regex`
can also accept arguments:
- Message is either a */start* or */help* **command**.
@ -109,18 +109,18 @@ More handlers using different filters can also live together.
Custom Filters
--------------
Pyrogram already provides lots of built-in :class:`Filters <pyrogram.Filters>` to work with, but in case you can't find
Pyrogram already provides lots of built-in :class:`~pyrogram.Filters` to work with, but in case you can't find
a specific one for your needs or want to build a custom filter by yourself (to be used in a different kind of handler,
for example) you can use :meth:`Filters.create() <pyrogram.Filters.create>`.
for example) you can use :meth:`~pyrogram.Filters.create`.
.. note::
At the moment, the built-in filters are intended to be used with the :obj:`MessageHandler <pyrogram.MessageHandler>`
only.
At the moment, the built-in filters are intended to be used with the :class:`~pyrogram.MessageHandler` only.
An example to demonstrate how custom filters work is to show how to create and use one for the
:obj:`CallbackQueryHandler <pyrogram.CallbackQueryHandler>`. Note that callback queries updates are only received by
bots; create and `authorize your bot <../start/Setup.html#bot-authorization>`_, then send a message with an inline
keyboard to yourself. This allows you to test your filter by pressing the inline button:
:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots; create and
:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to
test your filter by pressing the inline button:
.. code-block:: python
@ -137,7 +137,7 @@ keyboard to yourself. This allows you to test your filter by pressing the inline
Basic Filters
^^^^^^^^^^^^^
For this basic filter we will be using only the first two parameters of :meth:`Filters.create() <pyrogram.Filters.create>`.
For this basic filter we will be using only the first two parameters of :meth:`~pyrogram.Filters.create`.
The code below creates a simple filter for hardcoded, static callback data. This filter will only allow callback queries
containing "Pyrogram" as data, that is, the function *func* you pass returns True in case the callback query data
@ -175,7 +175,7 @@ Filters with Arguments
^^^^^^^^^^^^^^^^^^^^^^
A much cooler filter would be one that accepts "Pyrogram" or any other data as argument at usage time.
A dynamic filter like this will make use of the third parameter of :meth:`Filters.create() <pyrogram.Filters.create>`.
A dynamic filter like this will make use of the third parameter of :meth:`~pyrogram.Filters.create`.
This is how a dynamic custom filter looks like:

8
docs/source/topics/more-on-updates.rst
View File

@ -1,7 +1,8 @@
More on Updates
===============
Here we'll show some advanced usages when working with `update handlers`_ and `filters`_.
Here we'll show some advanced usages when working with :doc:`update handlers <../start/updates>` and
:doc:`filters <filters>`.
Handler Groups
--------------
@ -44,7 +45,7 @@ Or, if you want ``just_text`` to be fired *before* ``text_or_sticker`` (note ``-
def just_text(client, message):
print("Just Text")
With :meth:`add_handler() <pyrogram.Client.add_handler>` (without decorators) the same can be achieved with:
With :meth:`~pyrogram.Client.add_handler` (without decorators) the same can be achieved with:
.. code-block:: python
@ -217,6 +218,3 @@ The output of both (equivalent) examples will be:
0
1
2
.. _`update handlers`: ../start/updates
.. _`filters`: filters

7
docs/source/topics/serialize.rst
View File

@ -9,7 +9,8 @@ For Humans - str(obj)
---------------------
If you want a nicely formatted, human readable JSON representation of any object in the API -- namely, any object from
`Pyrogram types`_, `raw functions`_ and `raw types`_ -- you can use use ``str(obj)``.
:doc:`Pyrogram types <../api/types>`, :doc:`raw functions <../telegram/functions/index>` and
:doc:`raw types <../telegram/types/index>` -- you can use use ``str(obj)``.
.. code-block:: python
@ -25,10 +26,6 @@ If you want a nicely formatted, human readable JSON representation of any object
When using ``print()`` you don't actually need to use ``str()`` on the object because it is called automatically, we
have done that above just to show you how to explicitly convert a Pyrogram object to JSON.
.. _Pyrogram types: ../api/types
.. _raw functions: ../telegram/functions
.. _raw types: ../telegram/types
For Machines - repr(obj)
------------------------

2
docs/source/topics/session-settings.rst
View File

@ -5,7 +5,7 @@ As you may probably know, Telegram allows users (and bots) having more than one
in the system at the same time.
Briefly explaining, sessions are simply new logins in your account. They can be reviewed in the settings of an official
app (or by invoking `GetAuthorizations <../telegram/functions/account/GetAuthorizations.html>`_ with Pyrogram). They
app (or by invoking :class:`~pyrogram.api.functions.account.GetAuthorizations` with Pyrogram). They
store some useful information such as the client who's using them and from which country and IP address.
.. figure:: https://i.imgur.com/YaqtMLO.png

17
docs/source/topics/smart-plugins.rst
View File

@ -65,8 +65,8 @@ after importing your modules, like this:
app.run()
This is already nice and doesn't add *too much* boilerplate code, but things can get boring still; you have to
manually ``import``, manually :meth:`add_handler() <pyrogram.Client.add_handler>` and manually instantiate each
:obj:`MessageHandler <pyrogram.MessageHandler>` object because **you can't use those cool decorators** for your
manually ``import``, manually :meth:`~pyrogram.Client.add_handler` and manually instantiate each
:class:`~pyrogram.MessageHandler` object because **you can't use those cool decorators** for your
functions. So, what if you could? Smart Plugins solve this issue by taking care of handlers registration automatically.
Using Smart Plugins
@ -80,7 +80,7 @@ Setting up your Pyrogram project to accommodate Smart Plugins is pretty straight
.. note::
This is the same example application `as shown above <#introduction>`_, written using the Smart Plugin system.
This is the same example application as shown above, written using the Smart Plugin system.
.. code-block:: text
:emphasize-lines: 2, 3
@ -156,7 +156,7 @@ found inside each module will be, instead, loaded in the order they are defined,
.. note::
Remember: there can be at most one handler, within a group, dealing with a specific update. Plugins with overlapping
filters included a second time will not work. Learn more at `More on Updates <more-on-updates>`_.
filters included a second time will not work. Learn more at :doc:`More on Updates <more-on-updates>`.
This default loading behaviour is usually enough, but sometimes you want to have more control on what to include (or
exclude) and in which exact order to load plugins. The way to do this is to make use of ``include`` and ``exclude``
@ -288,9 +288,8 @@ also organized in subfolders:
Load/Unload Plugins at Runtime
------------------------------
In the `previous section <#specifying-the-plugins-to-include>`_ we've explained how to specify which plugins to load and
which to ignore before your Client starts. Here we'll show, instead, how to unload and load again a previously
registered plugin at runtime.
In the previous section we've explained how to specify which plugins to load and which to ignore before your Client
starts. Here we'll show, instead, how to unload and load again a previously registered plugin at runtime.
Each function decorated with the usual ``on_message`` decorator (or any other decorator that deals with Telegram updates
) will be modified in such a way that, when you reference them later on, they will be actually pointing to a tuple of
@ -318,7 +317,7 @@ Unloading
^^^^^^^^^
In order to unload a plugin, or any other handler, all you need to do is obtain a reference to it by importing the
relevant module and call :meth:`remove_handler() <pyrogram.Client.remove_handler>` Client's method with your function
relevant module and call :meth:`~pyrogram.Client.remove_handler` Client's method with your function
name preceded by the star ``*`` operator as argument. Example:
- ``main.py``
@ -343,7 +342,7 @@ Loading
^^^^^^^
Similarly to the unloading process, in order to load again a previously unloaded plugin you do the same, but this time
using :meth:`add_handler() <pyrogram.Client.add_handler>` instead. Example:
using :meth:`~pyrogram.Client.add_handler` instead. Example:
- ``main.py``

4
docs/source/topics/text-formatting.rst
View File

@ -12,7 +12,7 @@ Markdown Style
--------------
To use this mode, pass "markdown" in the *parse_mode* field when using
:obj:`send_message() <pyrogram.Client.send_message>`. Use the following syntax in your message:
:meth:`~pyrogram.Client.send_message`. Use the following syntax in your message:
.. code-block:: text
@ -34,7 +34,7 @@ To use this mode, pass "markdown" in the *parse_mode* field when using
HTML Style
----------
To use this mode, pass "html" in the *parse_mode* field when using :obj:`send_message() <pyrogram.Client.send_message>`.
To use this mode, pass "html" in the *parse_mode* field when using :meth:`~pyrogram.Client.send_message`.
The following tags are currently supported:
.. code-block:: text

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

@ -51,7 +51,7 @@ class SetChatPhoto(BaseClient):
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.
"""
peer = self.resolve_peer(chat_id)

2
pyrogram/client/types/messages_and_media/message.py
View File

@ -110,7 +110,7 @@ class Message(PyrogramType, Update):
new_chat_photo, delete_chat_photo, group_chat_created, supergroup_chat_created, channel_chat_created,
migrate_to_chat_id, migrate_from_chat_id, pinned_message.
media (``bool`` *optional*):
media (``bool``, *optional*):
The message is a media message.
A media message has one and only one of these fields set: audio, document, photo, sticker, video, animation,
voice, video_note, contact, location, venue.