From d5097f0b3995b7050b0f276d1d72de55afab28a5 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 10:48:17 +0200 Subject: [PATCH 1/9] Change badge style and rename scheme to schema --- docs/source/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 6e740dd0..ee00e682 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,13 +23,13 @@ Welcome to Pyrogram Community -

+
- Scheme Layer - TgCrypto

From d576cdffb385e4bdf89cc56481ce62e5a2ba3f51 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 10:48:39 +0200 Subject: [PATCH 2/9] Fix reported schema layer --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index ee00e682..b3015201 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -64,7 +64,7 @@ Features - **Easy to use**: You can easily install Pyrogram using pip and start building your app right away. - **High-level**: The low-level details of MTProto are abstracted and automatically handled. - **Fast**: Crypto parts are boosted up by TgCrypto_, a high-performance library written in pure C. -- **Updated** to the latest Telegram API version, currently Layer 81 on top of MTProto 2.0. +- **Updated** to the latest Telegram API version, currently Layer 82 on top of MTProto 2.0. - **Documented**: The Pyrogram API is well documented and resembles the Telegram Bot API. - **Full API**, allowing to execute any advanced action an official client is able to do, and more. From 317f584a2adae713c81c4a389a9ac1270232faf7 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 11:14:10 +0200 Subject: [PATCH 3/9] Yet another badge style change --- docs/source/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index b3015201..d4883ce8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,11 +25,11 @@ Welcome to Pyrogram
- Scheme Layer - TgCrypto

