Various improvements

docs/source/faq/client-started-but-nothing-happens.rst

@@ -0,0 +1,11 @@
+Client started, but nothing happens
+===================================
+
+A possible cause might be network issues, either yours or Telegram's. To check this, add the following code at
+the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable
+network:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(level=logging.INFO)

docs/source/faq/code-hangs-when-calling-stop-restart-add-remove-handler.rst

@@ -0,0 +1,12 @@
+Code hangs when calling stop, restart, add/remove_handler
+=========================================================
+
+You tried to ``.stop()``, ``.restart()``, ``.add_handler()`` or ``.remove_handler()`` inside a running handler, but
+that can't be done because the way Pyrogram deals with handlers would make it hang.
+
+When calling one of the methods above inside an event handler, Pyrogram needs to wait for all running handlers to finish
+in order to continue. Since your handler is blocking the execution by waiting for the called method to finish
+and since Pyrogram needs to wait for your handler to finish, you are left with a deadlock.
+
+The solution to this problem is to pass ``block=False`` to such methods so that they return immediately and the actual
+code called asynchronously.

docs/source/faq/how-to-avoid-flood-waits.rst

@@ -0,0 +1,23 @@
+How to avoid Flood Waits?
+=========================
+
+Slow things down and make less requests. Moreover, exact limits are unknown and can change anytime based on normal
+usages.
+
+When a flood wait happens the server will tell you how much time to wait before continuing.
+The following shows how to catch the exception in your code and wait the required seconds.
+
+.. code-block:: python
+
+  import time
+  from pyrogram.errors import FloodWait
+
+  ...
+      try:
+          ...  # Your code
+      except FloodWait as e:
+          await asyncio.sleep(e.x)  # Wait "x" seconds before continuing
+  ...
+
+
+More info about error handling can be found :doc:`here <../start/errors>`.

docs/source/faq/how-to-use-webhooks.rst

@@ -0,0 +1,9 @@
+How to use webhooks?
+====================
+
+There is no webhook in Pyrogram, simply because there is no HTTP involved. However, a similar technique is
+being used to make receiving updates efficient.
+
+Pyrogram uses persistent connections via TCP sockets to interact with the server and instead of actively asking for
+updates every time (polling), Pyrogram will sit down and wait for the server to send updates by itself the very moment
+they are available (server push).

docs/source/faq/index.rst

@@ -0,0 +1,47 @@
+Frequently Asked Questions
+==========================
+
+This FAQ page provides answers to common questions about Pyrogram and, to some extent, Telegram in general.
+
+**Contents**
+
+- :doc:`why-is-the-api-key-needed-for-bots`
+- :doc:`how-to-use-webhooks`
+- :doc:`using-the-same-file-id-across-different-accounts`
+- :doc:`using-multiple-clients-at-once-on-the-same-account`
+- :doc:`client-started-but-nothing-happens`
+- :doc:`what-are-the-ip-addresses-of-telegram-data-centers`
+- :doc:`migrating-the-account-to-another-data-center`
+- :doc:`why-is-the-client-reacting-slowly-in-supergroups-channels`
+- :doc:`peer-id-invalid-error`
+- :doc:`code-hangs-when-calling-stop-restart-add-remove-handler`
+- :doc:`unicodeencodeerror-codec-cant-encode`
+- :doc:`uploading-with-urls-gives-error-webpage-curl-failed`
+- :doc:`why-is-the-event-handler-triggered-twice-or-more`
+- :doc:`sqlite3-operationalerror-database-is-locked`
+- :doc:`sqlite3-interfaceerror-error-binding-parameter`
+- :doc:`socket-send-raised-exception-oserror-timeouterror`
+- :doc:`how-to-avoid-flood-waits`
+- :doc:`the-account-has-been-limited-deactivated`
+
+.. toctree::
+    :hidden:
+
+    why-is-the-api-key-needed-for-bots
+    how-to-use-webhooks
+    using-the-same-file-id-across-different-accounts
+    using-multiple-clients-at-once-on-the-same-account
+    client-started-but-nothing-happens
+    what-are-the-ip-addresses-of-telegram-data-centers
+    migrating-the-account-to-another-data-center
+    why-is-the-client-reacting-slowly-in-supergroups-channels
+    peer-id-invalid-error
+    code-hangs-when-calling-stop-restart-add-remove-handler
+    unicodeencodeerror-codec-cant-encode
+    uploading-with-urls-gives-error-webpage-curl-failed
+    why-is-the-event-handler-triggered-twice-or-more
+    sqlite3-operationalerror-database-is-locked
+    sqlite3-interfaceerror-error-binding-parameter
+    socket-send-raised-exception-oserror-timeouterror
+    how-to-avoid-flood-waits
+    the-account-has-been-limited-deactivated

docs/source/faq/migrating-the-account-to-another-data-center.rst

