Update documentation

client/doc/developing/faq.rst

@@ -1,2 +1,210 @@
-Frequently Asked Questions
+Frequently Asked Questions (FAQ)
-==========================
+================================
+
+.. currentmodule:: telethon
+
+.. contents::
+
+
+Code without errors doesn't work
+--------------------------------
+
+Then it probably has errors, but you haven't enabled logging yet.
+To enable logging, at the following code to the top of your main file:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(format='[%(levelname) 5s/%(asctime)s] %(name)s: %(message)s',
+                        level=logging.WARNING)
+
+Do not wrap your code in ``try / except`` blocks just to hide errors.
+It will be a lot more difficult to find what the problem is.
+Instead, let Python print the full traceback, or fix the actual error properly.
+
+See the official Python documentation for more information on :mod:`logging`.
+
+
+My account was deleted/limited when using the library
+-----------------------------------------------------
+
+First and foremost, **this is not a problem exclusive to Telethon.
+Any third-party library is prone to cause the accounts to appear banned.**
+Even official applications can make Telegram ban an account under certain circumstances.
+Third-party libraries such as Telethon are a lot easier to use, and as such,
+they are misused to spam, which causes Telegram to learn certain patterns and ban suspicious activity.
+
+There is no point in Telethon trying to circumvent this. Even if it succeeded,
+spammers would then abuse the library again, and the cycle would repeat.
+
+The library will only do things that you tell it to do.
+If you use the library with bad intentions, Telegram will hopefully ban you.
+
+However, you may also be part of a limited country, such as Iran or Russia.
+In that case, we have bad news for you. Telegram is much more likely to ban these numbers,
+as they are often used to spam other accounts, likely through the use of libraries like this one.
+The best advice we can give you is to not abuse the API, like calling many requests really quickly.
+
+We have also had reports from Kazakhstan and China, where connecting would fail.
+To solve these connection problems, you should use a proxy (see below).
+
+Telegram may also ban virtual (VoIP) phone numbers, as again, they're likely to be used for spam.
+
+More recently (year 2023 onwards), Telegram has started putting a lot more measures to prevent spam,
+with even additions such as anonymous participants in groups or the inability to fetch group members at all.
+This means some of the anti-spam measures have gotten more aggressive.
+
+The recommendation has usually been to use the library only on well-established accounts (and not an account you just created),
+and to not perform actions that could be seen as abuse.
+Telegram decides what those actions are, and they're free to change how they operate at any time.
+
+If you want to check if your account has been limited, simply send a private message to `@SpamBot <https://t.me/SpamBot>`_ through Telegram itself.
+You should notice this by getting errors like ``PeerFlood``, which means you're limited,
+for instance, when sending a message to some accounts but not others.
+
+For more discussion, please see `issue 297 <https://github.com/LonamiWebs/Telethon/issues/297>`_.
+
+
+How can I use a proxy?
+----------------------
+
+Proxies can be used with Telethon, but they are not directly supported.
+If you have problems with Telethon when using a proxy, it will *not* be considered a Telethon bug.
+
+You can use any :mod:`asyncio`-compatible proxy library of your choice, and then define a custom connector:
+
+.. code-block:: python
+
+    from telethon import Client
+    # from some_proxy_library import open_proxy_connection
+
+    async def my_proxy_connector(ip, port):
+        return await open_proxy_connection(
+            host=ip,
+            port=port,
+            proxy_url='socks5://user:password@127.0.0.1:1080'
+        )
+
+    client = Client(..., connector=my_proxy_connector)
+
+For more information, see the :doc:`/concepts/datacenters` concept.
+
+
+AttributeError: 'coroutine' object has no attribute 'id'
+--------------------------------------------------------
+
+Telethon is an asynchronous library, which means you must ``await`` calls that require network access:
+
+.. code-block:: python
+
+    async def handler(event):
+        me = await client.get_me()
+        #    ^^^^^ note the await
+        print(me.id)
+
+
+sqlite3.OperationalError: database is locked
+--------------------------------------------
+
+An older process is still running and is using the same ``'session'`` file.
+
+This error occurs when **two or more clients use the same session**,
+that is, when you write the same session name to be used in the client:
+
+* You have an older process using the same session file.
+* You have two different scripts running (interactive sessions count too).
+* You have two clients in the same script running at the same time.
+
+The solution is, if you need two clients, use two sessions.
+If the problem persists and you're on Linux, you can use ``fuser my.session`` to find out the process locking the file.
+As a last resort, you can reboot your system.
+
+If you really dislike SQLite, use a different session storage.
+See the :doc:`/concepts/sessions` concept to learn more about session storages.
+
+
+File download is slow or sending files takes too long
+-----------------------------------------------------
+
+The communication with Telegram is encrypted.
+Encryption requires a lot of math, and doing it in pure Python is very slow.
+
+``cryptg`` is a library which containns the encryption functions used by Telethon.
+If it is installed (via ``pip install cryptg``), it will automatically be used and should provide a considerable speed boost.
+
+
+What does "Task was destroyed but it is pending" mean?
+------------------------------------------------------
+
+Your script likely finished abruptly, the :mod:`asyncio` event loop got destroyed,
+and the library did not get a chance to properly close the connection and close the session.
+
+Make sure you're either using the context manager for the client (``with client``)
+or always call :meth:`~Client.disconnect` before the scripts exits (for example, using ``try / finally``).
+
+
+Can I use threading with the library?
+-------------------------------------
+
+Yes, if you know what you are doing.
+However, you will probably have a lot of headaches to get :mod:`threading` threads and :mod:`asyncio` tasks to work together.
+
+If you want to use a threaded library alongside Telethon, like `Flask <flask.pocoo.org/>`_,
+consider instead using an asynchronous alternative like `Quart <https://pgjones.gitlab.io/quart/>`_.
+
+If you want to do background work, you probably do not need threads.
+See the :mod:`asyncio` documentation to learn how to use tasks and wait on multiple things at the same time.
+
+
+Telethon gets stuck when used with other async libraries
+--------------------------------------------------------
+
+After you call :meth:`Client.connect` (either directly or implicitly via ``with client``),
+you cannot change the :mod:`asyncio` event loop from which it's used.
+
+The most common cause is :func:`asyncio.run`, since it creates a new event loop.
+If you :func:`asyncio.run` a function to create the client and set it up, you cannot then use a second :func:`asyncio.run` on that client.
+
+Instead, it's often a good idea to have a single ``async def main`` and :func:`asyncio.run` that.
+From it, you're also able to call other ``async def`` without having to touch :func:`asyncio.run` again:
+
+.. code-block:: python
+
+    # It's fine to create the client outside as long as you don't connect
+    client = Client(...)
+
+    async def main():
+        # Now the client will connect, so the loop must not change from now on.
+        # But as long as you do all the work inside main, including calling
+        # other async functions, things will work.
+        async with client:
+            ....
+
+    if __name__ == '__main__':
+        asyncio.run(main())
+
+Be sure to read the :mod:`asyncio` documentation if you want a better understanding of event loop, tasks, and what functions you can use.
+
+
+Can Telethon also do this thing the official clients do?
+--------------------------------------------------------
+
+With the exception of creating accounts, Telethon can do everything an official client can do.
+
+Following the `Pareto principle <https://en.wikipedia.org/wiki/Pareto_principle>`_,
+the small curated API Telethon offers aims to cover most common use-cases, but not all of them.
+If your use-case is not covered by the :class:`Client` methods, you can instead resort to the :doc:`/concepts/full-api`.
+
+To learn how Telegram Desktop performs a certain request, you can enable what is known as "debug mode".
+Different clients may have different ways to enable this feature.
+
+With the Settings screen of Telegram Desktop open, type "debugmode" on your keyboard (without quotes).
+This should prompt you to confirm whether you want to enable DEBUG logs.
+Confirm, and logging should commence.
+
+With logging enabled, perform the action you want (for example, "delete all messages").
+After that, open the text file starting with ``mtp_`` inside Telegram's ``DebugLogs`` folder.
+You should find this folder where Telegram is installed (on Windows, ``%AppData%\Telegram Desktop``).
+
+After you're done, you can disable debug mode in the same way you enabled it.
+The debug logs may have recorded sensitive information, so be sure to delete them afterwards if you need to.

client/src/telethon/_impl/session/storage/memory.py

@@ -8,9 +8,7 @@ class MemorySession(Storage):
     """
     Session storage without persistence.
 
-    This is the simplest storage and is the one used by default.
+    Session data is only kept in memory and is not saved to disk.
-
-    Session data is only kept in memory and is not persisted to disk.
     """
 
     __slots__ = ("session",)