Add examples to all events

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

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

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

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

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

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

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

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,

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)

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