Repository navigation
Annotate return types of GF and IntegerModRing factories - #42670
Conversation
There was a problem hiding this comment.
Pull request overview
This PR aims to improve static typing support for Sage’s finite field and integer-mod-ring factory constructors by adding explicit return type annotations to the UniqueFactory subclasses behind GF/FiniteField and Zmod/Integers/IntegerModRing.
Changes:
- Add a forwarding, annotated
__call__override toFiniteFieldFactoryso type checkers can inferGF(...) -> FiniteField. - Add a forwarding, annotated
__call__override toIntegerModFactoryso type checkers can inferIntegers(n) -> IntegerModRing_generic | ZZ. - Import
FiniteFieldfromfinite_field_basefor the new annotation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/sage/rings/finite_rings/integer_mod_ring.py | Adds an annotated IntegerModFactory.__call__ to expose the factory’s return type. |
| src/sage/rings/finite_rings/finite_field_constructor.py | Imports FiniteField and adds an annotated FiniteFieldFactory.__call__ to expose the factory’s return type. |
Suppressed comments (1)
src/sage/rings/finite_rings/finite_field_constructor.py:202
- This forwarding Python-level
__call__adds an extra Python frame to everyGF(...)/FiniteField(...)invocation compared to dispatching directly toUniqueFactory.__call__. SinceGFis a very hot constructor and often hits the cache, this can be a measurable regression.
class FiniteFieldFactory(UniqueFactory):
def __call__(self, *args, **kwds) -> FiniteField:
return super().__call__(*args, **kwds)
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Static type checkers cannot infer the return type of GF, Zmod, Integers and IntegerModRing because these are UniqueFactory instances whose Cython __call__ carries no annotation. Add an annotated, purely forwarding __call__ override to the two factory classes: - FiniteFieldFactory.__call__ returns FiniteField, the common base of FiniteField_prime_modn, FiniteField_givaro, FiniteField_ntl_gf2e and FiniteField_pari_ffelt; - IntegerModFactory.__call__ returns IntegerModRing_generic or IntegerRing_class, because Integers(0) returns ZZ. Verified against Sage 10.9: the annotations appear in inspect.signature, import sage.all is unaffected, the doctests of both modules pass, and factory behavior is unchanged for GF(29), GF(2^8, 'a'), Zmod(17) and Integers(0).
daea1f3 to
6bbcfc4
Compare
|
@cxzhong thanks again for the review — the fix has been pushed: |
tobiasdiez
left a comment
There was a problem hiding this comment.
Thanks, looks good to me.
Maybe add a comment explaining that this method is there only for the typing info.
@sagemath/core could you please run the CI.
|
Thanks — moving both overrides below the class docstrings fixes the original issue in both factories: the class docstrings are again the first class-body statements, so class-level documentation and introspection are preserved. I also checked the return types. Every One compatibility fix remains: please import the finite-field base under a stable alias, for example: and use With Python 3.14’s deferred annotation evaluation, the current annotation can therefore resolve to the factory instance when first inspected rather than to the base class. The alias also avoids the same-name type/value rebinding for mypy. With that rename, this looks good to me. |
Add a comment explaining that the __call__ overrides exist only to expose the return types to static type checkers (review feedback).
The TESTS blocks assert, on every backend, that the annotated return type matches the runtime type: - typing.get_type_hints(type(GF).__call__)['return'] is FiniteField - GF(2^8, 'a', implementation=impl) is a FiniteField for givaro/ntl/pari_ffelt - typing.get_type_hints(type(Zmod).__call__)['return'] equals the declared union - Zmod(29) is an IntegerModRing_generic; Integers(0) is an IntegerRing_class This mechanically guards the annotations against future runtime drift (replacing the manual verification against Sage 10.9).
|
I've prepared three additions around this PR's typing work, based on 1. Regression doctests for this PR (pushed here in The
This guards the annotations against runtime drift in future releases. 2. Follow-up draft PR #42672: element-returning methods The factory annotation gives checkers the field type, but the chain still
Draft: #42672 (annotations only, no 3. Downstream convergence in sage-pycharm-stubgen Once this PR merges, the stub engine prefers the source-declared return Happy to adjust anything here (including dropping the doctests if you |
|
One more offer alongside the three posted earlier — a type-stub The external stub engine ( Suggestion: once these annotations land, add an optional/nightly CI lane The engine intentionally supports older Sage versions (runtime probing Happy to prepare a follow-up PR adding the lane if there is interest. |
The typing.get_type_hints(...) is FiniteField identity check failed on the Python 3.14 CI job (sage's 3.14 build resolves the annotation to a non-identical object). The isinstance assertions are the actual regression guard for the annotation contract; keep those and drop the fragile get_type_hints comparisons.
|
@cxzhong the Python 3.14 CI failure is fixed — thanks for running the tests. What happened: one of the The fix (pushed as @sagemath/core could you please approve and re-run the CI on the updated |
|
Status update on the CI runs (run 31956724841 and siblings):
|
|
Thanks for the approvals! One clarification on the CI state, plus the verification evidence: Current state: the code is approved (tobiasdiez, cxzhong), but the workflow runs created for the current head Which of those red runs were caused by this PR, and which were not:
Fork-CI verification of
So the current head is green on every check that can run in a fork. Could a maintainer approve the pending |
|
Note: the remaining docker-CI redness (ecl.pyx # Killed due to abort on 3.14) is tracked upstream now — see issue #42680. It reproduces on branches that do not touch libs/ecl.pyx at all, so it is independent of this PR. |
vincentmacri
left a comment
There was a problem hiding this comment.
Suggestion to avoid the extra function calls.
| # This override is only there for the typing info: it exists so that | ||
| # static type checkers can infer the return type of ``GF``. The | ||
| # behavior is identical to the ``UniqueFactory`` base implementation. | ||
| def __call__(self, *args, **kwds) -> FiniteField: | ||
| """ | ||
| TESTS: | ||
|
|
||
| The return annotation matches the runtime type for every backend:: | ||
|
|
||
| sage: from sage.rings.finite_rings.finite_field_base import FiniteField | ||
| sage: all(isinstance(GF(2**8, 'a', implementation=impl), FiniteField) | ||
| ....: for impl in ('givaro', 'ntl', 'pari_ffelt')) | ||
| True | ||
| sage: isinstance(GF(29), FiniteField) | ||
| True | ||
| """ | ||
| return super().__call__(*args, **kwds) | ||
|
|
There was a problem hiding this comment.
| # This override is only there for the typing info: it exists so that | |
| # static type checkers can infer the return type of ``GF``. The | |
| # behavior is identical to the ``UniqueFactory`` base implementation. | |
| def __call__(self, *args, **kwds) -> FiniteField: | |
| """ | |
| TESTS: | |
| The return annotation matches the runtime type for every backend:: | |
| sage: from sage.rings.finite_rings.finite_field_base import FiniteField | |
| sage: all(isinstance(GF(2**8, 'a', implementation=impl), FiniteField) | |
| ....: for impl in ('givaro', 'ntl', 'pari_ffelt')) | |
| True | |
| sage: isinstance(GF(29), FiniteField) | |
| True | |
| """ | |
| return super().__call__(*args, **kwds) | |
| __call__: Callable[..., FiniteField] # So static type checkers can infer the return type of ``GF``. |
I think this works without having to potentially introduce more function call overhead? If this works, can you make the same change in the other file? You'll probably need to move the tests somewhere else (maybe the TESTS block of the class).
There was a problem hiding this comment.
Using generics would be another option, but I think that would likely be a much larger change than we want to deal with right now.
There was a problem hiding this comment.
Agreed. Increasing the number of function calls just to aid type inference is a bad deal: function calls incur a real, expensive penalty, as does the "super" lookup. It's not clear type inference in python has a real benefit. The python interpreter is certainly declared-type-agnostic.
There was a problem hiding this comment.
I think type inference has a real benefit for development and LSP projects (which have the potential to make writing Sage code easier for users), but I agree that we ought to find a way to do it without a performance penalty. While I can't measure a slowdown in this particular case, that's likely just because the slowdown is insignificant compared to the rest of the overhead of calling GF, but if we were to optimize the GF factory then this slowdown might start to be more apparent.
With the current state of the CPython interpreter, you are correct that there is no real runtime benefit (although I think some CPython devs have mused about potentially incorporating type hint information into a JIT compiler one day, we are a long way out from that being real).
Replace the forwarding __call__ overrides with bare class-level variable annotations: static type checkers still infer the factory return types, while factory calls keep dispatching directly to the inherited UniqueFactory.__call__ with no extra Python frame or super() lookup (review feedback). Move the regression doctests to class-level TESTS blocks and add a structural check that the __call__ annotation resolves to the declared return type. Import FiniteField under the alias FiniteField_base so that the annotation resolves to the class rather than to the factory instance once PEP 649 deferred annotations (Python 3.14) evaluate it through the live module namespace.
|
@vincentmacri @nbruin thanks — I've implemented exactly the inline suggestion: the forwarding # finite_field_constructor.py
__call__: Callable[..., FiniteField_base]
# integer_mod_ring.py
__call__: Callable[..., "IntegerModRing_generic | integer_ring.IntegerRing_class"]No runtime penalty anymore. The annotation assigns no value, so Tests moved to class-level @cxzhong's alias request is also in: Why we want this typing info at all — agreed that it is for the static-tooling layer, not the interpreter (which ignores declared types). It is the input contract of two downstream projects:
Verification: mypy and pyright — including 1.1.332, the exact version pinned in sage's The push regenerated the workflow runs, so they will need maintainer approval again to execute. Happy to adjust anything else. |
| # would add a Python frame and a ``super()`` lookup to every factory | ||
| # call. No value is assigned, so instances keep dispatching directly | ||
| # to the inherited ``UniqueFactory.__call__`` at full speed. | ||
| __call__: Callable[..., "IntegerModRing_generic | integer_ring.IntegerRing_class"] |
There was a problem hiding this comment.
| __call__: Callable[..., "IntegerModRing_generic | integer_ring.IntegerRing_class"] | |
| __call__: Callable[..., IntegerModRing_generic | integer_ring.IntegerRing_class] |
I think some combination of from __future__ import annotations and placing some imports in an if TYPE_CHECKING block should allow you to remove these quotes, which I think helps with readability (I'm actually surprised the linter allowed this through, I thought UP037 enforced this). If there is something weird about Callable and you can't get it working without the string, no worries.
|
One more small request (although perhaps you should let the CI runs finish before making a new commit). Otherwise LGTM! |
Use from __future__ import annotations so the unquoted forward reference to IntegerModRing_generic (defined later in this module) is safe at runtime, and resolve the annotation via typing.get_type_hints in the doctest (review feedback from vincentmacri). Keep the collections.abc.Callable import at runtime visibility: get_type_hints - used by the doctest contract and by downstream stub generators - evaluates the annotation string in the module namespace, so the name must exist there. Exempt that import from TC003 via per-file-ignores with a comment.
|
@vincentmacri thanks — done in One deliberate deviation from the suggested combination, with the reason: This is the last planned commit — I won't push again unless review asks for something. CI: the seven workflow runs generated for this head are already sitting in
@sagemath/core — could someone approve these runs (or let me know if fork-based PRs can't be approved and I should move the branch into the main repo)? In the meantime the identical pull_request suite runs automatically on the same head in my fork with no approval gate — starnotes-xj/sage#1 — currently in progress for @vincentmacri @nbruin — happy to address anything else. |
| "src/sage/rings/finite_rings/integer_mod_ring.py" = [ | ||
| # Callable must stay a runtime import (outside TYPE_CHECKING): the | ||
| # class-level __call__ annotation is resolved by typing.get_type_hints | ||
| # in the doctests and by downstream stub generators, so the name has | ||
| # to be present in the module namespace at runtime. | ||
| "TC003", | ||
| ] |
There was a problem hiding this comment.
I'd prefer for this to be a local noqa or ruff:ignore comment in src/sage/rings/finite_rings/integer_mod_ring.py than added to pyproject.toml.
Per review, keep the ruff exemption next to the import itself instead of a per-file-ignores entry in pyproject.toml: the runtime visibility of Callable is intentional (typing.get_type_hints resolves the class-level __call__ annotation in the module namespace).
|
@vincentmacri done — the ruff passes in both This push (review-requested) regenerated the workflow runs, so they will again need a maintainer approval to execute — the approval links in my previous comment point to the now-outdated run set, but the same seven workflows are available for the current head on the Actions tab. The fork CI (starnotes-xj/sage#1) reruns automatically on the same head with no approval gate. |
|
LGTM. I am okay with approving after the CI finishes on your fork. |
|
@vincentmacri — thanks for the LGTM. On the fork CI for the current head (
So the red lane is exactly the code-infrastructure issue: once the doc-baseline download works for fork CI (or that lane runs in the main repo where the artifact exists), this PR's CI is fully green — no failure is attributable to the changed code ( Meanwhile the main-repo workflow runs for this head are still sitting in |
|
@vincentmacri — the evidence that the only red lanes are code-infrastructure issues (not this PR) is in the earlier comments on this thread; pointing at them here for a quick look:
So the only thing between this PR and fully green CI is that fork-side doc-baseline download. Once that infrastructure piece works for forks (or that lane runs in the main repo, where the artifact exists), the PR passes entirely — no failure is attributable to the two changed ring modules ( |
|
Download old doc will work after it runs in your develop, so probably next time you merge upstream develop into your fork it will work after that. So that's fine. Thank you for the contribution! |
|
@vincentmacri — the fork CI for
The two failing 3.14 jobs fail with the same single doctest, in code this PR does not touch: So both remaining red lanes are upstream issues unrelated to the two ring modules this PR changes:
Nothing further is needed from the code side. Thanks again for the review! |
|
Documentation preview for this PR (built with commit 4e2fa5a; changes) is ready! 🎉 |
FiniteField.from_integer, gen, multiplicative_generator and random_element all return finite field elements. Add `-> FinitePolyExtElement` return annotations so static type checkers can follow the element type after `F = GF(2^8, 'a')`, complementing the factory return annotations of sagemath#42670. FinitePolyExtElement is the common base of the three concrete element classes (verified against Sage 10.9 for every backend): - FiniteField_givaroElement (implementation='givaro') - FiniteField_ntl_gf2eElement (implementation='ntl') - FiniteFieldElement_pari_ffelt (implementation='pari_ffelt') Cython 3 retains annotations of def methods of cdef classes (e.g. `_latex_` already carries `-> str` in this file), and the added TESTS block verifies the runtime contract on all backends.
…uotientRing
Static type checkers cannot infer the return type of these module-level
constructor functions. Add return annotations using the common base of
the concrete implementations (verified against Sage 10.9):
- PowerSeriesRing -> PowerSeriesRing_generic (covers PowerSeriesRing_domain,
PowerSeriesRing_over_field and MPowerSeriesRing_generic)
- LaurentPolynomialRing -> LaurentPolynomialRing_generic (covers the
univariate and multivariate implementations)
- QuotientRing -> QuotientRing_generic (covers the generic and
polynomial quotient implementations)
TESTS blocks assert the annotation against the runtime type for the
common univariate and multivariate cases. Follow-up to sagemath#42670.
sagemathgh-42672: Annotate element-returning methods of FiniteField (follow-up to sagemath#42670) Follow-up to sagemath#42670: the factory return annotations let static type checkers infer the field type, but the chain breaks on the next step because several element-returning methods of `FiniteField` have no return annotation. This PR adds `-> FiniteRingElement` to `from_integer`, `gen`, `multiplicative_generator` and `random_element` in `finite_field_base.pyx`. `FiniteField` serves both extension fields and prime fields: extension- field implementations return `FinitePolyExtElement` subclasses, while prime fields return `IntegerMod` elements. `FiniteRingElement` is the common base of both families, so it is the sound return type for the shared base-class methods. The `TESTS` block checks the runtime contract for both `GF(29)` and `GF(2^8, 'a')`, and verifies the exposed annotation. These are annotations only; factory and field behavior is unchanged. URL: sagemath#42672 Reported by: 星记 Reviewer(s): Copilot
sagemathgh-42675: Annotate return types of PowerSeriesRing, LaurentPolynomialRing and QuotientRing (follow-up to sagemath#42670) Follow-up to sagemath#42670: this PR annotates three constructor functions whose return types static type checkers cannot infer. - `PowerSeriesRing` returns `PowerSeriesRing_generic`, the common base of its univariate and multivariate implementations. - `LaurentPolynomialRing` returns `LaurentPolynomialRing_generic`, the common base of its univariate and multivariate implementations. - `QuotientRing` returns `Parent`: unlike the narrower generic quotient class, this accurately covers all supported branches, including ordinary and principal quotients, noncommutative quotients, Boolean-polynomial implementations, integer quotients and the zero-ideal path that returns the original parent. Forward references are quoted locally where the implementation class is defined later in the module, avoiding import-time `NameError` without changing annotation evaluation semantics for unrelated functions. Regression doctests cover representative runtime branches and `typing.get_type_hints` resolution. No runtime behavior changes; these are annotations only. URL: sagemath#42675 Reported by: 星记 Reviewer(s): Copilot
Static type checkers (Pyright, mypy, PyCharm) cannot infer the return type
of
GF,Zmod,IntegersandIntegerModRingbecause these are instancesof
UniqueFactorysubclasses whose Cython__call__carries noannotation. Downstream tooling currently compensates by probing the factory
at runtime (e.g. the
sage-pycharm-stubgen
engine infers and ships these types for the IDE); annotating the factories
upstream makes the same information available to every tool.
This PR adds an annotated, purely forwarding
__call__override to the twofactory classes:
FiniteFieldFactory.__call__returnsFiniteField(the common importablebase of
FiniteField_prime_modn,FiniteField_givaro,FiniteField_ntl_gf2e,FiniteField_pari_ffelt);IntegerModFactory.__call__returnsIntegerModRing_generic | IntegerRing_class, becauseIntegers(0)returnsZZ.Both signatures were verified against Sage 10.9 at runtime:
inspect.signaturenow reports the annotations,import sage.allisunaffected (no import cycles), the doctests of both modules pass, and the
factory behavior is unchanged for
GF(29),GF(2^8, 'a'),Zmod(17)andIntegers(0).The remaining ring factories from the runtime probe (58 in total, e.g.
RealField,ComplexField,NumberField, ...) can be annotated infollow-up PRs.
🤖 Generated with Claude Code