Codestyle: modernisations to accompany Python 3.12 baseline

[jayaddison]

Purpose

From commit ad0497b onwards, Python 3.12 is the baseline version required for Sphinx:

sphinx/pyproject.toml

Line 20 in ad0497b

requires-python = ">=3.12"

This pull request uses pyupgrade v3.21.2 to upgrade the Sphinx codebase to refresh it given that new baseline.

Unusually, running pyupgrade --py312-plus ... twice (something I did by accident) made a small difference; the result (87aa828) is a nice improvement, so I've included it in the pull request.

References

N/A

[AA-Turner]

Most of the typing test changes should be reverted.

A

[jayaddison]

Ah, ok. Perhaps the changeset itself isn't worthwhile, in that case - and that's OK. Is it the ~typing.List-style representations that should be kept, and if so, is there a reason to emit those rather than the abbreviated versions?

[jayaddison]

(I did feel that perhaps the longer-format ~typing.List-style representations may be more formally descriptive -- even so, I felt that perhaps it'd be better if documentation expresses Python types the way they should be written in code -- and in my mind, the abbreviated versions are almost always (or in fact, even always?) preferable, because shorter and simpler code seems more Pythonic. wanted to explain my thinking, doesn't affect that I'm OK with discarding the changeset given that it may not be correct/worthwhile)

[danieleades]

ruff already supports these lints- you shouldn't need to use pyupgrade directly.

the config is here -

sphinx/.ruff.toml

Line 133 in cc7c6f4

"UP031", # Use format specifiers instead of percent format

only a couple of lints are selected.

so rather than using pyupgrade, this should ideally be a PR which proposes broadening the enforced pyupgrade lints in the ruff config

[jayaddison]

ruff already supports these lints- you shouldn't need to use pyupgrade directly.

the config is here -

sphinx/.ruff.toml

Line 133 in cc7c6f4

"UP031", # Use format specifiers instead of percent format

only a couple of lints are selected.

so rather than using pyupgrade, this should ideally be a PR which proposes broadening the enforced pyupgrade lints in the ruff config

Those two UP* rules are within the ruff config ignore-list, I think. But even so, I should mention that in fact, I'm not entirely convinced by the f-string modifications applied by pyupgrade - and so I think perhaps those rules should remain disabled.

When I mentioned:

Unusually, running pyupgrade --py312-plus ... twice (something I did by accident) made a small difference; the result (87aa828) is a nice improvement, so I've included it in the pull request.

...I hadn't noticed that the previous commit, 056818b, had expanded a bunch of f-strings in a way that introduces (I think) slightly-confusing escaping of brackets ({ and }), particularly in the context of LaTeX where those are used frequently and allowing people to pattern-match as closely as possible to the native appearance of LaTeX syntax probably makes sense in terms of maintainability/reviewability.

So: I think I'll partially-revert the changes in this branch, by undoing most-if-not-all of the f-string suggestions.

[danieleades]

My comment about ruff was more- if we think these are good changes, why don't we change the existing ruff config to do this, instead of using pyupgrade as a one-off

[danieleades]

My comment about ruff was more- if we think these are good changes, why don't we change the existing ruff config to do this, instead of using pyupgrade as a one-off

[jayaddison]

I suppose we could do; for a few moments I thought doing that might require the use of per-file ignores (which I think are easy to forget about and cause annoying codestyle divergence/drift).

The number of affected string literals seems fairly low, though - so perhaps line-level ignore statements could work instead.

[jayaddison]

Hm; UP031 introduces about 300 errors when enabled, UP032 only 9 10.

[jayaddison]

@danieleades I think this works well, but it's not really related to Python 3.12 - either we should put it into a separate PR, or alter the description of this one to be more generic.

[jayaddison]

Given that the typing changes in the tests aren't acceptable, and that the f-string changes are fairly minimal, I'll close this as unnecessary.