Continue improving documentation

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

client/doc/basic/next-steps.rst

@@ -30,3 +30,15 @@ There are `several requests that applications must make <https://core.telegram.o
 The library will not make these calls for you, as it cannot know how users interact with the application being developed.
 If you use an official client alongside the application you are developing,
 it should be safe to rely on that client making the requests instead.
+
+Having your account banned might sound scary.
+However, keep in mind that people often don't post comments when things work fine!
+The only comments you're likely to see are negative ones.
+As long as you use a real phone number and don't abuse the API, you will most likely be fine.
+This library would not be used at all otherwise!
+
+If you believe your account was banned on accident,
+`there are ways to try to get it back <https://github.com/LonamiWebs/Telethon/issues/824>`_.
+
+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.

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 <https://t.me/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 <https://t.me/BotFather>`_.
 

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 <modules/client>`
-
-.. 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 <modules/client>`
+
+.. toctree::
+    :hidden:
+    :caption: API reference
+
+    modules/client
+    modules/events
+    modules/types
+    modules/sessions
+
+
 Development resources
 =====================
 

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

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"
         )