Repository navigation
Extend the Integer stub with return types for 78 high-use accessors - #43000
Merged
Merged
Conversation
integer.pyi currently declares only low-level hooks typed as object, so Integer — the most-used Sage element class — still infers Unknown for its public surface. This adds the 78 most-used accessors with return types verified against the live runtime (Sage 10.9): factor -> Factorization, the prime family / sqrt-family / divisibility family -> Integer or bool, bit_length/nbits/jacobi/kronecker/test_bit/trailing_zero_bits -> int, str/hex/oct/ordinal_str/binary -> str, to_bytes -> bytes, list-returning accessors -> list[Integer], xgcd -> tuple[Integer, Integer, Integer], perfect_power/quo_rem/sqrtrem/val_unit -> 2-tuples, and the flag- dependent is_prime_power/is_pseudoprime_power (get_data=True always returns tuple[Integer, Integer]) and is_norm (element=True returns tuple[bool, Any]) as Literal overloads. Builtin names shadowed by same-named Integer methods (list, str) are qualified builtins.* because checkers otherwise resolve the annotation to the method symbol. Adds a checker-only probe with 45 assertions.
Contributor
There was a problem hiding this comment.
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.
This was referenced Oct 17, 2026
|
Documentation preview for this PR (built with commit adb7f93; changes) is ready! 🎉 |
This was referenced Oct 17, 2026
Merged
vbraun
pushed a commit
to vbraun/sage
that referenced
this pull request
Oct 18, 2026
sagemathgh-43000: Extend the Integer stub with return types for 78 high-use accessors ## Motivation `integer.pyi` currently declares only a handful of low-level hooks (typed as `object`), so `Integer` — the most-used Sage element class — still infers as `Unknown` for its entire public surface in ty/Pyright/mypy/PyCharm. This extends the existing stub with the 78 highest-use accessors, following the stub-plus-probe pattern of sagemath#42672 and building on the newly-added `rational.pyi` (sagemath#42999, which provides the `Rational` referenced by `rational_reconstruction`). ## Changes **`src/sage/rings/integer.pyi`** — 78 new method declarations, return types verified one-by-one against the live runtime (Sage 10.9, Python 3.13): - `factor` → `Factorization`; the prime family (`next_prime`, `previous_prime`, `next_prime_power`, `previous_prime_power`, `next_probable_prime`, `powermod`, `inverse_mod`, `inverse_of_unit`, `exact_log`, `factorial`, `binomial`, `class_number`, `isqrt`, `odd_part`, `p_primary_part`, `prime_to_m_part`, `popcount`, `trial_division`, `euclidean_degree`, `trunc`, `ceil`, `floor`, `round`, `sign`, `numerator`, `denominator`, `squarefree_part`, `valuation`, `nth_root`-family) → `Integer` - bit/symbol accessors `bit_length`/`nbits`/`test_bit`/`trailing_zero_bi ts`/`jacobi`/`kronecker` → `int`; `ndigits` → `Integer` (both verified) - string forms `str`/`hex`/`oct`/`binary`/`ordinal_str` → `str`; `to_bytes` → `bytes` - `list`-returning accessors (`balanced_digits`, `coprime_integers`, `digits`, `prime_divisors`, `support`) → `list[...]` - tuple forms: `xgcd` → `tuple[Integer, Integer, Integer]`, `perfect_power`/`quo_rem`/`sqrtrem`/`val_unit`/`canonical_associate` → 2-tuples - flag-dependent methods as `Literal` overloads, all shapes executed at runtime: `is_prime_power`/`is_pseudoprime_power` (`get_data=True` always returns `tuple[Integer, Integer]` — including `(n, 0)` for non-prime- powers), `is_norm` (`element=True` → `tuple[bool, Any]`) - the `is_*` predicates → `bool`; heights → `RealNumber` Builtin names shadowed by same-named `Integer` methods (`list`, `str`) are qualified as `builtins.*` — checkers otherwise resolve the annotation to the class's own method symbol (this cost a `ty` iteration). **`src/sage/tests/type_checking/integer_returns.py`** — checker-only probe, 45 `assert_type` assertions, all runtime-valid. ## Verification Every accessor executed with its runtime type recorded (`Integer(12)` and value-dependent cases on `8`, `9`, `12`); flag-dependent returns probed in both directions; the probe executes cleanly under the doctest loader; `ty` and ruff clean locally with source-tree resolution matching the CI Type check job. URL: sagemath#43000 Reported by: 星记 Reviewer(s): Copilot
vbraun
pushed a commit
to vbraun/sage
that referenced
this pull request
Oct 18, 2026
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
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
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
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
pushed a commit
that referenced
this pull request
Oct 22, 2026
gh-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 #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_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: #43001 Reported by: 星记 Reviewer(s): Copilot
vbraun
pushed a commit
that referenced
this pull request
Oct 22, 2026
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
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
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
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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
integer.pyicurrently declares only a handful of low-level hooks (typed asobject), soInteger— the most-used Sage element class — still infers asUnknownfor its entire public surface in ty/Pyright/mypy/PyCharm. This extends the existing stub with the 78 highest-use accessors, following the stub-plus-probe pattern of #42672 and building on the newly-addedrational.pyi(#42999, which provides theRationalreferenced byrational_reconstruction).Changes
src/sage/rings/integer.pyi— 78 new method declarations, return types verified one-by-one against the live runtime (Sage 10.9, Python 3.13):factor→Factorization; the prime family (next_prime,previous_prime,next_prime_power,previous_prime_power,next_probable_prime,powermod,inverse_mod,inverse_of_unit,exact_log,factorial,binomial,class_number,isqrt,odd_part,p_primary_part,prime_to_m_part,popcount,trial_division,euclidean_degree,trunc,ceil,floor,round,sign,numerator,denominator,squarefree_part,valuation,nth_root-family) →Integerbit_length/nbits/test_bit/trailing_zero_bits/jacobi/kronecker→int;ndigits→Integer(both verified)str/hex/oct/binary/ordinal_str→str;to_bytes→byteslist-returning accessors (balanced_digits,coprime_integers,digits,prime_divisors,support) →list[...]xgcd→tuple[Integer, Integer, Integer],perfect_power/quo_rem/sqrtrem/val_unit/canonical_associate→ 2-tuplesLiteraloverloads, all shapes executed at runtime:is_prime_power/is_pseudoprime_power(get_data=Truealways returnstuple[Integer, Integer]— including(n, 0)for non-prime-powers),is_norm(element=True→tuple[bool, Any])is_*predicates →bool; heights →RealNumberBuiltin names shadowed by same-named
Integermethods (list,str) are qualified asbuiltins.*— checkers otherwise resolve the annotation to the class's own method symbol (this cost atyiteration).src/sage/tests/type_checking/integer_returns.py— checker-only probe, 45assert_typeassertions, all runtime-valid.Verification
Every accessor executed with its runtime type recorded (
Integer(12)and value-dependent cases on8,9,12); flag-dependent returns probed in both directions; the probe executes cleanly under the doctest loader;tyand ruff clean locally with source-tree resolution matching the CI Type check job.