@@ -0,0 +1,10 @@
+Migrating the account to another data center
+============================================
+
+This question is asked by people who find their account always being connected to one DC (data center), but are
+connecting from a place far away, thus resulting in slower interactions when using the API because of the greater
+physical distance between the user and the associated DC.
+
+When registering an account for the first time, is up to Telegram to decide which DC the new user is going to be
+created in. It's also up to the server to decide whether to automatically migrate a user in case of prolonged usages
+from a distant location.

docs/source/faq/peer-id-invalid-error.rst

@@ -0,0 +1,14 @@
+PEER_ID_INVALID error
+=====================
+
+This error could mean several things:
+
+- The chat id you tried to use is simply wrong, check it again.
+- The chat id refers to a group or channel you are not a member of.
+- The chat id argument you passed is in form of a string; you have to convert it into an integer with ``int(chat_id)``.
+- The chat id refers to a user or chat your current session hasn't met yet.
+
+About the last point: in order for you to meet a user and thus communicate with them, you should ask yourself how to
+contact people using official apps. The answer is the same for Pyrogram too and involves normal usages such as searching
+for usernames, meeting them in a common group, having their phone contacts saved, getting a message mentioning them
+or obtaining the dialogs list.

docs/source/faq/socket-send-raised-exception-oserror-timeouterror.rst

@@ -0,0 +1,10 @@
+socket.send() raised exception, OSError(), TimeoutError()
+=========================================================
+
+If you get this error chances are you are blocking the event loop for too long.
+In general, it means you are executing thread-blocking code that prevents the event loop from
+running properly. For example:
+
+- You are using ``time.sleep()`` instead of ``asyncio.sleep()``.
+- You are running processing loops that take too much time to complete.
+- You are reading/writing files to disk that take too much time to complete.

docs/source/faq/sqlite3-interfaceerror-error-binding-parameter.rst

@@ -0,0 +1,13 @@
+sqlite3.InterfaceError: Error binding parameter
+===============================================
+
+This error occurs when you pass a chat id value of the wrong type when trying to call a method. Most likely, you
+accidentally passed the whole user or chat object instead of the id or username.
+
+.. code-block:: python
+
+    # Wrong. You passed the whole Chat instance
+    app.send_message(chat, "text")
+
+    # Correct
+    app.send_message(chat.id, "text")

docs/source/faq/sqlite3-operationalerror-database-is-locked.rst

@@ -0,0 +1,17 @@
+sqlite3.OperationalError: database is locked
+============================================
+
+This error occurs when more than one process is using the same session file, that is, when you run two or more clients
+at the same time using the same session name or in case another program has accessed the file.
+
+For example, it could occur when a background script is still running and you forgot about it. In this case, you either
+restart your system or find and kill the process that is locking the database. On Unix based systems, you can try the
+following:
+
+#. ``cd`` into your session file directory.
+#. ``fuser my_account.session`` to find the process id.
+#. ``kill 1234`` to gracefully stop the process.
+#. If the last command doesn't help, use ``kill -9 1234`` instead.
+
+If you want to run multiple clients on the same account, you must authorize your account (either user or bot)
+from the beginning every time, and use different session names for each parallel client you are going to use.

docs/source/faq/the-account-has-been-limited-deactivated.rst

@@ -0,0 +1,16 @@
+The account has been limited/deactivated
+========================================
+
+Pyrogram is a framework that interfaces with Telegram; it is at your commands, meaning it only does what you tell it to
+do, the rest is up to you and Telegram (see `Telegram's ToS`_).
+
+If you found your account being limited/deactivated, it could be due spam/flood/abuse of the API or the usage of certain
+virtual/VoIP numbers.
+
+If you think your account was limited/deactivated by mistake, you can write to recover@telegram.org, contact
+`@SpamBot`_ or use `this form`_.
+
+.. _@SpamBot: https://t.me/spambot
+.. _this form: https://telegram.org/support
+.. _Telegram's ToS: https://telegram.org/tos
+

docs/source/faq/unicodeencodeerror-codec-cant-encode.rst

@@ -0,0 +1,7 @@
+UnicodeEncodeError: '...' codec can't encode ...
+================================================
+
+Where ``<encoding>`` might be *ascii*, *cp932*, *charmap* or anything else other than *utf-8*. This error usually
+shows up when you try to print something and has very little to do with Pyrogram itself as it is strictly related to
+your own terminal. To fix it, either find a way to change the encoding settings of your terminal to UTF-8 or switch to
+another terminal altogether.

docs/source/faq/uploading-with-urls-gives-error-webpage-curl-failed.rst

@@ -0,0 +1,7 @@
+Uploading with URLs gives error WEBPAGE_CURL_FAILED
+===================================================
+
+When uploading media files using an URL, the server automatically tries to download the media and uploads it to the
+Telegram cloud. This error usually happens in case the provided URL is not publicly accessible by Telegram itself or the
+media file is too large. In such cases, your only option is to download the media yourself and upload it from your
+local machine.

