Continue documentation

client/doc/_static/custom.css

@@ -18,3 +18,7 @@
     background-color: unset;
     color: unset;
 }
+
+li {
+    list-style: circle;
+}

client/doc/index.rst

@@ -30,7 +30,7 @@
     asyncio.run(main())
 
 * Are you new here? Jump straight into :doc:`basic/installation`!
-* Looking for the Client API reference? See :doc:`modules/client`.
+* Looking for the Client API reference? See the :doc:`Client class <modules/client>`.
 * Did you upgrade the library? Please read :doc:`developing/changelog`.
 * Coming from Bot API or want to create new bots? See :doc:`concepts/botapi-vs-mtproto`.
 * Used Telethon before v2.0? See :doc:`developing/migration-guide`.

client/doc/modules/sessions.rst

@@ -1,7 +1,18 @@
 Sessions
 ========
 
-.. currentmodule:: telethon.session
+Classes related to session data and session storages.
+
+.. note::
+
+    This module is mostly of interest if you plan to write a custom session storage.
+    You should not need to interact with these types directly under normal use.
+
+.. seealso::
+
+    The :doc:`/concepts/sessions` concept for more details.
+
+.. module:: telethon.session
 
 Storages
 --------

client/doc/modules/types.rst

@@ -68,3 +68,19 @@ Errors
                 await asyncio.sleep(e.value)
             else:
                 raise
+
+Private definitions
+-------------------
+
+.. warning::
+
+    These are **not** intended to be imported directly.
+    They are *not* available from :mod:`telethon.types`.
+
+    This section exists for documentation purposes only.
+
+.. currentmodule:: telethon._impl.client.types.async_list
+
+.. data:: T
+
+    Generic parameter used by :class:`AsyncList`.

client/src/telethon/_impl/client/client/client.py

@@ -558,7 +558,7 @@ class Client:
 
         .. seealso::
 
-            :meth:`telethon.types.Message.forward_to`
+            :meth:`telethon.types.Message.forward`
         """
         return await forward_messages(self, target, message_ids, source)
 
@@ -1292,7 +1292,7 @@ class Client:
         :param name:
             Override for the default file name.
 
-            When given a string or path, the :attr:`pathlib.Path.name` will be used by default only if this parameter is omitted.
+            When given a string or path, its :attr:`~pathlib.PurePath.name` will be used by default only if this parameter is omitted.
 
             This parameter **must** be specified when sending a previously-opened or in-memory files.
             The library will not attempt to read any ``name`` attributes the object may have.

client/src/telethon/_impl/client/events/filters/messages.py

@@ -144,9 +144,6 @@ class TextOnly:
     """
 
 
-MediaType = Union[Literal["photo"], Literal["audio"], Literal["video"]]
-
-
 class Media:
     """
     Filter by the media type in the message.
@@ -166,11 +163,15 @@ class Media:
 
     __slots__ = "_types"
 
-    def __init__(self, *types: MediaType) -> None:
+    def __init__(
+        self, *types: Union[Literal["photo"], Literal["audio"], Literal["video"]]
+    ) -> None:
         self._types = types or None
 
     @property
-    def types(self) -> Tuple[MediaType, ...]:
+    def types(
+        self,
+    ) -> Tuple[Union[Literal["photo"], Literal["audio"], Literal["video"]], ...]:
         """
         The media types being checked.
         """

client/src/telethon/_impl/client/types/async_list.py

@@ -9,8 +9,8 @@ class AsyncList(abc.ABC, Generic[T]):
     """
     An asynchronous list.
 
-    It can be awaited to get all the items as a normal `list`,
+    It can be awaited to get all the items as a normal :class:`list`,
-    or iterated over via `async for`.
+    or iterated over via `async for <https://docs.python.org/3/reference/compound_stmts.html#the-async-for-statement>`_.
 
     Both approaches will perform as many requests as needed to retrieve the
     items, but awaiting will need to do it all at once, which can be slow.
@@ -18,10 +18,25 @@ class AsyncList(abc.ABC, Generic[T]):
     Using asynchronous iteration will perform the requests lazily as needed,
     and lets you break out of the loop at any time to stop fetching items.
 
-    The `len()` of the asynchronous list will be the "total count" reported
+    The :func:`len` of the asynchronous list will be the "total count" reported
     by the server. It does not necessarily reflect how many items will
     actually be returned. This count can change as more items are fetched.
     Note that this method cannot be awaited.
