From 0c14a0aa3c511abcb445a1953c06d2a9c52ec041 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Mon, 25 Jun 2018 18:06:00 +0200 Subject: [PATCH 01/16] Add CustomizeSessions page --- docs/source/index.rst | 1 + docs/source/resources/CustomizeSessions.rst | 68 +++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 docs/source/resources/CustomizeSessions.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index c52e239b..cffa851d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -89,6 +89,7 @@ To get started, press the Next button. resources/AutoAuthorization resources/TextFormatting resources/BotsInteraction + resources/CustomizeSessions resources/ErrorHandling .. toctree:: diff --git a/docs/source/resources/CustomizeSessions.rst b/docs/source/resources/CustomizeSessions.rst new file mode 100644 index 00000000..4564eaf0 --- /dev/null +++ b/docs/source/resources/CustomizeSessions.rst @@ -0,0 +1,68 @@ +Customize Sessions +================== + +As you may probably know, Telegram allows Users (and Bots) having more than one session (authorizations) registered +in the system at the same time. + +Briefly explaining, sessions are simply new logins in your account and can be reviewed in the settings of an official +app or by invoking `GetAuthorizations <../functions/account/GetAuthorizations>`_ with Pyrogram. + + +.. figure:: https://i.imgur.com/lzGPCdZ.png + :width: 70% + :align: center + + A Pyrogram session running on Linux, Python 3.6. + +That's how a session looks like on the Android app, showing the three main pieces of information. + +- ``app_version``: **Pyrogram 🔥 0.7.5** +- ``device_model``: **CPython 3.6.5** +- ``system_version``: **Linux 4.15.0-23-generic** + +Set Custom Values +----------------- + +To set custom values, you can either make use of the ``config.ini`` file, this way: + +.. code-block:: ini + + [pyrogram] + app_version = 1.2.3 + device_model = PC + system_version = Linux + +Or, pass the arguments directly in the Client's constructor. + +.. code-block:: python + + app = Client( + "my_account", + app_version="1.2.3", + device_model="PC", + system_version="Linux" + ) + +Set Custom Languages +-------------------- + +These are two extra parameters you can change: ``system_lang_code`` (OS language) and ``lang_code`` (Client language). +They exist to tell Telegram in which language it should speak to you (terms of service, service messages, ...) and are +usually both set to the same value, in `ISO 639-1 `_ standard. +Pyrogram uses "en" (English) for both by default. + +With the following code we make Telegram know we want it to speak in Italian (it): + +.. code-block:: ini + + [pyrogram] + system_lang_code = it + lang_code = it + +.. code-block:: python + + app = Client( + "my_account", + system_lang_code="it", + lang_code="it", + ) \ No newline at end of file From 9d31673f2c4a3ba5bc82c4672d11f8ee8a94d3dc Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Mon, 25 Jun 2018 18:06:15 +0200 Subject: [PATCH 02/16] Make example more readable --- docs/source/resources/BotsInteraction.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/resources/BotsInteraction.rst b/docs/source/resources/BotsInteraction.rst index cbbe23c1..de7925a2 100644 --- a/docs/source/resources/BotsInteraction.rst +++ b/docs/source/resources/BotsInteraction.rst @@ -28,8 +28,12 @@ Inline Bots .. code-block:: python - # Send the first result (bot_results.results[0]) to your own chat (Saved Messages) - app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id) + # Send the first result to your own chat + app.send_inline_bot_result( + "me", + bot_results.query_id, + bot_results.results[0].id + ) .. figure:: https://i.imgur.com/wwxr7B7.png :width: 90% From 1510bc12a8eaf47fb1dbdf97eafff57917f71737 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Mon, 25 Jun 2018 18:27:30 +0200 Subject: [PATCH 03/16] Cleanup docs --- docs/source/resources/UpdateHandling.rst | 1 + docs/source/start/Setup.rst | 2 +- docs/source/start/Usage.rst | 6 ++---- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst index ffa01be9..0aa6457f 100644 --- a/docs/source/resources/UpdateHandling.rst +++ b/docs/source/resources/UpdateHandling.rst @@ -9,6 +9,7 @@ from, one for each kind of update: - `DeletedMessagesHandler <../pyrogram/handlers/DeletedMessagesHandler.html>`_ - `CallbackQueryHandler <../pyrogram/handlers/CallbackQueryHandler.html>`_ - `RawUpdateHandler <../pyrogram/handlers/RawUpdateHandler.html>`_ +- `DisconnectHandler <../pyrogram/handlers/DisconnectHandler.html>`_ Registering an Handler ---------------------- diff --git a/docs/source/start/Setup.rst b/docs/source/start/Setup.rst index 8b7c0597..417d62d8 100644 --- a/docs/source/start/Setup.rst +++ b/docs/source/start/Setup.rst @@ -54,7 +54,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 ``session_name`` of your choice -(e.g.: "my_account") and call the :meth:`start() ` method: +(e.g.: "my_account") and call the :meth:`run() ` method: .. code-block:: python diff --git a/docs/source/start/Usage.rst b/docs/source/start/Usage.rst index d9cb8fe1..531e997f 100644 --- a/docs/source/start/Usage.rst +++ b/docs/source/start/Usage.rst @@ -10,10 +10,6 @@ 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`_. -.. hint:: If you can't find an high-level method you want to use, chances are it's not implemented yet. - In this case, you must use the `Raw Functions`_. Meanwhile, feel free to join our Community_ if you get stuck - or want to propose a new method! - Examples (more on `GitHub `_): - Get information about the authorized user: @@ -45,8 +41,10 @@ you have to use the raw :mod:`functions ` and :mod:`type method provided by the Client class. .. 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. + If you think a raw function should be wrapped and added as a high-level method, feel free to ask in our Community_! Examples (more on `GitHub `_): From 1cc66c898d3b47601e2e3b1ad4b840afffe1b121 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Tue, 26 Jun 2018 14:05:45 +0200 Subject: [PATCH 04/16] Fix request_callback_answer call with wrong kwarg --- pyrogram/client/types/message.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyrogram/client/types/message.py b/pyrogram/client/types/message.py index ce6d158f..d80c657d 100644 --- a/pyrogram/client/types/message.py +++ b/pyrogram/client/types/message.py @@ -561,7 +561,7 @@ class Message(Object): return self._client.request_callback_answer( chat_id=self.chat.id, message_id=self.message_id, - data=button.callback_data + callback_data=button.callback_data ) elif button.url: return button.url From fc1c653c05717e55cd2a237b0c40532d309293b3 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Tue, 26 Jun 2018 16:16:10 +0200 Subject: [PATCH 05/16] Add TimeoutError on possible raises of Message.click() --- pyrogram/client/types/message.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pyrogram/client/types/message.py b/pyrogram/client/types/message.py index d80c657d..b969865c 100644 --- a/pyrogram/client/types/message.py +++ b/pyrogram/client/types/message.py @@ -516,7 +516,8 @@ class Message(Object): Raises: :class:`Error ` - ``ValueError``: If the provided index or position is out of range or the button label was not found. + ``ValueError``: If the provided index or position is out of range or the button label was not found + ``TimeoutError``: If, after clicking an inline button, the bot fails to answer within 10 seconds """ if isinstance(self.reply_markup, ReplyKeyboardMarkup): if quote is None: From ef69dbd396934e669bc0a73e54aed98e29a63fce Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 00:02:54 +0200 Subject: [PATCH 06/16] Use shields.io badges --- docs/source/index.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index cffa851d..fb7022ab 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,11 +26,11 @@ Welcome to Pyrogram

