From 0727c1d1f1713a1e0bfc4adce7b206b42a8b659d Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Mon, 16 Oct 2023 20:12:16 +0200 Subject: [PATCH] Continue improving documentation --- client/doc/basic/installation.rst | 6 +- client/doc/basic/next-steps.rst | 12 ++++ client/doc/basic/signing-in.rst | 55 ++++++++++++++----- client/doc/index.rst | 34 ++++++------ client/doc/modules/types.rst | 6 ++ .../src/telethon/_impl/client/types/meta.py | 2 +- 6 files changed, 82 insertions(+), 33 deletions(-) diff --git a/client/doc/basic/installation.rst b/client/doc/basic/installation.rst index 0abde3ac..cca00952 100644 --- a/client/doc/basic/installation.rst +++ b/client/doc/basic/installation.rst @@ -17,6 +17,9 @@ You can confirm that you have Python installed with: python --version Which should print something similar to ``Python 3.11.5`` (or newer). +Be sure to run the command in a terminal such as PowerShell or Terminal. +The above won't work inside a Python shell! +If you had the terminal open before installing Python, you will probably need to open a new one. Installing the latest stable version @@ -28,7 +31,8 @@ Once you have a working Python 3 installation, you can install or upgrade the `` python -m pip install --upgrade telethon -Be sure to use lock-files if your project depends on a specific, older version of the library! +Be sure to use lock-files if your project! +The above is just a quick way to get started and install Telethon globally. Installing development versions diff --git a/client/doc/basic/next-steps.rst b/client/doc/basic/next-steps.rst index 4c1e7abf..e9f6cdc4 100644 --- a/client/doc/basic/next-steps.rst +++ b/client/doc/basic/next-steps.rst @@ -30,3 +30,15 @@ There are `several requests that applications must make `_. + +If you are using a bot account instead, the risk of a ban is either zero or very close to it. +If you know of a bot causing account bans, please let me know so it can be documented. diff --git a/client/doc/basic/signing-in.rst b/client/doc/basic/signing-in.rst index ff0757dd..8e099324 100644 --- a/client/doc/basic/signing-in.rst +++ b/client/doc/basic/signing-in.rst @@ -26,10 +26,10 @@ Before working with Telegram's API, you (as the application developer) need to g This API ID and hash can now be used to develop an application using Telegram's API. Telethon consumes this API ID and hash in order to make the requests to Telegram. -It is important to note that this API ID and hash is attached to a developer account, +It is important to note that this API ID and hash is attached to a **developer account**, and can be used to develop applications or otherwise using libraries such as Telethon. -The *users* of the application you develop do *not* need to provide their own API ID and hash. +The *users* of the application you develop do **not** need to provide their own API ID and hash. The API ID and hash values are meant to be hardcoded in the application. Any user is then able to login with just their phone number or bot token, even if they have not registered an application themselves. @@ -106,6 +106,27 @@ To summarize: await client.connect() await client.interactive_login() +If you want to automatically login as a bot when needed, you can do so without any prompts, too: + +.. code-block:: python + + from telethon import Client + client = Client('name', 12345, '0123456789abcdef0123456789abcdef') + await client.connect() + await client.interactive_login('54321:hJrIQtVBab0M2Yqg4HL1K-EubfY_v2fEVR') + +.. note:: + + The bot token obtained from `@BotFather `_ looks something like this:: + + 54321:hJrIQtVBab0M2Yqg4HL1K-EubfY_v2fEVR + + This is **not** the API ID and hash separated by a colon! + All of it is the bot token. + Using a bot with Telethon still requires a separate API ID and hash. + + See :doc:`/concepts/botapi-vs-mtproto` for more details. + Manual login ------------ @@ -160,19 +181,20 @@ Put into code, a user can thus login as follows: phone = input('phone: ') login_token = await client.request_login_code(phone_or_token) - code = input('code: ') - user_or_token = await client.sign_in(login_token, code) + code = input('code: ') + user_or_token = await client.sign_in(login_token, code) - if isinstance(user_or_token, User): - return user_or_token + if isinstance(user_or_token, User): + return user_or_token - # user_or_token is PasswordToken - password_token = user_or_token + # user_or_token is PasswordToken + password_token = user_or_token - import getpass - password = getpass.getpass("password: ") - user = await client.check_password(password_token, password) - return user + import getpass + password = getpass.getpass("password: ") + user = await client.check_password(password_token, password) + + ... # can now use the client and user A bot account does not need to request login code and cannot have passwords, so the login flow is much simpler: @@ -182,9 +204,12 @@ A bot account does not need to request login code and cannot have passwords, so # SESSION, API_ID, API_HASH should be previously defined in your code async with Client(SESSION, API_ID, API_HASH) as client: - bot_token = input('token: ') - bot_user = await client.bot_sign_in(bot_token) - return bot_user + if not await client.is_authorized(): + bot_token = input('token: ') + bot_user = await client.bot_sign_in(bot_token) + bot_user + + ... # can now use the client and bot_user To get a bot account, you need to talk with `@BotFather `_. diff --git a/client/doc/index.rst b/client/doc/index.rst index 783a0201..13e3cd0d 100644 --- a/client/doc/index.rst +++ b/client/doc/index.rst @@ -73,22 +73,6 @@ In this section you will learn how to install the library and login to your Tele basic/next-steps -API reference -============= - -This section contains all the functions and types offered by the library. - -:doc:`‣ Start reading Client API ` - -.. toctree:: - :hidden: - :caption: API reference - - modules/client - modules/events - modules/types - modules/sessions - Concepts ======== @@ -109,6 +93,24 @@ A more in-depth explanation of some of the concepts and words used in Telethon. concepts/full-api concepts/glossary + +API reference +============= + +This section contains all the functions and types offered by the library. + +:doc:`‣ Start reading Client API ` + +.. toctree:: + :hidden: + :caption: API reference + + modules/client + modules/events + modules/types + modules/sessions + + Development resources ===================== diff --git a/client/doc/modules/types.rst b/client/doc/modules/types.rst index 3f955b8b..8470e70e 100644 --- a/client/doc/modules/types.rst +++ b/client/doc/modules/types.rst @@ -84,3 +84,9 @@ Private definitions .. data:: T Generic parameter used by :class:`AsyncList`. + +.. currentmodule:: telethon._impl.client.types.file + +.. autoclass:: InFileLike + +.. autoclass:: OutFileLike diff --git a/client/src/telethon/_impl/client/types/meta.py b/client/src/telethon/_impl/client/types/meta.py index 3996e577..600ca003 100644 --- a/client/src/telethon/_impl/client/types/meta.py +++ b/client/src/telethon/_impl/client/types/meta.py @@ -28,7 +28,7 @@ class Final(abc.ABCMeta): class NoPublicConstructor(Final): - def __call__(cls, *args: object, **kwargs: object) -> None: + def __call__(cls) -> None: raise TypeError( f"{cls.__module__}.{cls.__qualname__} has no public constructor" )