cbook docs cleanup #14267
cbook docs cleanup #14267
Conversation
| @@ -1617,17 +1645,17 @@ def normalize_kwargs(kw, alias_mapping=None, required=(), forbidden=(), | |||
| If an Artist subclass or instance is passed, use its properties alias | |||
| mapping. | |||
|
|
|||
| required : iterable, optional | |||
| A tuple of fields that must be in kwargs. | |||
| required : list of str, optional | |||
There was a problem hiding this comment.
These don't have to be lists, any non-generator iterable will work.
There was a problem hiding this comment.
I would leave that. non-generator iterable of str feels a bit too bulky. The essence that it's a homogeneous sequence of str is best described by list of str. I find it ok to accept a slightly broader range of types than documented in this case.
Note: I searched through the code to find out how it's actually used and found out that neither of required, forbidden and allowed are used anywhere.
There was a problem hiding this comment.
I agree that list is the "practical" documentation.
Unless we have concrete plans to use required/forbidden/allowed I would suggest just deprecating them. IIRC @tacaswell you wrote this helper originally; thoughts?
448b5c3 to
86d670f
Compare
lib/matplotlib/cbook/__init__.py
Outdated
| homogeneous list of a given type | ||
| A list with a short ``repr()``. | ||
|
|
||
| This is meant to be used for a homogeneous list of a given type. In |
There was a problem hiding this comment.
"This is meant to be used for homogeneous lists of artists, so that they don't cause long, meaningless outputs [at the REPL]".
|
@meeseeksdev backport to v3.1.x |
|
Owee, I'm MrMeeseeks, Look at me. There seem to be a conflict, please backport manually. Here are approximate instructions:
And apply the correct labels and milestones. Congratulation you did some good work ! Hopefully your backport PR will be tested by the continuous integration and merged soon! If these instruction are inaccurate, feel free to suggest an improvement. |
|
I'm not going to go through the trouble of backporting this. Feel free to do so if you wish. |
|
Probably too much going on currently. I think I'm giving up on backporting doc changes to 3.1.2. Hopefully 3.2.0 won't be much later than 3.1.2. |
PR Summary
Some random docstring cleanup.