diff --git a/Usage-Modes.md b/Usage-Modes.md index c68c77e..4a4741b 100644 --- a/Usage-Modes.md +++ b/Usage-Modes.md @@ -1,22 +1,8 @@ -There are two ways in which you may want to use the library. Some people will simply want to process updates as they come, while other people don't care about processing updates at all. A mix between the two if still possible. +There are two ways in which you may want to use the library. Some people will simply want to show information about updates as they come, or invoke other requests as certain events happen, while other people don't care about processing updates at all. A mix between all of these is also possible. -## Processing updates +## Listening for updates -By default, the library won't process updates at all (while it will still send periodic pings to ensure that the connection stays alive). To enable updates, you must set `enable_updates=True` when creating a `TelegramClient`: - -```python -client = TelegramClient('myself', api_id, api_hash, enable_updates=True) -``` - -This way, updates will be processed as soon as they arrive. This behavior is disabled by default to avoid unnecessary processing, although it's cost is hardly noticeable. - -If you already have a `client` created you can also enable the `.updates` member: - -```python -client.updates.enabled = True -``` - -To add an update handler (this is, a callback method that will be called with the update object as soon as it arrives), you should make use of the following methods: +By default, the library won't process updates at all (while it will still send periodic pings to ensure that the connection stays alive). If you want to listen for updates, simply add a new handler: ```python def my_handler(update_object): @@ -31,22 +17,27 @@ client.remove_update_handler(my_handler) # handlers = client.list_update_handlers() ``` +An update handler is nothing else than a method accepting a single parameter, the update object to be processed. + +Updates will be processed as long as there is at least one handler added, and adding the first handler will trigger a forced synchronization of the update state (manually called through `client.sync_updates()`) + **You cannot invoke requests from within these handlers**. The handlers are called from a **read-only thread**, and attempting to invoke a request (hence sending it) will raise an `AssertionError`. ## Reacting to updates In order to invoke some request upon receiving an update, you need your own thread. If all you need is to react to updates, you may just use the main thread instead creating a new one. -To enable active update polling, do as follows: +The first step is to tell the `TelegramClient` that we will be actively polling new updates: ```python -client = TelegramClient('myself', api_id, api_hash, - enable_updates=True, active_updates_polling=True) +client = TelegramClient('myself', api_id, api_hash, process_updates=True) # Or, if you already have a client -client.updates.set_polling(True) +client.updates.polling = True ``` +Setting this flag to `True` will also cause the library to process updates, even if no `update_handler` was added. You should generally prefer this if you're going to only have a handler, and the main thread has no other job to do. + Now, you **must** poll updates, or your memory will eventually fill. On your thread (or simply on the main thread) do: ```python