+
+    .. rubric:: Example
+
+    :meth:`telethon.Client.get_messages` returns an :class:`AsyncList`\ [:class:`Message`].
+    This means:
+
+    .. code-block:: python
+
+        # You can await it directly:
+        messages = await client.get_messages(chat, 1)
+        # ...and now messages is a normal list with a single Message.
+
+        # Or you can use async for:
+        async for mesasge in client.get_messages(chat, 1):
+            ...  # the messages are fetched lazily, rather than all up-front.
     """
 
     def __init__(self) -> None:

client/src/telethon/_impl/client/types/chat/channel.py

@@ -8,6 +8,9 @@ from ..meta import NoPublicConstructor
 class Channel(metaclass=NoPublicConstructor):
     """
     A broadcast channel.
+
+    You can get a channel from messages via :attr:`telethon.types.Message.chat`,
+    or from methods such as :meth:`telethon.Client.resolve_username`.
     """
 
     __slots__ = ("_raw",)

client/src/telethon/_impl/client/types/chat/group.py

@@ -8,6 +8,9 @@ from ..meta import NoPublicConstructor
 class Group(metaclass=NoPublicConstructor):
     """
     A small group or supergroup.
+
+    You can get a group from messages via :attr:`telethon.types.Message.chat`,
+    or from methods such as :meth:`telethon.Client.resolve_username`.
     """
 
     __slots__ = ("_raw",)

client/src/telethon/_impl/client/types/chat/user.py

@@ -36,6 +36,9 @@ class RestrictionReason(metaclass=NoPublicConstructor):
 class User(metaclass=NoPublicConstructor):
     """
     A user, representing either a bot account or an account created with a phone number.
+
+    You can get a user from messages via :attr:`telethon.types.Message.sender`,
+    or from methods such as :meth:`telethon.Client.resolve_username`.
     """
 
     __slots__ = ("_raw",)

client/src/telethon/_impl/client/types/dialog.py

@@ -12,6 +12,8 @@ class Dialog(metaclass=NoPublicConstructor):
     This represents an open conversation your chat list.
 
     This includes the groups you've joined, channels you've subscribed to, and open one-to-one private conversations.
+
+    You can obtain dialogs with methods such as :meth:`telethon.Client.get_dialogs`.
     """
 
     __slots__ = ("_raw", "_chat_map")

client/src/telethon/_impl/client/types/draft.py

@@ -8,6 +8,8 @@ from .meta import NoPublicConstructor
 class Draft(metaclass=NoPublicConstructor):
     """
     A draft message in a chat.
+
+    You can obtain drafts with methods such as :meth:`telethon.Client.get_drafts`.
     """
 
     __slots__ = ("_raw", "_chat_map")

client/src/telethon/_impl/client/types/file.py

@@ -72,6 +72,9 @@ class InFileLike(Protocol):
     """
     A :term:`file-like object` used for input only.
     The :meth:`read` method can be :keyword:`async`.
+
+    This is never returned and should never be constructed.
+    It's only used in function parameters.
     """
 
     def read(self, n: int) -> Union[bytes, Coroutine[Any, Any, bytes]]:
@@ -87,6 +90,9 @@ class OutFileLike(Protocol):
     """
     A :term:`file-like object` used for output only.
     The :meth:`write` method can be :keyword:`async`.
+
+    This is never returned and should never be constructed.
+    It's only used in function parameters.
     """
 
     def write(self, data: bytes) -> Union[Any, Coroutine[Any, Any, Any]]:
