Update examples

examples/README.md

@@ -5,16 +5,13 @@ You can start with [hello_world.py](https://github.com/pyrogram/pyrogram/blob/ma
 with the more advanced examples.
 
 Every script is working right away (provided you correctly set up your credentials), meaning
-you can simply copy-paste and run, the only things you have to change are the target chats (username, id) and file paths for
+you can simply copy-paste and run, the only things you have to change are your session names and the target chats
-sending media (photo, video, ...). 
 
-- [**hello_world.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py)
+- [**echo_bot.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/echo_bot.py)
 - [**get_history.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/get_history.py)
 - [**get_participants.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/get_participants.py)
 - [**get_participants2.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/get_participants2.py)
+- [**hello_world.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py)
 - [**inline_bots.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/inline_bots.py)
-- [**updates.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/updates.py)
+- [**raw_update_handler.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/raw_update_handler.py)
-- [**simple_echo.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/simple_echo.py)
-- [**advanced_echo.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/advanced_echo.py)
-- [**advanced_echo2.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/advanced_echo2.py)
 - [**welcome_bot.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/welcome_bot.py)

examples/advanced_echo.py

@@ -1,64 +0,0 @@
-from pyrogram import Client
-from pyrogram.api import types
-
-"""This is a more advanced example bot that will reply to all private and basic groups text messages
-by also mentioning the Users.
-
-Beware! This script will make you reply to ALL new messages in private chats and in every basic group you are in.
-Make sure you add an extra check to filter them:
-
-# Filter Groups by ID
-if message.to_id.chat_id == MY_GROUP_ID:
-    ...
-"""
-
-
-def update_handler(client, update, users, chats):
-    if isinstance(update, types.UpdateNewMessage):  # Filter by UpdateNewMessage (PM and Chats)
-        message = update.message
-
-        if isinstance(message, types.Message):  # Filter by Message to exclude MessageService and MessageEmpty
-            if isinstance(message.to_id, types.PeerUser):  # Private Messages
-                text = '[{}](tg://user?id={}) said "{}" to me ([{}](tg://user?id={}))'.format(
-                    users[message.from_id].first_name,
-                    users[message.from_id].id,
-                    message.message,
-                    users[message.to_id.user_id].first_name,
-                    users[message.to_id.user_id].id
-                )
-
-                client.send_message(
-                    message.from_id,  # Send the message to the private chat (from_id)
-                    text,
-                    reply_to_message_id=message.id
-                )
-            else:  # Group chats
-                text = '[{}](tg://user?id={}) said "{}" in **{}** group'.format(
-                    users[message.from_id].first_name,
-                    users[message.from_id].id,
-                    message.message,
-                    chats[message.to_id.chat_id].title
-                )
-
-                client.send_message(
-                    message.to_id,  # Send the message to the group chat (to_id)
-                    text,
-                    reply_to_message_id=message.id
-                )
-
-
-def main():
-    # Pyrogram setup
-    client = Client("example")
-
-    # Set the update_handler callback function
-    client.set_update_handler(update_handler)
-    client.start()
-
-    # Blocks the program execution until you press CTRL+C then
-    # automatically stops the Client by closing the underlying connection
-    client.idle()
-
-
-if __name__ == "__main__":
-    main()

examples/advanced_echo2.py

@@ -1,55 +0,0 @@
-from pyrogram import Client
-from pyrogram.api import types
-
-"""This example is similar to advanced_echo.py, except for the fact that it will reply to Supergroup text messages only.
-
-Beware! This script will make you reply to ALL new messages in every single supergroup you are in.
-Make sure you add an extra check to filter them:
-
-# Filter Supergroups by ID
-if message.to_id.channel_id == MY_SUPERGROUP_ID:
-    ...
-
-# Filter Supergroups by Username
-if chats[message.to_id.channel_id].username == MY_SUPERGROUP_USERNAME:
-    ...
-"""
-
-
-def update_handler(client, update, users, chats):
-    # Channels and Supergroups share the same type (Channel). The .megagroup field is used to tell them apart, and is
-    # True for Supegroups, False for Channels.
-    if isinstance(update, types.UpdateNewChannelMessage):  # Filter by UpdateNewChannelMessage (Channels/Supergroups)
-        message = update.message
-
-        if isinstance(message, types.Message):  # Filter by Message to exclude MessageService and MessageEmpty
-            if chats[message.to_id.channel_id].megagroup:  # Only handle messages from Supergroups not Channels
-                text = '[{}](tg://user?id={}) said "{}" in **{}** supergroup'.format(
-                    users[message.from_id].first_name,
-                    users[message.from_id].id,
-                    message.message,
-                    chats[message.to_id.channel_id].title
-                )
-
-                client.send_message(
-                    message.to_id,
-                    text,
-                    reply_to_message_id=message.id
-                )
-
-
-def main():
-    # Pyrogram setup
-    client = Client("example")
-
-    # Set the update_handler callback function
-    client.set_update_handler(update_handler)
-    client.start()
-
-    # Blocks the program execution until you press CTRL+C then
-    # automatically stops the Client by closing the underlying connection
-    client.idle()
-
-
-if __name__ == "__main__":
-    main()

examples/echo_bot.py

@@ -0,0 +1,17 @@
+from pyrogram import Client, Filters
+
+"""This simple echo bot replies to every private text message"""
+
+app = Client("my_account")
+
+
+@app.on_message(Filters.text & Filters.private)
+def echo(client, message):
+    client.send_message(
+        message.chat.id, message.text,
+        reply_to_message_id=message.message_id
+    )
+
+
+app.start()
+app.idle()

examples/get_history.py

@@ -4,8 +4,8 @@ from pyrogram import Client
 from pyrogram.api import functions
 from pyrogram.api.errors import FloodWait
 
-client = Client("example")
+app = Client("my_account")
-client.start()
+app.start()
 
 target = "me"  # "me" refers to your own chat (Saved Messages)
 history = []  # List that will contain all the messages of the target chat
@@ -14,9 +14,9 @@ offset = 0  # Offset starts at 0
 
 while True:
     try:
-        messages = client.send(
+        messages = app.send(
             functions.messages.GetHistory(
-                client.resolve_peer(target),
+                app.resolve_peer(target),
                 0, 0, offset, limit, 0, 0, 0
             )
         )
@@ -31,7 +31,7 @@ while True:
     history.extend(messages.messages)
     offset += limit
 
-client.stop()
+app.stop()
 
 # Now the "history" list contains all the messages sorted by date in
 # descending order (from the most recent to the oldest one)

examples/get_participants.py

@@ -4,8 +4,8 @@ from pyrogram import Client
 from pyrogram.api import functions, types
 from pyrogram.api.errors import FloodWait
 
-client = Client("example")
+app = Client("my_account")
-client.start()
+app.start()
 
 target = "username"  # Target channel/supergroup
 users = []  # List that will contain all the users of the target chat
@@ -14,9 +14,9 @@ offset = 0  # Offset starts at 0
 
 while True:
     try:
-        participants = client.send(
+        participants = app.send(
             functions.channels.GetParticipants(
-                channel=client.resolve_peer(target),
+                channel=app.resolve_peer(target),
                 filter=types.ChannelParticipantsSearch(""),  # Filter by empty string (search for all)
                 offset=offset,
                 limit=limit,
@@ -35,6 +35,6 @@ while True:
     users.extend(participants.users)
     offset += limit
 
-client.stop()
+app.stop()
 
 # Now the "users" list contains all the members of the target chat

examples/get_participants2.py

@@ -15,8 +15,8 @@ This can be further improved by also searching for non-ascii characters (e.g.: J
 as some user names may not contain ascii letters at all.
 """
 
-client = Client("example")
+app = Client("my_account")
-client.start()
+app.start()
 
 target = "username"  # Target channel/supergroup username or id
 users = {}  # To ensure uniqueness, users will be stored in a dictionary with user_id as key
@@ -31,9 +31,9 @@ for q in queries:
 
     while True:
         try:
-            participants = client.send(
+            participants = app.send(
                 functions.channels.GetParticipants(
-                    channel=client.resolve_peer(target),
+                    channel=app.resolve_peer(target),
                     filter=types.ChannelParticipantsSearch(q),
                     offset=offset,
                     limit=limit,
@@ -60,4 +60,4 @@ for q in queries:
 
         print("Total users: {}".format(len(users)))
 
-client.stop()
+app.stop()

examples/hello_world.py

@@ -1,5 +1,7 @@
 from pyrogram import Client
 
+"""This example demonstrates a simple API methods usage"""
+
 # Create a new Client
 app = Client("my_account")
 

examples/inline_bots.py

@@ -1,15 +1,15 @@
 from pyrogram import Client
 
 # Create a new Client
-client = Client("example")
+app = Client("my_account")
 
 # Start the Client
-client.start()
+app.start()
 
 # Get bot results for "Fuzz Universe" from the inline bot @vid
-bot_results = client.get_inline_bot_results("vid", "Fuzz Universe")
+bot_results = app.get_inline_bot_results("vid", "Fuzz Universe")
 # Send the first result (bot_results.results[0]) to your own chat (Saved Messages)
-client.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id)
+app.send_inline_bot_result("me", bot_results.query_id, bot_results.results[0].id)
 
 # Stop the client
-client.stop()
+app.stop()

examples/raw_update_handler.py

@@ -0,0 +1,14 @@
+from pyrogram import Client
+
+"""This example shows how to handle raw updates"""
+
+app = Client("my_account")
+
+
+@app.on_raw_update()
+def raw(client, update, users, chats):
+    print(update)
+
+
+app.start()
+app.idle()

examples/simple_echo.py

@@ -1,34 +0,0 @@
-from pyrogram import Client
-from pyrogram.api import types
-
-"""This simple example bot will reply to all private text messages"""
-
-
-def update_handler(client, update, users, chats):
-    if isinstance(update, types.UpdateNewMessage):  # Filter by UpdateNewMessage (Private Messages)
-        message = update.message  # type: types.Message
-
-        if isinstance(message, types.Message):  # Filter by Message to exclude MessageService and MessageEmpty
-            if isinstance(message.to_id, types.PeerUser):  # Private Messages (Message from user)
-                client.send_message(
-                    chat_id=message.from_id,
-                    text=message.message,
-                    reply_to_message_id=message.id
-                )
-
-
-def main():
-    # Pyrogram setup
-    client = Client("example")
-
-    # Set the update_handler callback function
-    client.set_update_handler(update_handler)
-    client.start()
-
-    # Blocks the program execution until you press CTRL+C then
-    # automatically stops the Client by closing the underlying connection
-    client.idle()
-
-
-if __name__ == "__main__":
-    main()

examples/updates.py

@@ -1,25 +0,0 @@
-from pyrogram import Client
-
-
-# This function will be called every time a new Update is received from Telegram
-def update_handler(client, update, users, chats):
-    # Send EVERY update that arrives to your own chat (Saved Messages)
-    # Use triple backticks to make the text look nicer.
-    client.send_message("me", "```\n" + str(update) + "```")
-
-
-def main():
-    # Pyrogram setup
-    client = Client("example")
-
-    # Set the update_handler callback function
-    client.set_update_handler(update_handler)
-    client.start()
-
-    # Blocks the program execution until you press CTRL+C then
-    # automatically stops the Client by closing the underlying connection
-    client.idle()
-
-
-if __name__ == "__main__":
-    main()

examples/welcome_bot.py

@@ -1,52 +1,32 @@
-from pyrogram import Client, Emoji
+from pyrogram import Client, Emoji, Filters
-from pyrogram.api import types
 
 """
 This is the Welcome Bot in @PyrogramChat
-The code is commented to help you understand each part
+It uses the Emoji module to easily add emojis in your text messages and Filters
-
+to make it only work for specific messages in a specific chat 
-It also uses the Emoji module to easily add emojis in your text messages
 """
 
-# Your Supergroup ID
+app = Client("my_account")
-SUPERGROUP_ID = 1387666944
 
 
-def update_handler(client, update, users, chats):
+@app.on_message(Filters.chat("PyrogramChat") & Filters.new_chat_members)
-    # Supergroup messages are contained in the "UpdateNewChannelMessage" update type
+def welcome(client, message):
-    if isinstance(update, types.UpdateNewChannelMessage):
+    new_members = ", ".join([
-        message = update.message
+        "[{}](tg://user?id={})".format(i.first_name, i.id)
-        # When a user joins, a "MessageService" is received
+        for i in message.new_chat_members]
-        if isinstance(message, types.MessageService):
+    )
-            # Check if the message is sent to your SUPERGROUP_ID
+
-            if message.to_id.channel_id == SUPERGROUP_ID:
+    text = "{} Welcome to [Pyrogram](https://docs.pyrogram.ml/)'s group chat {}!".format(
-                # A "MessageService" contains the "action" field.
+        Emoji.SPARKLES,
-                # The action for user joins is "MessageActionChatAddUser" if the user
+        new_members
-                # joined using the username, otherwise is "MessageActionChatJoinedByLink" if
+    )
-                # the user joined a private group by link
+
-                if isinstance(message.action, (types.MessageActionChatAddUser, types.MessageActionChatJoinedByLink)):
+    client.send_message(
-                    # Now send the welcome message. Extra info about a user (such as the first_name, username, ...)
+        message.chat.id, text,
-                    # are contained in the users dictionary and can be accessed by the user ID
+        reply_to_message_id=message.message_id,
-                    client.send_message(
+        disable_web_page_preview=True
-                        SUPERGROUP_ID,
+    )
-                        "{} Welcome to [Pyrogram](https://docs.pyrogram.ml/)'s "
-                        "group chat, [{}](tg://user?id={})!".format(
-                            Emoji.SPARKLES,  # Add an emoji
-                            users[message.from_id].first_name,
-                            users[message.from_id].id
-                        ),
-                        reply_to_message_id=message.id,
-                        disable_web_page_preview=True
-                    )
 
 
-def main():
+app.start()
-    client = Client("example")
+app.idle()
-    client.set_update_handler(update_handler)
-
-    client.start()
-    client.idle()
-
-
-if __name__ == "__main__":
-    main()