diff --git a/docs/source/index.rst b/docs/source/index.rst index 38403c58..b9b422b0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -51,35 +51,22 @@ Welcome to Pyrogram app.start() app.idle() -About ------ - 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: **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 in Python that interact with the MTProto API as both User and Bot. +custom Telegram applications that interact with the MTProto API as both User and Bot. +Awesomeness +----------- -Features --------- - -- **Easy to setup**: Pyrogram can be easily installed using pip and requires very few lines of code to get started with. - -- **Easy to use**: Pyrogram provides idiomatic, clean and readable Python code making the Telegram API simple to use. - -- **High-level**: Pyrogram automatically handles all the low-level details of communication with Telegram servers. - -- **Updated**: Pyrogram makes use of the latest Telegram MTProto API version, currently Layer 76. - -- **Fast**: Pyrogram critical parts are boosted up by `TgCrypto`_, a high-performance Crypto Library written in pure C. - -- **Documented**: Pyrogram API methods are documented and resemble the well established Telegram Bot API, - thus offering a familiar look to Bot developers. - -- **Full API support**: Beside the simple Bot API-like methods, Pyrogram also provides an easy access to every single - Telegram MTProto API method allowing you to programmatically execute any action an official client is able to do, and more. +- ๐Ÿ“ฆ **Easy to use**: You can easily install Pyrogram using pip and start building your app right away. +- ๐Ÿš€ **High-level**: All the low-level details of communication with Telegram servers are automatically handled. +- โšก๏ธ **Fast**: Critical parts are boosted up by TgCrypto_, a high-performance Crypto Library written in pure C. +- ๐Ÿ”„ **Updated** to the latest Telegram MTProto API version, currently Layer 76. +- ๐Ÿ“– **Documented**: Pyrogram public API methods are documented and resemble the Telegram Bot API. +- ๐Ÿ”‹ **Full API**, allows to execute any advanced action an official client is able to do, and more. To get started, press the Next button. diff --git a/docs/source/pyrogram/index.rst b/docs/source/pyrogram/index.rst index 6b2bc5dd..9a86c11d 100644 --- a/docs/source/pyrogram/index.rst +++ b/docs/source/pyrogram/index.rst @@ -4,7 +4,7 @@ Pyrogram In this section you can find a detailed description of the Pyrogram package and its high-level API. :class:`Client ` is the main class. It exposes easy-to-use methods that are named -after the `Telegram Bot API`_ methods, thus offering a familiar look to Bot developers. +after the well established `Telegram Bot API`_ methods, thus offering a familiar look to Bot developers. .. toctree:: Client diff --git a/docs/source/resources/AutoAuthorization.rst b/docs/source/resources/AutoAuthorization.rst index 1e2d72f0..46f0809d 100644 --- a/docs/source/resources/AutoAuthorization.rst +++ b/docs/source/resources/AutoAuthorization.rst @@ -26,15 +26,15 @@ ask you to input the phone code manually. return code # Must be string, e.g., "12345" - client = Client( + app = Client( session_name="example", phone_number="39**********", phone_code=phone_code_callback, password="password" # (if you have one) ) - client.start() - print(client.get_me()) + app.start() + print(app.get_me()) Sign Up ------- @@ -52,7 +52,7 @@ Telegram account in case the phone number you passed is not registered yet. return code # Must be string, e.g., "12345" - client = Client( + app = Client( session_name="example", phone_number="39**********", phone_code=phone_code_callback, @@ -60,5 +60,5 @@ Telegram account in case the phone number you passed is not registered yet. last_name="" # Can be an empty string ) - client.start() - print(client.get_me()) \ No newline at end of file + app.start() + print(app.get_me()) \ No newline at end of file diff --git a/docs/source/resources/BotsInteraction.rst b/docs/source/resources/BotsInteraction.rst index 5bdba777..cbbe23c1 100644 --- a/docs/source/resources/BotsInteraction.rst +++ b/docs/source/resources/BotsInteraction.rst @@ -13,7 +13,7 @@ Inline Bots .. code-block:: python # Get bot results for "Fuzz Universe" from the inline bot @vid - bot_results = client.get_inline_bot_results("vid", "Fuzz Universe") + bot_results = app.get_inline_bot_results("vid", "Fuzz Universe") .. figure:: https://i.imgur.com/IAqLs54.png :width: 90% @@ -29,7 +29,7 @@ Inline Bots .. code-block:: python # Send the first result (bot_results.results[0]) to your own chat (Saved Messages) - client.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id) + app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id) .. figure:: https://i.imgur.com/wwxr7B7.png :width: 90% diff --git a/docs/source/resources/SOCKS5Proxy.rst b/docs/source/resources/SOCKS5Proxy.rst index f51448ec..761899e6 100644 --- a/docs/source/resources/SOCKS5Proxy.rst +++ b/docs/source/resources/SOCKS5Proxy.rst @@ -32,7 +32,7 @@ Usage from pyrogram import Client - client = Client( + app = Client( session_name="example", proxy=dict( hostname="11.22.33.44", @@ -42,7 +42,7 @@ Usage ) ) - client.start() + app.start() ... diff --git a/docs/source/resources/TextFormatting.rst b/docs/source/resources/TextFormatting.rst index b822dd5f..124d02da 100644 --- a/docs/source/resources/TextFormatting.rst +++ b/docs/source/resources/TextFormatting.rst @@ -56,7 +56,7 @@ Examples .. code-block:: python - client.send_message( + app.send_message( chat_id="me", text=( "**bold**, " @@ -71,7 +71,7 @@ Examples .. code-block:: python - client.send_message( + app.send_message( chat_id="me", text=( # Code block language is optional @@ -88,7 +88,7 @@ Examples from pyrogram import ParseMode - client.send_message( + app.send_message( chat_id="me", text=( "bold, bold, " diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst index 0e9b67d4..e2484af9 100644 --- a/docs/source/resources/UpdateHandling.rst +++ b/docs/source/resources/UpdateHandling.rst @@ -54,7 +54,7 @@ Using Filters ------------- 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 +:class:`Filters `. The next example will show you how to handle only messages containing an :obj:`Audio ` object: .. code-block:: python @@ -97,7 +97,7 @@ Here are some examples: def my_handler(client, message): print(message) -- Message is a **sticker** **and** is coming from a **channel** or a **private** chat. +- Message is a **sticker** **and** is coming from a **channel or** a **private** chat. .. code-block:: python @@ -119,7 +119,7 @@ can also accept arguments: def my_handler(client, message): print(message) -- Message is a **text** message matching the given regex pattern. +- Message is a **text** message matching the given **regex** pattern. .. code-block:: python @@ -127,7 +127,7 @@ can also accept arguments: def my_handler(client, message): print(message) -More handlers using different filters can be created as well: +More handlers using different filters can also live together: .. code-block:: python diff --git a/docs/source/start/BasicUsage.rst b/docs/source/start/BasicUsage.rst index 8a7572c1..2f376675 100644 --- a/docs/source/start/BasicUsage.rst +++ b/docs/source/start/BasicUsage.rst @@ -9,31 +9,29 @@ Basic Usage Simple API Access ----------------- -The easiest way to interact with the Telegram API is via the :class:`Client ` 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 schema. - -The result is a much cleaner interface that allows you to: +The easiest way to interact with the Telegram API is via the :class:`Client ` class, which +exposes bot-like_ methods: - Get information about the authorized user: .. code-block:: python - print(client.get_me()) + print(app.get_me()) - Send a message to yourself (Saved Messages): .. code-block:: python - client.send_message("me", "Hi there! I'm using Pyrogram") + app.send_message("me", "Hi there! I'm using Pyrogram") -- Upload a photo (with caption): +- Upload a new photo (with caption): .. code-block:: python - client.send_photo("me", "/home/dan/perla.jpg", "Cute!") + app.send_photo("me", "/home/dan/perla.jpg", "Cute!") -.. seealso:: For a complete list of the available methods have a look at the :class:`Client ` class. +.. seealso:: For a complete list of the available methods and an exhaustive description for each of them, have a look + at the :class:`Client ` class. .. _using-raw-functions: @@ -55,7 +53,7 @@ Here some examples: ... - client.send( + app.send( functions.account.UpdateProfile( first_name="Dan", last_name="Tรจs", about="Bio written from Pyrogram" @@ -70,7 +68,7 @@ Here some examples: ... - client.send( + app.send( functions.account.SetPrivacy( key=types.InputPrivacyKeyStatusTimestamp(), rules=[types.InputPrivacyValueAllowContacts()] @@ -85,13 +83,13 @@ Here some examples: ... - client.send( + app.send( functions.channels.InviteToChannel( - channel=client.resolve_peer(123456789), # ID or Username + channel=app.resolve_peer(123456789), # ID or Username users=[ # The users you want to invite - client.resolve_peer(23456789), # By ID - client.resolve_peer("username"), # By username - client.resolve_peer("393281234567"), # By phone number + app.resolve_peer(23456789), # By ID + app.resolve_peer("username"), # By username + app.resolve_peer("393281234567"), # By phone number ] ) ) diff --git a/docs/source/start/ProjectSetup.rst b/docs/source/start/ProjectSetup.rst index c61e2791..3ac16336 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" - ) + app = Client( + session_name="my_account", + 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. @@ -52,15 +52,15 @@ 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 +the :class:`Client ` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call the :meth:`start() ` method: .. code-block:: python from pyrogram import Client - client = Client("my_account") - client.start() + app = Client("my_account") + app.start() This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the **phone code** you will receive: @@ -90,11 +90,11 @@ Instead of phone numbers, Bots are authorized via their tokens which are created from pyrogram import Client - client = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11") - client.start() + app = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11") + app.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. +That's all, no further action is needed. The session file will be named after the Bot user_id, which is +``123456.session`` for 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