iframe-proxy

timhoffm · 2026-08-01T08:21:43Z

PR summary

The added _Param.type attribute is currently used only for documentation, not for validation.
This allows to be more flexible and conveniently use type annotations such as int and list[float] | None, but also strings such as ":mpltype:`color`".

Additional notes:
type has a strong overlap with validators. Keeping them separate and have the duplication for now is a conscious design decision. In addtion to type checking, validators do more: They convert from string, because they are primarily built as a tooling to parse matplotlibrc. They can also do value validation beyond type validation (e.g. _validate_greaterthan_minushalf).
It is furthermore intentional to mostly standardize type towards type annotation and not use free text, even if that means we cannot express "greater thatn minus half". It is anticipated that we may use this information for type checking / validation eventually, e.g. we could build a TypedDict from this information, or maybe at some point we want to switch from a _Param specification to a specification via dataclasses. Proper type annotations will facilitate this.

AI Disclosure

no AI

PR quality check

Use an expressive title, e.g. "Fix title font property precedence"
[N/A] New and changed code is tested
[N/A] Plotting related features are demonstrated in an example
[N/A] New features and API changes have release notes
Documentation complies with general and docstring guidelines

The added `_Param.type` attribute is currently used only for documentation, not for validation. This allows to be more flexible and conveniently use type annotations such as int and list[float] | None, but also strings such as ":mpltype:`color`".

iccir · 2026-08-03T03:35:50Z

+# circular dependencies between matploblib.rcsetup and matplotlib.typing.
+# Resolving this will require a dedicated effort.
+
+type _FontSizeType = float | Literal[


validate_fontsize() performs a s.lower(), so technically isn't this list too narrow? I don't think there's a way to specify a case-insensitive string as a type, however.

Correct. Here I define the "normalized" version as recommended spelling. It's ok if the parser is more permissive. For now, this is just for documentation, so a user is directed to use these forms. Even if we at some point in the future use this for type checking, it may prompt corrections in some cases, where they are not strictly necessary, but IMHO this is bearable and perferrable compared to doing a permissive specification.

The lower() is a historic artifact. I wouldn't do these nowadays because it's unnecessarily lax. But it's not important enough to narrow down the implementation and break user code.

That makes a lot of sense! I figured that this was the case, but I wanted to mention every case where the type and the validator were mismatched.

iccir · 2026-08-03T03:48:18Z

        "mathtext.fallback",
        default="cm",
+        type=Literal["cm", "stix", "stixsans"] | None,
        validator=_validate_mathtext_fallback,


_validate_mathtext_fallback also does a s.lower()

As above. If in doubt, make the specification more strict and the implementation more permissive.

iccir · 2026-08-03T03:58:19Z

        "xtick.minor.ndivs",
        default="auto",
+        type=int | Literal["auto"],
        validator=_validate_minor_tick_ndivs,


_validate_minor_tick_ndivs() calls cbook._str_lower_equal

iccir · 2026-08-03T15:46:57Z

        "center", "top", "bottom", "baseline", "center_baseline"],

    "grid.color":        validate_color,  # grid color
    "grid.linestyle":    _validate_linestyle,  # solid


I think this is the mismatch causing the current test failure. I'm not sure if this can be _LineStyleType or not.

Whoops, the quick fix was too quick. I intended to update the type not the validator. Fixed.

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

story645 · 2026-08-05T19:16:03Z

even if that means we cannot express "greater thatn minus half".

That can get encapsulated in a proper datatype though? (the __post_init__(self) method of a dataclass)

timhoffm · 2026-08-05T20:19:00Z

I don't follow. You could create a type LimitedFloat that does only accept this, but as far as I understand typing, a user supplied val: float = 0,1 will not be compatible with this. Or are you saying you want to internally store the values in a dataclass that does validation in __post_init__? Well first we are not using dataclasses, and second this would be runtime validation not static type limitation. In I expect that some form of normalization and validation will stay around and replace the _validate_* methods. The _validate_* methods are awkward because they convert everything from string. This was handy for simply parsing matplotlibrc files. But it's mixing concerns and we'll want to separate this in the future.

But that's all for later PRs.

story645 · 2026-08-05T21:21:46Z

But it's mixing concerns and we'll want to separate this in the future.

Yeah, was just mentioning it as I think there's a way to encapsulate those constraints in types, with the implication being it's fine if this less precise form gets dropped now. Going down this rabbit hole, looks like Annotated is the way to do this cleanly.

story645

Mostly questions/nits but useful info for docs.

story645 · 2026-08-05T22:05:45Z

+# for _Param(). They are currently only used for documentation. Eventually, they
+# should be reconciled with matplotlib.typing. However, this would cause non-trivial
+# circular dependencies between matploblib.rcsetup and matplotlib.typing.
+# Resolving this will require a dedicated effort.


Just to make sure I'm understanding, this is why you can't use the colortypes in typing and the like and are using the doc types instead?

* MNT: Add type information to rcParams The added `_Param.type` attribute is currently used only for documentation, not for validation. This allows to be more flexible and conveniently use type annotations such as int and list[float] | None, but also strings such as ":mpltype:`color`". * Apply suggestions from code review Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> * Add review suggestions

github-actions Bot added topic: rcparams Documentation: build building the docs labels Aug 1, 2026

timhoffm force-pushed the rcparams-type branch 3 times, most recently from 1c203be to 6e24b6c Compare August 1, 2026 09:54

MNT: Add type information to rcParams

53006a7

The added `_Param.type` attribute is currently used only for documentation, not for validation. This allows to be more flexible and conveniently use type annotations such as int and list[float] | None, but also strings such as ":mpltype:`color`".

timhoffm force-pushed the rcparams-type branch from 6e24b6c to 53006a7 Compare August 2, 2026 10:19

iccir reviewed Aug 3, 2026

View reviewed changes

Comment thread lib/matplotlib/rcsetup.py Outdated

iccir reviewed Aug 3, 2026

View reviewed changes

Comment thread lib/matplotlib/rcsetup.py

iccir reviewed Aug 3, 2026

View reviewed changes

Apply suggestions from code review

eec8979

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>

timhoffm force-pushed the rcparams-type branch from 3049a28 to eec8979 Compare August 3, 2026 20:49

iccir approved these changes Aug 4, 2026

View reviewed changes

story645 approved these changes Aug 5, 2026

View reviewed changes

Add review suggestions

25c1646

timhoffm merged commit f38d4ac into matplotlib:main Aug 6, 2026
40 of 41 checks passed

timhoffm deleted the rcparams-type branch August 6, 2026 20:58

QuLogic added this to the v3.12.0 milestone Aug 7, 2026

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Uh oh!

Conversation

timhoffm commented Aug 1, 2026

PR summary

AI Disclosure

PR quality check

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

story645 commented Aug 5, 2026

Uh oh!

timhoffm commented Aug 5, 2026

Uh oh!

story645 commented Aug 5, 2026

Uh oh!

story645 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

timhoffm Aug 3, 2026 •

edited

Loading