The ThreadGroup.add_timer() API is unintuitive, inflexible, and all
around pretty terrible. By allowing the caller to pass *args and
**kwargs, it strongly implies that you can write a wrapper like:
def add_timer(self, interval, func, *args, **kwargs):
self.group.add_timer(interval, func, *args, **kwargs)
and in fact at least 6 projects have done so (probably copying and
pasting from each other). But this is wrong, and will result in the
first positional arg intended for the callback function to be treated as
the initial_delay parameter and dropped from the list of arguments to be
passed to the callback when it is run. When called like this, the
initial_delay argument not only must be passed (preventing the caller
from relying on the default), interspersed between the callback function
and its arguments, but it must be passed as a positional and not a
keyword argument (preventing the caller from effectively documenting
what is going on):
self.group.add_timer(interval, func, None, *args, **kwargs)
We are also unable to add any further options without breaking existing
consumers.
To improve the situation in the future, add a new add_timer_args() API
that takes the args and kwargs as individual sequence/mapping parameters
rather than as variadic parameters. The above call would become:
self.group.add_timer_args(interval, func, args, kwargs)
and any optional parameters can be passed as keyword arguments. Any new
keyword arguments we might want to add can be safely added to this
method.
Calling the original add_timer() method with arguments (either
positional or keyword) intended for the callback function is now
deprecated. Those parameters could be removed in a future major release.
Change-Id: Ib2791342263e2b88c045bcc92adc8160f57a0ed6
750b51caaa