LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2024-11-10 19:46:36 +03:00
Code Issues Packages Projects Releases Wiki Activity

Create a new page with a summary of the method reference

Browse Source
This commit is contained in:
Lonami Exo 2019-05-06 11:38:26 +02:00
parent 744f5f50fe
commit 61613ab6ac
15 changed files with 303 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
readthedocs/conf.py
View File

@ -40,6 +40,7 @@ tl_ref_url = 'https://lonamiwebs.github.io/Telethon'
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'custom_roles'
]

187
readthedocs/extra/reference.rst Normal file
View File

@ -0,0 +1,187 @@
.. _ref-summary:
=================
Reference Summary
=================
This page contains a summary of all the important methods and properties that
you may need when using Telethon. They are sorted by relevance and are not in
alphabetical order.
The way you should use this page is by looking up the type you need in the
table of contents (method index below) and searching for the method or
property that you are interested in.
.. contents:: Method Index
TelegramClient
==============
This is a summary of the methods you will find at :ref:`telethon-client`.
Auth
----
.. currentmodule:: telethon.client.auth.AuthMethods
.. autosummary::
:nosignatures:
start
send_code_request
sign_in
sign_up
log_out
edit_2fa
Base
----
.. py:currentmodule:: telethon.client.telegrambaseclient.TelegramBaseClient
.. autosummary::
:nosignatures:
connect
disconnect
is_connected
disconnected
loop
Messages
--------
.. py:currentmodule:: telethon.client.messages.MessageMethods
.. autosummary::
:nosignatures:
send_message
edit_message
delete_messages
forward_messages
iter_messages
get_messages
send_read_acknowledge
Uploads
-------
.. py:currentmodule:: telethon.client.uploads.UploadMethods
.. autosummary::
:nosignatures:
send_file
upload_file
Downloads
---------
.. currentmodule:: telethon.client.downloads.DownloadMethods
.. autosummary::
:nosignatures:
download_media
download_profile_photo
download_file
Dialogs
-------
.. py:currentmodule:: telethon.client.dialogs.DialogMethods
.. autosummary::
:nosignatures:
iter_dialogs
get_dialogs
iter_drafts
get_drafts
conversation
Users
-----
.. py:currentmodule:: telethon.client.users.UserMethods
.. autosummary::
:nosignatures:
get_me
is_bot
is_user_authorized
get_entity
get_input_entity
get_peer_id
Chats
-----
.. currentmodule:: telethon.client.chats.ChatMethods
.. autosummary::
:nosignatures:
iter_participants
get_participants
iter_admin_log
get_admin_log
action
Parse Mode
----------
.. py:currentmodule:: telethon.client.messageparse.MessageParseMethods
.. autosummary::
:nosignatures:
parse_mode
Updates
-------
.. py:currentmodule:: telethon.client.updates.UpdateMethods
.. autosummary::
:nosignatures:
on
run_until_disconnected
add_event_handler
remove_event_handler
list_event_handlers
catch_up
Bots
----
.. currentmodule:: telethon.client.bots.BotMethods
.. autosummary::
:nosignatures:
inline_query
Buttons
-------
.. currentmodule:: telethon.client.buttons.ButtonMethods
.. autosummary::
:nosignatures:
build_reply_markup
Account
-------
.. currentmodule:: telethon.client.account.AccountMethods
.. autosummary::
:nosignatures:
takeout
end_takeout

3
readthedocs/index.rst
View File

@ -17,7 +17,7 @@ when you upgrade!
.. important::
* Are you new here? Jump straight into :ref:`getting-started`!
* Looking for available friendly methods? See :ref:`telethon-client`.
* Looking for available friendly methods? See :ref:`ref-summary`.
* Used Telethon before v1.0? See :ref:`compatibility-and-convenience`.
* Need the full API reference? https://lonamiwebs.github.io/Telethon/.
@ -41,6 +41,7 @@ heavy job for you, so you can focus on developing an application.
extra/basic/installation
extra/basic/creating-a-client
extra/basic/telegram-client
extra/reference
extra/basic/entities
extra/basic/working-with-updates
extra/basic/compatibility-and-convenience

10
telethon/client/account.py
View File

@ -120,7 +120,9 @@ class AccountMethods(UserMethods):
files: bool = None,
max_file_size: bool = None) -> 'TelegramClient':
"""
Creates a proxy object over the current :ref:`TelegramClient` through
Returns a :ref:`TelegramClient` which calls methods behind a takeout session.
It does so by creating a proxy object over the current client through
which making requests will use :tl:`InvokeWithTakeoutRequest` to wrap
them. In other words, returns the current client modified so that
requests are done as a takeout:
@ -210,7 +212,11 @@ class AccountMethods(UserMethods):
async def end_takeout(self: 'TelegramClient', success: bool) -> bool:
"""
Finishes a takeout, with specified result sent back to Telegram.
Finishes the current takeout session.
Args:
success (`bool`):
Whether the takeout completed successfully or not.
Returns:
``True`` if the operation was successful, ``False`` otherwise.