@@ -126,6 +132,9 @@ class OutWrapper:
 class File(metaclass=NoPublicConstructor):
     """
     File information of media sent to Telegram that can be downloaded.
+
+    You can get a file from messages via :attr:`telethon.types.Message.file`,
+    or from methods such as :meth:`telethon.Client.get_profile_photos`.
     """
 
     def __init__(
@@ -292,7 +301,7 @@ class File(metaclass=NoPublicConstructor):
         """
         The file extension, including the leading dot ``.``.
 
-        If the name is not known, the mime-type is used in :meth:`mimetypes.guess_extension`.
+        If the name is not known, the mime-type is used in :func:`mimetypes.guess_extension`.
 
         If no extension is known for the mime-type, the empty string will be returned.
         This makes it safe to always append this property to a file name.

client/src/telethon/_impl/client/types/inline_result.py

@@ -47,7 +47,7 @@ class InlineResult(metaclass=NoPublicConstructor):
         :param chat:
             The chat where the inline result should be sent to.
 
-            This can be omitted if a chat was previously specified in the :meth:`~Client.inline_query`.
+            This can be omitted if a chat was previously specified in the :meth:`~telethon.Client.inline_query`.
 
         :return: The sent message.
         """

client/src/telethon/_impl/client/types/message.py

@@ -17,6 +17,9 @@ if TYPE_CHECKING:
 class Message(metaclass=NoPublicConstructor):
     """
     A sent message.
+
+    You can get a message from :class:`telethon.events.NewMessage`,
+    or from methods such as :meth:`telethon.Client.get_messages`.
     """
 
     __slots__ = ("_client", "_raw", "_chat_map")
@@ -154,14 +157,14 @@ class Message(metaclass=NoPublicConstructor):
 
         .. seealso::
 
-            :meth:`get_reply_message`
+            :meth:`get_replied_message`
         """
         if header := getattr(self._raw, "reply_to", None):
             return getattr(header, "reply_to_msg_id", None)
 
         return None
 
-    async def get_reply_message(self) -> Optional[Message]:
+    async def get_replied_message(self) -> Optional[Message]:
         """
         Alias for :meth:`telethon.Client.get_messages_with_ids`.
 

client/src/telethon/_impl/client/types/participant.py

@@ -8,6 +8,8 @@ from .meta import NoPublicConstructor
 class Participant(metaclass=NoPublicConstructor):
     """
     A participant in a chat, including the corresponding user and permissions.
+
+    You can obtain participants with methods such as :meth:`telethon.Client.get_participants`.
     """
 
     __slots__ = ("_raw", "_chat_map")

client/src/telethon/_impl/client/types/recent_action.py

@@ -10,6 +10,8 @@ class RecentAction(metaclass=NoPublicConstructor):
     A recent action in a chat, also known as an "admin log event action" or :tl:`ChannelAdminLogEvent`.
 
     Only administrators of the chat can access these.
+
+    You can obtain recent actions with methods such as :meth:`telethon.Client.get_admin_log`.
     """
 
     __slots__ = ("_raw", "_chat_map")

client/src/telethon/_impl/session/chat/packed.py

@@ -25,6 +25,9 @@ class PackedChat:
 
     You can reuse it as many times as you want.
 
+    You can call ``chat.pack()`` on :class:`~telethon.types.User`,
+    :class:`~telethon.types.Group` or :class:`~telethon.types.Channel` to obtain it.
+
     .. seealso::
 
         :doc:`/concepts/chats`

client/src/telethon/events/__init__.py

@@ -1,7 +1,9 @@
 """
 Classes related to the different event types that wrap incoming Telegram updates.
 
-See the :doc:`/concepts/updates` concept for more details.
+.. seealso::
+
+    The :doc:`/concepts/updates` concept to learn how to listen to these events.
 """
 from .._impl.client.events import (
     CallbackQuery,

client/src/telethon/session.py

@@ -1,8 +1,3 @@
-"""
-Classes related to session data and session storages.
-
-See the :doc:`/concepts/sessions` concept for more details.
-"""
 from ._impl.session import (
     ChannelState,
     DataCenter,

client/src/telethon/types.py

@@ -1,13 +1,13 @@
 """
 Classes for the various objects the library returns.
 """
-from ._impl.client.client import Config
 from ._impl.client.types import (
     AsyncList,
     Channel,
     Chat,
     ChatLike,
     Dialog,
+    Draft,
     File,
     Group,
     InFileLike,
@@ -17,19 +17,20 @@ from ._impl.client.types import (
     OutFileLike,
     Participant,
     PasswordToken,
+    RecentAction,
     RestrictionReason,
     User,
 )
 from ._impl.session import PackedChat, PackedType
 
 __all__ = [
-    "Config",
     "InlineResult",
     "AsyncList",
     "Channel",
     "Chat",
     "ChatLike",
     "Dialog",
+    "Draft",
     "File",
     "Group",
     "InFileLike",
@@ -38,6 +39,7 @@ __all__ = [
     "OutFileLike",
     "Participant",
     "PasswordToken",
+    "RecentAction",
     "RestrictionReason",
     "User",
     "PackedChat",

tools/docgen.py

@@ -10,7 +10,7 @@ def run(*args: str) -> int:
 
 
 def main() -> None:
-    exit(run("sphinx", "-nW", "client/doc", "dist-doc"))
+    exit(run("sphinx", "-n", "client/doc", "dist-doc"))
 
 
 if __name__ == "__main__":