Merge branch 'examples'

examples/README.md

@@ -0,0 +1,14 @@
+# Examples
+
+This folder contains example scripts to show you how **Pyrogram** looks like.
+You can start with [hello_world.py](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.py) and continue
+with the more advanced examples. Every script is working right away, 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 sending media (photo, video, ...). 
+
+- [**hello_world.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/hello_world.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)
+- [**updates.py**](https://github.com/pyrogram/pyrogram/blob/master/examples/updates.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)

examples/advanced_echo.py

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,55 @@
+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/get_history.py

@@ -0,0 +1,37 @@
+import time
+
+from pyrogram import Client
+from pyrogram.api import functions
+from pyrogram.api.errors import FloodWait
+
+client = Client("example")
+client.start()
+
+target = "me"  # "me" refers to your own chat (Saved Messages)
+history = []  # List that will contain all the messages of the target chat
+limit = 100  # Amount of messages to retrieve for each API call
+offset = 0  # Offset starts at 0
+
+while True:
+    try:
+        messages = client.send(
+            functions.messages.GetHistory(
+                client.resolve_peer(target),
+                0, 0, offset, limit, 0, 0, 0
+            )
+        )
+    except FloodWait as e:
+        # For very large chats the method call can raise a FloodWait
+        time.sleep(e.x)  # Sleep X seconds before continuing
+        continue
+
+    if not messages.messages:
+        break  # No more messages left
+
+    history.extend(messages.messages)
+    offset += limit
+
+client.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

@@ -0,0 +1,40 @@
+import time
+
+from pyrogram import Client
+from pyrogram.api import functions, types
+from pyrogram.api.errors import FloodWait
+
+client = Client("example")
+client.start()
+
+target = "username"  # Target channel/supergroup
+users = []  # List that will contain all the users of the target chat
+limit = 200  # Amount of users to retrieve for each API call
+offset = 0  # Offset starts at 0
+
+while True:
+    try:
+        participants = client.send(
+            functions.channels.GetParticipants(
+                channel=client.resolve_peer(target),
+                filter=types.ChannelParticipantsSearch(""),  # Filter by empty string (search for all)
+                offset=offset,
+                limit=limit,
+                hash=0
+            )
+        )
+    except FloodWait as e:
+        # Very large channels will trigger FloodWait.
+        # When happens, wait X seconds before continuing
+        time.sleep(e.x)
+        continue
+
+    if not participants.participants:
+        break  # No more participants left
+
+    users.extend(participants.users)
+    offset += limit
+
+client.stop()
+
+# Now the "users" list contains all the members of the target chat

examples/hello_world.py

@@ -0,0 +1,19 @@
+from pyrogram import Client
+
+# Create a new Client
+client = Client("example")
+
+# Start the Client
+client.start()
+
+# Send a message to yourself, Markdown is enabled by default
+client.send_message("me", "Hi there! I'm using **Pyrogram**")
+
+# Send a photo with a formatted caption to yourself
+client.send_photo("me", "data/pyrogram.png", "__This is a formatted__ **caption**")
+
+# Send a location to yourself
+client.send_location("me", 51.500729, -0.124583)
+
+# Stop the client
+client.stop()

examples/simple_echo.py

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,25 @@
+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()