From 1ccda820c1d486235fb25e8cc8253d8828859d3a Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Thu, 12 Apr 2018 13:43:16 +0200 Subject: [PATCH] Update docs --- docs/source/resources/BotsInteraction.rst | 8 ++-- docs/source/resources/UpdateHandling.rst | 52 +++++++++++++++++------ docs/source/start/BasicUsage.rst | 2 +- docs/source/start/ProjectSetup.rst | 40 +++++++++-------- 4 files changed, 67 insertions(+), 35 deletions(-) diff --git a/docs/source/resources/BotsInteraction.rst b/docs/source/resources/BotsInteraction.rst index 48551b4e..5bdba777 100644 --- a/docs/source/resources/BotsInteraction.rst +++ b/docs/source/resources/BotsInteraction.rst @@ -7,7 +7,7 @@ Inline Bots ----------- - If a bot accepts inline queries, you can call it by using - :obj:`get_inline_bot_results ` to get the list of its inline results + :meth:`get_inline_bot_results() ` to get the list of its inline results for a query: .. code-block:: python @@ -20,11 +20,11 @@ Inline Bots :align: center :figwidth: 60% - ``get_inline_bot_results`` is the equivalent action of writing ``@vid Fuzz Universe`` and getting the + ``get_inline_bot_results()`` is the equivalent action of writing ``@vid Fuzz Universe`` and getting the results list. - After you retrieved the bot results, you can use - :obj:`send_inline_bot_result ` to send a chosen result to any chat: + :meth:`send_inline_bot_result() ` to send a chosen result to any chat: .. code-block:: python @@ -36,5 +36,5 @@ Inline Bots :align: center :figwidth: 60% - ``send_inline_bot_result`` is the equivalent action of choosing a result from the list and sending it + ``send_inline_bot_result()`` is the equivalent action of choosing a result from the list and sending it to a chat. diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst index 4ce86656..0e9b67d4 100644 --- a/docs/source/resources/UpdateHandling.rst +++ b/docs/source/resources/UpdateHandling.rst @@ -1,8 +1,9 @@ Update Handling =============== -Updates are handled by registering one or more callback functions with an Handler. -There are multiple Handlers to choose from, one for each kind of update. +Updates are events that happen in your Telegram account (incoming messages, new channel posts, new members join, ...) +and are handled by registering one or more callback functions with an Handler. There are multiple Handlers to choose +from, one for each kind of update. Registering an Handler ---------------------- @@ -29,16 +30,18 @@ of a message as soon as it arrives. app.start() app.idle() -Alternatively, if you prefer not to use decorators, there is an alternative way for registering Handlers. +If you prefer not to use decorators, there is an alternative way for registering Handlers. This is useful, for example, if you want to keep your callback functions in a separate file. .. code-block:: python from pyrogram import Client, MessageHandler + def my_handler(client, message): print(message) + app = Client("my_account") app.add_handler(MessageHandler(my_handler)) @@ -46,10 +49,11 @@ This is useful, for example, if you want to keep your callback functions in a se app.start() app.idle() + Using Filters ------------- -For a finer grained control over what kind of messages will be allowed or not, you can use +For a finer grained control over what kind of messages will be allowed or not in your callback functions, you can use :class:`Filters `. The next example will show you how to handler only messages containing an :obj:`Audio ` object: @@ -57,6 +61,7 @@ containing an :obj:`Audio ` object: from pyrogram import Filters + @app.on_message(Filters.audio) def my_handler(client, message): print(message) @@ -67,18 +72,20 @@ or, without decorators: from pyrogram import Filters, Messagehandler + def my_handler(client, message): print(message) + app.add_handler(MessageHandler(my_handler, Filters.audio)) -Advanced Filters ----------------- +Combining Filters +----------------- Filters can also be used in a more advanced way by combining more filters together using bitwise operators: - Use ``~`` to invert a filter (behaves like the ``not`` operator). -- Use ``&`` and ``|`` to merge two filters (``and``, ``or`` operators respectively). +- Use ``&`` and ``|`` to merge two filters (behave like ``and``, ``or`` operators respectively). Here are some examples: @@ -90,7 +97,7 @@ Here are some examples: def my_handler(client, message): print(message) -- Message is a **sticker** **and** was sent in a **channel** or in a **private** chat. +- Message is a **sticker** **and** is coming from a **channel** or a **private** chat. .. code-block:: python @@ -98,10 +105,13 @@ Here are some examples: def my_handler(client, message): print(message) -Some filters can also accept parameters, like :obj:`command ` or -:obj:`regex `: +Advanced Filters +---------------- -- Message is either a /start or /help **command**. +Some filters, like :obj:`command() ` or :obj:`regex() ` +can also accept arguments: + +- Message is either a */start* or */help* **command**. .. code-block:: python @@ -115,4 +125,22 @@ Some filters can also accept parameters, like :obj:`command ` class, which exposes bot-like_ methods. The purpose of this Client class is to make it even simpler to work with the -API by abstracting the raw functions listed in the scheme. +API by abstracting the raw functions listed in the schema. The result is a much cleaner interface that allows you to: diff --git a/docs/source/start/ProjectSetup.rst b/docs/source/start/ProjectSetup.rst index ca6f388e..c61e2791 100644 --- a/docs/source/start/ProjectSetup.rst +++ b/docs/source/start/ProjectSetup.rst @@ -21,28 +21,28 @@ Configuration There are two ways to configure a Pyrogram application project, and you can choose the one that fits better for you: -- Create a new ``config.ini`` file at the root of your working directory, copy-paste the following and replace the - **api_id** and **api_hash** values with `your own <#api-keys>`_. This is the preferred method because allows you - to keep your credentials out of your code without having to deal with how to load them: +Create a new ``config.ini`` file at the root of your working directory, copy-paste the following and replace the +**api_id** and **api_hash** values with `your own <#api-keys>`_. This is the preferred method because allows you +to keep your credentials out of your code without having to deal with how to load them: - .. code-block:: ini +.. code-block:: ini - [pyrogram] - api_id = 12345 - api_hash = 0123456789abcdef0123456789abcdef + [pyrogram] + api_id = 12345 + api_hash = 0123456789abcdef0123456789abcdef -- Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash* - parameters of the Client class. This way you can have full control on how to store and load your credentials: +Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash* +parameters of the Client class. This way you can have full control on how to store and load your credentials: - .. code-block:: python +.. code-block:: python - from pyrogram import Client + from pyrogram import Client - client = Client( - session_name="example", - api_id=12345 - api_hash="0123456789abcdef0123456789abcdef" - ) + client = Client( + session_name="example", + api_id=12345 + api_hash="0123456789abcdef0123456789abcdef" + ) .. note:: The examples below assume you have created a ``config.ini`` file, thus they won't show the *api_id* and *api_hash* parameters usage. @@ -53,7 +53,7 @@ User Authorization In order to use the API, Telegram requires that Users be authorized via their phone numbers. Pyrogram automatically manages this access, all you need to do is create an instance of the :class:`Client ` class by passing to it a ```` of your choice -(e.g.: "my_account") and call the :meth:`start ` method: +(e.g.: "my_account") and call the :meth:`start() ` method: .. code-block:: python @@ -81,7 +81,9 @@ Bot Authorization ----------------- Being written entirely from the ground up, Pyrogram is also able to authorize Bots. -This means that you can use Pyrogram to execute API calls with a Bot identity. +Bots are a special kind of users which also make use of MTProto. This means that you can use Pyrogram to +execute API calls with a Bot identity. + Instead of phone numbers, Bots are authorized via their tokens which are created by BotFather_: .. code-block:: python @@ -91,6 +93,8 @@ Instead of phone numbers, Bots are authorized via their tokens which are created client = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11") client.start() +That's all, no further action is needed. The session file created will be named after the Bot user_id, which is +``123456.session`` in the example above. .. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes .. _BotFather: https://t.me/botfather \ No newline at end of file