Repository navigation
Add a return-type stub for the univariate Polynomial base class - #43001
Conversation
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.
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.
|
Documentation preview for this PR (built with commit 2893644; changes) is ready! 🎉 |
|
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 |
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
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
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
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
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
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
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
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
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
Motivation
polynomial_element.pyx(the univariatePolynomialbase class behind everyR = QQ['x']; R.gen() + 1expression) is a Cython module with no stub, so static checkers inferUnknownfor 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 ofPolynomial(CommutativePolynomial), return types verified against the live runtime (Sage 10.9, Python 3.13):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— →Polynomialdegree,dispersion,euclidean_degree→Integer;number_of_real_roots,number_of_roots_in_interval→intfactor→Factorization; theis_*predicates →bool;exponents→list[int];variable_name→strroots/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_polynomialas aLiteraloverload:return_q=False→bool,return_q=True→tuple[bool, Any](theqelement type varies with the base ring; verified(True, q)at runtime)quo_remdeclaredtuple[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 qualifiedbuiltins.*, 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, 32assert_typeassertions (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;tyand ruff clean with source-tree resolution matching the CI Type check job.