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

Enhance documentation

Browse Source
This commit is contained in:
Lonami Exo 2018-05-17 12:00:22 +02:00
parent a8be4bb615
commit cffef411b2
13 changed files with 94 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
readthedocs/extra/advanced-usage/accessing-the-full-api.rst
View File

@ -4,6 +4,12 @@
Accessing the Full API
======================
.. important::
While you have access to this, you should always use the friendly
methods listed on :ref:`telethon-package` unless you have a better
reason not to, like a method not existing or you wanting more control.
The ``TelegramClient`` doesn't offer a method for every single request
the Telegram API supports. However, it's very simple to *call* or *invoke*

2
readthedocs/extra/basic/getting-started.rst
View File

@ -65,6 +65,8 @@ Basic Usage
**More details**: :ref:`telegram-client`
See :ref:`telethon-package` for all available friendly methods.
Handling Updates
****************

6
readthedocs/extra/basic/telegram-client.rst
View File

@ -10,8 +10,10 @@ Introduction
.. note::
Check the :ref:`telethon-package` if you're looking for the methods
reference instead of this tutorial.
Make sure to use the friendly methods described in :ref:`telethon-package`!
This section is just an introduction to using the client, but all the
available methods are in the :ref:`telethon-package` reference, including
detailed descriptions to what they do.
The ``TelegramClient`` is the central class of the library, the one
you will be using most of the time. For this reason, it's important

11
readthedocs/extra/examples/chats-and-channels.rst
View File

@ -94,12 +94,13 @@ the hash of said channel or group.
Retrieving all chat members (channels too)
******************************************
You can use
`client.get_participants <telethon.telegram_client.TelegramClient.get_participants>`
to retrieve the participants (click it to see the relevant parameters).
Most of the time you will just need ``client.get_participants(entity)``.
.. note::
Use the `telethon.telegram_client.TelegramClient.iter_participants`
friendly method instead unless you have a better reason not to!
This method will handle different chat types for you automatically.
This is what said method is doing behind the scenes as an example.
In order to get all the members from a mega-group or channel, you need
to use :tl:`GetParticipantsRequest`. As we can see it needs an

3
readthedocs/extra/examples/projects-using-telethon.rst
View File

@ -12,6 +12,7 @@ the library.
`issue 744 <https://github.com/LonamiWebs/Telethon/issues/744>`_
so it can be included in the next revision of the documentation!
.. _projects-telegram-export:
telegram-export
***************
@ -22,6 +23,7 @@ telegram-export
A tool to download Telegram data (users, chats, messages, and media)
into a database (and display the saved data).
.. _projects-mautrix-telegram:
mautrix-telegram
****************
@ -31,6 +33,7 @@ mautrix-telegram
A Matrix-Telegram hybrid puppeting/relaybot bridge.
.. _projects-telegramtui:
TelegramTUI
***********

2
readthedocs/extra/examples/users.rst
View File