- Scheme Layer 75 + - TgCrypto

@@ -56,7 +56,7 @@ button at the end of each page. But first, here's a brief overview of what is th About ----- -Pyrogram is a brand new Telegram_ Client Library written from the ground up in Python and C. It can be used for building +**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 @@ -65,8 +65,8 @@ 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 76 running on MTProto 2.0. -- **Documented**: Pyrogram API methods are documented and resemble the Telegram Bot API. +- **Updated** to the latest Telegram API version, currently Layer 81 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. To get started, press the Next button. From 36519cb3ca9f373a2d5cde6ac297bbae2e0bbaa9 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 00:11:53 +0200 Subject: [PATCH 07/16] Sort Resources --- 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 fb7022ab..4143cfee 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -84,12 +84,12 @@ To get started, press the Next button. :caption: Resources resources/UpdateHandling - resources/SOCKS5Proxy - resources/TgCrypto resources/AutoAuthorization - resources/TextFormatting - resources/BotsInteraction resources/CustomizeSessions + resources/TgCrypto + resources/TextFormatting + resources/SOCKS5Proxy + resources/BotsInteraction resources/ErrorHandling .. toctree:: From 27020ca1bb594492ac4edb9b6390be0b045cc355 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 00:12:09 +0200 Subject: [PATCH 08/16] Rename Raw Functions section --- docs/source/start/Usage.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/start/Usage.rst b/docs/source/start/Usage.rst index 531e997f..6c20decd 100644 --- a/docs/source/start/Usage.rst +++ b/docs/source/start/Usage.rst @@ -30,10 +30,8 @@ Examples (more on `GitHub ` and :mod:`types ` exposed by the From ecaba45523170f4d4de4c8c386a24d3fa95a98f8 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 00:42:32 +0200 Subject: [PATCH 09/16] Keep only lang_code --- pyrogram/client/client.py | 8 +------- pyrogram/session/session.py | 2 +- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py index 2cb153db..f21d2ef2 100644 --- a/pyrogram/client/client.py +++ b/pyrogram/client/client.py @@ -86,10 +86,6 @@ class Client(Methods, BaseClient): Operating System version. Defaults to *platform.system() + " " + platform.release()* This is an alternative way to set it if you don't want to use the *config.ini* file. - system_lang_code (``str``, *optional*): - Code of the language used on the system, in ISO 639-1 standard. Defaults to "en". - This is an alternative way to set it if you don't want to use the *config.ini* file. - lang_code (``str``, *optional*): Code of the language used on the client, in ISO 639-1 standard. Defaults to "en". This is an alternative way to set it if you don't want to use the *config.ini* file. @@ -149,7 +145,6 @@ class Client(Methods, BaseClient): app_version: str = None, device_model: str = None, system_version: str = None, - system_lang_code: str = None, lang_code: str = None, proxy: dict = None, test_mode: bool = False, @@ -170,7 +165,6 @@ class Client(Methods, BaseClient): self.app_version = app_version self.device_model = device_model self.system_version = system_version - self.system_lang_code = system_lang_code self.lang_code = lang_code # TODO: Make code consistent, use underscore for private/protected fields self._proxy = proxy @@ -889,7 +883,7 @@ class Client(Methods, BaseClient): "More info: https://docs.pyrogram.ml/start/ProjectSetup#configuration" ) - for option in {"app_version", "device_model", "system_version", "system_lang_code", "lang_code"}: + for option in {"app_version", "device_model", "system_version", "lang_code"}: if getattr(self, option): pass else: diff --git a/pyrogram/session/session.py b/pyrogram/session/session.py index 7bafd71f..ef7b565c 100644 --- a/pyrogram/session/session.py +++ b/pyrogram/session/session.py @@ -145,7 +145,7 @@ class Session: app_version=self.client.app_version, device_model=self.client.device_model, system_version=self.client.system_version, - system_lang_code=self.client.system_lang_code, + system_lang_code=self.client.lang_code, lang_code=self.client.lang_code, lang_pack="", query=functions.help.GetConfig(), From 7ed9cd6759dd18cabf037fe5014f669c81a19e9a Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 14:42:04 +0200 Subject: [PATCH 10/16] Add "Login successful" message upon login --- pyrogram/client/client.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py index f21d2ef2..20a3e50c 100644 --- a/pyrogram/client/client.py +++ b/pyrogram/client/client.py @@ -585,6 +585,8 @@ class Client(Methods, BaseClient): self.password = None self.user_id = r.user.id + print("Login successful") + def fetch_peers(self, entities: list): for entity in entities: if isinstance(entity, types.User): From c0ad63f72cec666f98c0c3f52dd0d31bef2a6448 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 14:45:56 +0200 Subject: [PATCH 11/16] Update CustomizeSessions page --- docs/source/resources/CustomizeSessions.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/source/resources/CustomizeSessions.rst b/docs/source/resources/CustomizeSessions.rst index 4564eaf0..498003d4 100644 --- a/docs/source/resources/CustomizeSessions.rst +++ b/docs/source/resources/CustomizeSessions.rst @@ -4,8 +4,9 @@ Customize Sessions As you may probably know, Telegram allows Users (and Bots) having more than one session (authorizations) registered in the system at the same time. -Briefly explaining, sessions are simply new logins in your account and can be reviewed in the settings of an official -app or by invoking `GetAuthorizations <../functions/account/GetAuthorizations>`_ with Pyrogram. +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 <../functions/account/GetAuthorizations>`_ with Pyrogram) and store some useful +information about the client who generated them. .. figure:: https://i.imgur.com/lzGPCdZ.png @@ -46,23 +47,20 @@ Or, pass the arguments directly in the Client's constructor. Set Custom Languages -------------------- -These are two extra parameters you can change: ``system_lang_code`` (OS language) and ``lang_code`` (Client language). -They exist to tell Telegram in which language it should speak to you (terms of service, service messages, ...) and are -usually both set to the same value, in `ISO 639-1 `_ standard. -Pyrogram uses "en" (English) for both by default. +To tell Telegram in which language should speak to you (terms of service, bots, service messages, ...) you can +set ``lang_code`` in `ISO 639-1 `_ standard (defaults to "en", +English). With the following code we make Telegram know we want it to speak in Italian (it): .. code-block:: ini [pyrogram] - system_lang_code = it lang_code = it .. code-block:: python app = Client( "my_account", - system_lang_code="it", lang_code="it", ) \ No newline at end of file From c1cd8ec12dee39b8153d6f670518090b4dda3c53 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 14:52:13 +0200 Subject: [PATCH 12/16] Tiny fix --- 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 4143cfee..051b5af8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,7 +26,7 @@ Welcome to Pyrogram