27
telethon/client/auth.py
View File

@ -29,8 +29,10 @@ class AuthMethods(MessageParseMethods, UserMethods):
last_name: str = '',
max_attempts: int = 3) -> 'TelegramClient':
"""
Convenience method to interactively connect and sign in if required,
also taking into consideration that 2FA may be enabled in the account.
Starts the client (connects and logs in if necessary).
By default, this method will be interactive (asking for
user input if needed), and will handle 2FA if enabled too.
If the phone doesn't belong to an existing account (and will hence
`sign_up` for a new one), **you are agreeing to Telegram's
@ -252,8 +254,11 @@ class AuthMethods(MessageParseMethods, UserMethods):
bot_token: str = None,
phone_code_hash: str = None) -> types.User:
"""
Starts or completes the sign in process with the given phone number
or code that Telegram sent.
Logs in to Telegram to an existing user or bot account.
You should only use this if you are not authorized yet.
This method will send the code if it's not provided.
Args:
phone (`str` | `int`):
@ -324,8 +329,11 @@ class AuthMethods(MessageParseMethods, UserMethods):
phone: str = None,
phone_code_hash: str = None) -> types.User:
"""
Signs up to Telegram if you don't have an account yet.
You must call .send_code_request(phone) first.
Signs up to Telegram as a new user account.
Use this if you don't have an account yet.
You must call `send_code_request` first.
**By using this method you're agreeing to Telegram's
Terms of Service. This is required and your account
@ -400,7 +408,7 @@ class AuthMethods(MessageParseMethods, UserMethods):
*,
force_sms: bool = False) -> types.auth.SentCode:
"""
Sends a code request to the specified phone number.
Sends the Telegram code needed to login to the given phone number.
Args:
phone (`str` | `int`):
@ -468,8 +476,9 @@ class AuthMethods(MessageParseMethods, UserMethods):
email: str = None,
email_code_callback: typing.Callable[[int], str] = None) -> bool:
"""
Changes the 2FA settings of the logged in user, according to the
passed parameters. Take note of the parameter explanations.
Changes the 2FA settings of the logged in user.
Review carefully the parameter explanations before using this method.
Note that this method may be *incredibly* slow depending on the
prime numbers that must be used during the process to make sure

3
telethon/client/bots.py
View File

@ -17,8 +17,7 @@ class BotMethods(UserMethods):
offset: str = None,
geo_point: types.GeoPoint = None) -> custom.InlineResults:
"""
Makes the given inline query to the specified bot
i.e. ``@vote My New Poll`` would be as follows:
Makes an inline query to the specified bot (e.g. ``@vote New Poll``).
>>> client = ...
>>> client.inline_query('vote', 'My New Poll')

19
telethon/client/buttons.py
View File

@ -9,20 +9,21 @@ if typing.TYPE_CHECKING:
class ButtonMethods(UpdateMethods):
@staticmethod
def build_reply_markup(
self: 'TelegramClient',
buttons: typing.Optional[hints.MarkupLike],
inline_only: bool = False) -> typing.Optional[types.TypeReplyMarkup]:
"""
Builds a :tl`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
the given buttons, or does nothing if either no buttons are
provided or the provided argument is already a reply markup.
Builds a :tl:`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
the given buttons.
This will add any event handlers defined in the
buttons and delete old ones not to call them twice,
so you should probably call this method manually for
serious bots instead re-adding handlers every time you
send a message. Magic can only go so far.
Does nothing if either no buttons are provided or the provided
argument is already a reply markup.
You should consider using this method if you are going to reuse
the markup very often. Otherwise, it is not necessary.
This method is **not** asynchronous (don't use ``await`` on it).
"""
if buttons is None:
return None

9
telethon/client/dialogs.py
View File

@ -111,9 +111,7 @@ class DialogMethods(UserMethods):
ignore_migrated: bool = False
) -> _DialogsIter:
"""
Returns an iterator over the dialogs, yielding 'limit' at most.
Dialogs are the open "chats" or conversations with other people,
groups you have joined, or channels you are subscribed to.
Iterator over the dialogs (open conversations/subscribed channels).
Args:
limit (`int` | `None`):
@ -186,7 +184,10 @@ class DialogMethods(UserMethods):
replies_are_responses: bool = True) -> custom.Conversation:
"""
Creates a `Conversation <telethon.tl.custom.conversation.Conversation>`
with the given entity so you can easily send messages and await for
with the given entity.
This is not the same as just sending a message to create a "dialog"
with them, but rather a way to easily send messages and await for
responses or other reactions. Refer to its documentation for more.
Args:

