Fully typed RangeMap and avoid complete iterations to find matches

[Avasam]

Bringing improvements over from mhammond/pywin32#2334

• Fully typed RangeMap
• Avoid complete iterations to find matches
• Use dict literal instead of dict call https://docs.astral.sh/ruff/rules/unnecessary-collection-call/ see https://docs.astral.sh/ruff/settings/#lintflake8-comprehensions

[jaraco]

Looks good. I appreciate the contrib, especially the more efficient use of the filter.

I'd prefer to see contributions like these applied in separate commits for each concern (i.e. 3 commits for the described changes plus additional commits for any style changes). No need to re-write as different commits now, but please consider it for the future. Probably the changes to win32timezone should have been contributed here first and then vendored downstream, but that opportunity has passed.

[jaraco]

Oh. I didn't know you could subclass from Dict. TIL.

int is overspecified here. RangeMap accepts any keys (possibly heterogeneous) that are comparable based on the key_match_comparator.

Also, the values don't need to be uniform. They can be heterogeneous.

[Avasam]

Oh. I didn't know you could subclass from Dict. TIL.

Yeah typing re-exports runtime generic aliases of builtin and collection types. It's useful when trying to specify generic parameters for builtins and collections that are not yet subscriptable in older Python versions.

Also, the values don't need to be uniform. They can be heterogeneous.

Is RangeMap meant to be mutable? If not I think it would make sense to make the value covariant like a Mapping

[jaraco]

Is RangeMap meant to be mutable?

I was not intending for it to be restricted to be immutable. I can't recall if I've used it for an application that changes it dynamically, but it's a use-case that should be supported unless there's a practical benefit to making it immutable. It was modeled after the dict, so is meant to have similar flexibility.

[Avasam]

Alright, in that case I think it's correct to keep both keys and values invariant.

[Avasam]

I'd prefer to see contributions like these applied in separate commits for each concern (i.e. 3 commits for the described changes plus additional commits for any style changes). No need to re-write as different commits now, but please consider it for the future.

I can rebase into clean commits once you've fully approved the changes if you'd like. (unless it was for review purposes, and not a clean commit history, in which case please squash merge).

Probably the changes to win32timezone should have been contributed here first and then vendored downstream

It was kinda done at the same time (midway through changes I figured I should probably provide the improvements back upstream), at which point I may as well complete and push my changes to not loose or forget it. But chances are this PR will be completed and included in a new version before mhammond reviews the downstream PR, and even then I'll just wait before merging.

[jaraco]

I can rebase into clean commits once you've fully approved the changes if you'd like. (unless it was for review purposes, and not a clean commit history, in which case please squash merge).

I'll plan to do a squash merge. I tend to avoid them, but happy to employ in select cases like this one.

[Avasam]

@jaraco is there anything I can do about these docs warnings causing failure ?

[jaraco]

I let Gemini do the hard work, applied in 228c7ba.