Skip to content

[Doc]: Incomplete annotation for labels in Axes.set_xticklabels #27297

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

Closed
pawjast opened this issue Nov 9, 2023 · 3 comments
Closed

[Doc]: Incomplete annotation for labels in Axes.set_xticklabels #27297

pawjast opened this issue Nov 9, 2023 · 3 comments

Comments

@pawjast
Copy link

pawjast commented Nov 9, 2023

Documentation Link

https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_xticklabels.html

Problem

The explanation for labels says it accepts either sequence of strings or Texts:

image

However, it's also possible to pass as a parameter e.g. list of ints or floats or similar and the method works too.

I think this should be reflected in the doc.

import random
import matplotlib.pyplot as plt

x = sorted(random.sample(range(15), 5))
y = sorted(random.sample(range(10), 5))

fig, ax = plt.subplots(
    figsize=(10, 6)
)

ax.plot(x, y, "o-")
ax.set_xticks(x)
ax.set_xticklabels(x)  # x is `list` of INTs, not strings
ax.grid(axis="x")

Gives this, without any problems:

image

Or if you generate list of floats:

x_labels = [random.random() for _ in range(len(x))]

And then update the tick labels:

ax.set_xticklabels(x_labels)  # x is `list` of FLOATs, not strings

I'll get this:
image

Suggested improvement

Update the description so it's clear numeric arrays can be passed on as a parameter.

@ksunden
Copy link
Member

ksunden commented Nov 9, 2023

This is the same (core) problem as the point about xlabel in #26858. The actual code certainly will accept any object (by virtue of having a __str__ method), but how much of that should be considered "expected" vs "implementation detail"?

One suggestion we have been discussing (from the type hinting side at least) is having an alias like StrLike which actually resolves to object or Any but communicates the intent to treat it as a str.

In the case of passing numbers, it is actually quite unintuitive what happens, as the numbers are now labeling a point (possibly) other than the point that is numerically equivalent. (Even in your (float) example, the numbers appear out of order, for instance, which is likely to cause confusion.) While it works, and if that is truly what you want, you can do it, I actually think by encouraging (if not requiring) explicit casting to string makes your code easier to tell that that was intentional and not e.g. wanting to call set_xticks, but actually calling set_xticklabels. Even moreso with floats, as I think if you were actually wanting float labels, it is likely that you would want to format them to e.g. have 3 decimal places (and also likely that you want it showing up at the numerical equivalence point, at which point, a Formatter is usually the tool for the job rather than passing tick labels directly)

@ksunden
Copy link
Member

ksunden commented Nov 9, 2023

See also this comment on the subject:

#26867 (comment)

@timhoffm
Copy link
Member

As written in #26867 (comment), we’re not going to broaden the docstring types. It’s important that this is logically a str. Consider it an implementation detail that we accept other objects and convert them to str. We’re not making any guarantee that this will always work in the future.

@timhoffm timhoffm closed this as not planned Won't fix, can't repro, duplicate, stale Jan 20, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants