Oh, one mypy_primer error isn't actually too bad at all. I vote for doing this, in that case!

Maybe add a test case? We can't use mypy_primer to ensure we don't break this again, since the improvement doesn't show up in the diff and open-source projects are unlikely to contain CaseInsensitiveDict() | dict() anyway.

Sure, I'll add a test

And the one primer hit actually shows a genuine problem as using an arbitrary mapping wouldn't work either. This is actually something I wasn't aware of, so +10 for changing these annotations.

I don't understand what's going on with the remaining pyright errors on the test cases I've added. @srittau / @Akuli, do either of you understand why they're happening? Mypy is fine with all the test cases I've added.

One thing I'd try is using a small custom mapping-like type in the tests instead of os.environ. The latter has a lot going on, with generics and python-specific branches, and I wouldn't be surprised if a typechecker would special-case it due to its importance.

Okay, for now I've just commented out the tests that were failing on pyright and left TODO comments. There's definitely a behaviour difference from mypy there -- to me it looks like a bug, but not sure. I'll file an issue with pyright later.

Diff from mypy_primer, showing the effect of this PR on open source code:

mkosi (https://github.com/systemd/mkosi)
+ mkosi/run.py:177:11: error: No overload variant of "__or__" of "dict" matches argument type "Mapping[str, str]"  [operator]
+ mkosi/run.py:177:11: note: Possible overload variants:
+ mkosi/run.py:177:11: note:     def __or__(self, dict[str, str], /) -> dict[str, str]
+ mkosi/run.py:177:11: note:     def [_T1, _T2] __or__(self, dict[_T1, _T2], /) -> dict[Union[str, _T1], Union[str, _T2]]

At first glance the tests seemed like too much copy/pasta, but I think it's fine because dict and defaultdict behave differently.

Yeah, dict.__or__ always returns dict, whereas defaultdict.__or__ returns Self. I considered putting all the tests into a check_pep584.py file, but thought it would be too confusing to have some of the tests for dict in a file that had a name that didn't start with check_dict.