From fa9b0332bc7303dcf5ee2a4565513b6bc0e6550c Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sat, 6 Jan 2018 12:18:15 +0100 Subject: [PATCH] Revamp docs and move wiki content here --- docs/source/errors/BadRequest.rst | 2 + docs/source/errors/Flood.rst | 2 + docs/source/errors/InternalServerError.rst | 2 + docs/source/errors/SeeOther.rst | 2 + docs/source/errors/Unauthorized.rst | 2 + docs/source/errors/UnknownError.rst | 2 + docs/source/getting_started/BasicUsage.rst | 71 +++++++++++++++++++ docs/source/getting_started/ProjectSetup.rst | 66 +++++++++++++++++ .../getting_started/QuickInstallation.rst | 37 ++++++++++ docs/source/index.rst | 52 ++++++++++---- docs/source/pyrogram/index.rst | 8 +++ docs/source/resources/ErrorHandling.rst | 61 ++++++++++++++++ docs/source/resources/TextFormatting.rst | 55 ++++++++++++++ docs/source/resources/UpdateHandling.rst | 46 ++++++++++++ 14 files changed, 396 insertions(+), 12 deletions(-) create mode 100644 docs/source/getting_started/BasicUsage.rst create mode 100644 docs/source/getting_started/ProjectSetup.rst create mode 100644 docs/source/getting_started/QuickInstallation.rst create mode 100644 docs/source/resources/ErrorHandling.rst create mode 100644 docs/source/resources/TextFormatting.rst create mode 100644 docs/source/resources/UpdateHandling.rst diff --git a/docs/source/errors/BadRequest.rst b/docs/source/errors/BadRequest.rst index f10b70dc..7ea6cb4b 100644 --- a/docs/source/errors/BadRequest.rst +++ b/docs/source/errors/BadRequest.rst @@ -1,6 +1,8 @@ Bad Request =========== +.. module:: pyrogram.api.errors.BadRequest + .. automodule:: pyrogram.api.errors.exceptions.bad_request_400 :members: :show-inheritance: diff --git a/docs/source/errors/Flood.rst b/docs/source/errors/Flood.rst index 89b3b713..a83a216c 100644 --- a/docs/source/errors/Flood.rst +++ b/docs/source/errors/Flood.rst @@ -1,6 +1,8 @@ Flood ===== +.. module:: pyrogram.api.errors.Flood + .. automodule:: pyrogram.api.errors.exceptions.flood_420 :members: :show-inheritance: diff --git a/docs/source/errors/InternalServerError.rst b/docs/source/errors/InternalServerError.rst index 5fdb1d48..310c5cfc 100644 --- a/docs/source/errors/InternalServerError.rst +++ b/docs/source/errors/InternalServerError.rst @@ -1,6 +1,8 @@ Internal Server Error ===================== +.. module:: pyrogram.api.errors.InternalServerError + .. automodule:: pyrogram.api.errors.exceptions.internal_server_error_500 :members: :show-inheritance: diff --git a/docs/source/errors/SeeOther.rst b/docs/source/errors/SeeOther.rst index 6d2875c3..49411379 100644 --- a/docs/source/errors/SeeOther.rst +++ b/docs/source/errors/SeeOther.rst @@ -1,6 +1,8 @@ See Other ========= +.. module:: pyrogram.api.errors.SeeOther + .. automodule:: pyrogram.api.errors.exceptions.see_other_303 :members: :show-inheritance: diff --git a/docs/source/errors/Unauthorized.rst b/docs/source/errors/Unauthorized.rst index ef73e75b..b3926132 100644 --- a/docs/source/errors/Unauthorized.rst +++ b/docs/source/errors/Unauthorized.rst @@ -1,6 +1,8 @@ Unauthorized ============ +.. module:: pyrogram.api.errors.Unauthorized + .. automodule:: pyrogram.api.errors.exceptions.unauthorized_401 :members: :show-inheritance: diff --git a/docs/source/errors/UnknownError.rst b/docs/source/errors/UnknownError.rst index e617777d..18b4a4e8 100644 --- a/docs/source/errors/UnknownError.rst +++ b/docs/source/errors/UnknownError.rst @@ -1,6 +1,8 @@ Unknown Error ============= +.. module:: pyrogram.api.errors.UnknownError + .. autoclass:: pyrogram.api.errors.error.UnknownError :members: :show-inheritance: diff --git a/docs/source/getting_started/BasicUsage.rst b/docs/source/getting_started/BasicUsage.rst new file mode 100644 index 00000000..33f23a8f --- /dev/null +++ b/docs/source/getting_started/BasicUsage.rst @@ -0,0 +1,71 @@ +Basic Usage +=========== + +.. note:: + + All the snippets below assume you have successfully created and started a :obj:`pyrogram.Client` instance. + You also must be authorized, that is, a valid *.session file does exist in your working directory. + +Simple API Access +----------------- + +The easiest way to interact with the API is via the :obj:`pyrogram.Client` class which exposes bot-like_ methods. +The purpose of this Client class is to make it even simpler to work with Telegram's API by abstracting the +raw functions listed in the API scheme. + +The result is a much cleaner interface that allows you to: + +- Get information about the authorized user: + + .. code-block:: python + + print(client.get_me()) + +- Send a message to yourself (Saved Messages): + + .. code-block:: python + + client.send_message( + chat_id="me", + text="Hi there! I'm using Pyrogram" + ) + +.. seealso:: For a complete list of the available methods have a look at the :obj:`pyrogram.Client` class. + +Using Raw Functions +------------------- + +If you want **complete**, low-level access to the Telegram API you have to use the raw +:obj:`functions ` and :obj:`types ` exposed by the ``pyrogram.api`` +package and call any Telegram API method you wish using the :obj:`send ` method provided by +the Client class. + +Here some examples: + +- Update first name, last name and bio: + + .. code-block:: python + + from pyrogram.api import functions + + client.send( + functions.account.UpdateProfile( + first_name="Dan", last_name="Tès", + about="Bio written from Pyrogram" + ) + ) + +- Share your Last Seen time only with your contacts: + + .. code-block:: python + + from pyrogram.api import functions, types + + client.send( + functions.account.SetPrivacy( + key=types.InputPrivacyKeyStatusTimestamp(), + rules=[types.InputPrivacyValueAllowContacts()] + ) + ) + +.. _bot-like: https://core.telegram.org/bots/api#available-methods \ No newline at end of file diff --git a/docs/source/getting_started/ProjectSetup.rst b/docs/source/getting_started/ProjectSetup.rst new file mode 100644 index 00000000..77f2f834 --- /dev/null +++ b/docs/source/getting_started/ProjectSetup.rst @@ -0,0 +1,66 @@ +Project Setup +============= + +This section provides all the information you need to setup your project with Pyrogram. +There are a few steps you have to follow before you can actually use the library to make API calls. + +API Keys +-------- + +The very first step requires you to obtain a valid Telegram API key. +If you already have one you can skip this, otherwise: + +#. Visit https://my.telegram.org/apps and log in with your Telegram Account. +#. Fill out the form to register a new Telegram application. +#. Done. The Telegram API key consists of two parts: the **App api_id** and the **App api_hash** + +.. important:: This key should be kept secret. + +Configuration +------------- + +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>`_: + +.. code-block:: ini + + [pyrogram] + api_id = 12345 + api_hash = 0123456789abcdef0123456789abcdef + +Authorization +------------- + +Telegram requires that users be authorized in order to use the API. +Pyrogram automatically manages this access, all you need to do is create an instance of +the :class:`pyrogram.Client` class by passing to it a ```` of your choice +and call the :obj:`start ` method: + +.. code-block:: python + + from pyrogram import Client + + client = Client(session_name="example") + client.start() + +This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) +and the **phone code** you will receive: + +.. code:: + + Enter phone number: +39********** + Is "+39**********" correct? (y/n): y + Enter phone code: 32768 + +After successfully authorizing yourself, a new file called ``example.session`` will be created allowing +Pyrogram executing API calls with your identity. + +.. important:: Your *.session file(s) must be kept secret. + +.. note:: + + The authorization process is executed only once. + However, the code above is always required; as soon as a valid session file exists, + Pyrogram will use that and won't ask you to enter your phone number again when you restart your script. + +.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes \ No newline at end of file diff --git a/docs/source/getting_started/QuickInstallation.rst b/docs/source/getting_started/QuickInstallation.rst new file mode 100644 index 00000000..4d2912b8 --- /dev/null +++ b/docs/source/getting_started/QuickInstallation.rst @@ -0,0 +1,37 @@ +Quick Installation +================== + +The most straightforward and recommended way to install or upgrade Pyrogram is by using **pip**: + +.. code-block:: bash + + $ pip install --upgrade pyrogram + +Bleeding Edge +------------- + +If you want the latest development version of the library, you can either install it automatically with: + +.. code-block:: bash + + $ pip install git+https://github.com/pyrogram/pyrogram.git + +or manually, using: + +.. code-block:: bash + + $ git clone https://github.com/pyrogram/pyrogram.git + $ cd pyrogram + $ python setup.py install + +Verifying +--------- + +To verify that Pyrogram is correctly installed, open a Python shell and try to import it. +If no errors show up you are good to go. + +.. code-block:: bash + + >>> import pyrogram + >>> pyrogram.__version__ + '0.3.2' diff --git a/docs/source/index.rst b/docs/source/index.rst index 80fb6a7d..a45efa74 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,26 +13,54 @@ Welcome to Pyrogram Telegram MTProto API Client Library for Python

-Welcome to Pyrogram's documentation. Here you can find a detailed description of the Pyrogram API. -You will notice that methods are named after the well established `Telegram Bot API`_ and that most of them -accept the same parameters as well. +Preview +------- -.. note:: - This document is intended to be used as an API reference documentation. - For more information on how to install and setup the library, please refer to the Wiki_. +.. code-block:: python + + from pyrogram import Client + + client = Client("example") + client.start() + + client.send_message("me", "Hi there! I'm using Pyrogram") + client.send_photo("me", "/home/dan/pic.jpg", "Nice photo!") + + client.stop() + +About +----- + +Welcome to the Pyrogram's documentation! Here you can find resources for learning how to use the library. +Contents are organized by topic and are accessible from the sidebar. + +To get started, press Next. .. toctree:: + :hidden: + :caption: Getting Started + + getting_started/QuickInstallation + getting_started/ProjectSetup + getting_started/BasicUsage + +.. toctree:: + :hidden: + :caption: Resources + + resources/TextFormatting + resources/UpdateHandling + resources/ErrorHandling + +.. toctree:: + :hidden: :caption: Main Package pyrogram/index .. toctree:: - :caption: Telegram API - Layer 74 + :hidden: + :caption: Telegram API functions/index types/index - - -.. _Wiki: https://github.com/pyrogram/pyrogram/wiki - -.. _`Telegram Bot API`: https://core.telegram.org/bots/api#available-methods \ No newline at end of file diff --git a/docs/source/pyrogram/index.rst b/docs/source/pyrogram/index.rst index fb03072d..3ea4ae8f 100644 --- a/docs/source/pyrogram/index.rst +++ b/docs/source/pyrogram/index.rst @@ -1,7 +1,15 @@ Pyrogram ======== +In this section you can find a detailed description of the Pyrogram API. + +:obj:`pyrogram.Client` is the main class you have to deal with. +You will notice that methods are named after the well established `Telegram Bot API`_ and that most of them accept +the same parameters as well, thus offering a familiar look to Bot developers. + .. toctree:: Client ChatAction Error + +.. _Telegram Bot API: https://core.telegram.org/bots/api#available-methods diff --git a/docs/source/resources/ErrorHandling.rst b/docs/source/resources/ErrorHandling.rst new file mode 100644 index 00000000..74a9091a --- /dev/null +++ b/docs/source/resources/ErrorHandling.rst @@ -0,0 +1,61 @@ +Error Handling +============== + +Errors are inevitable when working with the API, and they must be correctly handled by +the use of ``try..except`` blocks. + +There are many errors that Telegram could return, but they all fall in one of these five exception categories +(which are in turn children of the :obj:`pyrogram.Error` superclass) + +- :obj:`303 See Other ` +- :obj:`400 Bad Request ` +- :obj:`401 Unauthorized ` +- :obj:`420 Flood ` +- :obj:`500 Internal Server Error ` + +As stated above, there are really many (too many) errors, and in case Pyrogram does not know anything yet about a +specific one, it raises a special :obj:`520 Unknown Error ` exception and logs it +in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors; in later versions of Pyrogram +some kind of automatic error reporting module might be implemented. + +Examples +-------- + +.. code-block:: python + + from pyrogram.api.errors import ( + BadRequest, Flood, InternalServerError, + SeeOther, Unauthorized, UnknownError + ) + + try: + # Something + pass + except BadRequest: + pass + except Flood: + pass + except InternalServerError: + pass + except SeeOther: + pass + except Unauthorized: + pass + except UnknownError: + pass + +Exceptions may also contain some informative values which can be useful. +e.g. :obj:`FloodWait ` holds the amount of seconds you have to wait before you +can try again. The value is always stored in the ``x`` field of the returned exception object: + +.. code-block:: python + + from pyrogram.api.errors import FloodWait + + try: + # something + pass + except FloodWait as e: + print(e.x) + +**TODO: Better explanation on how to deal with exceptions** \ No newline at end of file diff --git a/docs/source/resources/TextFormatting.rst b/docs/source/resources/TextFormatting.rst new file mode 100644 index 00000000..07651d9c --- /dev/null +++ b/docs/source/resources/TextFormatting.rst @@ -0,0 +1,55 @@ +Text Formatting +=============== + +Pyrogram, just like `Telegram Bot API`_, supports basic Markdown formatting for messages; +it uses the same syntax as Telegram Desktop's and is enabled by default. +Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline URLs and inline mentions of users**. + +Here is the complete syntax you can use when sending or editing messages: + +.. code:: + + **bold text** + + __italic text__ + + [inline URL](http://www.example.com/) + + [inline mention of a user](tg://user?id=123456789) + + `inline fixed-width code` + + ```block_language + pre-formatted fixed-width code block + ``` + +Code Snippets +------------- + +- Inline entities (bold, italic, ...): + + .. code-block:: python + + client.send_message( + chat_id="me", + text="**bold**, __italic__, [mention](tg://user?id=23122162), [url](https://pyrogram.ml), `code`" + ) + + .. note:: Mentions are only guaranteed to work if you have already contacted the user. + +- Code blocks: + + .. code-block:: python + + client.send_message( + chat_id="me", + text=( + # Code block language is optional + "``` python\n" + "for i in range(10):\n" + " print(i)\n" + "```" + ) + ) + +.. _Telegram Bot API: https://core.telegram.org/bots/api#formatting-options \ No newline at end of file diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst new file mode 100644 index 00000000..a30198bd --- /dev/null +++ b/docs/source/resources/UpdateHandling.rst @@ -0,0 +1,46 @@ +Update Handling +=============== + +Updates are events that happen in your Telegram account (incoming messages, new channel posts, user name changes, ...) +and can be handled by using a callback function, that is, a function called every time an ``Update`` is received from +Telegram. + +To set an update handler simply call :obj:`set_update_handler ` +by passing the name of your defined callback function as argument *before* you start the Client. + +Here's a complete example on how to set it up: + +.. code-block:: python + + from pyrogram import Client + + + def callback(update): + print(update) + + + client = Client(session_name="example") + client.set_update_handler(callback) + + client.start() + client.idle() + +The last line, :obj:`client.idle() ` is not strictly necessary but highly recommended; +it will block your script execution until you press :obj:`CTRL`:obj:`C` and automatically call the +:obj:`stop ` method which stops the Client and gently close the underlying connection. + +Examples +-------- + +- Echo: + + .. code-block:: python + + from pyrogram.api import types + + def callback(update): + if isinstance(update, types.UpdateShortMessage) and not update.out: + client.send_message(update.user_id, update.message) + + This checks if the update type is :obj:`types.UpdateShortMessage ` and that the + update is not generated by yourself (i.e., the message is not outgoing), then sends back the same message. \ No newline at end of file