Skip to content

Rename parameter selectors #20585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Jul 19, 2021
Merged

Conversation

ericpre
Copy link
Member

@ericpre ericpre commented Jul 6, 2021

PR Summary

Follow up of #20558. Rename parameters (maxdist, markers_props, etc.) to make them consistent between the different selectors.

PR Checklist

  • Has pytest style unit tests (and pytest passes).
  • Is Flake 8 compliant (run flake8 on changed files to check).
  • [n/a] New features are documented, with examples if plot related.
  • [n/a] Documentation is sphinx and numpydoc compliant (the docs should build without error).
  • Conforms to Matplotlib style conventions (install flake8-docstrings and run flake8 --docstring-convention=all).
  • [n/a] New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
  • API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).

@tacaswell tacaswell added this to the v3.5.0 milestone Jul 6, 2021
Copy link
Member

@tacaswell tacaswell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems reasonable, left 2 small comments.

@ericpre
Copy link
Member Author

ericpre commented Jul 7, 2021

Thanks for the review @tacaswell, it should be good now.

@ericpre
Copy link
Member Author

ericpre commented Jul 8, 2021

Should be all done!

Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that some of the commented changes have precedence in other widget classes, however I'm not convinced, we should go that direction (e.g. code blocks for defaults).


dict(color='k', linestyle='-', linewidth=2, alpha=0.5)

handle_props : dict
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's the name markerprops. This is a bit different from SpanSelector. First, here we have lineprops + markerprops, keeping this consistent within the class is more important than consistency with another class. Second, while semantically we have handles in both classes, they are realized by markers and lines respectively and thus accept different parameters. I favor making this clear from the name.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what you what you mean, but I am convinced that simplifying the API and making it more generic is worth it at the cost of the being slightly less precise. I agree that using a more specific terminology is more explicit but at the end of the day, when we create a selector - regardless of what selector it is - what we want is to set the properties of the patch and/or the handle, regardless of what their are or of their implementation details.
For example, as an average matplotlib user, I don't know what are the different parameters between lineprops and markerprops, I will need to look it up.

In 35ee92d, I have changed the various patch properties (rectprops, lineprops) argument to props, so that now we have only props and handleprops for all selectors.
To address #20618, we could add two method to set the properties of the selector patch and the handle separately. The idea is that either at initialisation or when using set_props or set_handle_props, we could set the properties regardless of what type of object they are.

I am happy to revert 35ee92d if others also think that this is going in the wrong direction!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For example, as an average matplotlib user, I don't know what are the different parameters between lineprops and markerprops, I will need to look it up.

Conversely, I argue that props is even less helpful. The different selectors are realized by different Artists and thus have different properties. We cannot hide that fact. SpanSelector accepts facecolor, LassoSelector accepts solid_linestyle, and neither accepts the other one respectively. With props the user has to lookup what is supported as well. But it's more surpising and harder to remember that the same parameter name accepts different inputs depending on the class.

state_modifier_keys : dict, optional
Keyboard modifiers which affect the widget's behavior. Values
amend the defaults.
@docstring.Substitution(_RECTANGLESELECTOR_PARAMETERS_DOCSTRING)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why this indirection?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be able to reuse the docstring in EllipseSelector and RectangleSelector.

Copy link
Member

@timhoffm timhoffm Jul 11, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. I'm not a fan of too much indirection in the docs. Some duplication is ok sometimes.

Reuse implies coupling. The risk with indirection is that people start to write about Rectangle explicitly, which does not make sense for the Ellipse case. Conversly, the risk with duplicated docstrings is that they are not in sync (which IMHO is not the end of the world).
I even claim it's a mistake that EllipseSelector inherits from RectangleSelector.

It's a tradeoff which I would decide in favor of the duplication here. But I'm not going to fight over it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have put a placeholder for the artist type to be replaced by ellipse or selector to fix this issue.

I even claim it's a mistake that EllipseSelector inherits from RectangleSelector.

I don't know about that, maybe for another PR! ;)

@timhoffm
Copy link
Member

Ok, so here is an overview of the current APIs

grafik

  • Green entries are consistent (don't need any change).
  • Orange entries should be synchronized.
  • Yellow: needs discussion.

props and handle_props face the same problem that the selection indicator and the handles respectively are realized by different objects in the different classes and thus accept different values depending on the class. An additional complication is that RectangleSelector / EllipseSelector takes lineprops or rectprops depending on drawtype. Either solution for that is bad (drawtype deciding which parameters are accepted and drawtype deciding which values of a prop parameter are supported).

Given the overall situation I propose the following:

  • lineprops/ rectprops get unified to props, but each docstring has to clearly specify which values are supported by linking the respective Artist properties.
  • Similarly, we unifiy to handle_props and also link the Artist properties.
  • We unify to handle_grab_distance / vertex_select_radius / maxdist to grab_range (or if you want handle_grab_range).

@ericpre
Copy link
Member Author

ericpre commented Jul 12, 2021

Thanks @timhoffm for the summary, this clarify the current situation!
I have improve the docstrings in 44b37fb, where I have tried to put the relevant links to the doc and I have rename handle_grab_distance to grab_range in a22f8cb.

@ericpre ericpre force-pushed the rename_parameter_selectors branch from 97456b4 to a22f8cb Compare July 12, 2021 15:55
@QuLogic
Copy link
Member

QuLogic commented Jul 12, 2021

An additional complication is that RectangleSelector / EllipseSelector takes lineprops or rectprops depending on drawtype. Either solution for that is bad (drawtype deciding which parameters are accepted and drawtype deciding which values of a prop parameter are supported).

We should not worry about drawtype in designing the desired configuration API, because it's deprecated already.

@timhoffm
Copy link
Member

timhoffm commented Jul 13, 2021

We should not worry about drawtype in designing the desired configuration API, because it's deprecated already.

Thanks for pointing this out, I have overlooked this. However, I don't think it changes the above assessment. We're still at rect_props for RectangleSelector and EllipseSelector. The name is awkward for the latter. Though, I would also be ok to leave one lineprops / rectprops parameter per Selector for now.

@ericpre
Copy link
Member Author

ericpre commented Jul 16, 2021

I think that I have addressed all comments. I have no idea why the doc build is failing and I can't see how it is related to this PR; the warning is:

/home/circleci/project/lib/matplotlib/projections/geo.py:docstring of matplotlib.projections.geo.GeoAxes.set_xlim:47: WARNING: py:obj reference target not found: get_ylim

@QuLogic
Copy link
Member

QuLogic commented Jul 16, 2021

A rebase should fix that.

@ericpre ericpre force-pushed the rename_parameter_selectors branch from f8df989 to 8ff493c Compare July 16, 2021 20:22
@ericpre
Copy link
Member Author

ericpre commented Jul 16, 2021

A rebase should fix that.

Ok, thanks!

ericpre and others added 2 commits July 17, 2021 09:01
… deprecation

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
@ericpre
Copy link
Member Author

ericpre commented Jul 18, 2021

Thanks @timhoffm, I have updated the span selector example too.

Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the quick response. I did a careful full review now, which revealed still some open issues.

@ericpre ericpre force-pushed the rename_parameter_selectors branch from b3925a9 to 8682b5f Compare July 19, 2021 08:46
@timhoffm timhoffm merged commit 9869421 into matplotlib:master Jul 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants