From 183d07ff2506fcf928f1e91332f8e8d05b8a3472 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Sat, 16 Mar 2024 21:08:48 +0100 Subject: [PATCH] Update documentation --- client/doc/developing/faq.rst | 212 +++++++++++++++++- .../telethon/_impl/session/storage/memory.py | 4 +- 2 files changed, 211 insertions(+), 5 deletions(-) diff --git a/client/doc/developing/faq.rst b/client/doc/developing/faq.rst index d738b9cd..bd886034 100644 --- a/client/doc/developing/faq.rst +++ b/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 `_ 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 `_. + + +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 `_, +consider instead using an asynchronous alternative like `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 `_, +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. diff --git a/client/src/telethon/_impl/session/storage/memory.py b/client/src/telethon/_impl/session/storage/memory.py index a5bcc036..eda1daaf 100644 --- a/client/src/telethon/_impl/session/storage/memory.py +++ b/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 persisted to disk. + Session data is only kept in memory and is not saved to disk. """ __slots__ = ("session",)