This updates the type hints forAxes.annotate inlib/matplotlib/axes/_axes.pyi so that thexy andxytext parameters are no longer restricted totuple[float, float], but instead accepttuple[Any, Any].

Why is this change necessary?

In real usage,Axes.annotate supports coordinates that are not just floats. A common example is using datetime-like values on the x-axis together with a float on the y-axis.
The previous stub annotated bothxy andxytext astuple[float, float], which caused type checkers (e.g. mypy/pyright) to incorrectly flag valid code.

What problem does it solve?

It removes false-positive type errors for users who annotate time series plots or other non-numeric coordinate systems.
This addresses the report in[Bug]: Type hints for xy and xycoords in annotate are too strict #30365.

What is the reasoning for this implementation?

We keep the runtime signature exactly as-is (argument names/order/defaults remain unchanged).
We only widen the stub side to:
- xy: tuple[Any, Any]
- xytext: tuple[Any, Any] | None
No runtime behavior is changed, and no API behavior is changed. This is strictly a typing/stub correction.

Title:TYPING: Broaden Axes.annotate xy/xytext types to allow datetime-like values (#30365)

PR checklist

"closes[Bug]: Type hints for xy and xycoords in annotate are too strict #30365" is in the body of the PR description to link the related issue
[N/A] new and changed code is tested (no runtime code changed; stub only)
[N/A]Plotting related features are demonstrated in an example
[N/A]New Features andAPI Changes are noted with a directive and release note (no API change)
Documentation complies with general and docstring guidelines (no docstring changes, but the types now match actual supported usage)

TYPING: Broaden Axes.annotate xy/xytext types to allow datetime-like …

2a0e388

…values (matplotlib#30365)

Copy link

Author

cnotley commentedOct 28, 2025

The failing check appears to be the first-interaction action complaining about a missing issue_message. This PR only updates the _axes.pyi stub for Axes.annotate and doesn’t touch code or CI

QuLogic added the topic: typing label

Oct 28, 2025

QuLogic requested a review fromksunden

October 28, 2025 09:23

Copy link

Member

rcomer commentedOct 28, 2025

Tests are failing becausepyplot.py also needs updating. Please follow the instructions in the test output
https://github.com/matplotlib/matplotlib/actions/runs/18865351077/job/53831829565?pr=30693#step:13:209

Copy link

Member

ksunden commentedOct 28, 2025

I think this needs to be amuch broader discussion than just aboutAnnotate...

It was an intentional choice to go withfloat in mostx/y cases for type hints. The reality is thatAny is "technically correct, but unhelpful in 90% of cases". theConverter system/registry allows fordynamic behavior of allowed types, which is impossible to encode accurately and narrowly in a static type check.

I have had various thoughts about having aMPLScalar type or something to broaden it, but keep semantic meaning. I've debated between that being a typealias forAny or e.g. including all of the types that are supported in the default library provided options.

A more complicated option that I don't think I want to go with would be to makeAxes generic overX_DataType andY_DataType. That could potentially solve it for the Axes methods themselves, but introduces significant complication into other places (notably pyplot, where the axes that it would refer to is held in dynamic global state). In all, I think that option is more trouble than it is worth.

Copy link

Member

timhoffm commentedOct 31, 2025

I would not do any changes here for now based on

The reality is that Any is "technically correct, but unhelpful in 90% of cases".

The rare other cases should just# type: ignore. Maybe we could document that somewhere.

tacaswell added the status: needs comment/discussionneeds consensus on next step label

Nov 2, 2025

Copy link

Member

tacaswell commentedNov 2, 2025

including all of the types that are supported in the default library provided options

This seems like a good option, but not sure how much work that is. I agree with Tim in teh short term we should document

It was an intentional choice to go with float in most x/y cases for type hints. The reality is that Any is "technically correct, but unhelpful in 90% of cases". the Converter system/registry allows for dynamic behavior of allowed types, which is impossible to encode accurately and narrowly in a static type check.