mir/pyrogram
2
0
Fork 0
mirror of https://github.com/pyrogram/pyrogram synced 2025-08-31 22:35:36 +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
Download Patch File Download Diff File Expand all files Collapse all files

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