diff --git a/client/doc/_static/custom.css b/client/doc/_static/custom.css index c6094f81..3909557e 100644 --- a/client/doc/_static/custom.css +++ b/client/doc/_static/custom.css @@ -18,3 +18,7 @@ background-color: unset; color: unset; } + +li { + list-style: circle; +} diff --git a/client/doc/index.rst b/client/doc/index.rst index e1b32122..783a0201 100644 --- a/client/doc/index.rst +++ b/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 `. * 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`. diff --git a/client/doc/modules/sessions.rst b/client/doc/modules/sessions.rst index aedfcd80..8453fdf1 100644 --- a/client/doc/modules/sessions.rst +++ b/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 -------- diff --git a/client/doc/modules/types.rst b/client/doc/modules/types.rst index 8ec7cf96..3f955b8b 100644 --- a/client/doc/modules/types.rst +++ b/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`. diff --git a/client/src/telethon/_impl/client/client/client.py b/client/src/telethon/_impl/client/client/client.py index f890798b..aef49473 100644 --- a/client/src/telethon/_impl/client/client/client.py +++ b/client/src/telethon/_impl/client/client/client.py @@ -497,10 +497,10 @@ class Client: :param message_id: The identifier of the message to edit. - :param text: See :ref:`formatting `. - :param markdown: See :ref:`formatting `. - :param html: See :ref:`formatting `. - :param link_preview: See :ref:`formatting `. + :param text: See :ref:`formatting`. + :param markdown: See :ref:`formatting`. + :param html: See :ref:`formatting`. + :param link_preview: See :ref:`formatting`. :return: The edited message. @@ -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. diff --git a/client/src/telethon/_impl/client/events/filters/messages.py b/client/src/telethon/_impl/client/events/filters/messages.py index c5a3b398..fa451192 100644 --- a/client/src/telethon/_impl/client/events/filters/messages.py +++ b/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. """ diff --git a/client/src/telethon/_impl/client/types/async_list.py b/client/src/telethon/_impl/client/types/async_list.py index eeb924ed..b93256b7 100644 --- a/client/src/telethon/_impl/client/types/async_list.py +++ b/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`, - or iterated over via `async for`. + It can be awaited to get all the items as a normal :class:`list`, + or iterated over via `async for `_. 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: diff --git a/client/src/telethon/_impl/client/types/chat/channel.py b/client/src/telethon/_impl/client/types/chat/channel.py index 7f106589..3228368e 100644 --- a/client/src/telethon/_impl/client/types/chat/channel.py +++ b/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",) diff --git a/client/src/telethon/_impl/client/types/chat/group.py b/client/src/telethon/_impl/client/types/chat/group.py index d1dd968e..6eba2602 100644 --- a/client/src/telethon/_impl/client/types/chat/group.py +++ b/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",) diff --git a/client/src/telethon/_impl/client/types/chat/user.py b/client/src/telethon/_impl/client/types/chat/user.py index 9917faba..1b76aa12 100644 --- a/client/src/telethon/_impl/client/types/chat/user.py +++ b/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",) diff --git a/client/src/telethon/_impl/client/types/dialog.py b/client/src/telethon/_impl/client/types/dialog.py index e0d12b64..76989789 100644 --- a/client/src/telethon/_impl/client/types/dialog.py +++ b/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") diff --git a/client/src/telethon/_impl/client/types/draft.py b/client/src/telethon/_impl/client/types/draft.py index 04f4c9ce..391f420f 100644 --- a/client/src/telethon/_impl/client/types/draft.py +++ b/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") diff --git a/client/src/telethon/_impl/client/types/file.py b/client/src/telethon/_impl/client/types/file.py index 6aa3d37e..21e428c8 100644 --- a/client/src/telethon/_impl/client/types/file.py +++ b/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. diff --git a/client/src/telethon/_impl/client/types/inline_result.py b/client/src/telethon/_impl/client/types/inline_result.py index 86471a6f..209271be 100644 --- a/client/src/telethon/_impl/client/types/inline_result.py +++ b/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. """ diff --git a/client/src/telethon/_impl/client/types/message.py b/client/src/telethon/_impl/client/types/message.py index 299f5df6..78cfb79b 100644 --- a/client/src/telethon/_impl/client/types/message.py +++ b/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`. diff --git a/client/src/telethon/_impl/client/types/participant.py b/client/src/telethon/_impl/client/types/participant.py index 912eadd1..4ec09a06 100644 --- a/client/src/telethon/_impl/client/types/participant.py +++ b/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") diff --git a/client/src/telethon/_impl/client/types/recent_action.py b/client/src/telethon/_impl/client/types/recent_action.py index f93a011d..19c178a8 100644 --- a/client/src/telethon/_impl/client/types/recent_action.py +++ b/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") diff --git a/client/src/telethon/_impl/session/chat/packed.py b/client/src/telethon/_impl/session/chat/packed.py index da31c139..00e27164 100644 --- a/client/src/telethon/_impl/session/chat/packed.py +++ b/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` diff --git a/client/src/telethon/events/__init__.py b/client/src/telethon/events/__init__.py index 220eabb2..93b11e34 100644 --- a/client/src/telethon/events/__init__.py +++ b/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, diff --git a/client/src/telethon/session.py b/client/src/telethon/session.py index a87159ae..eda49dd2 100644 --- a/client/src/telethon/session.py +++ b/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, diff --git a/client/src/telethon/types.py b/client/src/telethon/types.py index 482fb856..17a271c0 100644 --- a/client/src/telethon/types.py +++ b/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", diff --git a/tools/docgen.py b/tools/docgen.py index 9a5960ea..29ed054f 100644 --- a/tools/docgen.py +++ b/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__":