LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2024-09-21 03:08:49 +03:00
Code Issues Packages Projects Releases Wiki Activity

Link Python keywords with Python's documentation

Browse Source
This commit is contained in:
Lonami Exo 2019-07-06 12:10:25 +02:00
parent 42d5c0fe6d
commit 8e36bb4c4d
40 changed files with 238 additions and 238 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
readthedocs/concepts/full-api.rst
View File

@ -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:

4
readthedocs/concepts/updates.rst
View File

@ -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 <telethon.client.messages.MessageMethods.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
<telethon.client.updates.UpdateMethods.list_event_handlers>`.
The ``event`` argument is optional in all three methods and defaults to
`events.Raw <telethon.events.raw.Raw>` for adding, and ``None`` when
`events.Raw <telethon.events.raw.Raw>` for adding, and `None` when
removing (so all callbacks would be removed).
.. note::

2
readthedocs/developing/test-servers.rst
View File

@ -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).

8
readthedocs/examples/chats-and-channels.rst
View File

@ -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,

38
readthedocs/misc/changelog.rst
View File

@ -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
<telethon.tl.custom.button.Button>` as a bot.
* More properties for `Message
<telethon.tl.custom.message.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
<telethon.client.dialogs.DialogMethods.conversation>`.
- Implemented global search through `client.iter_messages
<telethon.client.messages.MessageMethods.iter_messages>`
with ``None`` entity.
with `None` entity.
- New `client.inline_query <telethon.client.bots.BotMethods.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
<telethon.tl.custom.message.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 <telethon.client.telegrambaseclient.TelegramBaseClient.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:

24
telethon/client/account.py
View File

@ -134,8 +134,8 @@ class AccountMethods:
to adjust the `wait_time` of methods like `client.iter_messages
<telethon.client.messages.MessageMethods.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
<telethon.sessions.abstract.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

10
telethon/client/auth.py
View File

@ -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

40
telethon/client/chats.py
View File

@ -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 <telethon.tl.custom.adminlogevent.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.

12
telethon/client/dialogs.py
View File

@ -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 <telethon.tl.custom.dialog.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,

14
telethon/client/downloads.py
View File

@ -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

4
telethon/client/messageparse.py
View File

@ -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.

32
telethon/client/messages.py
View File

@ -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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.Message>`):
@ -1142,7 +1142,7 @@ class MessageMethods:
message (`int` | `Message <telethon.tl.custom.message.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.

12
telethon/client/telegrambaseclient.py
View File

@ -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).

22
telethon/client/uploads.py
View File

@ -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 <telethon.tl.custom.button.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`

6
telethon/client/users.py
View File

@ -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

4
telethon/events/__init__.py
View File

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

8
telethon/events/album.py
View File

@ -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 <telethon.tl.custom.message.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.

18
telethon/events/callbackquery.py
View File

@ -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(

28
telethon/events/chataction.py
View File

@ -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
<telethon.tl.custom.message.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:

2
telethon/events/common.py
View File

@ -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.
"""

2
telethon/events/inlinequery.py
View File

@ -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__(

2
telethon/events/messageedited.py
View File

@ -13,7 +13,7 @@ class MessageEdited(NewMessage):
.. warning::
On channels, `Message.out <telethon.tl.custom.message.Message>`
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.

14
telethon/events/messageread.py
View File

@ -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:

12
telethon/events/newmessage.py
View File

@ -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))
...

4
telethon/requestiter.py
View File

@ -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.
"""

4
telethon/sessions/abstract.py
View File

@ -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

4
telethon/statecache.py
View File

@ -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

34
telethon/tl/custom/adminlogevent.py
View File

@ -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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.Message>`.
"""
return isinstance(self.original.action,

4
telethon/tl/custom/button.py
View File

@ -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.

10
telethon/tl/custom/chatgetter.py
View File

@ -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 <telethon.events.messagedeleted.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 <telethon.events.messagedeleted.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)

8
telethon/tl/custom/dialog.py
View File

@ -56,18 +56,18 @@ class Dialog:
this value won't update when new messages arrive.
draft (`Draft <telethon.tl.custom.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}

4
telethon/tl/custom/draft.py
View File

@ -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='')

2
telethon/tl/custom/file.py
View File

@ -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.
"""

2
telethon/tl/custom/inlinebuilder.py
View File

@ -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 <telethon.tl.custom.button.Button>`, :tl:`KeyboardButton`, optional):
Same as ``buttons`` for `client.send_message()

8
telethon/tl/custom/inlineresult.py
View File

@ -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.

2
telethon/tl/custom/inlineresults.py
View File

@ -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

40
telethon/tl/custom/message.py
View File

@ -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
<telethon.tl.custom.message.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):
<telethon.tl.custom.messagebutton.MessageButton>`,
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 <telethon.tl.custom.file.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 <telethon.tl.custom.file.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 <telethon.tl.custom.messagebutton.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)):

8
telethon/tl/custom/messagebutton.py
View File

@ -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(

2
telethon/tl/custom/sendergetter.py
View File

@ -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.

20
telethon/utils.py
View File

@ -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 <telethon.tl.custom.file.File.id>`,
returns the media it represents. If the `file_id <telethon.tl.custom.file.File.id>`
is not valid, ``None`` is returned instead.
is not valid, `None` is returned instead.
Note that the `file_id <telethon.tl.custom.file.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.