Skip to content

DOC: Add a warning on methods to access Tick parts (lines, labels, grid)#31691

Open
timhoffm wants to merge 2 commits into
matplotlib:mainfrom
timhoffm:doc-access-ticks
Open

DOC: Add a warning on methods to access Tick parts (lines, labels, grid)#31691
timhoffm wants to merge 2 commits into
matplotlib:mainfrom
timhoffm:doc-access-ticks

Conversation

@timhoffm
Copy link
Copy Markdown
Member

API docs in the same spirit as #31682.

@timhoffm timhoffm added this to the v3.11.0 milestone May 17, 2026
@timhoffm timhoffm added the Documentation: API files in lib/ and doc/api label May 17, 2026
Comment thread lib/matplotlib/axis.py Outdated
guaranteed to be persistent. Various operations can create, delete and
modify the Tick instances.

Consider using `.Axis.set_tick_params` / `.Axis.get_tick_params` to
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
Consider using `.Axis.set_tick_params` / `.Axis.get_tick_params` to
Use `.Axis.set_tick_params` / `.Axis.get_tick_params` to

Going by the above, folks should use the set/get methods unless they know what they're doing well enough to ignore the direct instruction?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

It's a little more complicated than that

  • Not all tick styling functionality is currently exposed through tick_params, some are just not implemented, but for others, the right appoach is to be discussed (e.g. the tick label alignment add label alignment to tick_params #20644 (comment))
  • There will still be some rare cases that we won't support via tick_params: e.g. rarely changed properties like clip_path, zorder(?) or individual tick styling ("make this one tick red").

The long description would be that this tick_params will serve almost all use cases, but there are certain corner cases, that are either currently not implemented or explicitly require full control over individual ticks. In these cases users may resort to working with these individual objects, but must be aware that they may be modified (moved, reused, deleted), which makes this basically only usable for statically rendered plots and needs extra care when creating.

That's much too much for this warning. We actually should link out to that, but we don't have that point to link to. 😭 When trying to improve one aspect of the documentation there's too often coming up some followup action - I've now created #31697.

Accept this PR as is or leave open until we've written the above.

Co-authored-by: hannah <story645@gmail.com>
@github-actions github-actions Bot removed the Documentation: API files in lib/ and doc/api label May 17, 2026
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.

2 participants