Doc timer docs #10188
Doc timer docs #10188
Conversation
- correct types listed in TimerBase.callbacks - add details about when callbacks remove them selves to new_timer
https://docs.python.org/3/library/stdtypes.html#boolean-values This makes the linter happy and is no change in behavior.
| events. This list can be manipulated directly, or the functions | ||
| `add_callback` and `remove_callback` can be used. | ||
| callbacks : List[Tuple[callable, Tuple, Dict]] | ||
| Stores list of (func, args, kwargs) tuples that will be called upon |
There was a problem hiding this comment.
I can guess what these tuples may look like, but it'd be nice if there were an example, or there was a link to where I could see an example....
lib/matplotlib/backend_bases.py
Outdated
| @@ -2405,10 +2408,13 @@ def new_timer(self, *args, **kwargs): | |||
| ---------------- | |||
| interval : scalar | |||
| Timer interval in milliseconds | |||
| callbacks : list | |||
| callbacks : List[Tuple[callable, Tuple, Dict]] | |||
| Sequence of (func, args, kwargs) where ``func(*args, **kwargs)`` | |||
There was a problem hiding this comment.
as above. Though I have to admit it is likely my lack of deep python knowledge showing through here.
There was a problem hiding this comment.
Is the un-changed line below this clear?
Are you asking about the inner tuple or the outer tuple?
See #10183 (comment) for this used in the wild.
There was a problem hiding this comment.
The unchanged line. I don't know how to represent args in the tuple. Is it a tuple of the args? A list? i.e. ax.plot(x, y, linewidth=2) would I write as (ax.plot, (x, y), {'linewidths': 2})?
As I said, its probably just my unfamiliarity with what *args and **kwargs really mean. They don't get used in a lot of other places in the language.
There was a problem hiding this comment.
https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments and the next we sections (4.7.2 - 4.7.4) . Basically in the function definition side the * and ** in the signature mean 'collect all the positional arguments that don't have a named position and put them in a tuple' and 'collect all of the keywords which are explicitly listed and put them in a dict'. On the call side, * and ** mean 'unpack' so foo(1, 2) is the same as foo(*(1, 2)) (technically works with any iterable) and ** is the same for dictionaries foo(a=1, b=2) is the same as foo(**{'a':1, 'b':2}).
This is super useful when you want to write generic wrappers ex
def my_decorator(func):
def inner(*args, **kwargs):
print("I'm a decorator")
return func(*args, **kwargs)
return inneror you are doing callbacks / defered execution
call_later = [(f, (1, 2), {'a': 3}), (f2, (), {}), (f3, ('foo',), {})]
# some time later
for func, args, kwargs in call_later:
func(*args, **kwargs)We also use it through mpl to 'forward' kwargs down to the Artist class's __init__ methods and then up the MRO chain.
There was a problem hiding this comment.
Hi @tacaswell, sorry, I didn't mean to squeeze you for a python lesson ;-) I have looked that stuff up before, and get it. I simply meant that I wouldn't have been sure about the call_later syntax in your example above off the top of my head.
We can argue how pandering the docs should be, but in this case, it'd be nice if there were something like:
"""
i.e. `callbacks = [(func1, (1, 2), {'a': 3}), (func2, (), {}), (func3, ('foo',), {})]`
"""to help the less with-it.
PR Summary
Minor documentation and style changes in TimerBase and friends.