From 944b672fe5b044446970887b868e9785addb6525 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Thu, 16 May 2019 21:28:34 +0200 Subject: [PATCH] Docs revamp. Part 4 --- compiler/docs/template/page.txt | 2 +- docs/source/api/bound-methods.rst | 102 ++++++++++++++++++ docs/source/api/client.rst | 13 ++- docs/source/api/decorators.rst | 7 +- docs/source/api/errors.rst | 23 ++-- docs/source/api/handlers.rst | 9 +- docs/source/api/methods.rst | 5 +- docs/source/api/types.rst | 98 +---------------- docs/source/index.rst | 12 ++- docs/source/intro/auth.rst | 1 + docs/source/intro/install.rst | 13 +-- docs/source/intro/start.rst | 7 +- docs/source/start/errors.rst | 88 ++++++++------- docs/source/start/invoking.rst | 9 +- docs/source/start/updates.rst | 4 +- docs/source/topics/advanced-usage.rst | 6 +- docs/source/topics/faq.rst | 58 ++++++++-- docs/source/topics/filters.rst | 3 + docs/source/topics/glossary.rst | 53 +++++++++ docs/source/topics/smart-plugins.rst | 26 ++--- pyrogram/client/client.py | 18 ++-- pyrogram/client/filters/filters.py | 34 ++---- .../methods/decorators/on_callback_query.py | 3 +- .../methods/decorators/on_deleted_messages.py | 3 +- .../methods/decorators/on_disconnect.py | 3 +- .../methods/decorators/on_inline_query.py | 3 +- .../client/methods/decorators/on_message.py | 3 +- pyrogram/client/methods/decorators/on_poll.py | 3 +- .../methods/decorators/on_raw_update.py | 3 +- .../methods/decorators/on_user_status.py | 2 +- .../methods/messages/forward_messages.py | 2 +- .../client/methods/messages/send_document.py | 2 +- .../client/types/keyboards/callback_query.py | 6 +- .../types/messages_and_media/message.py | 55 +++++----- .../client/types/user_and_chats/chat_photo.py | 2 +- 35 files changed, 402 insertions(+), 279 deletions(-) create mode 100644 docs/source/api/bound-methods.rst create mode 100644 docs/source/topics/glossary.rst diff --git a/compiler/docs/template/page.txt b/compiler/docs/template/page.txt index 25a396fa..638a10cf 100644 --- a/compiler/docs/template/page.txt +++ b/compiler/docs/template/page.txt @@ -1,5 +1,5 @@ {title} {title_markup} -.. autoclass:: {full_class_path} +.. autoclass:: {full_class_path}() :members: diff --git a/docs/source/api/bound-methods.rst b/docs/source/api/bound-methods.rst new file mode 100644 index 00000000..d93497fe --- /dev/null +++ b/docs/source/api/bound-methods.rst @@ -0,0 +1,102 @@ +Bound Methods +============= + +Some Pyrogram types define what are called bound methods. Bound methods are functions attached to a class which are +accessed via an instance of that class. They make it even easier to call specific methods by automatically inferring +some of the required arguments. + +.. code-block:: python + :emphasize-lines: 8 + + from pyrogram import Client + + app = Client("my_account") + + + @app.on_message() + def hello(client, message) + message.reply("hi") + + + app.run() + +.. currentmodule:: pyrogram + +- Message_ +- CallbackQuery_ +- InlineQuery_ + +.. _Message: + +Message +------- + +- :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()` + +.. automethod:: Message.click() +.. automethod:: Message.delete() +.. automethod:: Message.download() +.. automethod:: Message.edit() +.. automethod:: Message.edit_caption() +.. automethod:: Message.edit_media() +.. automethod:: Message.edit_reply_markup() +.. automethod:: Message.forward() +.. automethod:: Message.pin() +.. automethod:: Message.reply() +.. automethod:: Message.reply_animation() +.. automethod:: Message.reply_audio() +.. automethod:: Message.reply_cached_media() +.. automethod:: Message.reply_chat_action() +.. automethod:: Message.reply_contact() +.. automethod:: Message.reply_document() +.. automethod:: Message.reply_game() +.. automethod:: Message.reply_inline_bot_result() +.. automethod:: Message.reply_location() +.. automethod:: Message.reply_media_group() +.. automethod:: Message.reply_photo() +.. automethod:: Message.reply_poll() +.. automethod:: Message.reply_sticker() +.. automethod:: Message.reply_venue() +.. automethod:: Message.reply_video() +.. automethod:: Message.reply_video_note() +.. automethod:: Message.reply_voice() + +.. _CallbackQuery: + +CallbackQuery +------------- + +.. automethod:: CallbackQuery.answer() + +.. _InlineQuery: + +InlineQuery +----------- + +.. automethod:: InlineQuery.answer() \ No newline at end of file diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst index 05c5cd0c..01e3f5f8 100644 --- a/docs/source/api/client.rst +++ b/docs/source/api/client.rst @@ -1,7 +1,16 @@ Pyrogram Client =============== -The :class:`Client ` is the main class. It exposes easy-to-use methods that are named -after the well established Telegram Bot API methods, thus offering a familiar look to Bot developers. +This class exposes high-level methods for an easy access to the API. + +.. code-block:: python + :emphasize-lines: 1-3 + + from pyrogram import Client + + app = Client("my_account") + + with app: + app.send_message("me", "Hi!") .. autoclass:: pyrogram.Client() diff --git a/docs/source/api/decorators.rst b/docs/source/api/decorators.rst index a9cd70c7..26bd64e1 100644 --- a/docs/source/api/decorators.rst +++ b/docs/source/api/decorators.rst @@ -1,7 +1,7 @@ Decorators ========== -While still being methods bound to the :obj:`Client` class, decorators are of a special kind and thus deserve a +While still being methods bound to the :obj:`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 @@ -9,13 +9,12 @@ Decorators are able to register callback functions for handling updates in a muc :meth:`add_handler() `, automatically. All you need to do is adding the decorators on top of your functions. -**Example:** - .. code-block:: python + :emphasize-lines: 6 from pyrogram import Client - app = Client(...) + app = Client("my_account") @app.on_message() diff --git a/docs/source/api/errors.rst b/docs/source/api/errors.rst index 29dcafac..fad571e3 100644 --- a/docs/source/api/errors.rst +++ b/docs/source/api/errors.rst @@ -5,27 +5,26 @@ All Pyrogram API errors live inside the ``errors`` sub-package: ``pyrogram.error The errors ids listed here are shown as *UPPER_SNAKE_CASE*, but the actual exception names to import from Pyrogram follow the usual *PascalCase* convention. -**Example**: - .. code-block:: python + :emphasize-lines: 1, 5 - from pyrogram.errors import InternalServerError + from pyrogram.errors import FloodWait try: ... - except FloodWait: + except FloodWait as e: ... -303 - See Other ---------------- +303 - SeeOther +-------------- .. csv-table:: :file: ../../../compiler/error/source/303_SEE_OTHER.tsv :delim: tab :header-rows: 1 -400 - Bad Request ------------------ +400 - BadRequest +---------------- .. csv-table:: :file: ../../../compiler/error/source/400_BAD_REQUEST.tsv @@ -48,8 +47,8 @@ follow the usual *PascalCase* convention. :delim: tab :header-rows: 1 -406 - Not Acceptable --------------------- +406 - NotAcceptable +------------------- .. csv-table:: :file: ../../../compiler/error/source/406_NOT_ACCEPTABLE.tsv @@ -64,8 +63,8 @@ follow the usual *PascalCase* convention. :delim: tab :header-rows: 1 -500 - Internal Server Error ---------------------------- +500 - InternalServerError +------------------------- .. csv-table:: :file: ../../../compiler/error/source/500_INTERNAL_SERVER_ERROR.tsv diff --git a/docs/source/api/handlers.rst b/docs/source/api/handlers.rst index 08d40039..023f6e28 100644 --- a/docs/source/api/handlers.rst +++ b/docs/source/api/handlers.rst @@ -7,13 +7,12 @@ For a much more convenient way of registering callback functions have a look at In case you decided to manually create an handler, use :meth:`add_handler() ` to register it. -**Example:** - .. code-block:: python + :emphasize-lines: 1, 10 from pyrogram import Client, MessageHandler - app = Client(...) + app = Client("my_account") def dump(client, message): @@ -34,6 +33,7 @@ it. CallbackQueryHandler InlineQueryHandler UserStatusHandler + PollHandler DisconnectHandler RawUpdateHandler @@ -52,6 +52,9 @@ it. .. autoclass:: UserStatusHandler() :members: +.. autoclass:: PollHandler() + :members: + .. autoclass:: DisconnectHandler() :members: diff --git a/docs/source/api/methods.rst b/docs/source/api/methods.rst index 609a38a8..ded4d017 100644 --- a/docs/source/api/methods.rst +++ b/docs/source/api/methods.rst @@ -3,13 +3,12 @@ Available Methods All Pyrogram methods listed here are bound to a :obj:`Client ` instance. -**Example:** - .. code-block:: python + :emphasize-lines: 6 from pyrogram import Client - app = Client(...) + app = Client("my_account") with app: app.send_message("haskell", "hi") diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index 710a772d..506fe003 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -3,9 +3,8 @@ Available Types All Pyrogram types listed here are accessible through the main package directly. -**Example:** - .. code-block:: python + :emphasize-lines: 1 from pyrogram import User, Message, ... @@ -112,167 +111,72 @@ InputMessageContent ------------ .. autoclass:: User() - :members: - .. autoclass:: UserStatus() - :members: - .. autoclass:: Chat() - :members: - .. autoclass:: ChatPreview() - :members: - .. autoclass:: ChatPhoto() - :members: - .. autoclass:: ChatMember() - :members: - .. autoclass:: ChatMembers() - :members: - .. autoclass:: ChatPermissions() - :members: - .. autoclass:: Dialog() - :members: - .. autoclass:: Dialogs() - :members: .. Messages & Media ---------------- .. autoclass:: Message() - :members: - .. autoclass:: Messages() - :members: - .. autoclass:: MessageEntity() - :members: - .. autoclass:: Photo() - :members: - .. autoclass:: PhotoSize() - :members: - .. autoclass:: UserProfilePhotos() - :members: - .. autoclass:: Audio() - :members: - .. autoclass:: Document() - :members: - .. autoclass:: Animation() - :members: - .. autoclass:: Video() - :members: - .. autoclass:: Voice() - :members: - .. autoclass:: VideoNote() - :members: - .. autoclass:: Contact() - :members: - .. autoclass:: Location() - :members: - .. autoclass:: Venue() - :members: - .. autoclass:: Sticker() - :members: - .. autoclass:: Game() - :members: - .. autoclass:: Poll() - :members: - .. autoclass:: PollOption() - :members: .. Keyboards --------- .. autoclass:: ReplyKeyboardMarkup() - :members: - .. autoclass:: KeyboardButton() - :members: - .. autoclass:: ReplyKeyboardRemove() - :members: - .. autoclass:: InlineKeyboardMarkup() - :members: - .. autoclass:: InlineKeyboardButton() - :members: - .. autoclass:: ForceReply() - :members: - .. autoclass:: CallbackQuery() - :members: - .. autoclass:: GameHighScore() - :members: - .. autoclass:: CallbackGame() - :members: .. Input Media ----------- .. autoclass:: InputMedia() - :members: - .. autoclass:: InputMediaPhoto() - :members: - .. autoclass:: InputMediaVideo() - :members: - .. autoclass:: InputMediaAudio() - :members: - .. autoclass:: InputMediaAnimation() - :members: - .. autoclass:: InputMediaDocument() - :members: - .. autoclass:: InputPhoneContact() - :members: - .. Inline Mode ----------- .. autoclass:: InlineQuery() - :members: - .. autoclass:: InlineQueryResult() - :members: - .. autoclass:: InlineQueryResultArticle() - :members: .. InputMessageContent ------------------- .. autoclass:: InputMessageContent() - :members: - .. autoclass:: InputTextMessageContent() - :members: diff --git a/docs/source/index.rst b/docs/source/index.rst index 9ff0f720..9b878baf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -66,7 +66,7 @@ How the Documentation is Organized Contents are organized into self-contained topics and can be all accessed from the sidebar, or by following them in order using the Next button at the end of each page. Here below you can, instead, find a list of the most relevant -pages. +pages for a quick access. Getting Started ^^^^^^^^^^^^^^^ @@ -86,23 +86,27 @@ API Reference - `Client Class`_ - Details about the Client class. - `Available Methods`_ - A list of available high-level methods. - `Available Types`_ - A list of available high-level types. +- `Bound Methods`_ - A list of convenient bound methods. .. _Client Class: api/client .. _Available Methods: api/methods .. _Available Types: api/types +.. _Bound Methods: api/bound-methods -Topics -^^^^^^ +Relevant Topics +^^^^^^^^^^^^^^^ - `Smart Plugins`_ - How to modularize your application. - `Advanced Usage`_ - How to use Telegram's raw API. - `Release Notes`_ - Release notes for Pyrogram releases. - `Pyrogram FAQ`_ - Answers to common Pyrogram questions. +- `Pyrogram Glossary`_ - A list of words with brief explanations. .. _Smart Plugins: topics/smart-plugins .. _Advanced Usage: topics/advanced-usage .. _Release Notes: topics/releases .. _Pyrogram FAQ: topics/faq +.. _Pyrogram Glossary: topics/glossary .. toctree:: :hidden: @@ -128,6 +132,7 @@ Topics api/client api/methods api/types + api/bound-methods api/handlers api/decorators api/filters @@ -152,6 +157,7 @@ Topics topics/voice-calls topics/releases topics/faq + topics/glossary .. toctree:: :hidden: diff --git a/docs/source/intro/auth.rst b/docs/source/intro/auth.rst index 86217137..846a19a1 100644 --- a/docs/source/intro/auth.rst +++ b/docs/source/intro/auth.rst @@ -61,6 +61,7 @@ after the session name, which will be ``pyrogrambot.session`` for the example be "my_bot", bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" ) + app.run() .. _project is set up: setup.html diff --git a/docs/source/intro/install.rst b/docs/source/intro/install.rst index e2e4365a..c4df60d4 100644 --- a/docs/source/intro/install.rst +++ b/docs/source/intro/install.rst @@ -29,12 +29,12 @@ Install Pyrogram Bleeding Edge ------------- -Things are constantly evolving in Pyrogram, although new releases are published only when enough changes are added, -but this doesn't mean you can't try new features right now! +Pyrogram is always evolving, although new releases on PyPI are published only when enough changes are added, but this +doesn't mean you can't try new features right now! -In case you would like to try out the latest Pyrogram features and additions, the `GitHub repo`_ is always kept updated -with new changes; you can install the development version straight from the ``develop`` branch using this command -(note "develop.zip" in the link): +In case you'd like to try out the latest Pyrogram features, the `GitHub repo`_ is always kept updated with new changes; +you can install the development version straight from the ``develop`` branch using this command (note "develop.zip" in +the link): .. code-block:: text @@ -44,7 +44,8 @@ Asynchronous ------------ Pyrogram heavily depends on IO-bound network code (it's a cloud-based messaging framework after all), and here's -where asyncio shines the most by providing extra performance while running on a single OS-level thread only. +where asyncio shines the most by providing extra performance and efficiency while running on a single OS-level thread +only. **A fully asynchronous variant of Pyrogram is therefore available** (Python 3.5.3+ required). Use this command to install (note "asyncio.zip" in the link): diff --git a/docs/source/intro/start.rst b/docs/source/intro/start.rst index 7d6f0150..2fcd4633 100644 --- a/docs/source/intro/start.rst +++ b/docs/source/intro/start.rst @@ -10,7 +10,7 @@ Get Pyrogram Real Fast 2. Get your own Telegram API key from https://my.telegram.org/apps. -3. Open your best text editor and paste the following: +3. Open your best text editor and paste the following: .. code-block:: python @@ -40,10 +40,9 @@ 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. +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? 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 `Calling Methods`_ and come back later to learn some more details. .. _community: //t.me/pyrogramchat .. _Calling Methods: ../start/invoking \ No newline at end of file diff --git a/docs/source/start/errors.rst b/docs/source/start/errors.rst index 1260672e..1f4f5a2e 100644 --- a/docs/source/start/errors.rst +++ b/docs/source/start/errors.rst @@ -1,51 +1,57 @@ Error Handling ============== -Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks. - -There are many errors that Telegram could return, but they all fall in one of these categories -(which are in turn children of the ``RPCError`` superclass): - -- `303 - See Other <../api/errors#see-other>`_ -- `400 - Bad Request <../api/errors#bad-request>`_ -- `401 - Unauthorized <../api/errors#unauthorized>`_ -- `403 - Forbidden <../api/errors#forbidden>`_ -- `406 - Not Acceptable <../api/errors#not-acceptable>`_ -- `420 - Flood <../api/errors#flood>`_ -- `500 - Internal Server Error <../api/errors#internal-server-error>`_ - -As stated above, there are really many (too many) errors, and in case Pyrogram does not know anything yet about a -specific one, it raises a special ``520 Unknown Error`` exception and logs it -in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors. - -Examples --------- +Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks in order +to control the behaviour of your application. Pyrogram errors all live inside the ``errors`` package: .. code-block:: python - from pyrogram.errors import ( - BadRequest, Flood, InternalServerError, - SeeOther, Unauthorized, UnknownError - ) + from pyrogram import errors - try: - ... - except BadRequest: - pass - except Flood: - pass - except InternalServerError: - pass - except SeeOther: - pass - except Unauthorized: - pass - except UnknownError: - pass +RPCError +-------- -Exception objects may also contain some informative values. -E.g.: ``FloodWait`` holds the amount of seconds you have to wait -before you can try again. The value is always stored in the ``x`` field of the returned exception object: +The father of all errors is named ``RPCError``. This error exists in form of a Python exception and is able to catch all +Telegram API related errors. + +.. code-block:: python + + from pyrogram.errors import RPCError + +.. warning:: + + It must be noted that catching this error is bad practice, especially when no feedback is given (i.e. by + logging/printing the full error traceback), because it makes it impossible to understand what went wrong. + +Error Categories +---------------- + +The ``RPCError`` packs together all the possible errors Telegram could raise, but to make things tidier, Pyrogram +provides categories of errors, which are named after the common HTTP errors: + +.. code-block:: python + + from pyrogram.errors import BadRequest, Forbidden, ... + +- `303 - SeeOther <../api/errors#seeother>`_ +- `400 - BadRequest <../api/errors#badrequest>`_ +- `401 - Unauthorized <../api/errors#unauthorized>`_ +- `403 - Forbidden <../api/errors#forbidden>`_ +- `406 - NotAcceptable <../api/errors#notacceptable>`_ +- `420 - Flood <../api/errors#flood>`_ +- `500 - InternalServerError <../api/errors#internalservererror>`_ + +Unknown Errors +-------------- + +In case Pyrogram does not know anything yet about a specific error, it raises a special ``520 - UnknownError`` exception +and logs it in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors. + +Errors with Values +------------------ + +Exception objects may also contain some informative values. For example, ``FloodWait`` holds the amount of seconds you +have to wait before you can try again. The value is always stored in the ``x`` field of the returned exception object: .. code-block:: python @@ -55,4 +61,4 @@ before you can try again. The value is always stored in the ``x`` field of the r try: ... except FloodWait as e: - time.sleep(e.x) + time.sleep(e.x) # Wait before trying again diff --git a/docs/source/start/invoking.rst b/docs/source/start/invoking.rst index c27e86c3..fae19523 100644 --- a/docs/source/start/invoking.rst +++ b/docs/source/start/invoking.rst @@ -1,9 +1,12 @@ Calling Methods =============== -At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now pointing towards the +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! +Basic Usage +----------- + Making API method calls with Pyrogram is very simple. Here's an example we are going to examine: .. code-block:: python @@ -60,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 ` and :meth:`stop ` gracefully, even in case of unhandled -exceptions in your code. The example above can be therefore rewritten in a much nicer way, this way: +:meth:`start() ` and :meth:`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 diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst index 85005b9c..930096a3 100644 --- a/docs/source/start/updates.rst +++ b/docs/source/start/updates.rst @@ -8,7 +8,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, button presses, etc...), which are meant to notify you about a new +account (incoming messages, new members join, bot button presses, etc...), which are meant to notify you about a new specific state that changed. These updates are handled by registering one or more callback functions in your app using `Handlers <../api/handlers>`_. @@ -70,7 +70,7 @@ begins. app.add_handler(my_handler) -Last one, the :meth:`run() ` method. What this does is simply calling +Last one, the :meth:`run() ` method. What this does is simply call :meth:`start() ` and a special method :meth:`idle() ` that keeps your main scripts alive until you press ``CTRL+C``; the client will be automatically stopped after that. diff --git a/docs/source/topics/advanced-usage.rst b/docs/source/topics/advanced-usage.rst index 970e07e0..02a3e3b6 100644 --- a/docs/source/topics/advanced-usage.rst +++ b/docs/source/topics/advanced-usage.rst @@ -101,9 +101,9 @@ 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: - - `InputPeerUser `_ - Users - - `InputPeerChat `_ - Basic Chats - - `InputPeerChannel `_ - Either Channels or Supergroups + - :obj:`InputPeerUser <../telegram/types/InputPeerUser>` - Users + - :obj:`InputPeerChat <../telegram/types/InputPeerChat>` - Basic Chats + - :obj:`InputPeerChannel <../telegram/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() ` as a convenience utility method that returns the correct InputPeer diff --git a/docs/source/topics/faq.rst b/docs/source/topics/faq.rst index 0834389e..7f2086a1 100644 --- a/docs/source/topics/faq.rst +++ b/docs/source/topics/faq.rst @@ -17,21 +17,51 @@ C. It enables you to easily create custom applications for both user and bot ide .. _Telegram: https://telegram.org .. _MTProto API: https://core.telegram.org/api#telegram-api -What does "Pyrogram" mean? --------------------------- +What does the name mean? +------------------------ The word "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**, from *Telegram*. The word *pyro* itself is built from *Python*, **py** for short, and the suffix **ro** to come up with the word *fire*, which also inspired the project logo. -How old is Pyrogram? --------------------- +How old is the project? +----------------------- Pyrogram was first released on December 12, 2017. The actual work on the framework began roughly three months prior the initial public release on `GitHub`_. .. _GitHub: https://github.com/pyrogram/pyrogram +Why Pyrogram? +------------- + +- **Easy**: You can install Pyrogram with pip and start building your applications right away. +- **Elegant**: Low-level details are abstracted and re-presented in a much nicer and easier way. +- **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C. +- **Documented**: Pyrogram API methods, types and public interfaces are well documented. +- **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted. +- **Updated**, to make use of the latest Telegram API version and features. +- **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. + +.. _TgCrypto: https://github.com/pyrogram/tgcrypto +.. _Smart Plugin: smart-plugins +.. _advanced action: advanced-usage + +What can MTProto do more than the Bot API? +------------------------------------------ + +- Authorize both user and bot identities. +- Upload & download any file, up to 1500 MB each. +- Has less overhead due to direct connections to the actual Telegram servers. +- Run multiple sessions at once, up to 10 per account (either bot or user). +- Get information about any public chat by usernames, even if not a member. +- Obtain information about any message existing in a chat using message ids. +- retrieve the whole chat members list of either public or private chats. +- Receive extra updates, such as the one about a user name change. +- More meaningful errors in case something went wrong. +- Get API version updates, and thus new features, sooner. + Why do I need an API key for bots? ---------------------------------- @@ -46,6 +76,8 @@ Using MTProto is the only way to communicate with the actual Telegram servers, a identify applications by means of a unique key; the bot token identifies a bot as a user and replaces the user's phone number only. +Why is the main API (MTProto) superiod + I started a client but nothing happens! --------------------------------------- @@ -65,7 +97,7 @@ in a bunch of seconds: .. _you need a proxy: proxy -I keep getting [400 PEER_ID_INVALID] error! +I keep getting PEER_ID_INVALID error! ------------------------------------------- The error in question is **[400 PEER_ID_INVALID]: The id/access_hash combination is invalid**, and could mean several @@ -104,4 +136,18 @@ mistakes by either the automatic systems or a moderator. In such cases you can k recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_. .. _@smstelegram: https://twitter.com/smstelegram -.. _this form: https://telegram.org/support \ No newline at end of file +.. _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 a +different licence 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. \ No newline at end of file diff --git a/docs/source/topics/filters.rst b/docs/source/topics/filters.rst index ec3e2e10..cb2e2a4c 100644 --- a/docs/source/topics/filters.rst +++ b/docs/source/topics/filters.rst @@ -7,6 +7,9 @@ but there's much more than that to come. Here we'll discuss about :class:`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 +-------------- + Let's start right away with a simple example: - This example will show you how to **only** handle messages containing an :obj:`Audio ` object and diff --git a/docs/source/topics/glossary.rst b/docs/source/topics/glossary.rst new file mode 100644 index 00000000..5721306c --- /dev/null +++ b/docs/source/topics/glossary.rst @@ -0,0 +1,53 @@ +Pyrogram Glossary +----------------- + +This page contains a list of common words with brief explanations related to Pyrogram and, to some extent, Telegram in +general. + +.. glossary:: + + API + Application Programming Interface: a set of methods, protocols and tools that make it easier to develop programs + by providing useful building blocks to the developer. + + 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. + + MTProto + The name of the custom-made, open encryption protocol by Telegram, implemented in Pyrogram. + + 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 schema. + + Bot API + The `Telegram Bot API`_ that is able to only connect normal bots to Telegram using HTTP as application layer + protocol and allows to execute a subset of the main Telegram API. + + Pyrogrammer + A developer that uses Pyrogram to build Telegram applications. + + Userbot + Also known as *user bot* or *ubot* for short, is a user logged in by third-party Telegram libraries --- such as + Pyrogram --- to automate some behaviours, like sending messages or reacting to text commands or any other event. + + Session + Also known as *login session*, is a strictly personal piece of information created and held by both parties + (client and server) which is used to grant permission into a single account without having to start a new + authorization process from scratch. + + Callback + Also known as *callback function*, is a user-defined generic function that *can be* registered to and then + called-back by the framework when specific events occurs. + + 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. + + 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`_. + +.. _Telegram Bot API: https://core.telegram.org/bots/api +.. _handling updates: ../start/updates \ No newline at end of file diff --git a/docs/source/topics/smart-plugins.rst b/docs/source/topics/smart-plugins.rst index fbe27388..9f1592d1 100644 --- a/docs/source/topics/smart-plugins.rst +++ b/docs/source/topics/smart-plugins.rst @@ -30,7 +30,7 @@ after importing your modules, like this: handlers.py main.py -- ``handlers.py`` +- ``handlers.py`` .. code-block:: python @@ -41,7 +41,7 @@ after importing your modules, like this: def echo_reversed(client, message): message.reply(message.text[::-1]) -- ``main.py`` +- ``main.py`` .. code-block:: python @@ -91,7 +91,7 @@ Setting up your Pyrogram project to accommodate Smart Plugins is pretty straight config.ini main.py -- ``plugins/handlers.py`` +- ``plugins/handlers.py`` .. code-block:: python :emphasize-lines: 4, 9 @@ -108,14 +108,14 @@ Setting up your Pyrogram project to accommodate Smart Plugins is pretty straight def echo_reversed(client, message): message.reply(message.text[::-1]) -- ``config.ini`` +- ``config.ini`` .. code-block:: ini [plugins] root = plugins -- ``main.py`` +- ``main.py`` .. code-block:: python @@ -199,8 +199,8 @@ also organized in subfolders: ... ... -- Load every handler from every module, namely *plugins0.py*, *plugins1.py* and *plugins2.py* in alphabetical order - (files) and definition order (handlers inside files): +- Load every handler from every module, namely *plugins0.py*, *plugins1.py* and *plugins2.py* in alphabetical order + (files) and definition order (handlers inside files): Using *config.ini* file: @@ -217,7 +217,7 @@ also organized in subfolders: Client("my_account", plugins=plugins).run() -- Load only handlers defined inside *plugins2.py* and *plugins0.py*, in this order: +- Load only handlers defined inside *plugins2.py* and *plugins0.py*, in this order: Using *config.ini* file: @@ -243,7 +243,7 @@ also organized in subfolders: Client("my_account", plugins=plugins).run() -- Load everything except the handlers inside *plugins2.py*: +- Load everything except the handlers inside *plugins2.py*: Using *config.ini* file: @@ -264,7 +264,7 @@ also organized in subfolders: Client("my_account", plugins=plugins).run() -- Load only *fn3*, *fn1* and *fn2* (in this order) from *plugins1.py*: +- Load only *fn3*, *fn1* and *fn2* (in this order) from *plugins1.py*: Using *config.ini* file: @@ -297,7 +297,7 @@ Each function decorated with the usual ``on_message`` decorator (or any other de *(handler: Handler, group: int)*. The actual callback function is therefore stored inside the handler's *callback* attribute. Here's an example: -- ``plugins/handlers.py`` +- ``plugins/handlers.py`` .. code-block:: python :emphasize-lines: 5, 6 @@ -321,7 +321,7 @@ In order to unload a plugin, or any other handler, all you need to do is obtain relevant module and call :meth:`remove_handler() ` Client's method with your function name preceded by the star ``*`` operator as argument. Example: -- ``main.py`` +- ``main.py`` .. code-block:: python @@ -345,7 +345,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() ` instead. Example: -- ``main.py`` +- ``main.py`` .. code-block:: python diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py index 31a7c14c..d382b2fb 100644 --- a/pyrogram/client/client.py +++ b/pyrogram/client/client.py @@ -60,9 +60,7 @@ log = logging.getLogger(__name__) class Client(Methods, BaseClient): - """This class represents a Client, the main means for interacting with Telegram. - It exposes bot-like methods for an easy access to the API as well as a simple way to - invoke every single Telegram API method available. + """Pyrogram Client, the main means for interacting with Telegram. Parameters: session_name (``str``): @@ -80,7 +78,7 @@ class Client(Methods, BaseClient): This is an alternative way to pass it if you don't want to use the *config.ini* file. app_version (``str``, *optional*): - Application version. Defaults to "Pyrogram \U0001f525 vX.Y.Z" + Application version. Defaults to "Pyrogram :fire: vX.Y.Z" This is an alternative way to set it if you don't want to use the *config.ini* file. device_model (``str``, *optional*): @@ -110,6 +108,10 @@ class Client(Methods, BaseClient): Only applicable for new sessions and will be ignored in case previously created sessions are loaded. + bot_token (``str``, *optional*): + Pass your Bot API token to create a bot session, e.g.: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" + Only applicable for new sessions. + phone_number (``str`` | ``callable``, *optional*): Pass your phone number as string (with your Country Code prefix included) to avoid entering it manually. Or pass a callback function which accepts no arguments and must return the correct phone number as string @@ -143,10 +145,6 @@ class Client(Methods, BaseClient): a new Telegram account in case the phone number you passed is not registered yet. Only applicable for new sessions. - bot_token (``str``, *optional*): - Pass your Bot API token to create a bot session, e.g.: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11" - Only applicable for new sessions. - last_name (``str``, *optional*): Same purpose as *first_name*; pass a Last Name to avoid entering it manually. It can be an empty string: "". Only applicable for new sessions. @@ -193,12 +191,12 @@ class Client(Methods, BaseClient): ipv6: bool = False, proxy: dict = None, test_mode: bool = False, + bot_token: str = None, phone_number: str = None, phone_code: Union[str, callable] = None, password: str = None, recovery_code: callable = None, force_sms: bool = False, - bot_token: str = None, first_name: str = None, last_name: str = None, workers: int = BaseClient.WORKERS, @@ -221,12 +219,12 @@ class Client(Methods, BaseClient): # TODO: Make code consistent, use underscore for private/protected fields self._proxy = proxy self.test_mode = test_mode + self.bot_token = bot_token self.phone_number = phone_number self.phone_code = phone_code self.password = password self.recovery_code = recovery_code self.force_sms = force_sms - self.bot_token = bot_token self.first_name = first_name self.last_name = last_name self.workers = workers diff --git a/pyrogram/client/filters/filters.py b/pyrogram/client/filters/filters.py index 2117ec6e..169193a0 100644 --- a/pyrogram/client/filters/filters.py +++ b/pyrogram/client/filters/filters.py @@ -191,35 +191,19 @@ class Filters: """Filter messages sent via inline bots""" service = create("Service", lambda _, m: bool(m.service)) - """Filter service messages. A service message contains any of the following fields set + """Filter service messages. - - left_chat_member - - new_chat_title - - 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 - - game_score""" + A service message contains any of the following fields set: *left_chat_member*, + *new_chat_title*, *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*, *game_score*. + """ media = create("Media", lambda _, m: bool(m.media)) - """Filter media messages. A media message contains any of the following fields set + """Filter media messages. - - audio - - document - - photo - - sticker - - video - - animation - - voice - - video_note - - contact - - location - - venue - - poll""" + A media message contains any of the following fields set: *audio*, *document*, *photo*, *sticker*, *video*, + *animation*, *voice*, *video_note*, *contact*, *location*, *venue*, *poll*. + """ @staticmethod def command( diff --git a/pyrogram/client/methods/decorators/on_callback_query.py b/pyrogram/client/methods/decorators/on_callback_query.py index 9ead25b4..b76655fb 100644 --- a/pyrogram/client/methods/decorators/on_callback_query.py +++ b/pyrogram/client/methods/decorators/on_callback_query.py @@ -30,7 +30,8 @@ class OnCallbackQuery(BaseClient): filters=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling callback queries. + """Decorator for handling callback queries. + This does the same thing as :meth:`add_handler` using the :class:`CallbackQueryHandler`. Parameters: diff --git a/pyrogram/client/methods/decorators/on_deleted_messages.py b/pyrogram/client/methods/decorators/on_deleted_messages.py index eb9dfcd0..7637e6eb 100644 --- a/pyrogram/client/methods/decorators/on_deleted_messages.py +++ b/pyrogram/client/methods/decorators/on_deleted_messages.py @@ -30,7 +30,8 @@ class OnDeletedMessages(BaseClient): filters=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling deleted messages. + """Decorator for handling deleted messages. + This does the same thing as :meth:`add_handler` using the :class:`DeletedMessagesHandler`. Parameters: diff --git a/pyrogram/client/methods/decorators/on_disconnect.py b/pyrogram/client/methods/decorators/on_disconnect.py index 515a28c1..9305808e 100644 --- a/pyrogram/client/methods/decorators/on_disconnect.py +++ b/pyrogram/client/methods/decorators/on_disconnect.py @@ -23,7 +23,8 @@ from ...ext import BaseClient class OnDisconnect(BaseClient): def on_disconnect(self=None) -> callable: - """Use this decorator to automatically register a function for handling disconnections. + """Decorator for handling disconnections. + This does the same thing as :meth:`add_handler` using the :class:`DisconnectHandler`. """ diff --git a/pyrogram/client/methods/decorators/on_inline_query.py b/pyrogram/client/methods/decorators/on_inline_query.py index e9758c64..58837398 100644 --- a/pyrogram/client/methods/decorators/on_inline_query.py +++ b/pyrogram/client/methods/decorators/on_inline_query.py @@ -30,7 +30,8 @@ class OnInlineQuery(BaseClient): filters=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling inline queries. + """Decorator for handling inline queries. + This does the same thing as :meth:`add_handler` using the :class:`InlineQueryHandler`. Parameters: diff --git a/pyrogram/client/methods/decorators/on_message.py b/pyrogram/client/methods/decorators/on_message.py index ad95cd45..f590fd12 100644 --- a/pyrogram/client/methods/decorators/on_message.py +++ b/pyrogram/client/methods/decorators/on_message.py @@ -30,7 +30,8 @@ class OnMessage(BaseClient): filters=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling messages. + """Decorator for handling messages. + This does the same thing as :meth:`add_handler` using the :class:`MessageHandler`. Parameters: diff --git a/pyrogram/client/methods/decorators/on_poll.py b/pyrogram/client/methods/decorators/on_poll.py index 68f3d78e..de1c1d3d 100644 --- a/pyrogram/client/methods/decorators/on_poll.py +++ b/pyrogram/client/methods/decorators/on_poll.py @@ -30,7 +30,8 @@ class OnPoll(BaseClient): filters=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling poll updates. + """Decorator for handling poll updates. + This does the same thing as :meth:`add_handler` using the :class:`PollHandler`. Parameters: diff --git a/pyrogram/client/methods/decorators/on_raw_update.py b/pyrogram/client/methods/decorators/on_raw_update.py index 2ab1f61b..53a0f4cf 100644 --- a/pyrogram/client/methods/decorators/on_raw_update.py +++ b/pyrogram/client/methods/decorators/on_raw_update.py @@ -28,7 +28,8 @@ class OnRawUpdate(BaseClient): self=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling raw updates. + """Decorator for handling raw updates. + This does the same thing as :meth:`add_handler` using the :class:`RawUpdateHandler`. Parameters: diff --git a/pyrogram/client/methods/decorators/on_user_status.py b/pyrogram/client/methods/decorators/on_user_status.py index 5b49bb3c..e7db7b74 100644 --- a/pyrogram/client/methods/decorators/on_user_status.py +++ b/pyrogram/client/methods/decorators/on_user_status.py @@ -30,7 +30,7 @@ class OnUserStatus(BaseClient): filters=None, group: int = 0 ) -> callable: - """Use this decorator to automatically register a function for handling user status updates. + """Decorator for handling user status updates. This does the same thing as :meth:`add_handler` using the :class:`UserStatusHandler`. Parameters: diff --git a/pyrogram/client/methods/messages/forward_messages.py b/pyrogram/client/methods/messages/forward_messages.py index a3e161fb..82c35f92 100644 --- a/pyrogram/client/methods/messages/forward_messages.py +++ b/pyrogram/client/methods/messages/forward_messages.py @@ -28,7 +28,7 @@ class ForwardMessages(BaseClient): self, chat_id: Union[int, str], from_chat_id: Union[int, str], - message_ids: Iterable[int], + message_ids: Union[int, Iterable[int]], disable_notification: bool = None, as_copy: bool = False, remove_caption: bool = False diff --git a/pyrogram/client/methods/messages/send_document.py b/pyrogram/client/methods/messages/send_document.py index e966a11a..66b3f1c9 100644 --- a/pyrogram/client/methods/messages/send_document.py +++ b/pyrogram/client/methods/messages/send_document.py @@ -46,7 +46,7 @@ class SendDocument(BaseClient): progress: callable = None, progress_args: tuple = () ) -> Union["pyrogram.Message", None]: - """Send general files. + """Send generic files. Parameters: chat_id (``int`` | ``str``): diff --git a/pyrogram/client/types/keyboards/callback_query.py b/pyrogram/client/types/keyboards/callback_query.py index 4d657767..fe6a2175 100644 --- a/pyrogram/client/types/keyboards/callback_query.py +++ b/pyrogram/client/types/keyboards/callback_query.py @@ -30,9 +30,9 @@ from ..user_and_chats import User class CallbackQuery(PyrogramType, Update): """An incoming callback query from a callback button in an inline keyboard. - If the button that originated the query was attached to a message sent by the bot, the field message - will be present. If the button was attached to a message sent via the bot (in inline mode), - the field inline_message_id will be present. Exactly one of the fields data or game_short_name will be present. + If the button that originated the query was attached to a message sent by the bot, the field *message* + will be present. If the button was attached to a message sent via the bot (in inline mode), the field + *inline_message_id* will be present. Exactly one of the fields *data* or *game_short_name* will be present. Parameters: id (``str``): diff --git a/pyrogram/client/types/messages_and_media/message.py b/pyrogram/client/types/messages_and_media/message.py index a8f6d31b..e51f3425 100644 --- a/pyrogram/client/types/messages_and_media/message.py +++ b/pyrogram/client/types/messages_and_media/message.py @@ -661,7 +661,7 @@ class Message(PyrogramType, Update): reply_to_message_id: int = None, reply_markup=None ) -> "Message": - """Bound method *reply* of :obj:`Message`. + """Bound method *reply* :obj:`Message `. Use as a shortcut for: @@ -748,7 +748,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_animation* of :obj:`Message`. + """Bound method *reply_animation* :obj:`Message `. Use as a shortcut for: @@ -882,7 +882,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_audio* of :obj:`Message`. + """Bound method *reply_audio* :obj:`Message `. Use as a shortcut for: @@ -1010,7 +1010,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *reply_cached_media* of :obj:`Message`. + """Bound method *reply_cached_media* :obj:`Message `. Use as a shortcut for: @@ -1077,7 +1077,7 @@ class Message(PyrogramType, Update): ) def reply_chat_action(self, action: str) -> bool: - """Bound method *reply_chat_action* of :obj:`Message`. + """Bound method *reply_chat_action* :obj:`Message `. Use as a shortcut for: @@ -1130,7 +1130,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *reply_contact* of :obj:`Message`. + """Bound method *reply_contact* :obj:`Message `. Use as a shortcut for: @@ -1217,7 +1217,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_document* of :obj:`Message`. + """Bound method *reply_document* :obj:`Message `. Use as a shortcut for: @@ -1331,7 +1331,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *reply_game* of :obj:`Message`. + """Bound method *reply_game* :obj:`Message `. Use as a shortcut for: @@ -1396,7 +1396,7 @@ class Message(PyrogramType, Update): reply_to_message_id: int = None, hide_via: bool = None ) -> "Message": - """Bound method *reply_inline_bot_result* of :obj:`Message`. + """Bound method *reply_inline_bot_result* :obj:`Message `. Use as a shortcut for: @@ -1470,7 +1470,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *reply_location* of :obj:`Message`. + """Bound method *reply_location* :obj:`Message `. Use as a shortcut for: @@ -1538,7 +1538,7 @@ class Message(PyrogramType, Update): disable_notification: bool = None, reply_to_message_id: int = None ) -> "Message": - """Bound method *reply_media_group* of :obj:`Message`. + """Bound method *reply_media_group* :obj:`Message `. Use as a shortcut for: @@ -1610,7 +1610,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_photo* of :obj:`Message`. + """Bound method *reply_photo* :obj:`Message `. Use as a shortcut for: @@ -1724,7 +1724,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *reply_poll* of :obj:`Message`. + """Bound method *reply_poll* :obj:`Message `. Use as a shortcut for: @@ -1800,7 +1800,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_sticker* of :obj:`Message`. + """Bound method *reply_sticker* :obj:`Message `. Use as a shortcut for: @@ -1903,7 +1903,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *reply_venue* of :obj:`Message`. + """Bound method *reply_venue* :obj:`Message `. Use as a shortcut for: @@ -2005,7 +2005,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_video* of :obj:`Message`. + """Bound method *reply_video* :obj:`Message `. Use as a shortcut for: @@ -2140,7 +2140,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_video_note* of :obj:`Message`. + """Bound method *reply_video_note* :obj:`Message `. Use as a shortcut for: @@ -2258,7 +2258,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> "Message": - """Bound method *reply_voice* of :obj:`Message`. + """Bound method *reply_voice* :obj:`Message `. Use as a shortcut for: @@ -2368,7 +2368,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *edit* of :obj:`Message` + """Bound method *edit* :obj:`Message `. Use as a shortcut for: @@ -2425,7 +2425,7 @@ class Message(PyrogramType, Update): "pyrogram.ForceReply" ] = None ) -> "Message": - """Bound method *edit_caption* of :obj:`Message` + """Bound method *edit_caption* :obj:`Message `. Use as a shortcut for: @@ -2468,7 +2468,7 @@ class Message(PyrogramType, Update): ) def edit_media(self, media: InputMedia, reply_markup: "pyrogram.InlineKeyboardMarkup" = None) -> "Message": - """Bound method *edit_media* of :obj:`Message` + """Bound method *edit_media* :obj:`Message `. Use as a shortcut for: @@ -2506,7 +2506,7 @@ class Message(PyrogramType, Update): ) def edit_reply_markup(self, reply_markup: "pyrogram.InlineKeyboardMarkup" = None) -> "Message": - """Bound method *edit_reply_markup* of :obj:`Message` + """Bound method *edit_reply_markup* :obj:`Message `. Use as a shortcut for: @@ -2547,7 +2547,7 @@ class Message(PyrogramType, Update): as_copy: bool = False, remove_caption: bool = False ) -> "Message": - """Bound method *forward* of :obj:`Message`. + """Bound method *forward* :obj:`Message `. Use as a shortcut for: @@ -2690,7 +2690,7 @@ class Message(PyrogramType, Update): ) def delete(self, revoke: bool = True): - """Bound method *delete* of :obj:`Message`. + """Bound method *delete* :obj:`Message `. Use as a shortcut for: @@ -2726,7 +2726,7 @@ class Message(PyrogramType, Update): ) def click(self, x: int or str, y: int = 0, quote: bool = None, timeout: int = 10): - """Bound method *click* of :obj:`Message`. + """Bound method *click* :obj:`Message `. Use as a shortcut for clicking a button attached to the message instead of: @@ -2764,6 +2764,7 @@ class Message(PyrogramType, Update): Parameters: x (``int`` | ``str``): Used as integer index, integer abscissa (in pair with y) or as string label. + Defaults to 0 (first button). y (``int``, *optional*): Used as ordinate only (in pair with x). @@ -2853,7 +2854,7 @@ class Message(PyrogramType, Update): progress: callable = None, progress_args: tuple = () ) -> str: - """Bound method *download* of :obj:`Message`. + """Bound method *download* :obj:`Message `. Use as a shortcut for: @@ -2902,7 +2903,7 @@ class Message(PyrogramType, Update): ) def pin(self, disable_notification: bool = None) -> "Message": - """Bound method *pin* of :obj:`Message`. + """Bound method *pin* :obj:`Message `. Use as a shortcut for: diff --git a/pyrogram/client/types/user_and_chats/chat_photo.py b/pyrogram/client/types/user_and_chats/chat_photo.py index 37fde9fd..08e43138 100644 --- a/pyrogram/client/types/user_and_chats/chat_photo.py +++ b/pyrogram/client/types/user_and_chats/chat_photo.py @@ -25,7 +25,7 @@ from ...ext.utils import encode class ChatPhoto(PyrogramType): - """a chat photo. + """A chat photo. Parameters: small_file_id (``str``):