Simplify typing annotations (ruff UP006) #41108

vincentmacri · 2025-10-27T20:52:14Z

Replace things like List[T] with list[T] in type annotations. Enables this rule in CI and in configuration files.

To do this I used ruff to fix UP006, then fixed F401 on the changed files (to remove the UP006 unused imports left behind by UP006).

There are several other ruff UP rules that have autofix and can easily be enabled. To keep the PR a reasonable size we only do UP006 here.

📝 Checklist

The title is concise and informative.
The description explains in detail what this PR is about.
I have linked a relevant issue or discussion.
I have created tests covering the changes.
I have updated the documentation and checked the documentation preview.

vincentmacri · 2025-10-27T20:54:42Z

src/tox.ini

-#      2        PLE0302 [ ] The special method `__len__` expects 1 parameter, 3 were given
-#      1        F402    [ ] Import `factor` from line 259 shadowed by loop variable
-#      1        PLC0208 [*] Use a sequence type instead of a `set` when iterating over values
+# 10589	PLC0415	[ ] import-outside-top-level


I updated this comment while I was touching this file. Looks like that hasn't been done in a while.

vincentmacri · 2025-10-27T21:01:06Z

pyproject.toml

 [tool.ruff.lint]
 ignore = [
  "E501", # Line too long - hard to avoid in doctests, and better handled by black.
+  "UP045", # non-pep604-annotation-optional - Whether `Optional[T]` or `T | None` is better is subjective.


In preparation for eventually being able to enable more/all UP rules. At first glance this was the only one I saw that seemed potentially controversial. I'm not taking a stance on it for this PR, but my personal opinion is that Optional is more readable for parameters and less readable for return values.

Other rules in UP that would have a big impact for us: changing old-style string formatting to f-strings. I think that's only an issue for us because of how many files it would change. In principle I think f-strings are far more readable, but unless we want to do a patch bomb it's hard to see us ever transitioning the entire code base to f-strings. (I guess in theory we could do some kind of git hook autoformat when files get changed for other reasons to slowly transition things over automatically, but I think that would be controversial.)

I think

def func(param: str | None = None)

is clearer and involves less mental overhead to understand than having param: Optional[str] = None.

github-actions · 2025-10-27T22:06:22Z

Documentation preview for this PR (built with commit 4e3f7c9; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

tobiasdiez

Small nitpicks

tobiasdiez · 2025-11-05T02:39:22Z

src/sage/rings/function_field/element_rational.pyi

        ...

-    def list(self) -> List:
+    def list(self) -> builtins.list:


why not simply list?

This change was made by ruff. I think the reason it is using builtins is because (as seen on this line) there is a function called list which ruff thinks is overwriting the builtin name. I'll remove the builtins and see what happens (if there is an error I'll revert).

tobiasdiez · 2025-11-05T02:40:25Z

src/sage/rings/laurent_series_ring_element.pyi

        ...

-    def _im_gens_(self, codomain: Any, im_gens: List[Any], base_map: Optional[Any] = None) -> 'LaurentSeriesRingElement':
+    def _im_gens_(self, codomain: Any, im_gens: builtins.list[Any], base_map: Optional[Any] = None) -> 'LaurentSeriesRingElement':


same here in this file a couple of times

tobiasdiez · 2025-11-05T02:45:53Z

pyproject.toml

 [tool.ruff.lint]
 ignore = [
  "E501", # Line too long - hard to avoid in doctests, and better handled by black.
+  "UP045", # non-pep604-annotation-optional - Whether `Optional[T]` or `T | None` is better is subjective.


I think

def func(param: str | None = None)

is clearer and involves less mental overhead to understand than having param: Optional[str] = None.

vincentmacri · 2025-11-05T05:41:58Z

I think

def func(param: str | None = None)

is clearer and involves less mental overhead to understand than having param: Optional[str] = None.

As I said, this one is more of a matter of opinion than a strict style rule. Unlike Optional, List et al. are eventually supposed to be deprecated.

While I personally like Optional, I won't oppose if someone else wants to change Optional[str] to str | None. I'll remove this explicit ignore line for now.

The reason I like Optional is I think it's more clear to someone who isn't familiar with Python type annotation syntax.

tobiasdiez · 2025-11-05T06:18:58Z

I think
def func(param: str | None = None)
is clearer and involves less mental overhead to understand than having param: Optional[str] = None.

As I said, this one is more of a matter of opinion than a strict style rule. Unlike Optional, List et al. are eventually supposed to be deprecated.

While I personally like Optional, I won't oppose if someone else wants to change Optional[str] to str | None. I'll remove this explicit ignore line for now.

The reason I like Optional is I think it's more clear to someone who isn't familiar with Python type annotation syntax.

I also don't really care too much. After a bit of digging, I found python/cpython#30222 (review) which does state that the shorthand version is preferred. I would suggest we just choose one way, and than use that consistently.

vincentmacri · 2025-11-05T06:42:47Z

I think
def func(param: str | None = None)
is clearer and involves less mental overhead to understand than having param: Optional[str] = None.

As I said, this one is more of a matter of opinion than a strict style rule. Unlike Optional, List et al. are eventually supposed to be deprecated.
While I personally like Optional, I won't oppose if someone else wants to change Optional[str] to str | None. I'll remove this explicit ignore line for now.
The reason I like Optional is I think it's more clear to someone who isn't familiar with Python type annotation syntax.

I also don't really care too much. After a bit of digging, I found python/cpython#30222 (review) which does state that the shorthand version is preferred. I would suggest we just choose one way, and than use that consistently.

| is preferred to Union, but Optional I think is a special case where either is considered fine as long as we are consistent (this is why ruff has these are different rules). I think ruff can autofix Optional to | None so we probably just turn on that rule later as having autofix is kind of necessary for being consistent on a codebase as large as Sage.

Either way, this is a different rule in ruff than the rule this PR is fixing. So it's something to think about for followup work. I didn't want to submit a patch bomb (@fchapoton requested on one of my previous PRs that I split things up better) so I plan to submit a series of PRs enabling a handful of ruff rules at a time. Next will probably be fixing implicit Optional since that's an actual error. Maybe I'll change Optional to | None at the same time if it doesn't make the patch too big. After that maybe getting rid of Union since | is preferred as you pointed out.

vincentmacri · 2025-11-05T07:25:55Z

Thanks for the review!

vincentmacri · 2025-11-05T07:27:03Z

I'm assuming from you marking this as approved changes that you meant to set the positive review label, please change the label back if not.

vincentmacri added 2 commits October 27, 2025 14:45

ruff UP006

beacc6b

Fix ruff F401 on changed files

37242e0

github-actions bot added the s: needs review label Oct 27, 2025

vincentmacri added t: refactoring github_actions Pull requests that update GitHub Actions code labels Oct 27, 2025

vincentmacri commented Oct 27, 2025

View reviewed changes

Merge branch 'develop' into ruff-UP-typing

787b086

vincentmacri requested a review from fchapoton October 28, 2025 17:53

vincentmacri changed the title ~~Fix and enable ruff UP006~~ Fix and enable ruff UP006 (simplify typing annotations) Nov 4, 2025

vincentmacri changed the title ~~Fix and enable ruff UP006 (simplify typing annotations)~~ Simplify typing annotations (ruff UP006) Nov 4, 2025

tobiasdiez suggested changes Nov 5, 2025

View reviewed changes

Address reviewer comments

4e3f7c9

tobiasdiez approved these changes Nov 5, 2025

View reviewed changes

vincentmacri added s: positive review and removed s: needs review labels Nov 5, 2025

Uh oh!

Simplify typing annotations (ruff UP006) #41108

Are you sure you want to change the base?

Simplify typing annotations (ruff UP006) #41108

Uh oh!

Conversation

vincentmacri commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Checklist

Uh oh!

vincentmacri Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

vincentmacri Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

tobiasdiez Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tobiasdiez left a comment

Choose a reason for hiding this comment

Uh oh!

tobiasdiez Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

vincentmacri Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

tobiasdiez Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

tobiasdiez Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

vincentmacri commented Nov 5, 2025

Uh oh!

tobiasdiez commented Nov 5, 2025

Uh oh!

vincentmacri commented Nov 5, 2025

Uh oh!

vincentmacri commented Nov 5, 2025

Uh oh!

vincentmacri commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vincentmacri commented Oct 27, 2025 •

edited

Loading

github-actions bot commented Oct 27, 2025 •

edited

Loading

vincentmacri commented Nov 5, 2025 •

edited

Loading