From f063726d93f8ef1bafa015921e5f0baf098d7aa5 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 11:46:44 +0200 Subject: [PATCH 4/9] Update index.rst --- docs/source/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index d4883ce8..94a14228 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -49,14 +49,14 @@ Welcome to Pyrogram app.run() Welcome to Pyrogram's Documentation! Here you can find resources for learning how to use the library. -Contents are organized by topic and can be accessed from the sidebar, or by following them one by one using the Next -button at the end of each page. But first, here's a brief overview of what is this all about. +Contents are organized into self-contained topics and can be accessed from the sidebar, or by following them in order +using the Next button at the end of each page. But first, here's a brief overview of what is this all about. About ----- -**Pyrogram** is a brand new Telegram_ Client Library written from the ground up in Python and C. It can be used for building -custom Telegram applications that interact with the MTProto API as both User and Bot. +**Pyrogram** is a brand new Telegram_ Client Library written from the ground up in Python and C. It can be used for +building custom Telegram applications that interact with the MTProto API as both User and Bot. Features -------- From a3272d28d4d97a170783ce944c5a345b64725552 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 11:47:30 +0200 Subject: [PATCH 5/9] Update installation.rst --- docs/source/start/Installation.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/start/Installation.rst b/docs/source/start/Installation.rst index d3ddfe7d..41a7ccac 100644 --- a/docs/source/start/Installation.rst +++ b/docs/source/start/Installation.rst @@ -4,11 +4,12 @@ Installation Being a Python library, Pyrogram requires Python to be installed in your system. We recommend using the latest version of Python 3 and pip. -Get Python 3 from https://www.python.org/downloads/ or with your package manager and pip +Get Python 3 from https://www.python.org/downloads/ (or with your package manager) and pip by following the instructions at https://pip.pypa.io/en/latest/installing/. -.. note:: - Pyrogram supports Python 3 only, starting from version 3.4 and PyPy. +.. important:: + + Pyrogram supports **Python 3** only, starting from version 3.4. **PyPy** is supported too. Install Pyrogram ---------------- @@ -29,7 +30,7 @@ Bleeding Edge ------------- If you want the latest development version of Pyrogram, you can install it straight from the develop_ -branch using this command: +branch using this command (you might need to install **git** first): .. code-block:: bash From 3659ea82fb3ca0696f8c77f4f0145a42beec4c13 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 11:58:23 +0200 Subject: [PATCH 6/9] Small fixes to the Setup.rst page --- docs/source/start/Setup.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/source/start/Setup.rst b/docs/source/start/Setup.rst index e0cccc2c..24caa1f4 100644 --- a/docs/source/start/Setup.rst +++ b/docs/source/start/Setup.rst @@ -53,6 +53,7 @@ fits better for you: ) .. 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. @@ -74,7 +75,7 @@ the :class:`Client ` class by passing to it a ``session_name`` This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the **phone code** you will receive: -.. code:: +.. code-block:: text Enter phone number: +39********** Is "+39**********" correct? (y/n): y @@ -84,7 +85,9 @@ After successfully authorizing yourself, a new file called ``my_account.session` Pyrogram executing API calls with your identity. This file will be loaded again when you restart your app, and as long as you keep the session alive, Pyrogram won't ask you again to enter your phone number. -.. important:: Your ``*.session`` files are personal and must be kept secret. +.. important:: + + Your ``*.session`` files are personal and must be kept secret. Bot Authorization ----------------- From d03f04a560a5427976ca5d8fde5b79ce8de26dfe Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 11:59:33 +0200 Subject: [PATCH 7/9] Add more and clearer examples in the Usage.rst page --- docs/source/start/Usage.rst | 87 +++++++++++++++++++------------------ 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/docs/source/start/Usage.rst b/docs/source/start/Usage.rst index 6eac5cd1..4809df0b 100644 --- a/docs/source/start/Usage.rst +++ b/docs/source/start/Usage.rst @@ -10,25 +10,36 @@ High-level API The easiest and recommended way to interact with Telegram is via the high-level Pyrogram methods_ and types_, which are named after the `Telegram Bot API`_. -Examples (more on `GitHub `_): - -- Get information about the authorized user: +Here's a simple example: .. code-block:: python + from pyrogram import Client + + app = Client("my_account") + + app.start() + print(app.get_me()) + app.send_message("me", "Hi there! I'm using **Pyrogram**") + app.send_location("me", 51.500729, -0.124583) -- Send a message to yourself (Saved Messages): + app.stop() + +You can also use the Client instance in a context manager with the ``with`` statement: .. code-block:: python - app.send_message("me", "Hi there! I'm using Pyrogram") + from pyrogram import Client -- Upload a new photo (with caption): + app = Client("my_account") - .. code-block:: python + with app: + print(app.get_me()) + app.send_message("me", "Hi there! I'm using **Pyrogram**") + app.send_location("me", 51.500729, -0.124583) - app.send_photo("me", "/home/dan/perla.jpg", "Cute!") +More examples on `GitHub `_. Raw Functions ------------- @@ -38,7 +49,9 @@ you have to use the raw :mod:`functions ` and :mod:`type ``pyrogram.api`` package and call any Telegram API method you wish using the :meth:`send() ` method provided by the Client class. -.. hint:: Every high-level method mentioned in the section above is built on top of these raw functions. +.. hint:: + + Every high-level method mentioned in the section above 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. @@ -54,17 +67,13 @@ Examples (more on `GitHub Date: Sun, 14 Oct 2018 12:02:48 +0200 Subject: [PATCH 8/9] Add clearer details --- docs/source/start/Usage.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/start/Usage.rst b/docs/source/start/Usage.rst index 4809df0b..6c1697b9 100644 --- a/docs/source/start/Usage.rst +++ b/docs/source/start/Usage.rst @@ -26,7 +26,9 @@ Here's a simple example: app.stop() -You can also use the Client instance in a context manager with the ``with`` statement: +You can also use Pyrogram 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: .. code-block:: python From 474388d8a4d391252bfa5a26db3527c2c94fb2fa Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 14 Oct 2018 12:28:00 +0200 Subject: [PATCH 9/9] Small improvements on UpdateHandling.rst --- docs/source/resources/UpdateHandling.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst index 781a48af..12afe324 100644 --- a/docs/source/resources/UpdateHandling.rst +++ b/docs/source/resources/UpdateHandling.rst @@ -2,15 +2,15 @@ Update Handling =============== Updates are events that happen in your Telegram account (incoming messages, new channel posts, new members join, ...) -and can be handled by registering one or more callback functions in your app by using an `Handler <../pyrogram/Handlers.html>`_. +and can be handled by registering one or more callback functions in your app by using `Handlers <../pyrogram/Handlers.html>`_. To put it simply, whenever an update is received from Telegram it will be dispatched and your previously defined callback -function(s) will be called back with the update itself as argument. +function(s) matching it will be called back with the update itself as argument. Registering an Handler ---------------------- -To explain how `Handlers <../pyrogram/Handlers.html>`_ work let's have a look at the most used one, the +To explain how handlers work let's have a look at the most used one, the :obj:`MessageHandler `, which will be in charge for handling :obj:`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.