docs/source/faq/using-multiple-clients-at-once-on-the-same-account.rst

@@ -0,0 +1,7 @@
+Using multiple clients at once on the same account
+==================================================
+
+Both user and bot accounts are able to run multiple sessions in parallel. However, you must not use the same session
+in more than one client at the same time. The correct way to run multiple clients on the same account is by authorizing
+your account (either user or bot) from the beginning each time, and use one separate session for each parallel client.
+

docs/source/faq/using-the-same-file-id-across-different-accounts.rst

@@ -0,0 +1,6 @@
+Using the same file_id across different accounts
+================================================
+
+Telegram file_id strings are bound to the account which generated them. An attempt in using a foreign file id will
+result in errors such as ``[400 MEDIA_EMPTY]``. The only exception are stickers' file ids; you can use them across
+different accounts without any problem.

docs/source/faq/what-are-the-ip-addresses-of-telegram-data-centers.rst

@@ -0,0 +1,30 @@
+What are the IP addresses of Telegram Data Centers?
+===================================================
+
+Telegram is currently composed by a decentralized, multi-DC infrastructure (currently 5 DCs, each of which can
+work independently) spread across different locations worldwide. However, some of the less busy DCs have been lately
+dismissed and their IP addresses are now kept as aliases to the nearest one.
+
+.. csv-table:: Production Environment
+    :header: ID, Location, IPv4, IPv6
+    :widths: auto
+    :align: center
+
+    DC1, "MIA, Miami FL, USA", ``149.154.175.53``, ``2001:b28:f23d:f001::a``
+    DC2, "AMS, Amsterdam, NL", ``149.154.167.51``, ``2001:67c:4e8:f002::a``
+    DC3*, "MIA, Miami FL, USA", ``149.154.175.100``, ``2001:b28:f23d:f003::a``
+    DC4, "AMS, Amsterdam, NL", ``149.154.167.91``, ``2001:67c:4e8:f004::a``
+    DC5, "SIN, Singapore, SG", ``91.108.56.130``, ``2001:b28:f23f:f005::a``
+
+.. csv-table:: Test Environment
+    :header: ID, Location, IPv4, IPv6
+    :widths: auto
+    :align: center
+
+    DC1, "MIA, Miami FL, USA", ``149.154.175.10``, ``2001:b28:f23d:f001::e``
+    DC2, "AMS, Amsterdam, NL", ``149.154.167.40``, ``2001:67c:4e8:f002::e``
+    DC3*, "MIA, Miami FL, USA", ``149.154.175.117``, ``2001:b28:f23d:f003::e``
+
+.. centered:: More info about the Test Environment can be found :doc:`here <../topics/test-servers>`.
+
+***** Alias DC

docs/source/faq/why-is-the-api-key-needed-for-bots.rst

@@ -0,0 +1,12 @@
+Why is the API key needed for bots?
+===================================
+
+Requests against the official bot API endpoints are made via JSON/HTTP and are handled by an intermediate server
+application that implements the MTProto protocol and uses its own API key to communicate with the MTProto servers.
+
+.. figure:: //_static/img/mtproto-vs-bot-api.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.

docs/source/faq/why-is-the-client-reacting-slowly-in-supergroups-channels.rst

@@ -0,0 +1,18 @@
+Why is the client reacting slowly in supergroups/channels?
+==========================================================
+
+Because of how Telegram works internally, every message you receive and send must pass through the creator's DC, and in
+the worst case where you, the creator and another member all belong to three different DCs, the other member messages
+have to go through from their DC to the creator's DC and finally to your DC. This is applied to each message and member
+of a supergroup/channel and the process will inevitably take its time.
+
+Another reason that makes responses come slowly is that messages are dispatched by priority. Depending on the kind
+of member, some users receive messages faster than others and for big and busy supergroups the delay might become
+noticeable, especially if you are among the lower end of the priority list:
+
+1. Creator.
+2. Administrators.
+3. Bots.
+4. Mentioned users.
+5. Recent online users.
+6. Everyone else.

docs/source/faq/why-is-the-event-handler-triggered-twice-or-more.rst

@@ -0,0 +1,28 @@
+Why is the event handler called twice or more?
+==============================================
+
+The event handler is being called twice or more because one or more message edit events have arrived.
+By default, Pyrogram listens to both new and edit message events inside ``on_message`` handlers. To prevent edit events
+from calling the handler, use the "not edited" filter ``~filters.edited``.
+
+For example:
+
+.. code-block:: python
+
+    ...
+
+    @app.on_message(... & ~filters.edited)
+    async def handler(client, message):
+        ...
+
+Or, avoid handling any edited message altogether this way:
+
+.. code-block:: python
+
+    ...
+
+    @app.on_message(filters.edited)
+    async def edited(client, message):
+        pass
+
+    ...  # other handlers