Skip to content

Add a return-type stub for the univariate Polynomial base class - #43001

Merged
vbraun merged 2 commits into
sagemath:developfrom
starnotes-xj:polynomial-element-pyi-stub
Oct 22, 2026
Merged

vbraun merged 2 commits into
sagemath:developfrom
starnotes-xj:polynomial-element-pyi-stub

Conversation

@starnotes-xj

Copy link
Copy Markdown
Contributor

Motivation

polynomial_element.pyx (the univariate Polynomial base class behind every R = QQ['x']; R.gen() + 1 expression) is a Cython module with no stub, so static checkers infer Unknown for all univariate polynomial code. This adds a return-type stub following the pattern of #42672 / #42999 / #43000.

Changes

src/sage/rings/polynomial/polynomial_element.pyi (new): 72 accessors of Polynomial(CommutativePolynomial), return types verified against the live runtime (Sage 10.9, Python 3.13):

  • the algebra family — monic, lcm, nth_root, integral, homogenize, gradient-related forms, compose_power/compose_trunc/composed_op, the truncation family (multiplication_trunc, power_trunc, revert_series), reciprocal_transform, radical, cyclotomic_part, symmetric_power, adams_operator_on_roots, base_extend, change_variable_name, map_coefficients, numerator, denominator, lm/lt/square/polynomial — → Polynomial
  • degree, dispersion, euclidean_degree → Integer; number_of_real_roots, number_of_roots_in_interval → int
  • factor → Factorization; the is_* predicates → bool; exponents → list[int]; variable_name → str
  • element-type-varying containers stay honestly generic: roots/real_roots/complex_roots/coefficients/monomials/gradient/subresultants/newton_slopes/dispersion_set/padded_list/newton_raphson → list[Any]; variables/args/canonical_associate/pseudo_quo_rem/rational_reconstruction/trace_polynomial → tuple[Any, ...]; monomial_coefficients → dict[int, Any]
  • is_weil_polynomial as a Literal overload: return_q=False → bool, return_q=True → tuple[bool, Any] (the q element type varies with the base ring; verified (True, q) at runtime)
  • quo_rem declared tuple[Any, Any] on the base (implemented by all concrete subclasses with the same signature; the base itself raises)

Builtin names shadowed by same-named methods (list, dict — the class defines .list() and .dict()) are qualified builtins.*, otherwise checkers resolve the annotation to the method symbol.

src/sage/rings/polynomial/meson.build: registers the stub. src/sage/tests/type_checking/polynomial_returns.py: checker-only probe, 32 assert_type assertions (receiver pinned to the declared base type), all runtime-valid.

Verification

Every accessor executed on QQ['x'] elements with runtime types recorded; flag branches probed in both directions; the probe executes cleanly under the doctest loader; ty and ruff clean with source-tree resolution matching the CI Type check job.

polynomial_element.pyx is invisible to static checkers, so every
univariate polynomial expression infers as Unknown. This adds
polynomial_element.pyi declaring 72 accessors of the Polynomial base
class with return types verified against the live runtime (Sage 10.9):
the algebra family (monic/lcm/nth_root/integral/homogenize/compositions/
truncations) -> Polynomial, degree/dispersion/euclidean_degree ->
Integer, factor -> Factorization, the is_* predicates -> bool,
exponents -> list[int], variable_name -> str, roots/real_roots/
complex_roots/gradient/monomials/subresultants/newton_slopes ->
list[Any] (element types vary with the base ring), quo_rem/xgcd as
tuples, and is_weil_polynomial as a Literal overload (return_q=True
returns (bool, q)). quo_rem is declared on the base although only the
concrete subclasses implement it (verified identical signature).

Builtin names shadowed by same-named methods (list, dict) are qualified
builtins.*. Registered in meson.build; adds a checker-only probe with
32 assertions.
Copilot AI balanced review requested due to automatic review settings October 17, 2026 04:13

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown

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

@starnotes-xj

Copy link
Copy Markdown
Contributor Author