@ -65,6 +65,6 @@ through :tl:`UploadProfilePhoto`:
from telethon.tl.functions.photos import UploadProfilePhotoRequest
client(functions.photos.UploadProfilePhotoRequest(
client(UploadProfilePhotoRequest(
client.upload_file('/path/to/some/file')
))

22
readthedocs/extra/examples/working-with-messages.rst
View File

@ -11,11 +11,14 @@ Working with messages
Forwarding messages
*******************
This request is available as a friendly method through
`client.forward_messages <telethon.telegram_client.TelegramClient.forward_messages>`,
and can be used like shown below:
.. note::
.. code-block:: python
Use the `telethon.telegram_client.TelegramClient.forward_messages`
friendly method instead unless you have a better reason not to!
This method automatically accepts either a single message or many of them.
.. code-block:: python
# If you only have the message IDs
client.forward_messages(
@ -51,6 +54,14 @@ too, if that's all you have.
Searching Messages
*******************
.. note::
Use the `telethon.telegram_client.TelegramClient.iter_messages`
friendly method instead unless you have a better reason not to!
This method has ``search`` and ``filter`` parameters that will
suit your needs.
Messages are searched through the obvious :tl:`SearchRequest`, but you may run
into issues_. A valid example would be:
@ -71,7 +82,8 @@ into issues_. A valid example would be:
limit=10, # How many results
max_id=0, # Maximum message ID
min_id=0, # Minimum message ID
from_id=None # Who must have sent the message (peer)
from_id=None, # Who must have sent the message (peer)
hash=0 # Special number to return nothing on no-change
))
It's important to note that the optional parameter ``from_id`` could have

3
readthedocs/index.rst
View File

@ -18,6 +18,9 @@ when you upgrade!
If you're new here, you want to read :ref:`getting-started`. If you're
looking for the method reference, you should check :ref:`telethon-package`.
The mentioned :ref:`telethon-package` is an important section and it
contains the friendly methods that **you should use** most of the time.
What is this?
*************

7
readthedocs/telethon.events.rst
View File

@ -47,6 +47,13 @@ so all the methods in it can be used from any event builder/event instance.
:undoc-members:
:show-inheritance:
.. automodule:: telethon.events.raw
:members:
:undoc-members:
:show-inheritance:
.. automodule:: telethon.events
:members:
:undoc-members:

15
telethon/events/chataction.py
View File

@ -160,17 +160,19 @@ class ChatAction(EventBuilder):
def respond(self, *args, **kwargs):
"""
Responds to the chat action message (not as a reply).
Shorthand for ``client.send_message(event.chat, ...)``.
Responds to the chat action message (not as a reply). Shorthand for
`telethon.telegram_client.TelegramClient.send_message` with
``entity`` already set.
"""
return self._client.send_message(self.input_chat, *args, **kwargs)
def reply(self, *args, **kwargs):
"""
Replies to the chat action message (as a reply). Shorthand for
``client.send_message(event.chat, ..., reply_to=event.message.id)``.
`telethon.telegram_client.TelegramClient.send_message` with
both ``entity`` and ``reply_to`` already set.
Has the same effect as ``.respond()`` if there is no message.
Has the same effect as `respond` if there is no message.
"""
if not self.action_message:
return self.respond(*args, **kwargs)
@ -182,8 +184,9 @@ class ChatAction(EventBuilder):
"""
Deletes the chat action message. You're responsible for checking
whether you have the permission to do so, or to except the error
otherwise. This is a shorthand for
``client.delete_messages(event.chat, event.message, ...)``.
otherwise. Shorthand for
`telethon.telegram_client.TelegramClient.delete_messages` with
``entity`` and ``message_ids`` already set.
Does nothing if no message action triggered this event.
"""

3
telethon/events/common.py
View File

@ -1,12 +1,9 @@
import abc
import datetime
import itertools
import re
import warnings
from .. import utils
from ..errors import RPCError
from ..extensions import markdown
from ..tl import TLObject, types, functions

42
telethon/events/newmessage.py
View File

@ -1,16 +1,9 @@
import abc
import datetime
import itertools
import re
import warnings
from .. import utils
from ..errors import RPCError
from ..extensions import markdown
from ..tl import TLObject, types, functions
from .common import EventBuilder, EventCommon, name_inner_event
from .. import utils
from ..extensions import markdown
from ..tl import types, functions
@name_inner_event
@ -155,23 +148,26 @@ class NewMessage(EventBuilder):
def respond(self, *args, **kwargs):
"""
Responds to the message (not as a reply). This is a shorthand for
``client.send_message(event.chat, ...)``.
Responds to the message (not as a reply). Shorthand for
`telethon.telegram_client.TelegramClient.send_message` with
``entity`` already set.
"""
return self._client.send_message(self.input_chat, *args, **kwargs)
def reply(self, *args, **kwargs):
"""
Replies to the message (as a reply). This is a shorthand for
``client.send_message(event.chat, ..., reply_to=event.message.id)``.
Replies to the message (as a reply). Shorthand for
`telethon.telegram_client.TelegramClient.send_message` with
both ``entity`` and ``reply_to`` already set.
"""
kwargs['reply_to'] = self.message.id
return self._client.send_message(self.input_chat, *args, **kwargs)
def forward_to(self, *args, **kwargs):
"""
Forwards the message. This is a shorthand for
``client.forward_messages(entity, event.message, event.chat)``.
Forwards the message. Shorthand for
`telethon.telegram_client.TelegramClient.forward_messages` with
both ``messages`` and ``from_peer`` already set.
"""
kwargs['messages'] = self.message.id
kwargs['from_peer'] = self.input_chat
@ -179,11 +175,12 @@ class NewMessage(EventBuilder):
def edit(self, *args, **kwargs):
"""
Edits the message iff it's outgoing. This is a shorthand for
``client.edit_message(event.chat, event.message, ...)``.
Edits the message iff it's outgoing. Shorthand for
`telethon.telegram_client.TelegramClient.edit_message` with
both ``entity`` and ``message`` already set.
Returns ``None`` if the message was incoming,
or the edited message otherwise.
Returns ``None`` if the message was incoming, or the edited
:tl:`Message` otherwise.
"""
if self.message.fwd_from:
return None
@ -202,8 +199,9 @@ class NewMessage(EventBuilder):
"""
Deletes the message. You're responsible for checking whether you
have the permission to do so, or to except the error otherwise.
This is a shorthand for
``client.delete_messages(event.chat, event.message, ...)``.
Shorthand for
`telethon.telegram_client.TelegramClient.delete_messages` with
``entity`` and ``message_ids`` already set.
"""
return self._client.delete_messages(self.input_chat,
[self.message],

30
telethon/telegram_client.py
View File

@ -768,6 +768,12 @@ class TelegramClient(TelegramBareClient):
other false-y value is provided, the message will be sent with
no formatting.
If a ``callable`` is passed, it should be a function accepting
a `str` as an input and return as output a tuple consisting
of ``(parsed message str, [MessageEntity instances])``.
See :tl:`MessageEntity` for allowed message entities.
link_preview (`bool`, optional):
Should the link preview be shown?
@ -1462,9 +1468,6 @@ class TelegramClient(TelegramBareClient):
or its type won't be inferred, and it will be sent as an
"unnamed application/octet-stream".
Subsequent calls with the very same file will result in
immediate uploads, unless ``.clear_file_cache()`` is called.
Furthermore the file may be any media (a message, document,
photo or similar) so that it can be resent without the need
to download and re-upload it again.
@ -1486,7 +1489,7 @@ class TelegramClient(TelegramBareClient):
``(sent bytes, total)``.
reply_to (`int` | :tl:`Message`):
Same as reply_to from .send_message().
Same as `reply_to` from `send_message`.
attributes (`list`, optional):
Optional attributes that override the inferred ones, like
@ -1761,8 +1764,8 @@ class TelegramClient(TelegramBareClient):
progress_callback=None):
"""
Uploads the specified file and returns a handle (an instance of
InputFile or InputFileBig, as required) which can be later used
before it expires (they are usable during less than a day).
: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
@ -1775,9 +1778,6 @@ class TelegramClient(TelegramBareClient):
or its type won't be inferred, and it will be sent as an
"unnamed application/octet-stream".
Subsequent calls with the very same file will result in
immediate uploads, unless ``.clear_file_cache()`` is called.
part_size_kb (`int`, optional):
Chunk size when uploading files. The larger, the less
requests will be made (up to 512KB maximum).
@ -1788,8 +1788,8 @@ class TelegramClient(TelegramBareClient):
and if this is not a ``str``, it will be ``"unnamed"``.
use_cache (`type`, optional):
The type of cache to use (currently either ``InputDocument``
or ``InputPhoto``). If present and the file is small enough
The type of cache to use (currently either :tl:`InputDocument`
or :tl:`InputPhoto`). If present and the file is small enough
to need the MD5, it will be checked against the database,
and if a match is found, the upload won't be made. Instead,
an instance of type ``use_cache`` will be returned.
@ -1800,7 +1800,8 @@ class TelegramClient(TelegramBareClient):
Returns:
:tl:`InputFileBig` if the file size is larger than 10MB,
``InputSizedFile`` (subclass of :tl:`InputFile`) otherwise.
`telethon.tl.custom.input_sized_file.InputSizedFile`
(subclass of :tl:`InputFile`) otherwise.
"""
if isinstance(file, (InputFile, InputFileBig)):
return file # Already uploaded
@ -2357,8 +2358,9 @@ class TelegramClient(TelegramBareClient):
The event builder class or instance to be used,
for instance ``events.NewMessage``.
If left unspecified, ``events.Raw`` (the ``Update`` objects
with no further processing) will be passed instead.
If left unspecified, `telethon.events.raw.Raw` (the
:tl:`Update` objects with no further processing) will
be passed instead.
"""
if self.updates.workers is None:
warnings.warn(