6
telethon/client/downloads.py
View File

@ -28,7 +28,7 @@ class DownloadMethods(UserMethods):
*,
download_big: bool = True) -> typing.Optional[str]:
"""
Downloads the profile photo of the given entity (user/chat/channel).
Downloads the profile photo from the given user, chat or channel.
Args:
entity (`entity`):
@ -134,7 +134,7 @@ class DownloadMethods(UserMethods):
thumb: hints.FileLike = None,
progress_callback: hints.ProgressCallback = None) -> typing.Optional[str]:
"""
Downloads the given media, or the media from a specified Message.
Downloads the given media from a message object.
Note that if the download is too slow, you should consider installing
``cryptg`` (through ``pip install cryptg``) so that decrypting the
@ -216,7 +216,7 @@ class DownloadMethods(UserMethods):
progress_callback: hints.ProgressCallback = None,
dc_id: int = None) -> None:
"""
Downloads the given input location to a file.
Low-level method to download files from their input location.
Args:
input_location (:tl:`InputFileLocation`):

18
telethon/client/messages.py
View File

@ -314,7 +314,8 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
reverse: bool = False
) -> typing.Union[_MessagesIter, _IDsIter]:
"""
Iterator over the message history for the specified entity.
Iterator over the messages for the given chat.
If either `search`, `filter` or `from_user` are provided,
:tl:`messages.Search` will be used instead of :tl:`messages.getHistory`.
@ -486,7 +487,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
buttons: hints.MarkupLike = None,
silent: bool = None) -> types.Message:
"""
Sends the given message to the specified entity (user/chat/channel).
Sends a message to the specified user, chat or channel.
The default parse mode is the same as the official applications
(a custom flavour of markdown). ``**bold**, `code` or __italic__``
@ -642,7 +643,11 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
silent: bool = None,
as_album: bool = None) -> typing.Sequence[types.Message]:
"""
Forwards the given message(s) to the specified entity.
Forwards the given messages to the specified entity.
If you want to "forward" a message without the forward header
(the "forwarded from" text), you should use `send_message` with
the original message instead. This will send a copy of it.
Args:
entity (`entity`):
@ -759,7 +764,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
file: hints.FileLike = None,
buttons: hints.MarkupLike = None) -> types.Message:
"""
Edits the given message ID (to change its contents or disable preview).
Edits the given message to change its text or media.
Args:
entity (`entity` | `Message <telethon.tl.custom.message.Message>`):
@ -867,7 +872,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
*,
revoke: bool = True) -> typing.Sequence[types.messages.AffectedMessages]:
"""
Deletes a message from a chat, optionally "for everyone".
Deletes the given messages, optionally "for everyone".
Args:
entity (`entity`):
@ -925,8 +930,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
max_id: int = None,
clear_mentions: bool = False) -> bool:
"""
Sends a "read acknowledge" (i.e., notifying the given peer that we've
read their messages, also known as the "double check").
Marks messages as read and optionally clears mentions.
This effectively marks a message as read (or more than one) in the
given conversation.

8
telethon/client/telegrambaseclient.py
View File

@ -344,13 +344,15 @@ class TelegramBaseClient(abc.ABC):
@property
def loop(self: 'TelegramClient') -> asyncio.AbstractEventLoop:
"""
Property with the ``asyncio`` event loop used by this client.
"""
return self._loop
@property
def disconnected(self: 'TelegramClient') -> asyncio.Future:
"""
Future that resolves when the connection to Telegram
ends, either by user action or in the background.
Property with a ``Future`` that resolves upon disconnection.
"""
return self._sender.disconnected
@ -381,6 +383,8 @@ class TelegramBaseClient(abc.ABC):
def is_connected(self: 'TelegramClient') -> bool:
"""
Returns ``True`` if the user has connected.
This method is **not** asynchronous (don't use ``await`` on it).
"""
sender = getattr(self, '_sender', None)
return sender and sender.is_connected()

24
telethon/client/updates.py
View File

@ -27,9 +27,14 @@ class UpdateMethods(UserMethods):
def run_until_disconnected(self: 'TelegramClient'):
"""
Runs the event loop until `disconnect` is called or if an error
while connecting/sending/receiving occurs in the background. In
the latter case, said error will ``raise`` so you have a chance
Runs the event loop until the library is disconnected.
Disconnections can be manual (by calling `disconnect()
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`)
or not (if the library fails to reconnect automatically).
If a disconnection error occurs (i.e. not manual disconnect),
said error will be raised through here, so you have a chance
to ``except`` it on your own code.
If the loop is already running, this method returns a coroutine
@ -47,7 +52,7 @@ class UpdateMethods(UserMethods):
def on(self: 'TelegramClient', event: EventBuilder):
"""
Decorator helper method around `add_event_handler`. Example:
Decorator used to `add_event_handler` more conveniently.
>>> from telethon import TelegramClient, events
>>> client = TelegramClient(...)
@ -74,7 +79,9 @@ class UpdateMethods(UserMethods):
callback: callable,
event: EventBuilder = None):
"""
Registers the given callback to be called on the specified event.
Registers a new event handler callback.
The callback will be called when the specified event occurs.
Args:
callback (`callable`):
@ -110,7 +117,7 @@ class UpdateMethods(UserMethods):
callback: callable,
event: EventBuilder = None) -> int:
"""
Inverse operation of :meth:`add_event_handler`.
Inverse operation of `add_event_handler`.
If no event is given, all events for this callback are removed.
Returns how many callbacks were removed.
@ -132,8 +139,9 @@ class UpdateMethods(UserMethods):
def list_event_handlers(self: 'TelegramClient')\
-> typing.Sequence[typing.Tuple[callable, EventBuilder]]:
"""
Lists all added event handlers, returning a list of pairs
consisting of (callback, event).
Lists all registered event handlers.
Returns a list of pairs consisting of ``(callback, event)``.
"""
return [(callback, event) for event, callback in self._event_builders]

10
telethon/client/uploads.py
View File

@ -107,7 +107,7 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods):
supports_streaming: bool = False,
**kwargs) -> types.Message:
"""
Sends a file to the specified entity.
Sends message with the given file to the specified entity.
Args:
entity (`entity`):
@ -386,9 +386,11 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods):
use_cache: type = None,
progress_callback: hints.ProgressCallback = None) -> types.TypeInputFile:
"""
Uploads the specified file and returns a handle (an instance of
:tl:`InputFile` or :tl:`InputFileBig`, as required) which can be
later used before it expires (they are usable during less than a day).
Uploads a file to Telegram's servers, without sending it.
This method returns a handle (an instance of :tl:`InputFile` or
:tl:`InputFileBig`, as required) which can be later used before
it expires (they are usable during less than a day).
Uploading a file will simply return a "handle" to the file stored
remotely in the Telegram servers, which can be later used on. This

21
telethon/client/users.py
View File

@ -104,8 +104,9 @@ class UserMethods(TelegramBaseClient):
async def get_me(self: 'TelegramClient', input_peer: bool = False) \
-> typing.Union[types.User, types.InputPeerUser]:
"""
Gets "me" (the self user) which is currently authenticated,
or None if the request fails (hence, not authenticated).
Gets "me", the current :tl:`User` who is logged in.
If the user has not logged in yet, this method returns ``None``.
Args:
input_peer (`bool`, optional):
@ -144,7 +145,7 @@ class UserMethods(TelegramBaseClient):
async def is_user_authorized(self: 'TelegramClient') -> bool:
"""
Returns ``True`` if the user is authorized.
Returns ``True`` if the user is authorized (i.e. has logged in).
"""
if self._authorized is None:
try:
@ -254,11 +255,13 @@ class UserMethods(TelegramBaseClient):
self: 'TelegramClient',
peer: hints.EntityLike) -> types.TypeInputPeer:
"""
Turns the given peer into its input entity version. Most requests
use this kind of :tl:`InputPeer`, so this is the most suitable call
to make for those cases. **Generally you should let the library do
its job** and don't worry about getting the input entity first, but
if you're going to use an entity often, consider making the call:
Turns the given entity into its input entity version.
Most requests use this kind of :tl:`InputPeer`, so this is the most
suitable call to make for those cases. **Generally you should let the
library do its job** and don't worry about getting the input entity
first, but if you're going to use an entity often, consider making the
call:
>>> import asyncio
>>> rc = asyncio.get_event_loop().run_until_complete
@ -380,7 +383,7 @@ class UserMethods(TelegramBaseClient):
peer: hints.EntityLike,
add_mark: bool = True) -> int:
"""
Gets the ID for the given peer, which may be anything entity-like.
Gets the ID for the given entity.
This method needs to be ``async`` because `peer` supports usernames,
invite-links, phone numbers (from people in your contact list), etc.

17
telethon/helpers.py
View File

@ -159,6 +159,23 @@ class TotalList(list):
A list with an extra `total` property, which may not match its `len`
since the total represents the total amount of items *available*
somewhere else, not the items *in this list*.
Examples:
.. code-block:: python
# Telethon returns these lists in some cases (for example,
# only when a chunk is returned, but the "total" count
# is available).
result = client.get_messages(chat, limit=10)
print(result.total) # large number
print(len(result)) # 10
print(result[0]) # latest message
for x in result: # show the 10 messages
print(x.text)
"""
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)