From 8e36bb4c4d1881178d47a6f0861339a67fe536c9 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Sat, 6 Jul 2019 12:10:25 +0200 Subject: [PATCH] Link Python keywords with Python's documentation --- readthedocs/concepts/full-api.rst | 2 +- readthedocs/concepts/updates.rst | 4 +-- readthedocs/developing/test-servers.rst | 2 +- readthedocs/examples/chats-and-channels.rst | 8 ++--- readthedocs/misc/changelog.rst | 38 ++++++++++---------- telethon/client/account.py | 24 ++++++------- telethon/client/auth.py | 10 +++--- telethon/client/chats.py | 40 ++++++++++----------- telethon/client/dialogs.py | 12 +++---- telethon/client/downloads.py | 14 ++++---- telethon/client/messageparse.py | 4 +-- telethon/client/messages.py | 32 ++++++++--------- telethon/client/telegrambaseclient.py | 12 +++---- telethon/client/uploads.py | 22 ++++++------ telethon/client/users.py | 6 ++-- telethon/events/__init__.py | 4 +-- telethon/events/album.py | 8 ++--- telethon/events/callbackquery.py | 18 +++++----- telethon/events/chataction.py | 28 +++++++-------- telethon/events/common.py | 2 +- telethon/events/inlinequery.py | 2 +- telethon/events/messageedited.py | 2 +- telethon/events/messageread.py | 14 ++++---- telethon/events/newmessage.py | 12 +++---- telethon/requestiter.py | 4 +-- telethon/sessions/abstract.py | 4 +-- telethon/statecache.py | 4 +-- telethon/tl/custom/adminlogevent.py | 34 +++++++++--------- telethon/tl/custom/button.py | 4 +-- telethon/tl/custom/chatgetter.py | 10 +++--- telethon/tl/custom/dialog.py | 8 ++--- telethon/tl/custom/draft.py | 4 +-- telethon/tl/custom/file.py | 2 +- telethon/tl/custom/inlinebuilder.py | 2 +- telethon/tl/custom/inlineresult.py | 8 ++--- telethon/tl/custom/inlineresults.py | 2 +- telethon/tl/custom/message.py | 40 ++++++++++----------- telethon/tl/custom/messagebutton.py | 8 ++--- telethon/tl/custom/sendergetter.py | 2 +- telethon/utils.py | 20 +++++------ 40 files changed, 238 insertions(+), 238 deletions(-) diff --git a/readthedocs/concepts/full-api.rst b/readthedocs/concepts/full-api.rst index 2b1a6462..0c3119fb 100644 --- a/readthedocs/concepts/full-api.rst +++ b/readthedocs/concepts/full-api.rst @@ -62,7 +62,7 @@ If you're going to use a lot of these, you may do: We see that this request must take at least two parameters, a ``peer`` of type :tl:`InputPeer`, and a ``message`` which is just a Python -``str``\ ing. +`str`\ ing. How can we retrieve this :tl:`InputPeer`? We have two options. We manually construct one, for instance: diff --git a/readthedocs/concepts/updates.rst b/readthedocs/concepts/updates.rst index a5b978de..0c80c344 100644 --- a/readthedocs/concepts/updates.rst +++ b/readthedocs/concepts/updates.rst @@ -12,7 +12,7 @@ can access all the properties it has, like ``.sender``. **However** events are different to other methods in the client, like `client.get_messages `. Events *may not* send information about the sender or chat, which means it -can be ``None``, but all the methods defined in the client always have this +can be `None`, but all the methods defined in the client always have this information so it doesn't need to be re-fetched. For this reason, you have ``get_`` methods, which will make a network call if necessary. @@ -113,7 +113,7 @@ and `client.list_event_handlers `. The ``event`` argument is optional in all three methods and defaults to -`events.Raw ` for adding, and ``None`` when +`events.Raw ` for adding, and `None` when removing (so all callbacks would be removed). .. note:: diff --git a/readthedocs/developing/test-servers.rst b/readthedocs/developing/test-servers.rst index 98f93755..5210c8b6 100644 --- a/readthedocs/developing/test-servers.rst +++ b/readthedocs/developing/test-servers.rst @@ -12,7 +12,7 @@ To run Telethon on a test server, use the following code: You can check your ``'test ip'`` on https://my.telegram.org. -You should set ``None`` session so to ensure you're generating a new +You should set `None` session so to ensure you're generating a new authorization key for it (it would fail if you used a session where you had previously connected to another data center). diff --git a/readthedocs/examples/chats-and-channels.rst b/readthedocs/examples/chats-and-channels.rst index fa485c59..047ec8af 100644 --- a/readthedocs/examples/chats-and-channels.rst +++ b/readthedocs/examples/chats-and-channels.rst @@ -15,7 +15,7 @@ Joining a chat or channel Note that :tl:`Chat` are normal groups, and :tl:`Channel` are a special form of :tl:`Chat`, which can also be super-groups if -their ``megagroup`` member is ``True``. +their ``megagroup`` member is `True`. Joining a public channel @@ -142,7 +142,7 @@ Giving or revoking admin permissions can be done with the :tl:`EditAdminRequest` .. note:: Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all - parameters to ``True`` to give a user full permissions, as not all + parameters to `True` to give a user full permissions, as not all permissions are related to both broadcast channels/megagroups. E.g. trying to set ``post_messages=True`` in a megagroup will raise an @@ -167,8 +167,8 @@ banned rights of a user through :tl:`EditBannedRequest` and its parameter # Restricting a user for 7 days, only allowing view/send messages. # - # Note that it's "reversed". You must set to ``True`` the permissions - # you want to REMOVE, and leave as ``None`` those you want to KEEP. + # Note that it's "reversed". You must set to `True` the permissions + # you want to REMOVE, and leave as `None` those you want to KEEP. rights = ChatBannedRights( until_date=timedelta(days=7), view_messages=None, diff --git a/readthedocs/misc/changelog.rst b/readthedocs/misc/changelog.rst index 44fc2b4b..330130a9 100644 --- a/readthedocs/misc/changelog.rst +++ b/readthedocs/misc/changelog.rst @@ -360,7 +360,7 @@ Enhancements * Cleared up some parts of the documentation. * Improved some auto-casts to make life easier. -* Improved image detection. Now you can easily send ``bytes`` +* Improved image detection. Now you can easily send `bytes` and streams of images as photos, unless you force document. * Sending images as photos that are too large will now be resized before uploading, reducing the time it takes to upload them and @@ -479,7 +479,7 @@ object.to_json() (v1.5.1) The library already had a way to easily convert the objects the API returned into dictionaries through ``object.to_dict()``, but some of the fields are -dates or ``bytes`` which JSON can't serialize directly. +dates or `bytes` which JSON can't serialize directly. For convenience, a new ``object.to_json()`` has been added which will by default format both of those problematic types into something sensible. @@ -509,7 +509,7 @@ Enhancements ` as a bot. * More properties for `Message ` to make accessing media convenient. -* Downloading to ``file=bytes`` will now return a ``bytes`` object +* Downloading to ``file=bytes`` will now return a `bytes` object with the downloaded media. @@ -749,7 +749,7 @@ Breaking Changes * ``.sender`` is the ``.chat`` when the message is sent in a broadcast channel. This makes sense, because the sender of the message was the channel itself, but you now must take into consideration that it may - be either a :tl:`User` or :tl:`Channel` instead of being ``None``. + be either a :tl:`User` or :tl:`Channel` instead of being `None`. Additions @@ -850,7 +850,7 @@ Additions `. - Implemented global search through `client.iter_messages ` - with ``None`` entity. + with `None` entity. - New `client.inline_query ` method to perform inline queries. - Bot-API-style ``file_id`` can now be used to send files and download media. @@ -989,7 +989,7 @@ Bug fixes - Empty ``except`` are no longer used which means sending a keyboard interrupt should now work properly. -- The ``pts`` of incoming updates could be ``None``. +- The ``pts`` of incoming updates could be `None`. - UTC timezone information is properly set for read ``datetime``. - Some infinite recursion bugs in the custom message class. - :tl:`Updates` was being dispatched to raw handlers when it shouldn't. @@ -1093,7 +1093,7 @@ Additions Bug fixes ~~~~~~~~~ -- Count was always ``None`` for `message.button_count +- Count was always `None` for `message.button_count `. - Some fixes when disconnecting upon dropping the client. - Support for Python 3.4 in the sync version, and fix media download. @@ -1297,7 +1297,7 @@ Breaking Changes ``telethon.errors.rpc_error_list`` won't work, but you should have been using `telethon.errors` all this time instead. - `client.connect ` - no longer returns ``True`` on success. Instead, you should ``except`` the + no longer returns `True` on success. Instead, you should ``except`` the possible ``ConnectionError`` and act accordingly. This makes it easier to not ignore the error. - You can no longer set ``retries=n`` when calling a request manually. The @@ -1520,8 +1520,8 @@ Additions - Add ``search``, ``filter`` and ``from_user`` parameters to `telethon.telegram_client.TelegramClient.iter_messages`. - `telethon.telegram_client.TelegramClient.download_file` now - supports a ``None`` path to return the file in memory and - return its ``bytes``. + supports a `None` path to return the file in memory and + return its `bytes`. - Events now have a ``.original_update`` field. Bug fixes @@ -2079,8 +2079,8 @@ Bug fixes setting no last name). - Fix invalid assertion regarding flag parameters as well. - Avoid joining the background thread on disconnect, as it would be - ``None`` due to a race condition. -- Correctly handle ``None`` dates when downloading media. + `None` due to a race condition. +- Correctly handle `None` dates when downloading media. - ``.download_profile_photo`` was failing for some channels. - ``.download_media`` wasn't handling ``Photo``. @@ -2144,7 +2144,7 @@ Bug fixes - Getting an entity using their phone wasn't actually working. - Full entities aren't saved unless they have an ``access_hash``, to - avoid some ``None`` errors. + avoid some `None` errors. - ``.get_message_history`` was failing when retrieving items that had messages forwarded from a channel. @@ -2200,7 +2200,7 @@ Internal changes - The ``auth_key`` generation has been moved from ``.connect()`` to ``.invoke()``. There were some issues were ``.connect()`` failed and - the ``auth_key`` was ``None`` so this will ensure to have a valid + the ``auth_key`` was `None` so this will ensure to have a valid ``auth_key`` when needed, even if ``BrokenAuthKeyError`` is raised. - Support for higher limits on ``.get_history()`` and ``.get_dialogs()``. @@ -2351,7 +2351,7 @@ Enhancements - You can **invoke** requests from **update handlers**. And **any other thread**. A new temporary will be made, so that you can be sending even several requests at the same time! -- **Several worker threads** for your updates! By default, ``None`` +- **Several worker threads** for your updates! By default, `None` will spawn. I recommend you to work with ``update_workers=4`` to get started, these will be polling constantly for updates. - You can also change the number of workers at any given time. @@ -2426,8 +2426,8 @@ Bug fixes - **Important**, related to the serialization. Every object or request that had to serialize a ``True/False`` type was always being serialized - as ``false``! -- Another bug that didn't allow you to leave as ``None`` flag parameters + as `false`! +- Another bug that didn't allow you to leave as `None` flag parameters that needed a list has been fixed. Internal changes @@ -2512,7 +2512,7 @@ should have been on ``v0.13.5`` but were missed. Specifically, the Some other additions are a tiny fix when **handling updates**, which was ignoring some of them, nicer ``__str__`` and ``.stringify()`` methods for the ``TLObject``\ 's, and not stopping the ``ReadThread`` if you try -invoking something there (now it simply returns ``None``). +invoking something there (now it simply returns `None`). Attempts at more stability (v0.13.5) ==================================== @@ -2741,7 +2741,7 @@ Additions ``TelegramClient`` constructor (using ``**kwargs``). - ``RPCError``\ 's now belong to some request you've made, which makes more sense. -- ``get_input_*`` now handles ``None`` (default) parameters more +- ``get_input_*`` now handles `None` (default) parameters more gracefully (it used to crash). .. enhancements-4: diff --git a/telethon/client/account.py b/telethon/client/account.py index eaa4cf89..e21974c1 100644 --- a/telethon/client/account.py +++ b/telethon/client/account.py @@ -134,8 +134,8 @@ class AccountMethods: to adjust the `wait_time` of methods like `client.iter_messages `. - By default, all parameters are ``None``, and you need to enable those - you plan to use by setting them to either ``True`` or ``False``. + By default, all parameters are `None`, and you need to enable those + you plan to use by setting them to either `True` or `False`. You should ``except errors.TakeoutInitDelayError as e``, since this exception will raise depending on the condition of the session. You @@ -144,10 +144,10 @@ class AccountMethods: There's also a `success` property available in the takeout proxy object, so from the `with` body you can set the boolean result that - will be sent back to Telegram. But if it's left ``None`` as by + will be sent back to Telegram. But if it's left `None` as by default, then the action is based on the `finalize` parameter. If - it's ``True`` then the takeout will be finished, and if no exception - occurred during it, then ``True`` will be considered as a result. + it's `True` then the takeout will be finished, and if no exception + occurred during it, then `True` will be considered as a result. Otherwise, the takeout will not be finished and its ID will be preserved for future usage as `client.session.takeout_id `. @@ -158,26 +158,26 @@ class AccountMethods: exit or not. contacts (`bool`): - Set to ``True`` if you plan on downloading contacts. + Set to `True` if you plan on downloading contacts. users (`bool`): - Set to ``True`` if you plan on downloading information + Set to `True` if you plan on downloading information from users and their private conversations with you. chats (`bool`): - Set to ``True`` if you plan on downloading information + Set to `True` if you plan on downloading information from small group chats, such as messages and media. megagroups (`bool`): - Set to ``True`` if you plan on downloading information + Set to `True` if you plan on downloading information from megagroups (channels), such as messages and media. channels (`bool`): - Set to ``True`` if you plan on downloading information + Set to `True` if you plan on downloading information from broadcast channels, such as messages and media. files (`bool`): - Set to ``True`` if you plan on downloading media and + Set to `True` if you plan on downloading media and you don't only wish to export messages. max_file_size (`int`): @@ -228,7 +228,7 @@ class AccountMethods: Whether the takeout completed successfully or not. Returns - ``True`` if the operation was successful, ``False`` otherwise. + `True` if the operation was successful, `False` otherwise. Example .. code-block:: python diff --git a/telethon/client/auth.py b/telethon/client/auth.py index c201c112..0ba7225d 100644 --- a/telethon/client/auth.py +++ b/telethon/client/auth.py @@ -296,7 +296,7 @@ class AuthMethods: phone_code_hash (`str`, optional): The hash returned by `send_code_request`. This can be left as - ``None`` to use the last hash known for the phone to be used. + `None` to use the last hash known for the phone to be used. Returns The signed in user, or the information about @@ -379,7 +379,7 @@ class AuthMethods: phone_code_hash (`str`, optional): The hash returned by `send_code_request`. This can be left as - ``None`` to use the last hash known for the phone to be used. + `None` to use the last hash known for the phone to be used. Returns The new created :tl:`User`. @@ -495,7 +495,7 @@ class AuthMethods: Logs out Telegram and deletes the current ``*.session`` file. Returns - ``True`` if the operation was successful. + `True` if the operation was successful. Example .. code-block:: python @@ -546,7 +546,7 @@ class AuthMethods: new_password (`str`, optional): The password to set as 2FA. If 2FA was already enabled, ``current_password`` **must** be set. - Leaving this blank or ``None`` will remove the password. + Leaving this blank or `None` will remove the password. hint (`str`, optional): Hint to be displayed by Telegram when it asks for 2FA. @@ -567,7 +567,7 @@ class AuthMethods: ``CodeInvalidError``. Returns - ``True`` if successful, ``False`` otherwise. + `True` if successful, `False` otherwise. Example .. code-block:: python diff --git a/telethon/client/chats.py b/telethon/client/chats.py index aefaaa4c..45658ffd 100644 --- a/telethon/client/chats.py +++ b/telethon/client/chats.py @@ -476,9 +476,9 @@ class ChatMethods: Note that you must be an administrator of it to use this method. - If none of the filters are present (i.e. they all are ``None``), + If none of the filters are present (i.e. they all are `None`), *all* event types will be returned. If at least one of them is - ``True``, only those that are true will be returned. + `True`, only those that are true will be returned. Arguments entity (`entity`): @@ -487,7 +487,7 @@ class ChatMethods: limit (`int` | `None`, optional): Number of events to be retrieved. - The limit may also be ``None``, which would eventually return + The limit may also be `None`, which would eventually return the whole history. max_id (`int`): @@ -507,53 +507,53 @@ class ChatMethods: returned. join (`bool`): - If ``True``, events for when a user joined will be returned. + If `True`, events for when a user joined will be returned. leave (`bool`): - If ``True``, events for when a user leaves will be returned. + If `True`, events for when a user leaves will be returned. invite (`bool`): - If ``True``, events for when a user joins through an invite + If `True`, events for when a user joins through an invite link will be returned. restrict (`bool`): - If ``True``, events with partial restrictions will be + If `True`, events with partial restrictions will be returned. This is what the API calls "ban". unrestrict (`bool`): - If ``True``, events removing restrictions will be returned. + If `True`, events removing restrictions will be returned. This is what the API calls "unban". ban (`bool`): - If ``True``, events applying or removing all restrictions will + If `True`, events applying or removing all restrictions will be returned. This is what the API calls "kick" (restricting all permissions removed is a ban, which kicks the user). unban (`bool`): - If ``True``, events removing all restrictions will be + If `True`, events removing all restrictions will be returned. This is what the API calls "unkick". promote (`bool`): - If ``True``, events with admin promotions will be returned. + If `True`, events with admin promotions will be returned. demote (`bool`): - If ``True``, events with admin demotions will be returned. + If `True`, events with admin demotions will be returned. info (`bool`): - If ``True``, events changing the group info will be returned. + If `True`, events changing the group info will be returned. settings (`bool`): - If ``True``, events changing the group settings will be + If `True`, events changing the group settings will be returned. pinned (`bool`): - If ``True``, events of new pinned messages will be returned. + If `True`, events of new pinned messages will be returned. edit (`bool`): - If ``True``, events of message edits will be returned. + If `True`, events of message edits will be returned. delete (`bool`): - If ``True``, events of message deletions will be returned. + If `True`, events of message deletions will be returned. Yields Instances of `AdminLogEvent `. @@ -626,7 +626,7 @@ class ChatMethods: limit (`int` | `None`, optional): Number of photos to be retrieved. - The limit may also be ``None``, which would eventually all + The limit may also be `None`, which would eventually all the photos that are still available. offset (`int`): @@ -725,7 +725,7 @@ class ChatMethods: auto_cancel (`bool`): Whether the action should be cancelled once the context - manager exists or not. The default is ``True``, since + manager exists or not. The default is `True`, since you don't want progress to be shown when it has already completed. @@ -905,7 +905,7 @@ class ChatMethods: user (`entity`, optional): If specified, the permission will be changed for the specific user. - If left as ``None``, the default chat permissions will be updated. + If left as `None`, the default chat permissions will be updated. until_date (`DateLike`, optional): When the user will be unbanned. diff --git a/telethon/client/dialogs.py b/telethon/client/dialogs.py index ee57d82e..1156bdd0 100644 --- a/telethon/client/dialogs.py +++ b/telethon/client/dialogs.py @@ -134,7 +134,7 @@ class DialogMethods: Arguments limit (`int` | `None`): How many dialogs to be retrieved as maximum. Can be set to - ``None`` to retrieve all dialogs. Note that this may take + `None` to retrieve all dialogs. Note that this may take whole minutes if you have hundreds of dialogs, as Telegram will tell the library to slow down through a ``FloodWaitError``. @@ -150,12 +150,12 @@ class DialogMethods: ignore_pinned (`bool`, optional): Whether pinned dialogs should be ignored or not. - When set to ``True``, these won't be yielded at all. + When set to `True`, these won't be yielded at all. ignore_migrated (`bool`, optional): Whether :tl:`Chat` that have ``migrated_to`` a :tl:`Channel` should be included or not. By default all the chats in your - dialogs are returned, but setting this to ``True`` will ignore + dialogs are returned, but setting this to `True` will ignore (i.e. skip) them in the same way official applications do. folder (`int`, optional): @@ -176,7 +176,7 @@ class DialogMethods: archived (`bool`, optional): Alias for `folder`. If unspecified, all will be returned, - ``False`` implies ``folder=0`` and ``True`` implies ``folder=1``. + `False` implies ``folder=0`` and `True` implies ``folder=1``. Yields Instances of `Dialog `. @@ -361,8 +361,8 @@ class DialogMethods: revoke (`bool`, optional): On private chats, you may revoke the messages from - the other peer too. By default, it's ``False``. Set - it to ``True`` to delete the history for both. + the other peer too. By default, it's `False`. Set + it to `True` to delete the history for both. Returns The :tl:`Updates` object that the request produces, diff --git a/telethon/client/downloads.py b/telethon/client/downloads.py index bb129724..5f14ceab 100644 --- a/telethon/client/downloads.py +++ b/telethon/client/downloads.py @@ -125,7 +125,7 @@ class _GenericDownloadIter(_DirectDownloadIter): self.request.offset = before # 2. Fill the buffer with the data we have - # 2.1. Slicing ``bytes`` is expensive, yield ``memoryview`` instead + # 2.1. Slicing `bytes` is expensive, yield `memoryview` instead mem = memoryview(data) # 2.2. The current chunk starts at ``bad`` offset into the data, @@ -189,7 +189,7 @@ class DownloadMethods: Whether to use the big version of the available photos. Returns - ``None`` if no photo was provided, or if it was Empty. On success + `None` if no photo was provided, or if it was Empty. On success the file path is returned since it may differ from the one given. Example @@ -303,7 +303,7 @@ class DownloadMethods: instead of downloading the document or photo itself. If it's specified but the file does not have a thumbnail, - this method will return ``None``. + this method will return `None`. The parameter should be an integer index between ``0`` and ``len(sizes)``. ``0`` will download the smallest thumbnail, @@ -316,7 +316,7 @@ class DownloadMethods: and ``thumb=-1`` if you want the largest thumbnail. Returns - ``None`` if no media was provided, or if it was Empty. On success + `None` if no media was provided, or if it was Empty. On success the file path is returned since it may differ from the one given. Example @@ -382,7 +382,7 @@ class DownloadMethods: The output file path, directory, or stream-like object. If the path exists and is a file, it will be overwritten. - If the file path is ``None`` or ``bytes``, then the result + If the file path is `None` or `bytes`, then the result will be saved in memory and returned as `bytes`. part_size_kb (`int`, optional): @@ -519,8 +519,8 @@ class DownloadMethods: Yields - ``bytes`` objects representing the chunks of the file if the - right conditions are met, or ``memoryview`` objects instead. + `bytes` objects representing the chunks of the file if the + right conditions are met, or `memoryview` objects instead. Example .. code-block:: python diff --git a/telethon/client/messageparse.py b/telethon/client/messageparse.py index 80eabbb2..9e5e20a9 100644 --- a/telethon/client/messageparse.py +++ b/telethon/client/messageparse.py @@ -18,14 +18,14 @@ class MessageParseMethods: """ This property is the default parse mode used when sending messages. Defaults to `telethon.extensions.markdown`. It will always - be either ``None`` or an object with ``parse`` and ``unparse`` + be either `None` or an object with ``parse`` and ``unparse`` methods. When setting a different value it should be one of: * Object with ``parse`` and ``unparse`` methods. * A ``callable`` to act as the parse method. - * A ``str`` indicating the ``parse_mode``. For Markdown ``'md'`` + * A `str` indicating the ``parse_mode``. For Markdown ``'md'`` or ``'markdown'`` may be used. For HTML, ``'htm'`` or ``'html'`` may be used. diff --git a/telethon/client/messages.py b/telethon/client/messages.py index 1edfb6bd..d4b18c92 100644 --- a/telethon/client/messages.py +++ b/telethon/client/messages.py @@ -19,7 +19,7 @@ class _MessagesIter(RequestIter): self, entity, offset_id, min_id, max_id, from_user, offset_date, add_offset, filter, search ): - # Note that entity being ``None`` will perform a global search. + # Note that entity being `None` will perform a global search. if entity: self.entity = await self.client.get_input_entity(entity) else: @@ -331,7 +331,7 @@ class MessageMethods: entity (`entity`): The entity from whom to retrieve the message history. - It may be ``None`` to perform a global search, or + It may be `None` to perform a global search, or to get messages by their ID from no particular chat. Note that some of the offsets will not work if this is the case. @@ -344,7 +344,7 @@ class MessageMethods: the API retrieving more than 3000 messages will take longer than half a minute (or even more based on previous calls). - The limit may also be ``None``, which would eventually return + The limit may also be `None`, which would eventually return the whole history. offset_date (`datetime`): @@ -382,7 +382,7 @@ class MessageMethods: wait_time (`int`): Wait time (in seconds) between different :tl:`GetHistoryRequest`. Use this parameter to avoid hitting - the ``FloodWaitError`` as needed. If left to ``None``, it will + the ``FloodWaitError`` as needed. If left to `None`, it will default to 1 second only if the limit is higher than 3000. ids (`int`, `list`): @@ -390,7 +390,7 @@ class MessageMethods: should be returned. This parameter takes precedence over the rest (which will be ignored if this is set). This can for instance be used to get the message with ID 123 from - a channel. Note that if the message doesn't exist, ``None`` + a channel. Note that if the message doesn't exist, `None` will appear in its place, so that zipping the list of IDs with the messages can match one-to-one. @@ -404,7 +404,7 @@ class MessageMethods: careful if you use non-integers in this parameter. reverse (`bool`, optional): - If set to ``True``, the messages will be returned in reverse + If set to `True`, the messages will be returned in reverse order (from oldest to newest, instead of the default newest to oldest). This also means that the meaning of `offset_id` and `offset_date` parameters is reversed, although they will @@ -412,7 +412,7 @@ class MessageMethods: instead of being `max_id` as well since messages are returned in ascending order. - You cannot use this if both `entity` and `ids` are ``None``. + You cannot use this if both `entity` and `ids` are `None`. Yields Instances of `Message `. @@ -595,8 +595,8 @@ class MessageMethods: silent (`bool`, optional): Whether the message should notify people in a broadcast - channel or not. Defaults to ``False``, which means it will - notify them. Set it to ``True`` to alter this behaviour. + channel or not. Defaults to `False`, which means it will + notify them. Set it to `True` to alter this behaviour. Returns The sent `custom.Message `. @@ -761,8 +761,8 @@ class MessageMethods: silent (`bool`, optional): Whether the message should notify people in a broadcast - channel or not. Defaults to ``False``, which means it will - notify them. Set it to ``True`` to alter this behaviour. + channel or not. Defaults to `False`, which means it will + notify them. Set it to `True` to alter this behaviour. as_album (`bool`, optional): Whether several image messages should be forwarded as an @@ -772,8 +772,8 @@ class MessageMethods: are used. If IDs are used it will group by default. In short, the default should do what you expect, - ``True`` will group always (even converting separate - images into albums), and ``False`` will never group. + `True` will group always (even converting separate + images into albums), and `False` will never group. Returns The list of forwarded `Message `, @@ -781,7 +781,7 @@ class MessageMethods: Note that if all messages are invalid (i.e. deleted) the call will fail with ``MessageIdInvalidError``. If only some are - invalid, the list will have ``None`` instead of those messages. + invalid, the list will have `None` instead of those messages. Example .. code-block:: python @@ -1003,7 +1003,7 @@ class MessageMethods: Arguments entity (`entity`): From who the message will be deleted. This can actually - be ``None`` for normal chats, but **must** be present + be `None` for normal chats, but **must** be present for channels and megagroups. message_ids (`list` | `int` | `Message `): @@ -1142,7 +1142,7 @@ class MessageMethods: message (`int` | `Message `): The message or the message ID to pin. If it's - ``None``, the message will be unpinned instead. + `None`, the message will be unpinned instead. notify (`bool`, optional): Whether the pin should notify people or not. diff --git a/telethon/client/telegrambaseclient.py b/telethon/client/telegrambaseclient.py index e0fea3d2..1d09f3ad 100644 --- a/telethon/client/telegrambaseclient.py +++ b/telethon/client/telegrambaseclient.py @@ -39,7 +39,7 @@ class TelegramBaseClient(abc.ABC): session (`str` | `telethon.sessions.abstract.Session`, `None`): The file name of the session file to be used if a string is given (it may be a full path), or the Session instance to be - used otherwise. If it's ``None``, the session will not be saved, + used otherwise. If it's `None`, the session will not be saved, and you should call :meth:`.log_out()` when you're done. Note that if you pass a string it will be a file in the current @@ -64,7 +64,7 @@ class TelegramBaseClient(abc.ABC): use_ipv6 (`bool`, optional): Whether to connect to the servers through IPv6 or not. - By default this is ``False`` as IPv6 support is not + By default this is `False` as IPv6 support is not too widespread yet. proxy (`tuple` | `list` | `dict`, optional): @@ -87,14 +87,14 @@ class TelegramBaseClient(abc.ABC): when there is a ``errors.FloodWaitError`` less than `flood_sleep_threshold`, or when there's a migrate error. - May take a negative or ``None`` value for infinite retries, but + May take a negative or `None` value for infinite retries, but this is not recommended, since some requests can always trigger a call fail (such as searching for messages). connection_retries (`int` | `None`, optional): How many times the reconnection should retry, either on the initial connection or when Telegram disconnects us. May be - set to a negative or ``None`` value for infinite retries, but + set to a negative or `None` value for infinite retries, but this is not recommended, since the program can get stuck in an infinite loop. @@ -111,7 +111,7 @@ class TelegramBaseClient(abc.ABC): the order in which updates are processed to be sequential, and this setting allows them to do so. - If set to ``True``, incoming updates will be put in a queue + If set to `True`, incoming updates will be put in a queue and processed sequentially. This means your event handlers should *not* perform long-running operations since new updates are put inside of an unbounded queue. @@ -423,7 +423,7 @@ class TelegramBaseClient(abc.ABC): def is_connected(self: 'TelegramClient') -> bool: """ - Returns ``True`` if the user has connected. + Returns `True` if the user has connected. This method is **not** asynchronous (don't use ``await`` on it). diff --git a/telethon/client/uploads.py b/telethon/client/uploads.py index a405cccc..68e7825d 100644 --- a/telethon/client/uploads.py +++ b/telethon/client/uploads.py @@ -162,7 +162,7 @@ class UploadMethods: assigned to the files pairwise. force_document (`bool`, optional): - If left to ``False`` and the file is a path that ends with + If left to `False` and the file is a path that ends with the extension of an image file or a video file, it will be sent as such. Otherwise always as a document. @@ -187,8 +187,8 @@ class UploadMethods: allow_cache (`bool`, optional): Whether to allow using the cached version stored in the - database or not. Defaults to ``True`` to avoid re-uploads. - Must be ``False`` if you wish to use different attributes + database or not. Defaults to `True` to avoid re-uploads. + Must be `False` if you wish to use different attributes or thumb than those that were used when the file was cached. parse_mode (`object`, optional): @@ -198,16 +198,16 @@ class UploadMethods: default. voice_note (`bool`, optional): - If ``True`` the audio will be sent as a voice note. + If `True` the audio will be sent as a voice note. - Set `allow_cache` to ``False`` if you sent the same file + Set `allow_cache` to `False` if you sent the same file without this setting before for it to work. video_note (`bool`, optional): - If ``True`` the video will be sent as a video note, + If `True` the video will be sent as a video note, also known as a round video message. - Set `allow_cache` to ``False`` if you sent the same file + Set `allow_cache` to `False` if you sent the same file without this setting before for it to work. buttons (`list`, `custom.Button `, :tl:`KeyboardButton`): @@ -218,8 +218,8 @@ class UploadMethods: silent (`bool`, optional): Whether the message should notify people in a broadcast - channel or not. Defaults to ``False``, which means it will - notify them. Set it to ``True`` to alter this behaviour. + channel or not. Defaults to `False`, which means it will + notify them. Set it to `True` to alter this behaviour. supports_streaming (`bool`, optional): Whether the sent video supports streaming or not. Note that @@ -257,7 +257,7 @@ class UploadMethods: '/my/drawings/portrait.png' ]) """ - # i.e. ``None`` was used + # i.e. `None` was used if not file: raise TypeError('Cannot use {!r} as file'.format(file)) @@ -444,7 +444,7 @@ class UploadMethods: file_name (`str`, optional): The file name which will be used on the resulting InputFile. If not specified, the name will be taken from the ``file`` - and if this is not a ``str``, it will be ``"unnamed"``. + and if this is not a `str`, it will be ``"unnamed"``. use_cache (`type`, optional): The type of cache to use (currently either :tl:`InputDocument` diff --git a/telethon/client/users.py b/telethon/client/users.py index fafff8cd..7d352d0f 100644 --- a/telethon/client/users.py +++ b/telethon/client/users.py @@ -105,7 +105,7 @@ class UserMethods: """ Gets "me", the current :tl:`User` who is logged in. - If the user has not logged in yet, this method returns ``None``. + If the user has not logged in yet, this method returns `None`. Arguments input_peer (`bool`, optional): @@ -140,7 +140,7 @@ class UserMethods: async def is_bot(self: 'TelegramClient') -> bool: """ - Return ``True`` if the signed-in user is a bot, ``False`` otherwise. + Return `True` if the signed-in user is a bot, `False` otherwise. Example .. code-block:: python @@ -157,7 +157,7 @@ class UserMethods: async def is_user_authorized(self: 'TelegramClient') -> bool: """ - Returns ``True`` if the user is authorized (i.e. has logged in). + Returns `True` if the user is authorized (i.e. has logged in). Example .. code-block:: python diff --git a/telethon/events/__init__.py b/telethon/events/__init__.py index ffbbecdf..28f85b12 100644 --- a/telethon/events/__init__.py +++ b/telethon/events/__init__.py @@ -119,7 +119,7 @@ def unregister(callback, event=None): def is_handler(callback): """ - Returns ``True`` if the given callback is an + Returns `True` if the given callback is an event handler (i.e. you used `register` on it). """ return hasattr(callback, _HANDLERS_ATTRIBUTE) @@ -135,6 +135,6 @@ def list(callback): def _get_handlers(callback): """ - Like ``list`` but returns ``None`` if the callback was never registered. + Like ``list`` but returns `None` if the callback was never registered. """ return getattr(callback, _HANDLERS_ATTRIBUTE, None) diff --git a/telethon/events/album.py b/telethon/events/album.py index a9be9434..89e26d4e 100644 --- a/telethon/events/album.py +++ b/telethon/events/album.py @@ -122,7 +122,7 @@ class Album(EventBuilder): @property def is_reply(self): """ - ``True`` if the album is a reply to some other message. + `True` if the album is a reply to some other message. Remember that you can access the ID of the message this one is replying to through `reply_to_msg_id`, @@ -147,7 +147,7 @@ class Album(EventBuilder): async def get_reply_message(self): """ The `Message ` - that this album is replying to, or ``None``. + that this album is replying to, or `None`. The result will be cached after its first use. """ @@ -188,7 +188,7 @@ class Album(EventBuilder): `telethon.client.messages.MessageMethods.edit_message` with both ``entity`` and ``message`` already set. - Returns ``None`` if the message was incoming, + Returns `None` if the message was incoming, or the edited `Message` otherwise. .. note:: @@ -198,7 +198,7 @@ class Album(EventBuilder): and **will respect** the previous state of the message. For example, if the message didn't have a link preview, the edit won't add one by default, and you should force - it by setting it to ``True`` if you want it. + it by setting it to `True` if you want it. This is generally the most desired and convenient behaviour, and will work for link previews and message buttons. diff --git a/telethon/events/callbackquery.py b/telethon/events/callbackquery.py index 8097db57..12376ca8 100644 --- a/telethon/events/callbackquery.py +++ b/telethon/events/callbackquery.py @@ -28,7 +28,7 @@ class CallbackQuery(EventBuilder): pattern (`bytes`, `str`, `callable`, `Pattern`, optional): If set, only buttons with payload matching this pattern will be handled. You can specify a regex-like string which will be matched - against the payload data, a callable function that returns ``True`` + against the payload data, a callable function that returns `True` if a the payload data is acceptable, or a compiled regex pattern. """ @@ -210,7 +210,7 @@ class CallbackQuery(EventBuilder): alert (`bool`, optional): Whether an alert (a pop-up dialog) should be used - instead of showing a toast. Defaults to ``False``. + instead of showing a toast. Defaults to `False`. """ if self._answered: return @@ -231,11 +231,11 @@ class CallbackQuery(EventBuilder): """ Whether this callback was generated from an inline button sent via an inline query or not. If the bot sent the message itself - with buttons, and one of those is clicked, this will be ``False``. + with buttons, and one of those is clicked, this will be `False`. If a user sent the message coming from an inline query to the - bot, and one of those is clicked, this will be ``True``. + bot, and one of those is clicked, this will be `True`. - If it's ``True``, it's likely that the bot is **not** in the + If it's `True`, it's likely that the bot is **not** in the chat, so methods like `respond` or `delete` won't work (but `edit` will always work). """ @@ -249,7 +249,7 @@ class CallbackQuery(EventBuilder): This method also creates a task to `answer` the callback. - This method will likely fail if `via_inline` is ``True``. + This method will likely fail if `via_inline` is `True`. """ self._client.loop.create_task(self.answer()) return await self._client.send_message( @@ -263,7 +263,7 @@ class CallbackQuery(EventBuilder): This method also creates a task to `answer` the callback. - This method will likely fail if `via_inline` is ``True``. + This method will likely fail if `via_inline` is `True`. """ self._client.loop.create_task(self.answer()) kwargs['reply_to'] = self.query.msg_id @@ -276,7 +276,7 @@ class CallbackQuery(EventBuilder): `telethon.client.messages.MessageMethods.edit_message` with the ``entity`` set to the correct :tl:`InputBotInlineMessageID`. - Returns ``True`` if the edit was successful. + Returns `True` if the edit was successful. This method also creates a task to `answer` the callback. @@ -309,7 +309,7 @@ class CallbackQuery(EventBuilder): This method also creates a task to `answer` the callback. - This method will likely fail if `via_inline` is ``True``. + This method will likely fail if `via_inline` is `True`. """ self._client.loop.create_task(self.answer()) return await self._client.delete_messages( diff --git a/telethon/events/chataction.py b/telethon/events/chataction.py index 5d9b28af..320c0350 100644 --- a/telethon/events/chataction.py +++ b/telethon/events/chataction.py @@ -83,34 +83,34 @@ class ChatAction(EventBuilder): The message invoked by this Chat Action. new_pin (`bool`): - ``True`` if there is a new pin. + `True` if there is a new pin. new_photo (`bool`): - ``True`` if there's a new chat photo (or it was removed). + `True` if there's a new chat photo (or it was removed). photo (:tl:`Photo`, optional): - The new photo (or ``None`` if it was removed). + The new photo (or `None` if it was removed). user_added (`bool`): - ``True`` if the user was added by some other. + `True` if the user was added by some other. user_joined (`bool`): - ``True`` if the user joined on their own. + `True` if the user joined on their own. user_left (`bool`): - ``True`` if the user left on their own. + `True` if the user left on their own. user_kicked (`bool`): - ``True`` if the user was kicked by some other. + `True` if the user was kicked by some other. created (`bool`, optional): - ``True`` if this chat was just created. + `True` if this chat was just created. new_title (`str`, optional): The new title string for the chat, if applicable. unpin (`bool`): - ``True`` if the existing pin gets unpinned. + `True` if the existing pin gets unpinned. """ def __init__(self, where, new_pin=None, new_photo=None, added_by=None, kicked_by=None, created=None, @@ -141,7 +141,7 @@ class ChatAction(EventBuilder): self.user_added = True self._added_by = added_by - # If `from_id` was not present (it's ``True``) or the affected + # If `from_id` was not present (it's `True`) or the affected # user was "kicked by itself", then it left. Else it was kicked. if kicked_by is True or kicked_by == users: self.user_left = True @@ -205,7 +205,7 @@ class ChatAction(EventBuilder): async def get_pinned_message(self): """ - If ``new_pin`` is ``True``, this returns the `Message + If ``new_pin`` is `True`, this returns the `Message ` object that was pinned. """ if self._pinned_message == 0: @@ -231,7 +231,7 @@ class ChatAction(EventBuilder): @property def added_by(self): """ - The user who added ``users``, if applicable (``None`` otherwise). + The user who added ``users``, if applicable (`None` otherwise). """ if self._added_by and not isinstance(self._added_by, types.User): aby = self._entities.get(utils.get_peer_id(self._added_by)) @@ -252,7 +252,7 @@ class ChatAction(EventBuilder): @property def kicked_by(self): """ - The user who kicked ``users``, if applicable (``None`` otherwise). + The user who kicked ``users``, if applicable (`None` otherwise). """ if self._kicked_by and not isinstance(self._kicked_by, types.User): kby = self._entities.get(utils.get_peer_id(self._kicked_by)) @@ -275,7 +275,7 @@ class ChatAction(EventBuilder): """ The first user that takes part in this action (e.g. joined). - Might be ``None`` if the information can't be retrieved or + Might be `None` if the information can't be retrieved or there is no user taking part. """ if self.users: diff --git a/telethon/events/common.py b/telethon/events/common.py index 6181f0b0..ea91ecd2 100644 --- a/telethon/events/common.py +++ b/telethon/events/common.py @@ -106,7 +106,7 @@ class EventBuilder(abc.ABC): def filter(self, event): """ If the ID of ``event._chat_peer`` isn't in the chats set (or it is - but the set is a blacklist) returns ``None``, otherwise the event. + but the set is a blacklist) returns `None`, otherwise the event. The events must have been resolved before this can be called. """ diff --git a/telethon/events/inlinequery.py b/telethon/events/inlinequery.py index 13fc5de8..81c007f9 100644 --- a/telethon/events/inlinequery.py +++ b/telethon/events/inlinequery.py @@ -29,7 +29,7 @@ class InlineQuery(EventBuilder): pattern (`str`, `callable`, `Pattern`, optional): If set, only queries matching this pattern will be handled. You can specify a regex-like string which will be matched - against the message, a callable function that returns ``True`` + against the message, a callable function that returns `True` if a message is acceptable, or a compiled regex pattern. """ def __init__( diff --git a/telethon/events/messageedited.py b/telethon/events/messageedited.py index 382b9ade..91575f38 100644 --- a/telethon/events/messageedited.py +++ b/telethon/events/messageedited.py @@ -13,7 +13,7 @@ class MessageEdited(NewMessage): .. warning:: On channels, `Message.out ` - will be ``True`` if you sent the message originally, **not if + will be `True` if you sent the message originally, **not if you edited it**! This can be dangerous if you run outgoing commands on edits. diff --git a/telethon/events/messageread.py b/telethon/events/messageread.py index 3f71917c..99182003 100644 --- a/telethon/events/messageread.py +++ b/telethon/events/messageread.py @@ -10,8 +10,8 @@ class MessageRead(EventBuilder): Args: inbox (`bool`, optional): - If this argument is ``True``, then when you read someone else's - messages the event will be fired. By default (``False``) only + If this argument is `True`, then when you read someone else's + messages the event will be fired. By default (`False`) only when messages you sent are read by someone else will fire it. """ def __init__( @@ -55,10 +55,10 @@ class MessageRead(EventBuilder): with an ID equal or lower to it have been read. outbox (`bool`): - ``True`` if someone else has read your messages. + `True` if someone else has read your messages. contents (`bool`): - ``True`` if what was read were the contents of a message. + `True` if what was read were the contents of a message. This will be the case when e.g. you play a voice note. It may only be set on ``inbox`` events. """ @@ -74,7 +74,7 @@ class MessageRead(EventBuilder): @property def inbox(self): """ - ``True`` if you have read someone else's messages. + `True` if you have read someone else's messages. """ return not self.outbox @@ -108,7 +108,7 @@ class MessageRead(EventBuilder): def is_read(self, message): """ - Returns ``True`` if the given message (or its ID) has been read. + Returns `True` if the given message (or its ID) has been read. If a list-like argument is provided, this method will return a list of booleans indicating which messages have been read. @@ -121,7 +121,7 @@ class MessageRead(EventBuilder): else message.id) <= self.max_id def __contains__(self, message): - """``True`` if the message(s) are read message.""" + """`True` if the message(s) are read message.""" if utils.is_list_like(message): return all(self.is_read(message)) else: diff --git a/telethon/events/newmessage.py b/telethon/events/newmessage.py index ad71c34a..5ace95ed 100644 --- a/telethon/events/newmessage.py +++ b/telethon/events/newmessage.py @@ -12,11 +12,11 @@ class NewMessage(EventBuilder): Args: incoming (`bool`, optional): - If set to ``True``, only **incoming** messages will be handled. + If set to `True`, only **incoming** messages will be handled. Mutually exclusive with ``outgoing`` (can only set one of either). outgoing (`bool`, optional): - If set to ``True``, only **outgoing** messages will be handled. + If set to `True`, only **outgoing** messages will be handled. Mutually exclusive with ``incoming`` (can only set one of either). from_users (`entity`, optional): @@ -28,14 +28,14 @@ class NewMessage(EventBuilder): forwards (`bool`, optional): Whether forwarded messages should be handled or not. By default, - both forwarded and normal messages are included. If it's ``True`` - *only* forwards will be handled. If it's ``False`` only messages + both forwarded and normal messages are included. If it's `True` + *only* forwards will be handled. If it's `False` only messages that are *not* forwards will be handled. pattern (`str`, `callable`, `Pattern`, optional): If set, only messages matching this pattern will be handled. You can specify a regex-like string which will be matched - against the message, a callable function that returns ``True`` + against the message, a callable function that returns `True` if a message is acceptable, or a compiled regex pattern. """ def __init__(self, chats=None, *, blacklist_chats=False, func=None, @@ -181,7 +181,7 @@ class NewMessage(EventBuilder): >>> @client.on(events.NewMessage(pattern=r'hi (\\w+)!')) ... async def handler(event): ... # In this case, the result is a ``Match`` object - ... # since the ``str`` pattern was converted into + ... # since the `str` pattern was converted into ... # the ``re.compile(pattern).match`` function. ... print('Welcomed', event.pattern_match.group(1)) ... diff --git a/telethon/requestiter.py b/telethon/requestiter.py index dee55f5f..e51cfafe 100644 --- a/telethon/requestiter.py +++ b/telethon/requestiter.py @@ -23,7 +23,7 @@ class RequestIter(abc.ABC): be more efficient and fetch only as many items as they need. Iterators may be used with ``reversed``, and their `reverse` flag will - be set to ``True`` if that's the case. Note that if this flag is set, + be set to `True` if that's the case. Note that if this flag is set, `buffer` should be filled in reverse too. """ def __init__(self, client, limit, *, reverse=False, wait_time=None, **kwargs): @@ -124,7 +124,7 @@ class RequestIter(abc.ABC): It should extend the `buffer` with new items. - It should return ``True`` if it's the last chunk, + It should return `True` if it's the last chunk, after which moment the method won't be called again during the same iteration. """ diff --git a/telethon/sessions/abstract.py b/telethon/sessions/abstract.py index 7265b6a3..5fda1c18 100644 --- a/telethon/sessions/abstract.py +++ b/telethon/sessions/abstract.py @@ -49,7 +49,7 @@ class Session(ABC): def auth_key(self): """ Returns an ``AuthKey`` instance associated with the saved - data center, or ``None`` if a new one should be generated. + data center, or `None` if a new one should be generated. """ raise NotImplementedError @@ -66,7 +66,7 @@ class Session(ABC): def takeout_id(self): """ Returns an ID of the takeout process initialized for this session, - or ``None`` if there's no were any unfinished takeout requests. + or `None` if there's no were any unfinished takeout requests. """ raise NotImplementedError diff --git a/telethon/statecache.py b/telethon/statecache.py index 6125d101..adb5099e 100644 --- a/telethon/statecache.py +++ b/telethon/statecache.py @@ -144,11 +144,11 @@ class StateCache: def __getitem__(self, item): """ - If `item` is ``None``, returns the default ``(pts, date)``. + If `item` is `None`, returns the default ``(pts, date)``. If it's an **unmarked** channel ID, returns its ``pts``. - If no information is known, ``pts`` will be ``None``. + If no information is known, ``pts`` will be `None`. """ if item is None: return self._pts_date diff --git a/telethon/tl/custom/adminlogevent.py b/telethon/tl/custom/adminlogevent.py index 803e0be2..930102f8 100644 --- a/telethon/tl/custom/adminlogevent.py +++ b/telethon/tl/custom/adminlogevent.py @@ -131,7 +131,7 @@ class AdminLogEvent: """ Whether the channel's about was changed or not. - If ``True``, `old` and `new` will be present as ``str``. + If `True`, `old` and `new` will be present as `str`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionChangeAbout) @@ -141,7 +141,7 @@ class AdminLogEvent: """ Whether the channel's title was changed or not. - If ``True``, `old` and `new` will be present as ``str``. + If `True`, `old` and `new` will be present as `str`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionChangeTitle) @@ -151,7 +151,7 @@ class AdminLogEvent: """ Whether the channel's username was changed or not. - If ``True``, `old` and `new` will be present as ``str``. + If `True`, `old` and `new` will be present as `str`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionChangeUsername) @@ -161,7 +161,7 @@ class AdminLogEvent: """ Whether the channel's photo was changed or not. - If ``True``, `old` and `new` will be present as :tl:`Photo`. + If `True`, `old` and `new` will be present as :tl:`Photo`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionChangePhoto) @@ -171,7 +171,7 @@ class AdminLogEvent: """ Whether the channel's sticker set was changed or not. - If ``True``, `old` and `new` will be present as :tl:`InputStickerSet`. + If `True`, `old` and `new` will be present as :tl:`InputStickerSet`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionChangeStickerSet) @@ -181,7 +181,7 @@ class AdminLogEvent: """ Whether a message in this channel was edited or not. - If ``True``, `old` and `new` will be present as + If `True`, `old` and `new` will be present as `Message `. """ return isinstance(self.original.action, @@ -192,7 +192,7 @@ class AdminLogEvent: """ Whether a message in this channel was deleted or not. - If ``True``, `old` will be present as + If `True`, `old` will be present as `Message `. """ return isinstance(self.original.action, @@ -204,7 +204,7 @@ class AdminLogEvent: Whether the permissions for an admin in this channel changed or not. - If ``True``, `old` and `new` will be present as + If `True`, `old` and `new` will be present as :tl:`ChannelParticipant`. """ return isinstance( @@ -216,7 +216,7 @@ class AdminLogEvent: """ Whether a message in this channel was edited or not. - If ``True``, `old` and `new` will be present as + If `True`, `old` and `new` will be present as :tl:`ChannelParticipant`. """ return isinstance( @@ -228,7 +228,7 @@ class AdminLogEvent: """ Whether the invites in the channel were toggled or not. - If ``True``, `old` and `new` will be present as ``bool``. + If `True`, `old` and `new` will be present as `bool`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionToggleInvites) @@ -238,7 +238,7 @@ class AdminLogEvent: """ Whether the location setting of the channel has changed or not. - If ``True``, `old` and `new` will be present as :tl:`ChannelLocation`. + If `True`, `old` and `new` will be present as :tl:`ChannelLocation`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionChangeLocation) @@ -258,7 +258,7 @@ class AdminLogEvent: Whether a new user joined through an invite link to the channel or not. - If ``True``, `new` will be present as + If `True`, `new` will be present as :tl:`ChannelParticipant`. """ return isinstance(self.original.action, @@ -278,7 +278,7 @@ class AdminLogEvent: Whether hiding the previous message history for new members in the channel was toggled or not. - If ``True``, `old` and `new` will be present as ``bool``. + If `True`, `old` and `new` will be present as `bool`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionTogglePreHistoryHidden) @@ -289,7 +289,7 @@ class AdminLogEvent: Whether the message signatures in the channel were toggled or not. - If ``True``, `old` and `new` will be present as ``bool``. + If `True`, `old` and `new` will be present as `bool`. """ return isinstance(self.original.action, types.ChannelAdminLogEventActionToggleSignatures) @@ -299,7 +299,7 @@ class AdminLogEvent: """ Whether a new message in this channel was pinned or not. - If ``True``, `new` will be present as + If `True`, `new` will be present as `Message `. """ return isinstance(self.original.action, @@ -310,7 +310,7 @@ class AdminLogEvent: """ Whether the default banned rights were changed or not. - If ``True``, `old` and `new` will + If `True`, `old` and `new` will be present as :tl:`ChatBannedRights`. """ return isinstance(self.original.action, @@ -321,7 +321,7 @@ class AdminLogEvent: """ Whether a poll was stopped or not. - If ``True``, `new` will be present as + If `True`, `new` will be present as `Message `. """ return isinstance(self.original.action, diff --git a/telethon/tl/custom/button.py b/telethon/tl/custom/button.py index 2bfb4018..27ea10eb 100644 --- a/telethon/tl/custom/button.py +++ b/telethon/tl/custom/button.py @@ -43,7 +43,7 @@ class Button: @staticmethod def _is_inline(button): """ - Returns ``True`` if the button belongs to an inline keyboard. + Returns `True` if the button belongs to an inline keyboard. """ return isinstance(button, ( types.KeyboardButtonCallback, @@ -57,7 +57,7 @@ class Button: Creates a new inline button with some payload data in it. If `data` is omitted, the given `text` will be used as `data`. - In any case `data` should be either ``bytes`` or ``str``. + In any case `data` should be either `bytes` or `str`. Note that the given `data` must be less or equal to 64 bytes. If more than 64 bytes are passed as data, ``ValueError`` is raised. diff --git a/telethon/tl/custom/chatgetter.py b/telethon/tl/custom/chatgetter.py index e919e17b..ebf051d6 100644 --- a/telethon/tl/custom/chatgetter.py +++ b/telethon/tl/custom/chatgetter.py @@ -21,7 +21,7 @@ class ChatGetter(abc.ABC): def chat(self): """ Returns the :tl:`User`, :tl:`Chat` or :tl:`Channel` where this object - belongs to. It may be ``None`` if Telegram didn't send the chat. + belongs to. It may be `None` if Telegram didn't send the chat. If you only need the ID, use `chat_id` instead. @@ -109,9 +109,9 @@ class ChatGetter(abc.ABC): @property def is_private(self): """ - ``True`` if the message was sent as a private message. + `True` if the message was sent as a private message. - Returns ``None`` if there isn't enough information + Returns `None` if there isn't enough information (e.g. on `events.MessageDeleted `). """ return isinstance(self._chat_peer, types.PeerUser) if self._chat_peer else None @@ -121,7 +121,7 @@ class ChatGetter(abc.ABC): """ True if the message was sent on a group or megagroup. - Returns ``None`` if there isn't enough information + Returns `None` if there isn't enough information (e.g. on `events.MessageDeleted `). """ # TODO Cache could tell us more in the future @@ -138,7 +138,7 @@ class ChatGetter(abc.ABC): @property def is_channel(self): - """``True`` if the message was sent on a megagroup or channel.""" + """`True` if the message was sent on a megagroup or channel.""" # The only case where chat peer could be none is in MessageDeleted, # however those always have the peer in channels. return isinstance(self._chat_peer, types.PeerChannel) diff --git a/telethon/tl/custom/dialog.py b/telethon/tl/custom/dialog.py index 8e82feaa..bdc219cc 100644 --- a/telethon/tl/custom/dialog.py +++ b/telethon/tl/custom/dialog.py @@ -56,18 +56,18 @@ class Dialog: this value won't update when new messages arrive. draft (`Draft `): - The draft object in this dialog. It will not be ``None``, + The draft object in this dialog. It will not be `None`, so you can call ``draft.set_message(...)``. is_user (`bool`): - ``True`` if the `entity` is a :tl:`User`. + `True` if the `entity` is a :tl:`User`. is_group (`bool`): - ``True`` if the `entity` is a :tl:`Chat` + `True` if the `entity` is a :tl:`Chat` or a :tl:`Channel` megagroup. is_channel (`bool`): - ``True`` if the `entity` is a :tl:`Channel`. + `True` if the `entity` is a :tl:`Channel`. """ def __init__(self, client, dialog, entities, messages): # Both entities and messages being dicts {ID: item} diff --git a/telethon/tl/custom/draft.py b/telethon/tl/custom/draft.py index c5d5cc89..84289c58 100644 --- a/telethon/tl/custom/draft.py +++ b/telethon/tl/custom/draft.py @@ -131,7 +131,7 @@ class Draft: Preserved if left as None. :param str parse_mode: The parse mode to be used for the text. - :return bool: ``True`` on success. + :return bool: `True` on success. """ if text is None: text = self._text @@ -175,7 +175,7 @@ class Draft: async def delete(self): """ - Deletes this draft, and returns ``True`` on success. + Deletes this draft, and returns `True` on success. """ return await self.set_message(text='') diff --git a/telethon/tl/custom/file.py b/telethon/tl/custom/file.py index 1c17149a..0355d0e1 100644 --- a/telethon/tl/custom/file.py +++ b/telethon/tl/custom/file.py @@ -11,7 +11,7 @@ class File: supports accessing the attributes in a more convenient way. If any of the attributes are not present in the current media, - the properties will be ``None``. + the properties will be `None`. The original media is available through the ``media`` attribute. """ diff --git a/telethon/tl/custom/inlinebuilder.py b/telethon/tl/custom/inlinebuilder.py index 2f4cc7d4..223ba0d6 100644 --- a/telethon/tl/custom/inlinebuilder.py +++ b/telethon/tl/custom/inlinebuilder.py @@ -30,7 +30,7 @@ class InlineBuilder: If present, it must be the contact information to send. game (`bool`, optional): - May be ``True`` to indicate that the game will be sent. + May be `True` to indicate that the game will be sent. buttons (`list`, `custom.Button `, :tl:`KeyboardButton`, optional): Same as ``buttons`` for `client.send_message() diff --git a/telethon/tl/custom/inlineresult.py b/telethon/tl/custom/inlineresult.py index 04e82cab..4a411699 100644 --- a/telethon/tl/custom/inlineresult.py +++ b/telethon/tl/custom/inlineresult.py @@ -54,14 +54,14 @@ class InlineResult: @property def title(self): """ - The title for this inline result. It may be ``None``. + The title for this inline result. It may be `None`. """ return self.result.title @property def description(self): """ - The description for this inline result. It may be ``None``. + The description for this inline result. It may be `None`. """ return self.result.description @@ -110,11 +110,11 @@ class InlineResult: If present, the sent message will reply to this ID or message. silent (`bool`, optional): - If ``True``, the sent message will not notify the user(s). + If `True`, the sent message will not notify the user(s). clear_draft (`bool`, optional): Whether the draft should be removed after sending the - message from this result or not. Defaults to ``False``. + message from this result or not. Defaults to `False`. hide_via (`bool`, optional): Whether the "via @bot" should be hidden or not. diff --git a/telethon/tl/custom/inlineresults.py b/telethon/tl/custom/inlineresults.py index 2ac5ebfa..4c331962 100644 --- a/telethon/tl/custom/inlineresults.py +++ b/telethon/tl/custom/inlineresults.py @@ -59,7 +59,7 @@ class InlineResults(list): def results_valid(self): """ - Returns ``True`` if the cache time has not expired + Returns `True` if the cache time has not expired yet and the results can still be considered valid. """ return time.time() < self._valid_until diff --git a/telethon/tl/custom/message.py b/telethon/tl/custom/message.py index 27ecd00f..77743f0b 100644 --- a/telethon/tl/custom/message.py +++ b/telethon/tl/custom/message.py @@ -23,14 +23,14 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): Members: id (`int`): The ID of this message. This field is *always* present. - Any other member is optional and may be ``None``. + Any other member is optional and may be `None`. out (`bool`): Whether the message is outgoing (i.e. you sent it from another session) or incoming (i.e. someone else sent it). Note that messages in your own chat are always incoming, - but this member will be ``True`` if you send a message + but this member will be `True` if you send a message to your own chat. Messages you forward to your chat are *not* considered outgoing, just like official clients display them. @@ -72,15 +72,15 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): message (`str`): The string text of the message for `Message ` instances, - which will be ``None`` for other types of messages. + which will be `None` for other types of messages. action (:tl:`MessageAction`): The message action object of the message for :tl:`MessageService` - instances, which will be ``None`` for other types of messages. + instances, which will be `None` for other types of messages. from_id (`int`): The ID of the user who sent this message. This will be - ``None`` if the message was sent in a broadcast channel. + `None` if the message was sent in a broadcast channel. reply_to_msg_id (`int`): The ID to which this message is replying to, if any. @@ -101,7 +101,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): etc. properties instead. If the media was not present or it was :tl:`MessageMediaEmpty`, - this member will instead be ``None`` for convenience. + this member will instead be `None` for convenience. reply_markup (:tl:`ReplyMarkup`): The reply markup for this message (which was sent @@ -270,7 +270,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): def text(self): """ The message text, formatted using the client's default - parse mode. Will be ``None`` for :tl:`MessageService`. + parse mode. Will be `None` for :tl:`MessageService`. """ if self._text is None and self._client: if not self._client.parse_mode: @@ -293,7 +293,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): def raw_text(self): """ The raw message text, ignoring any formatting. - Will be ``None`` for :tl:`MessageService`. + Will be `None` for :tl:`MessageService`. Setting a value to this field will erase the `entities`, unlike changing the `message` member. @@ -309,7 +309,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): @property def is_reply(self): """ - ``True`` if the message is a reply to some other message. + `True` if the message is a reply to some other message. Remember that you can access the ID of the message this one is replying to through `reply_to_msg_id`, @@ -332,7 +332,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): `, if any. - Otherwise, it returns ``None``. + Otherwise, it returns `None`. """ if self._buttons is None and self.reply_markup: if not self.input_chat: @@ -384,7 +384,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): """ Returns a `File ` wrapping the `photo` or `document` in this message. If the media type is different - (polls, games, none, etc.), this property will be ``None``. + (polls, games, none, etc.), this property will be `None`. This instance lets you easily access other properties, such as `file.id `, @@ -548,9 +548,9 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): :tl:`MessageActionChatJoinedByLink` :tl:`MessageActionChatMigrateTo` and :tl:`MessageActionChannelMigrateFrom`. - If the action is neither of those, the result will be ``None``. + If the action is neither of those, the result will be `None`. If some entities could not be retrieved, the list may contain - some ``None`` items in it. + some `None` items in it. """ return self._action_entities @@ -559,7 +559,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): """ The bot :tl:`User` if the message was sent via said bot. - This will only be present if `via_bot_id` is not ``None`` and + This will only be present if `via_bot_id` is not `None` and the entity is known. """ return self._via_bot @@ -581,7 +581,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): (like bold or italics). The markup entity is a :tl:`MessageEntity` that represents bold, - italics, etc., and the inner text is the ``str`` inside that markup + italics, etc., and the inner text is the `str` inside that markup entity. For example: @@ -617,7 +617,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): async def get_reply_message(self): """ - The `Message` that this message is replying to, or ``None``. + The `Message` that this message is replying to, or `None`. The result will be cached after its first use. """ @@ -685,7 +685,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): `telethon.client.messages.MessageMethods.edit_message` with both ``entity`` and ``message`` already set. - Returns ``None`` if the message was incoming, + Returns `None` if the message was incoming, or the edited `Message` otherwise. .. note:: @@ -695,7 +695,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): and **will respect** the previous state of the message. For example, if the message didn't have a link preview, the edit won't add one by default, and you should force - it by setting it to ``True`` if you want it. + it by setting it to `True` if you want it. This is generally the most desired and convenient behaviour, and will work for link previews and message buttons. @@ -780,7 +780,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): filter (`callable`): Clicks the first button for which the callable - returns ``True``. The callable should accept a single + returns `True`. The callable should accept a single `MessageButton ` argument. @@ -929,7 +929,7 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): This is necessary for :tl:`KeyboardButtonSwitchInline` since we need to know what bot we want to start. Raises ``ValueError`` if the bot - cannot be found but is needed. Returns ``None`` if it's not needed. + cannot be found but is needed. Returns `None` if it's not needed. """ if self._client and not isinstance(self.reply_markup, ( types.ReplyInlineMarkup, types.ReplyKeyboardMarkup)): diff --git a/telethon/tl/custom/messagebutton.py b/telethon/tl/custom/messagebutton.py index 9d18804c..28e768f1 100644 --- a/telethon/tl/custom/messagebutton.py +++ b/telethon/tl/custom/messagebutton.py @@ -43,19 +43,19 @@ class MessageButton: @property def data(self): - """The ``bytes`` data for :tl:`KeyboardButtonCallback` objects.""" + """The `bytes` data for :tl:`KeyboardButtonCallback` objects.""" if isinstance(self.button, types.KeyboardButtonCallback): return self.button.data @property def inline_query(self): - """The query ``str`` for :tl:`KeyboardButtonSwitchInline` objects.""" + """The query `str` for :tl:`KeyboardButtonSwitchInline` objects.""" if isinstance(self.button, types.KeyboardButtonSwitchInline): return self.button.query @property def url(self): - """The url ``str`` for :tl:`KeyboardButtonUrl` objects.""" + """The url `str` for :tl:`KeyboardButtonUrl` objects.""" if isinstance(self.button, types.KeyboardButtonUrl): return self.button.url @@ -74,7 +74,7 @@ class MessageButton: returned. If it's a :tl:`KeyboardButtonUrl`, the URL of the button will - be passed to ``webbrowser.open`` and return ``True`` on success. + be passed to ``webbrowser.open`` and return `True` on success. """ if isinstance(self.button, types.KeyboardButton): return await self._client.send_message( diff --git a/telethon/tl/custom/sendergetter.py b/telethon/tl/custom/sendergetter.py index 37ea39fa..f0fa4168 100644 --- a/telethon/tl/custom/sendergetter.py +++ b/telethon/tl/custom/sendergetter.py @@ -17,7 +17,7 @@ class SenderGetter(abc.ABC): def sender(self): """ Returns the :tl:`User` or :tl:`Channel` that sent this object. - It may be ``None`` if Telegram didn't send the sender. + It may be `None` if Telegram didn't send the sender. If you only need the ID, use `sender_id` instead. diff --git a/telethon/utils.py b/telethon/utils.py index 7121602a..23cc9daa 100644 --- a/telethon/utils.py +++ b/telethon/utils.py @@ -374,7 +374,7 @@ def get_input_media( """ Similar to :meth:`get_input_peer`, but for media. - If the media is :tl:`InputFile` and ``is_photo`` is known to be ``True``, + If the media is :tl:`InputFile` and ``is_photo`` is known to be `True`, it will be treated as an :tl:`InputMediaUploadedPhoto`. Else, the rest of parameters will indicate how to treat it. """ @@ -692,7 +692,7 @@ def _get_extension(file): def is_image(file): """ - Returns ``True`` if the file extension looks like an image file to Telegram. + Returns `True` if the file extension looks like an image file to Telegram. """ match = re.match(r'\.(png|jpe?g)', _get_extension(file), re.IGNORECASE) if match: @@ -703,26 +703,26 @@ def is_image(file): def is_gif(file): """ - Returns ``True`` if the file extension looks like a gif file to Telegram. + Returns `True` if the file extension looks like a gif file to Telegram. """ return re.match(r'\.gif', _get_extension(file), re.IGNORECASE) def is_audio(file): - """Returns ``True`` if the file extension looks like an audio file.""" + """Returns `True` if the file extension looks like an audio file.""" file = 'a' + _get_extension(file) return (mimetypes.guess_type(file)[0] or '').startswith('audio/') def is_video(file): - """Returns ``True`` if the file extension looks like a video file.""" + """Returns `True` if the file extension looks like a video file.""" file = 'a' + _get_extension(file) return (mimetypes.guess_type(file)[0] or '').startswith('video/') def is_list_like(obj): """ - Returns ``True`` if the given object looks like a list. + Returns `True` if the given object looks like a list. Checking ``if hasattr(obj, '__iter__')`` and ignoring ``str/bytes`` is not enough. Things like ``open()`` are also iterable (and probably many @@ -732,7 +732,7 @@ def is_list_like(obj): def parse_phone(phone): - """Parses the given phone, or returns ``None`` if it's invalid.""" + """Parses the given phone, or returns `None` if it's invalid.""" if isinstance(phone, int): return str(phone) else: @@ -926,7 +926,7 @@ def _decode_telegram_base64(string): This is the way Telegram shares binary data as strings, such as Bot API-style file IDs or invite links. - Returns ``None`` if the input string was not valid. + Returns `None` if the input string was not valid. """ try: return base64.urlsafe_b64decode(string + '=' * (len(string) % 4)) @@ -948,7 +948,7 @@ def resolve_bot_file_id(file_id): """ Given a Bot API-style `file_id `, returns the media it represents. If the `file_id ` - is not valid, ``None`` is returned instead. + is not valid, `None` is returned instead. Note that the `file_id ` does not have information such as image dimensions or file size, so these will be zero if present. @@ -1152,7 +1152,7 @@ def get_appropriated_part_size(file_size): def encode_waveform(waveform): """ - Encodes the input ``bytes`` into a 5-bit byte-string + Encodes the input `bytes` into a 5-bit byte-string to be used as a voice note's waveform. See `decode_waveform` for the reverse operation.