The failing jobs here are infrastructure flakes, not diff-related: the distro builds (archlinux/debian/darwin/macos) die in the cypari2 package build (external packaging breakage affecting many PRs today); the conda test-job failures are a maxima pexpect timeout (#42999), a matrix_integer_dense.pyx slow-runner timeout (#43001, same flake as #42988), and a darwin cysignals sigdie during unrelated doctests (#43002). Retriggering those jobs should suffice.

vbraun pushed a commit to vbraun/sage that referenced this pull request Oct 18, 2026
Release Manager
sagemathgh-43001: Add a return-type stub for the univariate Polynomial base class
    
## Motivation

`polynomial_element.pyx` (the univariate `Polynomial` base class behind
every `R = QQ['x']; R.gen() + 1` expression) is a Cython module with no
stub, so static checkers infer `Unknown` for all univariate polynomial
code. This adds a return-type stub following the pattern of sagemath#42672 /
sagemath#42999 / sagemath#43000.

## Changes

**`src/sage/rings/polynomial/polynomial_element.pyi`** (new): 72
accessors of `Polynomial(CommutativePolynomial)`, return types verified
against the live runtime (Sage 10.9, Python 3.13):

- the algebra family — `monic`, `lcm`, `nth_root`, `integral`,
`homogenize`, `gradient`-related forms,
`compose_power`/`compose_trunc`/`composed_op`, the truncation family
(`multiplication_trunc`, `power_trunc`, `revert_series`),
`reciprocal_transform`, `radical`, `cyclotomic_part`, `symmetric_power`,
`adams_operator_on_roots`, `base_extend`, `change_variable_name`,
`map_coefficients`, `numerator`, `denominator`,
`lm`/`lt`/`square`/`polynomial` — → `Polynomial`
- `degree`, `dispersion`, `euclidean_degree` → `Integer`;
`number_of_real_roots`, `number_of_roots_in_interval` → `int`
- `factor` → `Factorization`; the `is_*` predicates → `bool`;
`exponents` → `list[int]`; `variable_name` → `str`
- element-type-varying containers stay honestly generic: `roots`/`real_r
oots`/`complex_roots`/`coefficients`/`monomials`/`gradient`/`subresultan
ts`/`newton_slopes`/`dispersion_set`/`padded_list`/`newton_raphson` →
`list[Any]`; `variables`/`args`/`canonical_associate`/`pseudo_quo_rem`/`
rational_reconstruction`/`trace_polynomial` → `tuple[Any, ...]`;
`monomial_coefficients` → `dict[int, Any]`
- `is_weil_polynomial` as a `Literal` overload: `return_q=False` →
`bool`, `return_q=True` → `tuple[bool, Any]` (the `q` element type
varies with the base ring; verified `(True, q)` at runtime)
- `quo_rem` declared `tuple[Any, Any]` on the base (implemented by all
concrete subclasses with the same signature; the base itself raises)

Builtin names shadowed by same-named methods (`list`, `dict` — the class
defines `.list()` and `.dict()`) are qualified `builtins.*`, otherwise
checkers resolve the annotation to the method symbol.

**`src/sage/rings/polynomial/meson.build`**: registers the stub.
**`src/sage/tests/type_checking/polynomial_returns.py`**: checker-only
probe, 32 `assert_type` assertions (receiver pinned to the declared base
type), all runtime-valid.

## Verification

Every accessor executed on `QQ['x']` elements with runtime types
recorded; flag branches probed in both directions; the probe executes
cleanly under the doctest loader; `ty` and ruff clean with source-tree
resolution matching the CI Type check job.
    
URL: sagemath#43001
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit to vbraun/sage that referenced this pull request Oct 18, 2026
Release Manager
sagemathgh-43002: Add a return-type stub for free module (vector) elements
    
## Motivation

`free_module_element.pyx` (the `FreeModuleElement` base class behind
every Sage vector) is a Cython module with no stub, so static checkers
infer `Unknown` for all vector code — including the ubiquitous module-
level `vector()` factory. This adds a return-type stub following sagemath#42672
/ sagemath#42999 / sagemath#43000 / sagemath#43001.

## Changes

**`src/sage/modules/free_module_element.pyi`** (new): 38 accessors of
`FreeModuleElement(Vector)` plus `def vector(...) -> FreeModuleElement`,
return types verified against the live runtime (Sage 10.9, Python 3.13):

- the vector-algebra family — `change_ring`, `apply_map`, `concatenate`,
`conjugate`, `pairwise_product`, `cross_product`,
`dense_vector`/`sparse_vector`, `derivative`, `integral`, `lift`,
`lift_centered`, `normalized`, `subs`, `Mod`, `compositional_inverse`,
`element` — → `FreeModuleElement`
- `column`, `row`, `outer_product`, `cross_product_matrix` → `Matrix`
(imported from `sage.matrix.matrix0`)
- `additive_order`, `denominator` → `Integer`; `degree` → `int`;
`coordinate_ring` → `Ring`
- containers: `dict`/`monomial_coefficients` → `dict[int, Any]`, `items`
→ `Iterator[tuple[int, Any]]`, `list`/`list_from_positions` →
`list[Any]`, `support`/`nonzero_positions` → `list[int]`
- `numpy(dtype)` → `ndarray`; the `set` mutator → `None`

Builtin names shadowed by same-named methods (`list`, `dict`, `set`) are
qualified `builtins.*` (checkers otherwise resolve the annotation to the
class's method symbol).

**`src/sage/modules/meson.build`**: registers the stub.
**`src/sage/tests/type_checking/vector_returns.py`**: checker-only
probe, 21 `assert_type` assertions (receiver pinned to the declared base
type), all runtime-valid.

## Verification

Every accessor executed on `vector(QQ, [1, 2])` with runtime types
recorded; the probe executes cleanly under the doctest loader; `ty` and
ruff clean with source-tree resolution matching the CI Type check job.
    
URL: sagemath#43002
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit to vbraun/sage that referenced this pull request Oct 18, 2026
Release Manager
sagemathgh-43004: Add return-type stubs for the Matrix class family and the matrix factory
    
## Motivation

The `Matrix` hierarchy lives in three Cython modules that each define a
class **named `Matrix`** extending the previous one (`matrix0.pyx` →
`matrix1.pyx` → `matrix2.pyx`; the MRO of any concrete matrix shows all
three), plus the `matrix()` factory in `constructor.pyx`. None of it is
visible to static checkers, so every matrix expression in Sage infers as
`Unknown`. This adds stubs for the whole family, following sagemath#42672 /
sagemath#42999 / sagemath#43000 / sagemath#43001 / sagemath#43002.

## Changes

- **`src/sage/matrix/matrix0.pyi`** (new): `Matrix` with its 39
accessors — `rank`/`nullity`/`multiplicative_order` → `Integer`, `ncols`
→ `int`, `dimensions` → `tuple[int, int]`, `pivots`/`nonpivots` →
`tuple[int, ...]`, `dict` → `dict[tuple[int, int], Any]`,
`nonzero_positions*` → `list[...]`, `str` → `str`, `kernel` →
`FreeModule_generic`, the `with_*` copy family → `Matrix`, and the in-
place mutator family (`add_to_entry`, `permute_*`, `swap_*`,
`rescale_*`, `set_*`, `mutate`, `set_immutable`) → `None`.
- **`src/sage/matrix/matrix1.pyi`** (new): the second `Matrix` extending
matrix0's, with 25 accessors — `column` → `FreeModuleElement`
(resolvable via sagemath#43002), `columns`/`rows` → `list[FreeModuleElement]`, `
augment`/`stack`/`submatrix`/`delete_*`/`matrix_from_*`/`lift*`/`dense_m
atrix`/`sparse_matrix` → `Matrix`, `set_column`/`set_row` → `None`.
- **`src/sage/matrix/matrix2.pyi`** (new): the third `Matrix` extending
matrix1's, with 68 accessors —
`charpoly`/`minpoly`/`characteristic_polynomial`/`minimal_polynomial` →
`Polynomial` (resolvable via sagemath#43001), `denominator`/`permanent`/`permane
ntal_minor`/`prod_of_row_sums`/`get_bandwidth` → `Integer`,
`left/right_nullity`/`eigenvalue_multiplicity`/`hadamard_bound` → `int`,
`eigenmatrix_left`/`eigenmatrix_right` → `tuple[Matrix, Matrix]`,
`left/right_kernel` + `row/column_space` → `FreeModule_generic`,
`solve_right` → `FreeModuleElement | Matrix`, `is_permutation_of` →
`bool | tuple[bool, Any]`, `subdivisions` → `tuple[list[int],
list[int]]`, factorization/decomposition families → generic tuples,
`echelonize`/`hessenbergize`/`randomize`/`set_block`/`subdivide` →
`None`, the rest → `Matrix`.
- **`src/sage/matrix/constructor.pyi`** (new): `def matrix(*args,
**kwds) -> Matrix` — the most ubiquitous constructor in Sage now
resolves for checkers to the most complete declared base.
- All four stubs registered in **`meson.build`**;
**`src/sage/tests/type_checking/matrix_returns.py`**: checker-only probe
with 30 `assert_type` assertions covering all three levels, runtime-
valid (executed under the doctest loader).

Builtin names shadowed by same-named methods (`list`, `str`, `dict`) are
qualified `builtins.*` (checkers otherwise resolve the annotation to the
method symbol).

## Verification

Return types verified entry-by-entry against the live runtime (Sage
10.9); signatures extracted via `sage_getargspec`; the probe executes
cleanly (nonsingular receiver for `inverse`/`solve_right`); `ty` and
ruff clean with source-tree resolution matching the CI Type check job.
Note: `matrix()` returns concrete subclasses (`Matrix_rational_dense`,
...) which remain unstubbbed — the declared base is the honest common
bound.
    
URL: sagemath#43004
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit to vbraun/sage that referenced this pull request Oct 18, 2026
Release Manager
sagemathgh-43006: Extend the finite field stubs: element_base, finite_field_base and four new element stubs
    
## Motivation

sagemath#42672 introduced `element_base.pyi` + `finite_field_base.pyi` as a
minimal skeleton (four `FiniteField` accessors typed as the
`FiniteRingElement` base). This extends the pair with the full high-use
surface and adds the four missing element-class stubs, so `GF`
extension-field elements and `Zmod` elements stop inferring as
`Unknown`. Follows sagemath#42999 / sagemath#43000 / sagemath#43001 / sagemath#43002 / sagemath#43004.

## Changes

- **`element_base.pyi`** (extended):
`FiniteRingElement.canonical_associate` → `tuple[Any, ...]`, `to_bytes`
→ `bytes`; `FinitePolyExtElement.additive_order`/`multiplicative_order`
→ `Integer`, `minimal_polynomial`/`minpoly` → `Polynomial`, `is_square`
→ `bool`, `to_integer` → `int`.
- **`finite_field_base.pyi`** (extended): 19 new `FiniteField` accessors
— `cardinality`/`characteristic`/`degree`/`order`/`absolute_degree`/`uni
t_group_exponent`/`zeta_order` → `Integer`, `ngens` → `int`,
`is_conway`/`is_finite`/`is_prime_field` → `bool`,
`modulus`/`polynomial` → `Polynomial`,
`dual_basis`/`embeddings`/`some_elements`/`subfields` → `list`,
`construction`/`factored_unit_order` → `tuple`. (`characteristic`,
`degree`, `is_finite`, `zeta_order` arrive through the category
framework at runtime — declared here with their verified no-argument
shapes.) The four accessors already declared in sagemath#42672 (`gen`,
`from_integer`, `multiplicative_generator`, `random_element`) keep their
existing `FiniteRingElement` returns so the `finite_fields.py` probe
continues to hold.
- **`element_givaro.pyi`**, **`element_ntl_gf2e.pyi`**,
**`element_pari_ffelt.pyi`** (new): the concrete extension-field element
classes — `sqrt` → self class, `log`/`multiplicative_order` → `Integer`,
`polynomial`/`charpoly`/`minpoly` → `Polynomial`, `weight` → `int`,
`lift` → `Integer`, `is_one`/`is_square`/`is_unit` → `bool`.
- **`integer_mod.pyi`** (new): `IntegerMod_abstract` with 15 accessors
(`lift_centered`/`log`/`modulus`/`multiplicative_order`/`additive_order`
→ `Integer`, `charpoly`/`minpoly`/`minimal_polynomial`/`polynomial` →
`Polynomial`, `rational_reconstruction` → `Rational`, `crt` →
`IntegerMod_abstract`, `generalised_log` → `list[Integer | int]`,
predicates → `bool`), `IntegerMod_gmp.lift`, an `IntegerMod_int`
placeholder, and the module-level `Mod()` / `square_root_mod_prime()`
factories → `IntegerMod_abstract`.
- All four new stubs registered in **`meson.build`**;
**`src/sage/tests/type_checking/finite_ring_returns.py`**: checker-only
probe, 32 runtime-valid `assert_type` assertions.

## Verification

Return types verified entry-by-entry against the live runtime (Sage
10.9: `GF(3^3, 'a')` for extension elements, `GF(11)` for `Zmod`);
signatures extracted via `sage_getargspec`; the probe executes cleanly
under the doctest loader; `ty` and ruff clean with source-tree
resolution matching the CI Type check job.
    
URL: sagemath#43006
Reported by: 星记
Reviewer(s): Copilot
@vbraun
vbraun merged commit 73b2fef into sagemath:develop Oct 22, 2026
28 of 33 checks passed
vbraun pushed a commit that referenced this pull request Oct 22, 2026
Release Manager
gh-43002: Add a return-type stub for free module (vector) elements
    
## Motivation

`free_module_element.pyx` (the `FreeModuleElement` base class behind
every Sage vector) is a Cython module with no stub, so static checkers
infer `Unknown` for all vector code — including the ubiquitous module-
level `vector()` factory. This adds a return-type stub following #42672
/ #42999 / #43000 / #43001.

## Changes

**`src/sage/modules/free_module_element.pyi`** (new): 38 accessors of
`FreeModuleElement(Vector)` plus `def vector(...) -> FreeModuleElement`,
return types verified against the live runtime (Sage 10.9, Python 3.13):

- the vector-algebra family — `change_ring`, `apply_map`, `concatenate`,
`conjugate`, `pairwise_product`, `cross_product`,
`dense_vector`/`sparse_vector`, `derivative`, `integral`, `lift`,
`lift_centered`, `normalized`, `subs`, `Mod`, `compositional_inverse`,
`element` — → `FreeModuleElement`
- `column`, `row`, `outer_product`, `cross_product_matrix` → `Matrix`
(imported from `sage.matrix.matrix0`)
- `additive_order`, `denominator` → `Integer`; `degree` → `int`;
`coordinate_ring` → `Ring`
- containers: `dict`/`monomial_coefficients` → `dict[int, Any]`, `items`
→ `Iterator[tuple[int, Any]]`, `list`/`list_from_positions` →
`list[Any]`, `support`/`nonzero_positions` → `list[int]`
- `numpy(dtype)` → `ndarray`; the `set` mutator → `None`

Builtin names shadowed by same-named methods (`list`, `dict`, `set`) are
qualified `builtins.*` (checkers otherwise resolve the annotation to the
class's method symbol).

**`src/sage/modules/meson.build`**: registers the stub.
**`src/sage/tests/type_checking/vector_returns.py`**: checker-only
probe, 21 `assert_type` assertions (receiver pinned to the declared base
type), all runtime-valid.

## Verification

Every accessor executed on `vector(QQ, [1, 2])` with runtime types
recorded; the probe executes cleanly under the doctest loader; `ty` and
ruff clean with source-tree resolution matching the CI Type check job.
    
URL: #43002
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit that referenced this pull request Oct 22, 2026
Release Manager
gh-43004: Add return-type stubs for the Matrix class family and the matrix factory
    
## Motivation

The `Matrix` hierarchy lives in three Cython modules that each define a
class **named `Matrix`** extending the previous one (`matrix0.pyx` →
`matrix1.pyx` → `matrix2.pyx`; the MRO of any concrete matrix shows all
three), plus the `matrix()` factory in `constructor.pyx`. None of it is
visible to static checkers, so every matrix expression in Sage infers as
`Unknown`. This adds stubs for the whole family, following #42672 /
#42999 / #43000 / #43001 / #43002.

## Changes

- **`src/sage/matrix/matrix0.pyi`** (new): `Matrix` with its 39
accessors — `rank`/`nullity`/`multiplicative_order` → `Integer`, `ncols`
→ `int`, `dimensions` → `tuple[int, int]`, `pivots`/`nonpivots` →
`tuple[int, ...]`, `dict` → `dict[tuple[int, int], Any]`,
`nonzero_positions*` → `list[...]`, `str` → `str`, `kernel` →
`FreeModule_generic`, the `with_*` copy family → `Matrix`, and the in-
place mutator family (`add_to_entry`, `permute_*`, `swap_*`,
`rescale_*`, `set_*`, `mutate`, `set_immutable`) → `None`.
- **`src/sage/matrix/matrix1.pyi`** (new): the second `Matrix` extending
matrix0's, with 25 accessors — `column` → `FreeModuleElement`
(resolvable via #43002), `columns`/`rows` → `list[FreeModuleElement]`, `
augment`/`stack`/`submatrix`/`delete_*`/`matrix_from_*`/`lift*`/`dense_m
atrix`/`sparse_matrix` → `Matrix`, `set_column`/`set_row` → `None`.
- **`src/sage/matrix/matrix2.pyi`** (new): the third `Matrix` extending
matrix1's, with 68 accessors —
`charpoly`/`minpoly`/`characteristic_polynomial`/`minimal_polynomial` →
`Polynomial` (resolvable via #43001), `denominator`/`permanent`/`permane
ntal_minor`/`prod_of_row_sums`/`get_bandwidth` → `Integer`,
`left/right_nullity`/`eigenvalue_multiplicity`/`hadamard_bound` → `int`,
`eigenmatrix_left`/`eigenmatrix_right` → `tuple[Matrix, Matrix]`,
`left/right_kernel` + `row/column_space` → `FreeModule_generic`,
`solve_right` → `FreeModuleElement | Matrix`, `is_permutation_of` →
`bool | tuple[bool, Any]`, `subdivisions` → `tuple[list[int],
list[int]]`, factorization/decomposition families → generic tuples,
`echelonize`/`hessenbergize`/`randomize`/`set_block`/`subdivide` →
`None`, the rest → `Matrix`.
- **`src/sage/matrix/constructor.pyi`** (new): `def matrix(*args,
**kwds) -> Matrix` — the most ubiquitous constructor in Sage now
resolves for checkers to the most complete declared base.
- All four stubs registered in **`meson.build`**;
**`src/sage/tests/type_checking/matrix_returns.py`**: checker-only probe
with 30 `assert_type` assertions covering all three levels, runtime-
valid (executed under the doctest loader).

Builtin names shadowed by same-named methods (`list`, `str`, `dict`) are
qualified `builtins.*` (checkers otherwise resolve the annotation to the
method symbol).

## Verification

Return types verified entry-by-entry against the live runtime (Sage
10.9); signatures extracted via `sage_getargspec`; the probe executes
cleanly (nonsingular receiver for `inverse`/`solve_right`); `ty` and
ruff clean with source-tree resolution matching the CI Type check job.
Note: `matrix()` returns concrete subclasses (`Matrix_rational_dense`,
...) which remain unstubbbed — the declared base is the honest common
bound.
    
URL: #43004
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit that referenced this pull request Oct 22, 2026
Release Manager
gh-43006: Extend the finite field stubs: element_base, finite_field_base and four new element stubs
    
## Motivation

#42672 introduced `element_base.pyi` + `finite_field_base.pyi` as a
minimal skeleton (four `FiniteField` accessors typed as the
`FiniteRingElement` base). This extends the pair with the full high-use
surface and adds the four missing element-class stubs, so `GF`
extension-field elements and `Zmod` elements stop inferring as
`Unknown`. Follows #42999 / #43000 / #43001 / #43002 / #43004.

## Changes

- **`element_base.pyi`** (extended):
`FiniteRingElement.canonical_associate` → `tuple[Any, ...]`, `to_bytes`
→ `bytes`; `FinitePolyExtElement.additive_order`/`multiplicative_order`
→ `Integer`, `minimal_polynomial`/`minpoly` → `Polynomial`, `is_square`
→ `bool`, `to_integer` → `int`.
- **`finite_field_base.pyi`** (extended): 19 new `FiniteField` accessors
— `cardinality`/`characteristic`/`degree`/`order`/`absolute_degree`/`uni
t_group_exponent`/`zeta_order` → `Integer`, `ngens` → `int`,
`is_conway`/`is_finite`/`is_prime_field` → `bool`,
`modulus`/`polynomial` → `Polynomial`,
`dual_basis`/`embeddings`/`some_elements`/`subfields` → `list`,
`construction`/`factored_unit_order` → `tuple`. (`characteristic`,
`degree`, `is_finite`, `zeta_order` arrive through the category
framework at runtime — declared here with their verified no-argument
shapes.) The four accessors already declared in #42672 (`gen`,
`from_integer`, `multiplicative_generator`, `random_element`) keep their
existing `FiniteRingElement` returns so the `finite_fields.py` probe
continues to hold.
- **`element_givaro.pyi`**, **`element_ntl_gf2e.pyi`**,
**`element_pari_ffelt.pyi`** (new): the concrete extension-field element
classes — `sqrt` → self class, `log`/`multiplicative_order` → `Integer`,
`polynomial`/`charpoly`/`minpoly` → `Polynomial`, `weight` → `int`,
`lift` → `Integer`, `is_one`/`is_square`/`is_unit` → `bool`.
- **`integer_mod.pyi`** (new): `IntegerMod_abstract` with 15 accessors
(`lift_centered`/`log`/`modulus`/`multiplicative_order`/`additive_order`
→ `Integer`, `charpoly`/`minpoly`/`minimal_polynomial`/`polynomial` →
`Polynomial`, `rational_reconstruction` → `Rational`, `crt` →
`IntegerMod_abstract`, `generalised_log` → `list[Integer | int]`,
predicates → `bool`), `IntegerMod_gmp.lift`, an `IntegerMod_int`
placeholder, and the module-level `Mod()` / `square_root_mod_prime()`
factories → `IntegerMod_abstract`.
- All four new stubs registered in **`meson.build`**;
**`src/sage/tests/type_checking/finite_ring_returns.py`**: checker-only
probe, 32 runtime-valid `assert_type` assertions.

## Verification

Return types verified entry-by-entry against the live runtime (Sage
10.9: `GF(3^3, 'a')` for extension elements, `GF(11)` for `Zmod`);
signatures extracted via `sage_getargspec`; the probe executes cleanly
under the doctest loader; `ty` and ruff clean with source-tree
resolution matching the CI Type check job.
    
URL: #43006
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit to vbraun/sage that referenced this pull request Oct 27, 2026
Release Manager
sagemathgh-43007: Add structure-cluster stubs (CategoryObject, Parent, ParentWithGens) and two matrix completions
    
## Motivation

`sage.structure`'s base classes (`CategoryObject`, `Parent`,
`ParentWithGens`) are Cython with no stubs, so the naming/generator
introspection surface shared by every Sage object — `variable_name()`,
`gens()`, `ngens()`, `base_ring()` — infers as `Unknown`. This adds
those stubs, two small completions of the matrix family from sagemath#43004, and
two stub fixes found by runtime probing. Follows sagemath#42672 / sagemath#42999 /
sagemath#43000 / sagemath#43001 / sagemath#43002 / sagemath#43004 / sagemath#43006.

## Changes

- **`src/sage/structure/category_object.pyi`** (new):
`CategoryObject(SageObject)` — `base_ring` → `Ring`,
`variable_name`/`latex_name` → `str`, `variable_names` → `tuple[str,
...]`, `latex_variable_names` → `list[str]`,
`gens_dict`/`gens_dict_recursive` → `dict[str, Any]`, `objgen`/`objgens`
→ `tuple[Any, Any]`, `categories` → `list[Any]`, `inject_variables` →
`None`, `_first_ngens`.
- **`src/sage/structure/parent.pyi`** (new): `Parent(CategoryObject)` —
`element_class: type` (a `lazy_attribute` at runtime) and the `register_
action`/`register_coercion`/`register_conversion`/`register_embedding`
mutators → `None`.
- **`src/sage/structure/parent_gens.pyi`** (new):
`ParentWithGens(CategoryObject)` — `gens` → `tuple[Any, ...]`, `ngens` →
`int`.
- **`src/sage/matrix/matrix_dense.pyi`**, **`matrix_integer_dense.pyi`**
(new): `Matrix_dense(Matrix).transpose → Matrix_dense` and
`Matrix_integer_dense(Matrix_dense).LLL → Matrix_integer_dense`,
completing the matrix family of sagemath#43004.
- **`src/sage/rings/fast_arith.pyi`** (fix): `prime_range` was declared
`-> list[int]`, which is wrong for the default path — at runtime
`prime_range(10)` yields `Integer`s and only `py_ints=True` yields
`int`s. Now two `Literal` overloads matching the verified behavior.
- **`src/sage/rings/integer_ring.pyi`**: adds module-level `crt_basis(X)
-> list[Integer]` (verified: returns a list of `Integer`s).
- Five new stubs registered in **`meson.build`**;
**`src/sage/tests/type_checking/structure_returns.py`**: checker-only
probe (receivers pinned with `typing.cast`, since `ty` keeps the
narrower inferred initializer type over a variable annotation).

## Verification

Return types verified entry-by-entry against the live runtime (Sage
10.9); the `register_*` mutators are annotated but not probe-called
(registration is only legal on fresh parents); the probe executes
cleanly under the doctest loader; `ty` and ruff clean with source-tree
resolution matching the CI Type check job.
    
URL: sagemath#43007
Reported by: 星记
Reviewer(s): Copilot
vbraun pushed a commit to vbraun/sage that referenced this pull request Oct 28, 2026
Release Manager
sagemathgh-43007: Add structure-cluster stubs (CategoryObject, Parent, ParentWithGens) and two matrix completions
    
## Motivation

`sage.structure`'s base classes (`CategoryObject`, `Parent`,
`ParentWithGens`) are Cython with no stubs, so the naming/generator
introspection surface shared by every Sage object — `variable_name()`,
`gens()`, `ngens()`, `base_ring()` — infers as `Unknown`. This adds
those stubs, two small completions of the matrix family from sagemath#43004, and
two stub fixes found by runtime probing. Follows sagemath#42672 / sagemath#42999 /
sagemath#43000 / sagemath#43001 / sagemath#43002 / sagemath#43004 / sagemath#43006.

## Changes

- **`src/sage/structure/category_object.pyi`** (new):
`CategoryObject(SageObject)` — `base_ring` → `Ring`,
`variable_name`/`latex_name` → `str`, `variable_names` → `tuple[str,
...]`, `latex_variable_names` → `list[str]`,
`gens_dict`/`gens_dict_recursive` → `dict[str, Any]`, `objgen`/`objgens`
→ `tuple[Any, Any]`, `categories` → `list[Any]`, `inject_variables` →
`None`, `_first_ngens`.
- **`src/sage/structure/parent.pyi`** (new): `Parent(CategoryObject)` —
`element_class: type` (a `lazy_attribute` at runtime) and the `register_
action`/`register_coercion`/`register_conversion`/`register_embedding`
mutators → `None`.
- **`src/sage/structure/parent_gens.pyi`** (new):
`ParentWithGens(CategoryObject)` — `gens` → `tuple[Any, ...]`, `ngens` →
`int`.
- **`src/sage/matrix/matrix_dense.pyi`**, **`matrix_integer_dense.pyi`**
(new): `Matrix_dense(Matrix).transpose → Matrix_dense` and
`Matrix_integer_dense(Matrix_dense).LLL → Matrix_integer_dense`,
completing the matrix family of sagemath#43004.
- **`src/sage/rings/fast_arith.pyi`** (fix): `prime_range` was declared
`-> list[int]`, which is wrong for the default path — at runtime
`prime_range(10)` yields `Integer`s and only `py_ints=True` yields
`int`s. Now two `Literal` overloads matching the verified behavior.
- **`src/sage/rings/integer_ring.pyi`**: adds module-level `crt_basis(X)
-> list[Integer]` (verified: returns a list of `Integer`s).
- Five new stubs registered in **`meson.build`**;
**`src/sage/tests/type_checking/structure_returns.py`**: checker-only
probe (receivers pinned with `typing.cast`, since `ty` keeps the
narrower inferred initializer type over a variable annotation).

## Verification

Return types verified entry-by-entry against the live runtime (Sage
10.9); the `register_*` mutators are annotated but not probe-called
(registration is only legal on fresh parents); the probe executes
cleanly under the doctest loader; `ty` and ruff clean with source-tree
resolution matching the CI Type check job.
    
URL: sagemath#43007
Reported by: 星记
Reviewer(s): Copilot
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants