From 518220431ecf25ee987bee30f5bff78aa7045510 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sat, 18 May 2019 01:45:01 +0200 Subject: [PATCH] Docs revamp. Part 5 --- README.md | 1 + docs/source/index.rst | 33 ++++------- docs/source/intro/auth.rst | 4 +- docs/source/intro/install.rst | 4 +- docs/source/intro/start.rst | 3 +- docs/source/start/errors.rst | 33 ++++++++++- docs/source/start/invoking.rst | 2 +- docs/source/start/updates.rst | 12 ++-- docs/source/topics/faq.rst | 79 +++++++++++++++++++------ docs/source/topics/glossary.rst | 23 ++++++- docs/source/topics/session-settings.rst | 10 ++-- pyrogram/__init__.py | 4 +- pyrogram/client/client.py | 2 +- pyrogram/client/ext/base_client.py | 2 +- 14 files changed, 144 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 4d202b4f..6e12bce0 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ ground up in Python and C. It enables you to easily create custom apps for both - **Documented**: Pyrogram API methods, types and public interfaces are well documented. - **Type-hinted**: Exposed Pyrogram types and method parameters are all type-hinted. - **Updated**, to make use of the latest Telegram API version and features. +- **Bot API-like**: Similar to the Bot API in its simplicity, but much more powerful and detailed. - **Pluggable**: The Smart Plugin system allows to write components with minimal boilerplate code. - **Comprehensive**: Execute any advanced action an official client is able to do, and even more. diff --git a/docs/source/index.rst b/docs/source/index.rst index d061b677..a68c81d9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,29 +14,15 @@ Welcome to Pyrogram
- GitHub + Source Code - • - - Community - - • Releases • - - PyPI - -
- - Schema Layer - - - TgCrypto Version + + Community

@@ -59,7 +45,7 @@ C. It enables you to easily create custom apps for both user and bot identities `MTProto API`_. .. _Telegram: https://telegram.org -.. _MTProto API: https://core.telegram.org/api#telegram-api +.. _MTProto API: topics/faq#what-can-mtproto-do-more-than-the-bot-api How the Documentation is Organized ---------------------------------- @@ -68,11 +54,11 @@ Contents are organized into self-contained topics and can be all accessed from t order using the Next button at the end of each page. Here below you can, instead, find a list of the most relevant pages for a quick access. -Getting Started -^^^^^^^^^^^^^^^ +First Steps +^^^^^^^^^^^ -- `Quick Start`_ - Overview to get you started as fast as possible. -- `Calling Methods`_ - How to use Pyrogram's API. +- `Quick Start`_ - Overview to get you started quickly. +- `Calling Methods`_ - How to call Pyrogram's methods. - `Handling Updates`_ - How to handle Telegram updates. - `Error Handling`_ - How to handle API errors correctly. @@ -83,7 +69,8 @@ Getting Started API Reference ^^^^^^^^^^^^^ -- `Client Class`_ - Details about the Client class. + +- `Client Class`_ - Reference details about the Client class. - `Available Methods`_ - A list of available high-level methods. - `Available Types`_ - A list of available high-level types. - `Bound Methods`_ - A list of convenient bound methods. diff --git a/docs/source/intro/auth.rst b/docs/source/intro/auth.rst index 846a19a1..483d1202 100644 --- a/docs/source/intro/auth.rst +++ b/docs/source/intro/auth.rst @@ -2,7 +2,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 -API calls. This section provides all the information you need in order to authorize yourself as user or a bot. +API calls. This section provides all the information you need in order to authorize yourself as user or bot. User Authorization ------------------ @@ -51,7 +51,7 @@ the `Bot Father`_. Bot tokens replace the users' phone numbers only — you stil 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 -after the session name, which will be ``pyrogrambot.session`` for the example below. +after the session name, which will be ``my_bot.session`` for the example below. .. code-block:: python diff --git a/docs/source/intro/install.rst b/docs/source/intro/install.rst index c4df60d4..f26fc37f 100644 --- a/docs/source/intro/install.rst +++ b/docs/source/intro/install.rst @@ -55,7 +55,7 @@ Use this command to install (note "asyncio.zip" in the link): $ pip3 install -U https://github.com/pyrogram/pyrogram/archive/asyncio.zip -Pyrogram API remains the same and features are kept up to date from the non-async, default develop branch, but you +Pyrogram's API remains the same and features are kept up to date from the non-async, default develop branch, but you are obviously required Python asyncio knowledge in order to take full advantage of it. @@ -87,7 +87,7 @@ If no error shows up you are good to go. >>> import pyrogram >>> pyrogram.__version__ - '0.12.0' + '0.13.0' .. _TgCrypto: ../topics/tgcrypto .. _`Github repo`: http://github.com/pyrogram/pyrogram diff --git a/docs/source/intro/start.rst b/docs/source/intro/start.rst index c7bfc74a..1aa7989e 100644 --- a/docs/source/intro/start.rst +++ b/docs/source/intro/start.rst @@ -1,7 +1,8 @@ Quick Start =========== -The next few steps serve as a quick start for all new Pyrogrammers that want to get something done as fast as possible! +The next few steps serve as a quick start for all new Pyrogrammers that want to get something done as fast as possible. +Let's go! Get Pyrogram Real Fast ---------------------- diff --git a/docs/source/start/errors.rst b/docs/source/start/errors.rst index 1f4f5a2e..cf329947 100644 --- a/docs/source/start/errors.rst +++ b/docs/source/start/errors.rst @@ -11,8 +11,9 @@ to control the behaviour of your application. Pyrogram errors all live inside th RPCError -------- -The father of all errors is named ``RPCError``. This error exists in form of a Python exception and is able to catch all -Telegram API related errors. +The father of all errors is named ``RPCError``. This error exists in form of a Python exception which is directly +subclass-ed from Python's main ``Exception`` and is able to catch all Telegram API related errors. This error is raised +every time a method call against Telegram's API was unsuccessful. .. code-block:: python @@ -27,7 +28,7 @@ Error Categories ---------------- The ``RPCError`` packs together all the possible errors Telegram could raise, but to make things tidier, Pyrogram -provides categories of errors, which are named after the common HTTP errors: +provides categories of errors, which are named after the common HTTP errors and subclass-ed from the RPCError: .. code-block:: python @@ -41,6 +42,32 @@ provides categories of errors, which are named after the common HTTP errors: - `420 - Flood <../api/errors#flood>`_ - `500 - InternalServerError <../api/errors#internalservererror>`_ +Single Errors +------------- + +For a fine-grained control over every single error, Pyrogram does also expose errors that deal each with a specific +issue. For example: + +.. code-block:: python + + from pyrogram.errors import FloodWait + +These errors subclass directly from the category of errors they belong to, which in turn subclass from the father +RPCError, thus building a class of error hierarchy such as this: + +- RPCError + - BadRequest + - ``MessageEmpty`` + - ``UsernameOccupied`` + - ``...`` + - InternalServerError + - ``RpcCallFail`` + - ``InterDcCallError`` + - ``...`` + - ``...`` + +.. _Errors: api/errors + Unknown Errors -------------- diff --git a/docs/source/start/invoking.rst b/docs/source/start/invoking.rst index fae19523..ef9bc373 100644 --- a/docs/source/start/invoking.rst +++ b/docs/source/start/invoking.rst @@ -36,7 +36,7 @@ Now instantiate a new Client object, "my_account" is a session name of your choi app = Client("my_account") -To actually make use of any method, the client has to be started: +To actually make use of any method, the client has to be started first: .. code-block:: python diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst index 930096a3..644cf31c 100644 --- a/docs/source/start/updates.rst +++ b/docs/source/start/updates.rst @@ -9,11 +9,11 @@ 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 changed. These updates are handled by registering one or more callback functions in your app using -`Handlers <../api/handlers>`_. +specific state that has changed. These updates are handled by registering one or more callback functions in your app +using `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 and its body executed. +function will be called back by the framework and its body executed. Registering an Handler ---------------------- @@ -63,8 +63,8 @@ above must only handle updates that are in form of a :obj:`Message `. 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 dispatching phase -begins. +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 @@ -109,4 +109,4 @@ to do so is by decorating your callback function with the :meth:`on_message()