- Scheme Layer From ec667035cd53c407cdb912f320af01019dfc57bf Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 15:27:15 +0200 Subject: [PATCH 13/16] Sort docs entries alphabetically --- compiler/docs/compiler.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/compiler/docs/compiler.py b/compiler/docs/compiler.py index 494697de..73b5a578 100644 --- a/compiler/docs/compiler.py +++ b/compiler/docs/compiler.py @@ -77,7 +77,8 @@ def generate(source_path, base): build(source_path) - for k, v in all_entities.items(): + for k, v in sorted(all_entities.items()): + v = sorted(v) entities = [] for i in v: From a65376a52be0c26c2e5cab6bea5589bbd5d754be Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 15:46:38 +0200 Subject: [PATCH 14/16] Fix broken link --- docs/source/resources/CustomizeSessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/resources/CustomizeSessions.rst b/docs/source/resources/CustomizeSessions.rst index 498003d4..e98792b7 100644 --- a/docs/source/resources/CustomizeSessions.rst +++ b/docs/source/resources/CustomizeSessions.rst @@ -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 <../functions/account/GetAuthorizations>`_ with Pyrogram) and store some useful +app (or by invoking `GetAuthorizations <../functions/account/GetAuthorizations.html>`_ with Pyrogram) and store some useful information about the client who generated them. From 37aae4382e67c45b27eec33250d8934999ec2465 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Wed, 27 Jun 2018 16:38:41 +0200 Subject: [PATCH 15/16] Update to v0.7.5 --- pyrogram/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyrogram/__init__.py b/pyrogram/__init__.py index daddb08f..96fb4a76 100644 --- a/pyrogram/__init__.py +++ b/pyrogram/__init__.py @@ -23,7 +23,7 @@ __copyright__ = "Copyright (C) 2017-2018 Dan Tès Date: Wed, 27 Jun 2018 16:53:18 +0200 Subject: [PATCH 16/16] Add missing method to docs --- docs/source/pyrogram/Client.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/pyrogram/Client.rst b/docs/source/pyrogram/Client.rst index 0448c3cb..0000b35f 100644 --- a/docs/source/pyrogram/Client.rst +++ b/docs/source/pyrogram/Client.rst @@ -62,6 +62,7 @@ Client get_inline_bot_results send_inline_bot_result answer_callback_query + request_callback_answer get_users get_chat get_messages