diff --git a/docs/Makefile b/docs/Makefile index cb346f83..c01e3d3d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line. SPHINXOPTS = -SPHINXBUILD = ~/PycharmProjects/pyrogram/venv/bin/sphinx-build +SPHINXBUILD = ~/PycharmProjects/pyrogram/venv3.6/bin/sphinx-build SPHINXPROJ = Pyrogram SOURCEDIR = source BUILDDIR = build diff --git a/docs/source/index.rst b/docs/source/index.rst index 61394d7b..414e47dd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,12 +44,11 @@ Welcome to Pyrogram @app.on_message(Filters.private) def hello(client, message): - client.send_message( - message.chat.id, "Hello {}".format(message.from_user.first_name)) + message.reply_text( + "Hello {}".format(message.from_user.first_name)) - app.start() - app.idle() + app.run() Welcome to Pyrogram's Documentation! Here you can find resources for learning how to use the library. Contents are organized by topic and can be accessed from the sidebar, or by following them one by one using the Next diff --git a/docs/source/pyrogram/Client.rst b/docs/source/pyrogram/Client.rst index 3e65b0f6..0448c3cb 100644 --- a/docs/source/pyrogram/Client.rst +++ b/docs/source/pyrogram/Client.rst @@ -17,6 +17,7 @@ Client start stop idle + run on_message on_callback_query on_raw_update diff --git a/docs/source/pyrogram/handlers/DeletedMessagesHandler.rst b/docs/source/pyrogram/handlers/DeletedMessagesHandler.rst new file mode 100644 index 00000000..128bc656 --- /dev/null +++ b/docs/source/pyrogram/handlers/DeletedMessagesHandler.rst @@ -0,0 +1,6 @@ +DeletedMessagesHandler +====================== + +.. autoclass:: pyrogram.DeletedMessagesHandler + :members: + :undoc-members: diff --git a/docs/source/pyrogram/handlers/index.rst b/docs/source/pyrogram/handlers/index.rst index 191d4eff..272e529f 100644 --- a/docs/source/pyrogram/handlers/index.rst +++ b/docs/source/pyrogram/handlers/index.rst @@ -5,6 +5,7 @@ Handlers .. toctree:: MessageHandler + DeletedMessagesHandler CallbackQueryHandler + DisconnectHandler RawUpdateHandler - DisconnectHandler \ No newline at end of file diff --git a/docs/source/resources/AutoAuthorization.rst b/docs/source/resources/AutoAuthorization.rst index 46f0809d..73504f80 100644 --- a/docs/source/resources/AutoAuthorization.rst +++ b/docs/source/resources/AutoAuthorization.rst @@ -35,6 +35,7 @@ ask you to input the phone code manually. app.start() print(app.get_me()) + app.stop() Sign Up ------- @@ -61,4 +62,5 @@ Telegram account in case the phone number you passed is not registered yet. ) app.start() - print(app.get_me()) \ No newline at end of file + print(app.get_me()) + app.stop() \ No newline at end of file diff --git a/docs/source/resources/UpdateHandling.rst b/docs/source/resources/UpdateHandling.rst index 4373433b..ffa01be9 100644 --- a/docs/source/resources/UpdateHandling.rst +++ b/docs/source/resources/UpdateHandling.rst @@ -6,6 +6,7 @@ and are handled by registering one or more callback functions with an Handler. T from, one for each kind of update: - `MessageHandler <../pyrogram/handlers/MessageHandler.html>`_ +- `DeletedMessagesHandler <../pyrogram/handlers/DeletedMessagesHandler.html>`_ - `CallbackQueryHandler <../pyrogram/handlers/CallbackQueryHandler.html>`_ - `RawUpdateHandler <../pyrogram/handlers/RawUpdateHandler.html>`_ @@ -31,8 +32,7 @@ We shall examine the :obj:`MessageHandler `, which will print(message) - app.start() - app.idle() + app.run() - If you prefer not to use decorators, there is an alternative way for registering Handlers. This is useful, for example, when you want to keep your callback functions in separate files. @@ -50,8 +50,7 @@ We shall examine the :obj:`MessageHandler `, which will app.add_handler(MessageHandler(my_handler)) - app.start() - app.idle() + app.run() Using Filters ------------- diff --git a/docs/source/start/Setup.rst b/docs/source/start/Setup.rst index dc837a86..8b7c0597 100644 --- a/docs/source/start/Setup.rst +++ b/docs/source/start/Setup.rst @@ -1,7 +1,7 @@ Setup ===== -Once you successfully installed_ Pyrogram, you will have to follow a few steps before you can actually use +Once you successfully `installed Pyrogram`_, you will still have to follow a few steps before you can actually use the library to make API calls. This section provides all the information you need in order to set up a project with Pyrogram. @@ -40,13 +40,13 @@ There are two ways to configure a Pyrogram application project, and you can choo from pyrogram import Client app = Client( - session_name="my_account", + "my_account", api_id=12345, api_hash="0123456789abcdef0123456789abcdef" ) .. note:: The examples below assume you have created a ``config.ini`` file, thus they won't show the *api_id* -and *api_hash* parameters usage. + and *api_hash* parameters usage. User Authorization ------------------ @@ -61,7 +61,7 @@ the :class:`Client ` class by passing to it a ``session_name`` from pyrogram import Client app = Client("my_account") - app.start() + app.run() This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the **phone code** you will receive: @@ -92,11 +92,11 @@ Instead of phone numbers, Bots are authorized via their tokens which are created from pyrogram import Client app = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11") - app.start() + app.run() That's all, no further action is needed. The session file will be named after the Bot user_id, which is ``123456.session`` for the example above. -.. _installed: Installation.html +.. _installed Pyrogram: Installation.html .. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes .. _BotFather: https://t.me/botfather \ No newline at end of file diff --git a/docs/source/start/Usage.rst b/docs/source/start/Usage.rst index 7750db3f..d9cb8fe1 100644 --- a/docs/source/start/Usage.rst +++ b/docs/source/start/Usage.rst @@ -10,11 +10,11 @@ High-level API The easiest and recommended way to interact with Telegram is via the high-level Pyrogram methods_ and types_, which are named after the `Telegram Bot API`_. -.. hint:: If you can't find a method you want to use, chances are it's not implemented yet. In this case, you must use - the `Raw Functions`_. Meanwhile, feel free to join our Community_ if you're stuck or want to propose a - new method! +.. hint:: If you can't find an high-level method you want to use, chances are it's not implemented yet. + In this case, you must use the `Raw Functions`_. Meanwhile, feel free to join our Community_ if you get stuck + or want to propose a new method! -Examples: +Examples (more on `GitHub `_): - Get information about the authorized user: @@ -39,7 +39,7 @@ Examples: Using Raw Functions ------------------- -If you can't find a high-level method for your needs or want complete, low-level access to the whole Telegram API, +If you can't find a high-level method for your needs or if want complete, low-level access to the whole Telegram API, you have to use the raw :mod:`functions ` and :mod:`types ` exposed by the ``pyrogram.api`` package and call any Telegram API method you wish using the :meth:`send() ` method provided by the Client class. @@ -49,15 +49,17 @@ method provided by the Client class. re-implemented by providing a much simpler and cleaner interface which is very similar to the Bot API. If you think a raw function should be wrapped and added as a high-level method, feel free to ask in our Community_! -Examples: +Examples (more on `GitHub `_): - Update first name, last name and bio: .. code-block:: python + from pyrogram import Client from pyrogram.api import functions - ... + app = Client("my_account") + app.start() app.send( functions.account.UpdateProfile( @@ -66,13 +68,17 @@ Examples: ) ) + app.stop() + - Share your Last Seen time only with your contacts: .. code-block:: python + from pyrogram import Client from pyrogram.api import functions, types - ... + app = Client("my_account") + app.start() app.send( functions.account.SetPrivacy( @@ -81,13 +87,17 @@ Examples: ) ) + app.stop() + - Invite users to your channel/supergroup: .. code-block:: python + from pyrogram import Client from pyrogram.api import functions, types - ... + app = Client("my_account") + app.start() app.send( functions.channels.InviteToChannel( @@ -100,6 +110,8 @@ Examples: ) ) + app.stop() + .. _methods: ../pyrogram/Client.html#available-methods .. _plenty of them: ../pyrogram/Client.html#available-methods .. _types: ../pyrogram/types/index.html diff --git a/examples/callback_query_handler.py b/examples/callback_query_handler.py index 6b76edd8..999c2686 100644 --- a/examples/callback_query_handler.py +++ b/examples/callback_query_handler.py @@ -34,5 +34,4 @@ def answer(client, callback_query): ) -app.start() -app.idle() +app.run() # Automatically start() and idle() diff --git a/examples/echo_bot.py b/examples/echo_bot.py index ed2d4df5..adda52c7 100644 --- a/examples/echo_bot.py +++ b/examples/echo_bot.py @@ -36,5 +36,4 @@ def echo(client, message): ) -app.start() -app.idle() +app.run() # Automatically start() and idle() diff --git a/examples/get_history.py b/examples/get_history.py index d53bed96..433d127c 100644 --- a/examples/get_history.py +++ b/examples/get_history.py @@ -24,12 +24,12 @@ from pyrogram.api.errors import FloodWait """This example shows how to retrieve the full message history of a chat""" app = Client("my_account") -app.start() - target = "me" # "me" refers to your own chat (Saved Messages) messages = [] # List that will contain all the messages of the target chat offset_id = 0 # ID of the last message of the chunk +app.start() + while True: try: m = app.get_history(target, offset_id=offset_id) diff --git a/examples/get_participants.py b/examples/get_participants.py index d10710ba..fd5257fb 100644 --- a/examples/get_participants.py +++ b/examples/get_participants.py @@ -28,13 +28,13 @@ Refer to get_participants2.py for more than 10.000 users. """ app = Client("my_account") -app.start() - target = "pyrogramchat" # 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 +app.start() + while True: try: participants = app.send( diff --git a/examples/get_participants2.py b/examples/get_participants2.py index dfad315b..a70afb74 100644 --- a/examples/get_participants2.py +++ b/examples/get_participants2.py @@ -33,15 +33,14 @@ as some user names may not contain ascii letters at all. """ app = Client("my_account") -app.start() - target = "pyrogramchat" # Target channel/supergroup username or id users = {} # To ensure uniqueness, users will be stored in a dictionary with user_id as key limit = 200 # Amount of users to retrieve for each API call (200 is the maximum) - # "" + "0123456789" + "abcdefghijklmnopqrstuvwxyz" (as list) queries = [""] + [str(i) for i in range(10)] + list(ascii_lowercase) +app.start() + for q in queries: print("Searching for '{}'".format(q)) offset = 0 # For each query, offset restarts from 0 diff --git a/examples/raw_update_handler.py b/examples/raw_update_handler.py index eb417c24..c7195761 100644 --- a/examples/raw_update_handler.py +++ b/examples/raw_update_handler.py @@ -28,5 +28,4 @@ def raw(client, update, users, chats): print(update) -app.start() -app.idle() +app.run() # Automatically start() and idle() diff --git a/examples/welcome_bot.py b/examples/welcome_bot.py index 8e087728..5fd93293 100644 --- a/examples/welcome_bot.py +++ b/examples/welcome_bot.py @@ -49,5 +49,4 @@ def welcome(client, message): ) -app.start() -app.idle() +app.run() # Automatically start() and idle() diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py index a3197d0c..ddfc3dc2 100644 --- a/pyrogram/client/client.py +++ b/pyrogram/client/client.py @@ -265,6 +265,38 @@ class Client(Methods, BaseClient): self.is_started = False await self.session.stop() + def signal_handler(self, *args): + self.is_idle = False + + def idle(self, stop_signals: tuple = (SIGINT, SIGTERM, SIGABRT)): + """Blocks the program execution until one of the signals are received, + then gently stop the Client by closing the underlying connection. + + Args: + stop_signals (``tuple``, *optional*): + Iterable containing signals the signal handler will listen to. + Defaults to (SIGINT, SIGTERM, SIGABRT). + """ + for s in stop_signals: + signal(s, self.signal_handler) + + self.is_idle = True + + while self.is_idle: + time.sleep(1) + + self.stop() + + def run(self): + """Use this method to automatically start and idle a Client. + Requires no parameters. + + Raises: + :class:`Error ` + """ + self.start() + self.idle() + def add_handler(self, handler, group: int = 0): """Use this method to register an update handler. diff --git a/pyrogram/client/handlers/callback_query_handler.py b/pyrogram/client/handlers/callback_query_handler.py index c0bba510..c5346519 100644 --- a/pyrogram/client/handlers/callback_query_handler.py +++ b/pyrogram/client/handlers/callback_query_handler.py @@ -23,6 +23,9 @@ class CallbackQueryHandler(Handler): """The CallbackQuery handler class. Used to handle callback queries coming from inline buttons. It is intended to be used with :meth:`add_handler() ` + For a nicer way to register this handler, have a look at the + :meth:`on_callback_query() ` decorator. + Args: callback (``callable``): Pass a function that will be called when a new CallbackQuery arrives. It takes *(client, callback_query)* diff --git a/pyrogram/client/handlers/deleted_messages_handler.py b/pyrogram/client/handlers/deleted_messages_handler.py index 6a1f7689..55d5715f 100644 --- a/pyrogram/client/handlers/deleted_messages_handler.py +++ b/pyrogram/client/handlers/deleted_messages_handler.py @@ -20,10 +20,13 @@ from .handler import Handler class DeletedMessagesHandler(Handler): - """The Deleted Messages handler class. Used to handle deleted messages coming from any chat + """The deleted Messages handler class. Used to handle deleted messages coming from any chat (private, group, channel). It is intended to be used with :meth:`add_handler() ` + For a nicer way to register this handler, have a look at the + :meth:`on_deleted_messages() ` decorator. + Args: callback (``callable``): Pass a function that will be called when one or more Messages have been deleted. diff --git a/pyrogram/client/handlers/disconnect_handler.py b/pyrogram/client/handlers/disconnect_handler.py index 9ad4ffbc..a8b800a8 100644 --- a/pyrogram/client/handlers/disconnect_handler.py +++ b/pyrogram/client/handlers/disconnect_handler.py @@ -23,6 +23,8 @@ class DisconnectHandler(Handler): """The Disconnect handler class. Used to handle disconnections. It is intended to be used with :meth:`add_handler() ` + For a nicer way to register this handler, have a look at the + :meth:`on_disconnect() ` decorator. Args: callback (``callable``): diff --git a/pyrogram/client/handlers/message_handler.py b/pyrogram/client/handlers/message_handler.py index 6aae27de..1b4770b3 100644 --- a/pyrogram/client/handlers/message_handler.py +++ b/pyrogram/client/handlers/message_handler.py @@ -24,6 +24,9 @@ class MessageHandler(Handler): any chat (private, group, channel). It is intended to be used with :meth:`add_handler() ` + For a nicer way to register this handler, have a look at the + :meth:`on_message() ` decorator. + Args: callback (``callable``): Pass a function that will be called when a new Message arrives. It takes *(client, message)* diff --git a/pyrogram/client/handlers/raw_update_handler.py b/pyrogram/client/handlers/raw_update_handler.py index 8a1e0a03..5a8913b6 100644 --- a/pyrogram/client/handlers/raw_update_handler.py +++ b/pyrogram/client/handlers/raw_update_handler.py @@ -23,6 +23,9 @@ class RawUpdateHandler(Handler): """The Raw Update handler class. Used to handle raw updates. It is intended to be used with :meth:`add_handler() ` + For a nicer way to register this handler, have a look at the + :meth:`on_raw_update() ` decorator. + Args: callback (``callable``): A function that will be called when a new update is received from the server. It takes diff --git a/pyrogram/client/methods/decorators/on_callback_query.py b/pyrogram/client/methods/decorators/on_callback_query.py index 3bafc94d..5f22fc92 100644 --- a/pyrogram/client/methods/decorators/on_callback_query.py +++ b/pyrogram/client/methods/decorators/on_callback_query.py @@ -24,7 +24,7 @@ class OnCallbackQuery(BaseClient): def on_callback_query(self, filters=None, group: int = 0): """Use this decorator to automatically register a function for handling callback queries. This does the same thing as :meth:`add_handler` using the - CallbackQueryHandler. + :class:`CallbackQueryHandler`. Args: filters (:obj:`Filters `): diff --git a/pyrogram/client/methods/decorators/on_deleted_messages.py b/pyrogram/client/methods/decorators/on_deleted_messages.py index 4cc2d904..3f603c41 100644 --- a/pyrogram/client/methods/decorators/on_deleted_messages.py +++ b/pyrogram/client/methods/decorators/on_deleted_messages.py @@ -24,7 +24,7 @@ class OnDeletedMessages(BaseClient): def on_deleted_messages(self, filters=None, group: int = 0): """Use this decorator to automatically register a function for handling deleted messages. This does the same thing as :meth:`add_handler` using the - DeletedMessagesHandler. + :class:`DeletedMessagesHandler`. Args: filters (:obj:`Filters `): diff --git a/pyrogram/client/methods/decorators/on_disconnect.py b/pyrogram/client/methods/decorators/on_disconnect.py index d1d03723..4bc593e3 100644 --- a/pyrogram/client/methods/decorators/on_disconnect.py +++ b/pyrogram/client/methods/decorators/on_disconnect.py @@ -24,7 +24,7 @@ class OnDisconnect(BaseClient): def on_disconnect(self): """Use this decorator to automatically register a function for handling disconnections. This does the same thing as :meth:`add_handler` using the - DisconnectHandler. + :class:`DisconnectHandler`. """ def decorator(func): diff --git a/pyrogram/client/methods/decorators/on_message.py b/pyrogram/client/methods/decorators/on_message.py index 43c6f9f8..0011e083 100644 --- a/pyrogram/client/methods/decorators/on_message.py +++ b/pyrogram/client/methods/decorators/on_message.py @@ -24,7 +24,7 @@ class OnMessage(BaseClient): def on_message(self, filters=None, group: int = 0): """Use this decorator to automatically register a function for handling messages. This does the same thing as :meth:`add_handler` using the - MessageHandler. + :class:`MessageHandler`. Args: filters (:obj:`Filters `): diff --git a/pyrogram/client/methods/decorators/on_raw_update.py b/pyrogram/client/methods/decorators/on_raw_update.py index ca1c9d9b..902d9854 100644 --- a/pyrogram/client/methods/decorators/on_raw_update.py +++ b/pyrogram/client/methods/decorators/on_raw_update.py @@ -24,7 +24,7 @@ class OnRawUpdate(BaseClient): def on_raw_update(self, group: int = 0): """Use this decorator to automatically register a function for handling raw updates. This does the same thing as :meth:`add_handler` using the - RawUpdateHandler. + :class:`RawUpdateHandler`. Args: group (``int``, *optional*):