mirror of
https://github.com/pyrogram/pyrogram
synced 2025-08-28 12:57:52 +00:00
Add examples to utility methods
This commit is contained in:
Dan
parent
72b7a53ff5
commit
8f56610c2c
@ -174,6 +174,17 @@ class Client(Methods, BaseClient):
|
||||
download_media, ...) are less prone to throw FloodWait exceptions.
|
||||
Only available for users, bots will ignore this parameter.
|
||||
Defaults to False (normal session).
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
with app:
|
||||
app.send_message("me", "Hi!")
|
||||
|
||||
"""
|
||||
|
||||
terms_of_service_displayed = False
|
||||
@ -269,11 +280,28 @@ class Client(Methods, BaseClient):
|
||||
self._proxy.update(value)
|
||||
|
||||
def start(self):
|
||||
"""Start the Client.
|
||||
"""Start the client.
|
||||
|
||||
This method connects the client to Telegram and, in case of new sessions, automatically manages the full login
|
||||
process using an interactive prompt (by default).
|
||||
|
||||
Has no parameters.
|
||||
|
||||
Raises:
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
ConnectionError: In case you try to start an already started Client.
|
||||
ConnectionError: In case you try to start an already started client.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 4
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
app.start()
|
||||
|
||||
... # Call API methods
|
||||
|
||||
app.stop()
|
||||
"""
|
||||
if self.is_started:
|
||||
raise ConnectionError("Client has already been started")
|
||||
@ -346,8 +374,25 @@ class Client(Methods, BaseClient):
|
||||
def stop(self):
|
||||
"""Stop the Client.
|
||||
|
||||
This method disconnects the client from Telegram and stops the underlying tasks.
|
||||
|
||||
Has no parameters.
|
||||
|
||||
Raises:
|
||||
ConnectionError: In case you try to stop an already stopped Client.
|
||||
ConnectionError: In case you try to stop an already stopped client.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 8
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
app.start()
|
||||
|
||||
... # Call API methods
|
||||
|
||||
app.stop()
|
||||
"""
|
||||
if not self.is_started:
|
||||
raise ConnectionError("Client is already stopped")
|
||||
@ -388,8 +433,30 @@ class Client(Methods, BaseClient):
|
||||
def restart(self):
|
||||
"""Restart the Client.
|
||||
|
||||
This method will first call :meth:`~Client.stop` and then :meth:`~Client.start` in a row in order to restart
|
||||
a client using a single method.
|
||||
|
||||
Has no parameters.
|
||||
|
||||
Raises:
|
||||
ConnectionError: In case you try to restart a stopped Client.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 8
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
app.start()
|
||||
|
||||
... # Call API methods
|
||||
|
||||
app.restart()
|
||||
|
||||
... # Call other API methods
|
||||
|
||||
app.stop()
|
||||
"""
|
||||
self.stop()
|
||||
self.start()
|
||||
@ -451,25 +518,40 @@ class Client(Methods, BaseClient):
|
||||
time.sleep(1)
|
||||
|
||||
def run(self):
|
||||
"""Start the Client and automatically idle the main script.
|
||||
"""Start the client, idle the main script and finally stop the client.
|
||||
|
||||
This is a convenience method that literally just calls :meth:`~Client.start` and :meth:`~Client.idle`. It makes
|
||||
running a client less verbose, but is not suitable in case you want to run more than one client in a single main
|
||||
script, since :meth:`~Client.idle` will block.
|
||||
This is a convenience method that calls :meth:`~Client.start`, :meth:`~Client.idle` and :meth:`~Client.stop` in
|
||||
sequence. It makes running a client less verbose, but is not suitable in case you want to run more than one
|
||||
client in a single main script, since idle() will block after starting the own client.
|
||||
|
||||
Has no parameters.
|
||||
|
||||
Raises:
|
||||
RPCError: In case of a Telegram RPC error.
|
||||
ConnectionError: In case you try to run an already started client.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 7
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
... # Set handlers up
|
||||
|
||||
app.run()
|
||||
"""
|
||||
self.start()
|
||||
self.idle()
|
||||
Client.idle()
|
||||
self.stop()
|
||||
|
||||
def add_handler(self, handler: Handler, group: int = 0):
|
||||
"""Register an update handler.
|
||||
|
||||
You can register multiple handlers, but at most one handler within a group
|
||||
will be used for a single update. To handle the same update more than once, register
|
||||
your handler using a different group id (lower group id == higher priority).
|
||||
You can register multiple handlers, but at most one handler within a group will be used for a single update.
|
||||
To handle the same update more than once, register your handler using a different group id (lower group id
|
||||
== higher priority). This mechanism is explained in greater details at
|
||||
:doc:`More on Updates <../../topics/more-on-updates>`.
|
||||
|
||||
Parameters:
|
||||
handler (``Handler``):
|
||||
@ -479,7 +561,22 @@ class Client(Methods, BaseClient):
|
||||
The group identifier, defaults to 0.
|
||||
|
||||
Returns:
|
||||
``tuple``: A tuple consisting of (handler, group).
|
||||
``tuple``: A tuple consisting of *(handler, group)*.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 8
|
||||
|
||||
from pyrogram import Client, MessageHandler
|
||||
|
||||
def dump(client, message):
|
||||
print(message)
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
app.add_handler(MessageHandler(dump))
|
||||
|
||||
app.run()
|
||||
"""
|
||||
if isinstance(handler, DisconnectHandler):
|
||||
self.disconnect_handler = handler.callback
|
||||
@ -491,9 +588,8 @@ class Client(Methods, BaseClient):
|
||||
def remove_handler(self, handler: Handler, group: int = 0):
|
||||
"""Remove a previously-registered update handler.
|
||||
|
||||
Make sure to provide the right group that the handler was added in. You can use
|
||||
the return value of the :meth:`~Client.add_handler` method, a tuple of (handler, group), and
|
||||
pass it directly.
|
||||
Make sure to provide the right group where the handler was added in. You can use the return value of the
|
||||
:meth:`~Client.add_handler` method, a tuple of *(handler, group)*, and pass it directly.
|
||||
|
||||
Parameters:
|
||||
handler (``Handler``):
|
||||
@ -501,6 +597,24 @@ class Client(Methods, BaseClient):
|
||||
|
||||
group (``int``, *optional*):
|
||||
The group identifier, defaults to 0.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 11
|
||||
|
||||
from pyrogram import Client, MessageHandler
|
||||
|
||||
def dump(client, message):
|
||||
print(message)
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
handler = app.add_handler(MessageHandler(dump))
|
||||
|
||||
# Starred expression to unpack (handler, group)
|
||||
app.remove_handler(*handler)
|
||||
|
||||
app.run()
|
||||
"""
|
||||
if isinstance(handler, DisconnectHandler):
|
||||
self.disconnect_handler = None
|
||||
@ -509,7 +623,28 @@ class Client(Methods, BaseClient):
|
||||
|
||||
def stop_transmission(self):
|
||||
"""Stop downloading or uploading a file.
|
||||
Must be called inside a progress callback function.
|
||||
|
||||
This method must be called inside a progress callback function in order to stop the transmission at the
|
||||
desired time. The progress callback is called every time a file chunk is uploaded/downloaded.
|
||||
|
||||
Has no parameters.
|
||||
|
||||
Example:
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 9
|
||||
|
||||
from pyrogram import Client
|
||||
|
||||
app = Client("my_account")
|
||||
|
||||
# Example to stop transmission once the upload progress reaches 50%
|
||||
# Useless in practice, but shows how to stop on command
|
||||
def progress(client, current, total):
|
||||
if (current * 100 / total) > 50:
|
||||
client.stop_transmission()
|
||||
|
||||
with app:
|
||||
app.send_document("me", "files.zip", progress=progress)
|
||||
"""
|
||||
raise Client.StopTransmission
|
||||
|
||||
@ -541,9 +676,9 @@ class Client(Methods, BaseClient):
|
||||
def set_parse_mode(self, parse_mode: Union[str, None] = "combined"):
|
||||
"""Set the parse mode to be used globally by the client.
|
||||
|
||||
When setting the parse mode with this method, all methods having a *parse_mode* parameter will follow the global
|
||||
value by default. The default value *"combined"* enables both Markdown and HTML styles to be used and combined
|
||||
together.
|
||||
When setting the parse mode with this method, all other methods having a *parse_mode* parameter will follow the
|
||||
global value by default. The default value *"combined"* enables both Markdown and HTML styles to be used and
|
||||
combined together.
|
||||
|
||||
Parameters:
|
||||
parse_mode (``str``):
|
||||
@ -1172,7 +1307,7 @@ class Client(Methods, BaseClient):
|
||||
])
|
||||
|
||||
if session_empty:
|
||||
self.storage.dc_id = 1
|
||||
self.storage.dc_id = 4
|
||||
self.storage.date = 0
|
||||
|
||||
self.storage.test_mode = self.test_mode
|
||||
@ -1445,23 +1580,22 @@ class Client(Methods, BaseClient):
|
||||
In case a file part expired, pass the file_id and the file_part to retry uploading that specific chunk.
|
||||
|
||||
progress (``callable``, *optional*):
|
||||
Pass a callback function to view the upload progress.
|
||||
The function must take *(client, current, total, \*args)* as positional arguments (look at the section
|
||||
below for a detailed description).
|
||||
Pass a callback function to view the file transmission progress.
|
||||
The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
|
||||
detailed description) and will be called back each time a new file chunk has been successfully
|
||||
transmitted.
|
||||
|
||||
progress_args (``tuple``, *optional*):
|
||||
Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
|
||||
a chat_id and a message_id in order to edit a message with the updated progress.
|
||||
Extra custom arguments for the progress callback function.
|
||||
You can pass anything you need to be available in the progress callback scope; for example, a Message
|
||||
object or a Client instance in order to edit the message with the updated progress status.
|
||||
|
||||
Other Parameters:
|
||||
client (:obj:`Client`):
|
||||
The Client itself, useful when you want to call other API methods inside the callback function.
|
||||
|
||||
current (``int``):
|
||||
The amount of bytes uploaded so far.
|
||||
The amount of bytes transmitted so far.
|
||||
|
||||
total (``int``):
|
||||
The size of the file.
|
||||
The total size of the file.
|
||||
|
||||
*args (``tuple``, *optional*):
|
||||
Extra custom arguments as defined in the *progress_args* parameter.
|
||||
@ -1775,11 +1909,3 @@ class Client(Methods, BaseClient):
|
||||
|
||||
if extensions:
|
||||
return extensions.split(" ")[0]
|
||||
|
||||
def export_session_string(self):
|
||||
"""Export the current session as serialized string.
|
||||
|
||||
Returns:
|
||||
``str``: The session serialized into a printable, url-safe string.
|
||||
"""
|
||||
return self.storage.export_session_string()
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user