Skip to content

ENH: Add which parameter to Axis.get_gridlines#31674

Closed
SharadhNaidu wants to merge 2 commits into
matplotlib:mainfrom
SharadhNaidu:enh-19021-get-gridlines-which
Closed

ENH: Add which parameter to Axis.get_gridlines#31674
SharadhNaidu wants to merge 2 commits into
matplotlib:mainfrom
SharadhNaidu:enh-19021-get-gridlines-which

Conversation

@SharadhNaidu

@SharadhNaidu SharadhNaidu commented May 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

PR summary

Closes #19021.

Axis.get_gridlines() currently returns only major gridlines, with no public way to obtain the minor gridlines. As called out in the issue thread, downstream libraries have been forced to reach into private API as a workaround:

  • seaborn reads Axis._minor_tick_kw['gridOn'] (source)
  • gwpy, mpld3, mplexporter and others were referenced in the same thread

This PR implements the API @jklymak proposed in the issue:

Or a new get_gridlines(which='minor'/'major'/'both')?

def get_gridlines(self, which='major'):
    """Return this Axis' grid lines as a list of Line2D's."""

The vocabulary 'major' | 'minor' | 'both' matches Axis.grid() and Axis.get_ticklabels(). Default 'major' preserves the previous behavior byte-for-byte, so every existing zero-argument caller continues to work unchanged.

Files changed

File Change
lib/matplotlib/axis.py Extend get_gridlines to accept which='major'/'minor'/'both'
lib/matplotlib/axis.pyi Update type stub signature
lib/matplotlib/axes/_base.pyi Update Axes.get_x/ygridlines stubs (auto-delegated wrappers)
lib/matplotlib/tests/test_axes.py Two new tests covering selection and visibility tracking
doc/release/next_whats_new/get_gridlines_which.rst What's new entry with example plot

Testing

I monkey-patched the new implementation onto an installed matplotlib==3.10.9 and ran the same assertions the new pytest cases exercise:

  • selection by which='major', which='minor', which='both' returns the expected lengths and ordering
  • the 'both' ordering is major + minor (matching get_ticklabels)
  • visibility on the returned Line2D objects tracks the active grid state through Axis.grid(visible=..., which=...) calls
  • backward compatibility: get_gridlines() and get_gridlines('major') are equivalent on both xaxis and yaxis
  • which='invalid' raises ValueError with the standard _api.check_in_list message
  • Axes.get_xgridlines(which=...) / Axes.get_ygridlines(which=...) auto-delegate via _axis_method_wrapper

All checks pass against the installed matplotlib with the new method patched in.

Notes for reviewers

  • The implementation follows @jklymak's exact API suggestion. If you would prefer separate get_majorgridlines / get_minorgridlines methods (briefly considered in the thread) I am happy to refactor.
  • For which='both', major gridlines come before minor gridlines, matching get_ticklabels(which='both').
  • The docstring's Notes section explicitly tells callers to check Line2D.get_visible() to address @anntzer's concern about per-gridline visibility.

AI Disclosure

AI was used to help proofread the grammar of this PR description and to understand some parts of the existing codebase during development. The code changes and design decisions were developed independently.

PR checklist

  • "closes Need a way to check if an axis minor or major grid is on #19021" is in the body of the PR description
  • new and changed code is tested
  • Plotting related features are demonstrated in an example (the What's new entry contains a .. plot:: directive showing minor-gridline coloring)
  • New Features and API Changes are noted with a directive and release note (versionchanged:: 3.11 in the docstring + doc/release/next_whats_new/get_gridlines_which.rst)
  • Documentation complies with general and docstring guidelines

@SharadhNaidu
ENH: Add which parameter to Axis.get_gridlines
676d602 
`Axis.get_gridlines` previously returned only major gridlines, with no
public way to get the minor gridlines. Downstream libraries (seaborn,
gwpy, mpld3, ...) had to reach into the private `_minor_tick_kw`
mapping to inspect minor grid state.

Extend the signature to `get_gridlines(which='major')`, accepting
`'major'`, `'minor'`, or `'both'` (matching the vocabulary of
`Axis.grid` and `get_ticklabels`). The default of `'major'` keeps the
existing behavior byte-for-byte.

Closes matplotlib#19021
@SharadhNaidu SharadhNaidu force-pushed the enh-19021-get-gridlines-which branch from 55bc9a1 to 676d602 Compare May 15, 2026 07:04
@SharadhNaidu
MNT: Update Axes.get_x/ygridlines stub for new which parameter
94a7b00 
The Axes.get_xgridlines and Axes.get_ygridlines methods are auto-generated
wrappers around Axis.get_gridlines (via _axis_method_wrapper), so they
inherit the new which parameter at runtime. Update the .pyi stubs to
match, fixing the mypy stubtest failure.
@rcomer

rcomer commented May 15, 2026

Copy link
Copy Markdown
Member

Please fill out the AI disclosure.

@rcomer rcomer added the status: autoclose candidate PRs that are not yet ready for review and may be automatically closed in two weeks label May 15, 2026
@github-actions

This comment was marked as outdated.

Sign in to view
@SharadhNaidu

SharadhNaidu commented May 15, 2026

Copy link
Copy Markdown
Contributor Author

@rcomer Sorry for disturbing but , are there any changes that i have to make with the PR or is the review still pending ?

@rcomer rcomer removed the status: autoclose candidate PRs that are not yet ready for review and may be automatically closed in two weeks label May 15, 2026
@timhoffm

timhoffm commented May 17, 2026

Copy link
Copy Markdown
Member

Thanks for the PR.

The original request of #19021 to get the grid on status is already handed through get_tick_params(). See #19021 (comment).

I'm a bit torn on the addtion for getting minor grid lines. From a technical and consistency perspective this is correct. However, we discourage accessing individual ticks and their constituent Artists (ticklines, labels, grid lines). These should be considered ephemal and may be changed or recreated whenever the plot changes.

@SharadhNaidu

SharadhNaidu commented May 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Thanks @timhoffm — you're right on both counts. I went back and checked the current state of things:

I should have re-validated the private-API claim in my PR body before writing it — apologies for the stale framing.

The remaining motivation is the styling case in the what's-new example. That's narrower than I implied to.

It's the same pattern get_gridlines() already enables for major gridlines, which is why @jklymak suggested this exact which= signature .

(#19021 (comment)) — but I take your point that ephemeral is a stronger principle than API symmetry.

Happy to close this if you'd prefer not to extend the gridline-access surface, or scope it down if there's a middle ground you'd like to see. Your call.

@rcomer

rcomer commented May 17, 2026

Copy link
Copy Markdown
Member

Styling the gridlines is also already covered by tick_params.

import matplotlib.pyplot as plt

fig, ax = plt.subplots()

ax.plot(range(10))
ax.minorticks_on()
ax.grid(which='both')
ax.tick_params(axis='x', which='minor', grid_color='red')

plt.show()
image

@SharadhNaidu

SharadhNaidu commented May 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Thanks @rcomer , that settles it.Both the status-check and the styling use cases are already covered by existing public API, so this PR isn't adding anything.Closing it now.Appreciate both of you taking the time to walk through this.

I am really sorry for wasting your time.

@rcomer

rcomer commented May 17, 2026

Copy link
Copy Markdown
Member

Thanks for your understanding @SharadhNaidu. It is not your fault that the issue was out of date.

@rcomer rcomer mentioned this pull request Jun 8, 2026
Merged
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

topic: axes topic: ticks axis labels

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Need a way to check if an axis minor or major grid is on

3 participants

@SharadhNaidu @rcomer @timhoffm