From eadda551c6f6c90a89b537c541df27903bcc24b2 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Sun, 12 May 2019 19:26:55 +0200 Subject: [PATCH] Docs revamp. Part 3 --- compiler/docs/compiler.py | 4 +- docs/source/api/client.rst | 7 + docs/source/{core => api}/decorators.rst | 0 docs/source/{core => api}/errors.rst | 4 +- docs/source/{core => api}/filters.rst | 4 +- docs/source/{core => api}/handlers.rst | 0 docs/source/{core => api}/methods.rst | 0 docs/source/{core => api}/types.rst | 0 docs/source/core/client.rst | 12 -- docs/source/index.rst | 128 +++++++++++------- docs/source/intro/start.rst | 8 +- .../error-handling.rst => start/errors.rst} | 3 +- .../{topics/usage.rst => start/invoking.rst} | 14 +- .../update-handling.rst => start/updates.rst} | 12 +- .../{auto-authorization.rst => auto-auth.rst} | 0 docs/source/topics/changelog.rst | 11 -- ...configuration-file.rst => config-file.rst} | 0 docs/source/topics/faq.rst | 107 +++++++++++++++ .../topics/{using-filters.rst => filters.rst} | 0 .../topics/{socks5-proxy.rst => proxy.rst} | 0 docs/source/topics/releases.rst | 13 ++ ...mize-sessions.rst => session-settings.rst} | 5 +- docs/source/topics/text-formatting.rst | 6 +- pyrogram/client/client.py | 4 +- setup.py | 2 +- 25 files changed, 235 insertions(+), 109 deletions(-) create mode 100644 docs/source/api/client.rst rename docs/source/{core => api}/decorators.rst (100%) rename docs/source/{core => api}/errors.rst (95%) rename docs/source/{core => api}/filters.rst (61%) rename docs/source/{core => api}/handlers.rst (100%) rename docs/source/{core => api}/methods.rst (100%) rename docs/source/{core => api}/types.rst (100%) delete mode 100644 docs/source/core/client.rst rename docs/source/{topics/error-handling.rst => start/errors.rst} (94%) rename docs/source/{topics/usage.rst => start/invoking.rst} (87%) rename docs/source/{topics/update-handling.rst => start/updates.rst} (87%) rename docs/source/topics/{auto-authorization.rst => auto-auth.rst} (100%) delete mode 100644 docs/source/topics/changelog.rst rename docs/source/topics/{configuration-file.rst => config-file.rst} (100%) create mode 100644 docs/source/topics/faq.rst rename docs/source/topics/{using-filters.rst => filters.rst} (100%) rename docs/source/topics/{socks5-proxy.rst => proxy.rst} (100%) create mode 100644 docs/source/topics/releases.rst rename docs/source/topics/{customize-sessions.rst => session-settings.rst} (97%) diff --git a/compiler/docs/compiler.py b/compiler/docs/compiler.py index 6ea2240d..2c67e66c 100644 --- a/compiler/docs/compiler.py +++ b/compiler/docs/compiler.py @@ -21,7 +21,7 @@ import os import shutil HOME = "compiler/docs" -DESTINATION = "docs/source" +DESTINATION = "docs/source/telegram" FUNCTIONS_PATH = "pyrogram/api/functions" TYPES_PATH = "pyrogram/api/types" @@ -129,6 +129,6 @@ if "__main__" == __name__: FUNCTIONS_PATH = "../../pyrogram/api/functions" TYPES_PATH = "../../pyrogram/api/types" HOME = "." - DESTINATION = "../../docs/source" + DESTINATION = "../../docs/source/telegram" start() diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst new file mode 100644 index 00000000..05c5cd0c --- /dev/null +++ b/docs/source/api/client.rst @@ -0,0 +1,7 @@ +Pyrogram Client +=============== + +The :class:`Client ` is the main class. It exposes easy-to-use methods that are named +after the well established Telegram Bot API methods, thus offering a familiar look to Bot developers. + +.. autoclass:: pyrogram.Client() diff --git a/docs/source/core/decorators.rst b/docs/source/api/decorators.rst similarity index 100% rename from docs/source/core/decorators.rst rename to docs/source/api/decorators.rst diff --git a/docs/source/core/errors.rst b/docs/source/api/errors.rst similarity index 95% rename from docs/source/core/errors.rst rename to docs/source/api/errors.rst index 68313bdd..51d1fcd3 100644 --- a/docs/source/core/errors.rst +++ b/docs/source/api/errors.rst @@ -1,5 +1,5 @@ -Errors -====== +RPC Errors +========== All the Pyrogram errors listed here live inside the ``errors`` sub-package. diff --git a/docs/source/core/filters.rst b/docs/source/api/filters.rst similarity index 61% rename from docs/source/core/filters.rst rename to docs/source/api/filters.rst index 091031ae..87faa801 100644 --- a/docs/source/core/filters.rst +++ b/docs/source/api/filters.rst @@ -1,5 +1,5 @@ -Filters -======= +Update Filters +============== .. autoclass:: pyrogram.Filters :members: diff --git a/docs/source/core/handlers.rst b/docs/source/api/handlers.rst similarity index 100% rename from docs/source/core/handlers.rst rename to docs/source/api/handlers.rst diff --git a/docs/source/core/methods.rst b/docs/source/api/methods.rst similarity index 100% rename from docs/source/core/methods.rst rename to docs/source/api/methods.rst diff --git a/docs/source/core/types.rst b/docs/source/api/types.rst similarity index 100% rename from docs/source/core/types.rst rename to docs/source/api/types.rst diff --git a/docs/source/core/client.rst b/docs/source/core/client.rst deleted file mode 100644 index 43524cb3..00000000 --- a/docs/source/core/client.rst +++ /dev/null @@ -1,12 +0,0 @@ -Pyrogram -======== - -In this section you can find a detailed description of the Pyrogram package and its API. - -:class:`Client ` is the main class. It exposes easy-to-use methods that are named -after the well established Telegram Bot API methods, thus offering a familiar look to Bot developers. - -Client ------- - -.. autoclass:: pyrogram.Client() diff --git a/docs/source/index.rst b/docs/source/index.rst index 74f68433..ae6a2fda 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -54,26 +54,54 @@ Welcome to Pyrogram app.run() -**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C. -It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_. +**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and +C. It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the +`MTProto API`_. -How the documentation is organized +.. _Telegram: https://telegram.org +.. _MTProto API: https://core.telegram.org/api#telegram-api + +How the Documentation is Organized ---------------------------------- -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. +Contents are organized into self-contained topics and can be all accessed from the sidebar, or by following them in +order using the Next button at the end of each page. Here below you can find a list of the most relevant pages. -Relevant Pages -^^^^^^^^^^^^^^ +Getting Started +^^^^^^^^^^^^^^^ -- `Quick Start`_ - Concise steps to get you started as fast as possible. -- `API Usage`_ - Guide on how to use Pyrogram's API. -- `Update Handling`_ - Guide on how to handle Telegram updates. -- Client_ - Reference details about the Client class. -- Types_ - All the available Pyrogram types. -- Methods_ - All the available Pyrogram methods. +- `Quick Start`_ - Overview to get you started as fast as possible. +- `Calling Methods`_ - How to use Pyrogram's API. +- `Handling Updates`_ - How to handle Telegram updates. +- `Error Handling`_ - How to handle API errors correctly. -**To get started, press the Next button** +.. _Quick Start: intro/start +.. _Calling Methods: start/invoking +.. _Handling Updates: start/updates +.. _Error Handling: start/errors + +API Reference +^^^^^^^^^^^^^ +- `Client Class`_ - Details about the Client class. +- `Available Methods`_ - A list of available high-level methods. +- `Available Types`_ - A list of available high-level types. + +.. _Client Class: core/client +.. _Available Methods: core/methods +.. _Available Types: core/types + +Topics +^^^^^^ + +- `Smart Plugins`_ - How to modularize your application. +- `Advanced Usage`_ - How to use Telegram's raw API. +- `Release Notes`_ - Release notes for Pyrogram releases. +- `Pyrogram FAQ`_ - Answers to common Pyrogram questions. + +.. _Smart Plugins: topics/smart-plugins +.. _Advanced Usage: topics/advanced-usage +.. _Release Notes: topics/releases +.. _Pyrogram FAQ: topics/faq .. toctree:: :hidden: @@ -82,55 +110,51 @@ Relevant Pages intro/start intro/install intro/setup - intro/auth .. toctree:: :hidden: - :caption: Topic Guides + :caption: Getting Started - topics/usage - topics/update-handling - topics/using-filters - topics/more-on-updates - topics/configuration-file - topics/smart-plugins - topics/auto-authorization - topics/customize-sessions - topics/tgcrypto - topics/text-formatting - topics/socks5-proxy - topics/bots-interaction - topics/error-handling - topics/test-servers - topics/advanced-usage - topics/voice-calls - topics/changelog + intro/auth + start/invoking + start/updates + start/errors .. toctree:: :hidden: :caption: API Reference - core/client - core/types - core/methods - core/handlers - core/decorators - core/filters - core/errors + api/client + api/methods + api/types + api/handlers + api/decorators + api/filters + api/errors + +.. toctree:: + :hidden: + :caption: Topic Guides + + topics/filters + topics/more-on-updates + topics/config-file + topics/smart-plugins + topics/auto-auth + topics/session-settings + topics/tgcrypto + topics/text-formatting + topics/proxy + topics/bots-interaction + topics/test-servers + topics/advanced-usage + topics/voice-calls + topics/releases + topics/faq .. toctree:: :hidden: :caption: Telegram API - functions/index - types/index - -.. _Telegram: https://telegram.org -.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto -.. _MTProto API: https://core.telegram.org/api#telegram-api -.. _Quick Start: intro/start.html -.. _API Usage: topics/usage.html -.. _Update Handling: topics/update-handling.html -.. _Client: core/client.html -.. _Types: core/types.html -.. _Methods: core/methods + telegram/functions/index + telegram/types/index diff --git a/docs/source/intro/start.rst b/docs/source/intro/start.rst index d6a8d5e3..7d6f0150 100644 --- a/docs/source/intro/start.rst +++ b/docs/source/intro/start.rst @@ -32,7 +32,7 @@ Get Pyrogram Real Fast 8. Watch Pyrogram send a message to yourself. -9. Join our `community `_. +9. Join our `community`_. 10. Say, "hi!". @@ -42,4 +42,8 @@ Enjoy the API That was just a quick overview that barely scratched the surface! In the next few pages of the introduction, we'll take a much more in-depth look of what we have just done. -Feeling eager? You can take a shortcut to `API Usage <../topics/usage.html>`_ and come back later to learn some more details. +Feeling eager? You can take a shortcut to `Calling Methods`_ and come back later to learn some more +details. + +.. _community: //t.me/pyrogramchat +.. _Calling Methods: ../start/invoking \ No newline at end of file diff --git a/docs/source/topics/error-handling.rst b/docs/source/start/errors.rst similarity index 94% rename from docs/source/topics/error-handling.rst rename to docs/source/start/errors.rst index 7e87b94a..d05206c9 100644 --- a/docs/source/topics/error-handling.rst +++ b/docs/source/start/errors.rst @@ -16,8 +16,7 @@ There are many errors that Telegram could return, but they all fall in one of th 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. +in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors. Examples -------- diff --git a/docs/source/topics/usage.rst b/docs/source/start/invoking.rst similarity index 87% rename from docs/source/topics/usage.rst rename to docs/source/start/invoking.rst index 34f57876..c27e86c3 100644 --- a/docs/source/topics/usage.rst +++ b/docs/source/start/invoking.rst @@ -1,14 +1,10 @@ -API Usage -========= +Calling Methods +=============== -At this point, we have successfully `installed Pyrogram`_ and authorized_ our account and we are now pointing towards -the core of the library. It's time to start playing with the API! +At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now pointing towards the +core of the library. It's time to start playing with the API! -Make API Method Calls ---------------------- - -Making API method calls with Pyrogram is very simple. -Here's an example we are going to examine: +Making API method calls with Pyrogram is very simple. Here's an example we are going to examine: .. code-block:: python diff --git a/docs/source/topics/update-handling.rst b/docs/source/start/updates.rst similarity index 87% rename from docs/source/topics/update-handling.rst rename to docs/source/start/updates.rst index c32bc2be..0dcb08ad 100644 --- a/docs/source/topics/update-handling.rst +++ b/docs/source/start/updates.rst @@ -1,12 +1,12 @@ -Update Handling -=============== +Handling Updates +================ Calling `API methods`_ sequentially is cool, but how to react when, for example, a new message arrives? This page deals -with updates and how to handle them in Pyrogram. Let's have a look at how they work. +with updates and how to handle such events in Pyrogram. Let's have a look at how they work. -First, let's define what are these updates. Updates are simply events that happen in your Telegram account (incoming -messages, new members join, 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 +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, 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 <../pyrogram/Handlers.html>`_. Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback diff --git a/docs/source/topics/auto-authorization.rst b/docs/source/topics/auto-auth.rst similarity index 100% rename from docs/source/topics/auto-authorization.rst rename to docs/source/topics/auto-auth.rst diff --git a/docs/source/topics/changelog.rst b/docs/source/topics/changelog.rst deleted file mode 100644 index 732a1311..00000000 --- a/docs/source/topics/changelog.rst +++ /dev/null @@ -1,11 +0,0 @@ -Changelog -========= - -Currently, all Pyrogram release notes live inside the GitHub repository web page: -https://github.com/pyrogram/pyrogram/releases - -(You will be automatically redirected in 10 seconds.) - -.. raw:: html - - \ No newline at end of file diff --git a/docs/source/topics/configuration-file.rst b/docs/source/topics/config-file.rst similarity index 100% rename from docs/source/topics/configuration-file.rst rename to docs/source/topics/config-file.rst diff --git a/docs/source/topics/faq.rst b/docs/source/topics/faq.rst new file mode 100644 index 00000000..f647e261 --- /dev/null +++ b/docs/source/topics/faq.rst @@ -0,0 +1,107 @@ +Pyrogram FAQ +============ + +This FAQ page provides answers to common questions about Pyrogram and, to some extent, Telegram in general. + +.. contents:: Contents + :backlinks: none + :local: + +What is Pyrogram? +----------------- + +**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and +C. It enables you to easily create custom applications using both user and bot identities (bot API alternative) via the +`MTProto API`_ with the Python programming language. + +.. _Telegram: https://telegram.org +.. _MTProto API: https://core.telegram.org/api#telegram-api + +What does "Pyrogram" mean? +-------------------------- + +The word "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**, +from *Telegram*. The word *pyro* itself is built from *Python*, **py** for short, and the suffix **ro** to come up with +the word *fire*, which also inspired the project logo. + +How old is Pyrogram? +-------------------- + +Pyrogram was first released on December 12, 2017. The actual work on the framework began roughly three months prior the +initial public release on `GitHub`_. + +.. _GitHub: + +Why do I need an API key for bots? +---------------------------------- + +Requests against the official bot API endpoint are made via JSON/HTTP, but are handled by a backend application that +implements the MTProto protocol -- just like Pyrogram -- and uses its own API key, which is always required, but hidden +to the public. + +.. figure:: https://i.imgur.com/C108qkX.png + :align: center + +Using MTProto is the only way to communicate with the actual Telegram servers, and the main API requires developers to +identify applications by means of a unique key; the bot token identifies a bot as a user and replaces the user's phone +number only. + +I started a client but nothing happens! +--------------------------------------- + +If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or +totally blocked in those countries. + +Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on +the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network +in a bunch of seconds: + +.. code-block:: python + + import logging + logging.basicConfig(level=logging.INFO) + +|bug report| + +.. _you need a proxy: proxy + +I keep getting [400 PEER_ID_INVALID] error! +------------------------------------------- + +The error in question is ``[400 PEER_ID_INVALID]: The id/access_hash combination is invalid``, and could mean several +things: + +- The chat id you tried to use is simply wrong, double check it. +- The chat id refers to a group or channel you are not a member of. +- The chat id refers to a user you have't seen yet (from contacts, groups in common, forwarded messages or private + chats). + +|bug report| + +.. |bug report| replace:: + + **Note:** If you really believe this should not happen, kindly open a `Bug Report`_. + +.. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md + +My account has been deactivated/limited! +---------------------------------------- + +First of all, you should understand that Telegram wants to be a safe place for people to stay in, and to pursue this +goal there are automatic protection systems running to prevent flood and spam, as well as a moderation team of humans +who reviews reports. + +**Pyrogram is a tool at your commands; it only does what you tell it to do, the rest is up to you.** + +Having said that, here's how a list of what Telegram definitely doesn't like: + +- Flood, abusing the API. +- Spam, sending unsolicited messages or adding people to unwanted groups and channels. +- Virtual/VoIP and cheap real numbers, because they are relatively easy to get and likely used for spam/flood. + +However, you might be right, and your account was deactivated/limited without any reason. This could happen because of +mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at +recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_. + +.. _@smstelegram: https://twitter.com/smstelegram +.. _this form: https://telegram.org/support \ No newline at end of file diff --git a/docs/source/topics/using-filters.rst b/docs/source/topics/filters.rst similarity index 100% rename from docs/source/topics/using-filters.rst rename to docs/source/topics/filters.rst diff --git a/docs/source/topics/socks5-proxy.rst b/docs/source/topics/proxy.rst similarity index 100% rename from docs/source/topics/socks5-proxy.rst rename to docs/source/topics/proxy.rst diff --git a/docs/source/topics/releases.rst b/docs/source/topics/releases.rst new file mode 100644 index 00000000..6c3b5b75 --- /dev/null +++ b/docs/source/topics/releases.rst @@ -0,0 +1,13 @@ +Release Notes +============= + +Release notes for Pyrogram releases will describe what's new in each version, and will also make you aware of any +backwards-incompatible changes made in that version. + +When upgrading to a new version of Pyrogram, you will need to check all the breaking changes in order to find +incompatible code in your application, but also to take advantage of new features and improvements. + +.. note:: + + Currently, all Pyrogram release notes live inside the GitHub repository web page: + https://github.com/pyrogram/pyrogram/releases. diff --git a/docs/source/topics/customize-sessions.rst b/docs/source/topics/session-settings.rst similarity index 97% rename from docs/source/topics/customize-sessions.rst rename to docs/source/topics/session-settings.rst index 77765287..47c6872e 100644 --- a/docs/source/topics/customize-sessions.rst +++ b/docs/source/topics/session-settings.rst @@ -1,5 +1,5 @@ -Customize Sessions -================== +Session Settings +================ As you may probably know, Telegram allows users (and bots) having more than one session (authorizations) registered in the system at the same time. @@ -8,7 +8,6 @@ Briefly explaining, sessions are simply new logins in your account. They can be app (or by invoking `GetAuthorizations <../functions/account/GetAuthorizations.html>`_ with Pyrogram). They store some useful information such as the client who's using them and from which country and IP address. - .. figure:: https://i.imgur.com/lzGPCdZ.png :width: 70% :align: center diff --git a/docs/source/topics/text-formatting.rst b/docs/source/topics/text-formatting.rst index 0ab08694..535fec31 100644 --- a/docs/source/topics/text-formatting.rst +++ b/docs/source/topics/text-formatting.rst @@ -11,7 +11,7 @@ Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline Markdown Style -------------- -To use this mode, pass :obj:`MARKDOWN ` or "markdown" in the *parse_mode* field when using +To use this mode, pass "markdown" in the *parse_mode* field when using :obj:`send_message() `. Use the following syntax in your message: .. code-block:: text @@ -34,8 +34,8 @@ To use this mode, pass :obj:`MARKDOWN ` or "markdow HTML Style ---------- -To use this mode, pass :obj:`HTML ` or "html" in the *parse_mode* field when using -:obj:`send_message() `. The following tags are currently supported: +To use this mode, pass "html" in the *parse_mode* field when using :obj:`send_message() `. +The following tags are currently supported: .. code-block:: text diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py index 823faf27..24373ce1 100644 --- a/pyrogram/client/client.py +++ b/pyrogram/client/client.py @@ -60,7 +60,7 @@ log = logging.getLogger(__name__) class Client(Methods, BaseClient): - """This class represents a Client, the main mean for interacting with Telegram. + """This class represents a Client, the main means for interacting with Telegram. It exposes bot-like methods for an easy access to the API as well as a simple way to invoke every single Telegram API method available. @@ -438,7 +438,7 @@ class Client(Methods, BaseClient): self.stop() def run(self): - """Use this method as a convenience shortcut to automatically start the Client and idle the main script. + """Use this method to start the Client and automatically idle the main script. This is a convenience method that literally just calls :meth:`start` and :meth:`idle`. It makes running a client less verbose, but is not suitable in case you want to run more than one client in a single main script, diff --git a/setup.py b/setup.py index ef02c428..437ba39a 100644 --- a/setup.py +++ b/setup.py @@ -48,7 +48,7 @@ def get_readme(): class Clean(Command): DIST = ["./build", "./dist", "./Pyrogram.egg-info"] API = ["pyrogram/api/errors/exceptions", "pyrogram/api/functions", "pyrogram/api/types", "pyrogram/api/all.py"] - DOCS = ["docs/source/functions", "docs/source/types", "docs/build"] + DOCS = ["docs/source/telegram", "docs/build"] ALL = DIST + API + DOCS description = "Clean generated files"