telegram.ext.messagequeue module

A throughput-limiting message processor for Telegram bots

class telegram.ext.messagequeue.DelayQueue(queue=None, burst_limit=30, time_limit_ms=1000, exc_route=None, autostart=True, name=None)

Bases: threading.Thread

Processes callbacks from queue with specified throughput limits. Creates a separate thread to process callbacks with delays.

Parameters:
  • queue (queue.Queue, optional) – used to pass callbacks to thread. Creates queue.Queue implicitly if not provided.
  • burst_limit (int, optional) – number of maximum callbacks to process per time-window defined by time_limit_ms. Defaults to 30.
  • time_limit_ms (int, optional) – defines width of time-window used when each processing limit is calculated. Defaults to 1000.
  • exc_route (callable, optional) – a callable, accepting 1 positional argument; used to route exceptions from processor thread to main thread; is called on Exception subclass exceptions. If not provided, exceptions are routed through dummy handler, which re-raises them.
  • autostart (bool, optional) – if True, processor is started immediately after object’s creation; if False, should be started manually by start method. Defaults to True.
  • name (str, optional) – thread’s name. Defaults to 'DelayQueue-N', where N is sequential number of object created.
run()

Do not use the method except for unthreaded testing purposes, the method normally is automatically called by start method.

stop(timeout=None)

Used to gently stop processor and shutdown its thread.

Parameters:timeout (float) – indicates maximum time to wait for processor to stop and its thread to exit. If timeout exceeds and processor has not stopped, method silently returns. is_alive could be used afterwards to check the actual status. If timeout set to None, blocks until processor is shut down. Defaults to None.
Returns:None
exception telegram.ext.messagequeue.DelayQueueError

Bases: exceptions.RuntimeError

Indicates processing errors

class telegram.ext.messagequeue.MessageQueue(all_burst_limit=30, all_time_limit_ms=1000, group_burst_limit=20, group_time_limit_ms=60000, exc_route=None, autostart=True)

Bases: object

Implements callback processing with proper delays to avoid hitting Telegram’s message limits. Contains two DelayQueue`s, for group and for all messages, interconnected in delay chain. Callables are processed through *group* `DelayQueue, then through all DelayQueue for group-type messages. For non-group messages, only the all DelayQueue is used.

Parameters:
  • all_burst_limit (int, optional) – numer of maximum all-type callbacks to process per time-window defined by all_time_limit_ms. Defaults to 30.
  • all_time_limit_ms (int, optional) – defines width of all-type time-window used when each processing limit is calculated. Defaults to 1000 ms.
  • group_burst_limit (int, optional) – numer of maximum group-type callbacks to process per time-window defined by group_time_limit_ms. Defaults to 20.
  • group_time_limit_ms (int, optional) – defines width of group-type time-window used when each processing limit is calculated. Defaults to 60000 ms.
  • exc_route (callable, optional) – a callable, accepting one positional argument; used to route exceptions from processor threads to main thread; is called on Exception subclass exceptions. If not provided, exceptions are routed through dummy handler, which re-raises them.
  • autostart (bool, optional) – if True, processors are started immediately after object’s creation; if False, should be started manually by start method. Defaults to True.
_all_delayq

telegram.ext.messagequeue.DelayQueue – actual DelayQueue used for all-type callback processing

_group_delayq

telegram.ext.messagequeue.DelayQueue – actual DelayQueue used for group-type callback processing

start()

Method is used to manually start the MessageQueue processing

Returns:None
stop(timeout=None)

Used to gently stop processor and shutdown its thread.

Parameters:timeout (float) – indicates maximum time to wait for processor to stop and its thread to exit. If timeout exceeds and processor has not stopped, method silently returns. is_alive could be used afterwards to check the actual status. If timeout set to None, blocks until processor is shut down. Defaults to None.
Returns:None
telegram.ext.messagequeue.queuedmessage(method)

A decorator to be used with telegram.bot.Bot send* methods.

Note

As it probably wouldn’t be a good idea to make this decorator a property, it had been coded as decorator function, so it implies that first positional argument to wrapped MUST be self.

The next object attributes are used by decorator:

self._is_messages_queued_default

bool – Value to provide class-defaults to queued kwarg if not provided during wrapped method call.

self._msg_queue

telegram.ext.messagequeue.MessageQueue – The actual MessageQueue used to delay outbond messages according to specified time-limits.

Wrapped method starts accepting the next kwargs:

Parameters:
  • queued (bool, optional) – if set to True, the MessageQueue is used to process output messages. Defaults to self._is_queued_out.
  • isgroup (bool, optional) – if set to True, the message is meant to be group-type (as there’s no obvious way to determine its type in other way at the moment). Group-type messages could have additional processing delay according to limits set in self._out_queue. Defaults to False.
Returns:

Either telegram.utils.promise.Promise in case call is queued, or original method’s return value if it’s not.