From 3a6c955c904bb307941a873b82fcd26f1412bd8e Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Thu, 20 Feb 2020 10:18:26 +0100 Subject: [PATCH] Add examples to all events --- telethon/events/album.py | 19 +++++++++++++++++++ telethon/events/callbackquery.py | 23 +++++++++++++++++++++++ telethon/events/chataction.py | 11 +++++++++++ telethon/events/inlinequery.py | 15 +++++++++++++++ telethon/events/messagedeleted.py | 11 +++++++++++ telethon/events/messageedited.py | 10 ++++++++++ telethon/events/messageread.py | 15 +++++++++++++++ telethon/events/newmessage.py | 18 ++++++++++++++++++ telethon/events/raw.py | 10 ++++++++++ telethon/events/userupdate.py | 11 +++++++++++ 10 files changed, 143 insertions(+) diff --git a/telethon/events/album.py b/telethon/events/album.py index 68e08e7c..2ba1e61b 100644 --- a/telethon/events/album.py +++ b/telethon/events/album.py @@ -20,6 +20,25 @@ class Album(EventBuilder): Occurs whenever you receive an album. This event only exists to ease dealing with an unknown amount of messages that belong to the same album. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.Album) + async def handler(event): + # Counting how many photos or videos the album has + print('Got an album with', len(event), 'items') + + # Forwarding the album as a whole to some chat + event.forward_to(chat) + + # Printing the caption + print(event.text) + + # Replying to the fifth item in the album + await event.messages[4].reply('Cool!') """ def __init__( diff --git a/telethon/events/callbackquery.py b/telethon/events/callbackquery.py index cb879682..5a6e1370 100644 --- a/telethon/events/callbackquery.py +++ b/telethon/events/callbackquery.py @@ -31,6 +31,29 @@ class CallbackQuery(EventBuilder): against the payload data, a callable function that returns `True` if a the payload data is acceptable, or a compiled regex pattern. + Example + .. code-block:: python + + from telethon import events, Button + + # Handle all callback queries and check data inside the handler + @client.on(events.CallbackQuery) + async def handler(event): + if event.data == b'yes': + await event.answer('Correct answer!') + + # Handle only callback queries with data being b'no' + @client.on(events.CallbackQuery(data=b'no')) + async def handler(event): + # Pop-up message with alert + await event.answer('Wrong answer!', alert=True) + + # Send a message with buttons users can click + async def main(): + await client.send_message(user, 'Yes or no?', buttons=[ + Button.inline('Yes!', b'yes') + Button.inline('Nope', b'no') + ]) """ def __init__( self, chats=None, *, blacklist_chats=False, func=None, data=None, pattern=None): diff --git a/telethon/events/chataction.py b/telethon/events/chataction.py index fd4542ef..7f9acb9d 100644 --- a/telethon/events/chataction.py +++ b/telethon/events/chataction.py @@ -17,6 +17,17 @@ class ChatAction(EventBuilder): Note that "chat" refers to "small group, megagroup and broadcast channel", whereas "group" refers to "small group and megagroup" only. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.ChatAction) + async def handler(event): + # Welcome every new user + if event.user_joined: + await event.reply('Welcome to the group!') """ @classmethod def build(cls, update, others=None, self_id=None): diff --git a/telethon/events/inlinequery.py b/telethon/events/inlinequery.py index 73044700..b23e3ac2 100644 --- a/telethon/events/inlinequery.py +++ b/telethon/events/inlinequery.py @@ -31,6 +31,21 @@ class InlineQuery(EventBuilder): You can specify a regex-like string which will be matched against the message, a callable function that returns `True` if a message is acceptable, or a compiled regex pattern. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.InlineQuery) + async def handler(event): + builder = event.builder + + # Two options (convert user text to UPPERCASE or lowercase) + await event.answer([ + builder.article('UPPERCASE', text=event.text.upper()), + builder.article('lowercase', text=event.text.lower()), + ]) """ def __init__( self, users=None, *, blacklist_users=False, func=None, pattern=None): diff --git a/telethon/events/messagedeleted.py b/telethon/events/messagedeleted.py index bd2a84a4..f631fd4f 100644 --- a/telethon/events/messagedeleted.py +++ b/telethon/events/messagedeleted.py @@ -23,6 +23,17 @@ class MessageDeleted(EventBuilder): This means that the ``chats=`` parameter will not work reliably, unless you intend on working with channels and super-groups only. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.MessageDeleted) + async def handler(event): + # Log all deleted message IDs + for msg_id in event.deleted_ids: + print('Message', msg_id, 'was deleted in', event.chat_id) """ @classmethod def build(cls, update, others=None, self_id=None): diff --git a/telethon/events/messageedited.py b/telethon/events/messageedited.py index a0578f41..c4a2b4a7 100644 --- a/telethon/events/messageedited.py +++ b/telethon/events/messageedited.py @@ -31,6 +31,16 @@ class MessageEdited(NewMessage): Instead, consider using ``from_users='me'`` (it won't work in broadcast channels at all since the sender is the channel and not you). + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.MessageEdited) + async def handler(event): + # Log the date of new edits + print('Message', event.id, 'changed at', event.date) """ @classmethod def build(cls, update, others=None, self_id=None): diff --git a/telethon/events/messageread.py b/telethon/events/messageread.py index 5dfec30f..29f17ab8 100644 --- a/telethon/events/messageread.py +++ b/telethon/events/messageread.py @@ -13,6 +13,21 @@ class MessageRead(EventBuilder): 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. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.MessageRead) + async def handler(event): + # Log when someone reads your messages + print('Someone has read all your messages until', event.max_id) + + @client.on(events.MessageRead(inbox=True)) + async def handler(event): + # Log when you read message in a chat (from your "inbox") + print('You have read messages until', event.max_id) """ def __init__( self, chats=None, *, blacklist_chats=False, func=None, inbox=False): diff --git a/telethon/events/newmessage.py b/telethon/events/newmessage.py index a1f03be7..fc3eaaf2 100644 --- a/telethon/events/newmessage.py +++ b/telethon/events/newmessage.py @@ -37,6 +37,24 @@ class NewMessage(EventBuilder): You can specify a regex-like string which will be matched against the message, a callable function that returns `True` if a message is acceptable, or a compiled regex pattern. + + Example + .. code-block:: python + + import asyncio + from telethon import events + + @client.on(events.NewMessage(pattern='(?i)hello.+')) + async def handler(event): + # Respond whenever someone says "Hello" and something else + await event.reply('Hey!') + + @client.on(events.NewMessage(outgoing=True, pattern='!ping')) + async def handler(event): + # Say "!pong" whenever you send "!ping", then delete both messages + m = await event.respond('!pong') + await asyncio.sleep(5) + await client.delete_messages(event.chat_id, [event.id, m.id]) """ def __init__(self, chats=None, *, blacklist_chats=False, func=None, incoming=None, outgoing=None, diff --git a/telethon/events/raw.py b/telethon/events/raw.py index f0a4cd9d..f7eebb6a 100644 --- a/telethon/events/raw.py +++ b/telethon/events/raw.py @@ -12,6 +12,16 @@ class Raw(EventBuilder): types (`list` | `tuple` | `type`, optional): The type or types that the :tl:`Update` instance must be. Equivalent to ``if not isinstance(update, types): return``. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.Raw) + async def handler(update): + # Print all incoming updates + print(update.stringify()) """ def __init__(self, types=None, *, func=None): super().__init__(func=func) diff --git a/telethon/events/userupdate.py b/telethon/events/userupdate.py index dee6e470..02dfe7d7 100644 --- a/telethon/events/userupdate.py +++ b/telethon/events/userupdate.py @@ -36,6 +36,17 @@ def _requires_status(function): class UserUpdate(EventBuilder): """ Occurs whenever a user goes online, starts typing, etc. + + Example + .. code-block:: python + + from telethon import events + + @client.on(events.UserUpdate) + async def handler(event): + # If someone is uploading, say something + if event.uploading: + await client.send_message(event.user_id, 'What are you sending?') """ @classmethod def build(cls, update, others=None, self_id=None):