quantpylib.throttler.decorators

Examples for both decorator usage, and synchronous, asynchronous semaphores are given here.

aconsume_credits(_func=None, *, costs, refund_in, attrname='rate_semaphore', timeout=0, verbose=False)

Decorator to wrap an asynchronous instance-level coroutine as an asynchronous transaction within a rate-limited semaphore. The return value is the return value of the decorated coroutine.

Parameters:

Name	Type	Description	Default
_func	coroutine	The asynchronous coroutine to be wrapped.	None
costs	float	The number of credits required for the transaction.	required
refund_in	float	The time in seconds after which the credits should be refunded.	required
attrname	str	The attribute name to access the AsyncRateSemaphore belonging to the object instance. Defaults to "rate_semaphore".	'rate_semaphore'
timeout	float	The maximum time in seconds to wait for the transaction to complete. Defaults to 0, which waits indefinitely.	0
verbose	bool	Whether to print verbose transaction information. Defaults to True.	False

Returns:

Type	Description
any	The return value of the decorated coroutine.

Raises:

Type	Description
AssertionError	If the instance does not have the specified attribute or if costs is less than 0.
TimeoutError	If wrapped transaction takes longer than the specified timeout.

Notes

For a timed-out transaction that does not get a chance to run due to it sitting behind other transactions that are opportunistically processed, a RuntimeWarning: Enable tracemalloc to get the object allocation traceback may be seen together with the asyncio.TimeoutError. This is because the transaction contains the coroutine, and the transact is wrapped in an asyncio task. If it is unable to enter the semaphore by timeout, the coroutine is never awaited and complains when garbage collected. If the timeout occurs after the coroutine has acquired the semaphore, this warning will not be seen but the asyncio.TimeoutError will still be thrown.

consume_credits(_func=None, *, costs, refund_in, attrname='rate_semaphore', verbose=False)

Decorator to wrap an synchronous instance-level method as an synchronous transaction within a rate-limited semaphore. The return value is the return value of the decorated method.

Parameters:

Name	Type	Description	Default
_func	callable	The method to be wrapped.	None
costs	float	The number of credits required for the transaction.	required
refund_in	float	The time in seconds after which the credits should be refunded.	required
attrname	str	The attribute name to access the RateSemaphore belonging to the object instance. Defaults to "rate_semaphore".	'rate_semaphore'
verbose	bool	Whether to print verbose transaction information. Defaults to True.	False

Returns:

Type	Description
any	The return value of the decorated method.

Raises:

Type	Description
AssertionError	If the instance does not have the specified attribute or if costs is less than 0.

wrap_in_thread(_func=None, *, costs, refund_in, attrname='rate_semaphore', daemon=False, verbose=True)

Decorator to wrap a synchronous instance-level method into a transaction, and that transaction into a thread. The return value is a thread, that is not yet alive, and can be activated by invoking the threading.Thread.start method.

Parameters:

Name	Type	Description	Default
_func	callable	The function to be wrapped.	None
costs	float	The number of credits required for the transaction.	required
refund_in	float	The time in seconds after which the credits should be refunded.	required
attrname	str	The attribute name to access the RateSemaphore belonging to the object instance. Defaults to "rate_semaphore".	'rate_semaphore'
daemon	bool	Whether the thread should be a daemon thread. Defaults to False.	False
verbose	bool	Whether to print verbose transaction information. Defaults to True.	True

Returns:

Type	Description
Thread	The thread with the transaction as target function, where the transaction wraps the decorated function. Not yet alive.

Raises:

Type	Description
AssertionError	If the instance does not have the specified attribute or if costs is less than 0.