Skip to content

Add structure-cluster stubs (CategoryObject, Parent, ParentWithGens) and two matrix completions - #43007

Merged
vbraun merged 5 commits into
sagemath:developfrom
starnotes-xj:structure-pyi-stubs
Oct 28, 2026
Merged

vbraun merged 5 commits into
sagemath:developfrom
starnotes-xj:structure-pyi-stubs

Conversation

@starnotes-xj

Copy link
Copy Markdown
Contributor

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 #43004, and two stub fixes found by runtime probing. Follows #42672 / #42999 / #43000 / #43001 / #43002 / #43004 / #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 Add return-type stubs for the Matrix class family and the matrix factory #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 Integers and only py_ints=True yields ints. 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 Integers).
  • 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.

…and matrix_dense/matrix_integer_dense

sage.structure's base classes are Cython and unstubbed, so the naming
and generator introspection surface every Sage object shares infers as
Unknown. This adds:

- category_object.pyi: CategoryObject with base_ring -> Ring,
  variable_name/latex_name -> str, variable_names -> tuple[str, ...],
  latex_variable_names -> list[str], gens_dict(_recursive) ->
  dict[str, Any], objgen/objgens -> tuple[Any, Any], categories ->
  list[Any], inject_variables -> None, _first_ngens
- parent.pyi: Parent(CategoryObject) with element_class: type (a
  lazy_attribute at runtime) and the register_action/coercion/
  conversion/embedding mutators -> None
- parent_gens.pyi: ParentWithGens(CategoryObject) with gens ->
  tuple[Any, ...] and ngens -> int
- matrix_dense.pyi / matrix_integer_dense.pyi: transpose -> Matrix_dense
  and LLL -> Matrix_integer_dense completing the matrix family of sagemath#43004

Also upgrades fast_arith.pyi's prime_range (previously declared
list[int], wrong for the default path) to Literal overloads matching
the runtime: py_ints=False -> list[Integer], py_ints=True -> list[int];
and adds integer_ring.crt_basis -> list[Integer].

All returns verified against the live runtime (Sage 10.9). Registers
five new stubs in meson.build; adds a checker-only probe.
Copilot AI balanced review requested due to automatic review settings October 17, 2026 05:53

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 36fafe1; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

@vbraun

vbraun commented Oct 17, 2026

Copy link
Copy Markdown
Member

ci fails?

…g import

crt_basis is already declared in integer_ring.pyi upstream (line ~137,
Optional[Any] style) — my earlier module-level addition duplicated it
(F811 after merge). The probe also lost its 'from sage.rings.ring
import Ring' line in an earlier cleanup, leaving the bare Ring in
assert_type as Unknown (unresolved-reference is in the lint baseline,
so it only surfaced as the assertion failure). Cast targets are now
quoted per ruff TC006.
@starnotes-xj

Copy link
Copy Markdown
Contributor Author

@vbraun Three real defects on my side, all fixed in the pushed commit:

  1. F811: I added a module-level crt_basis to integer_ring.pyi without noticing upstream already declares it further down the same file (different signature style) — the duplicate only surfaced when merging into develop. Dropped mine.
  2. Type check: the probe lost its from sage.rings.ring import Ring import in an earlier cleanup; the bare Ring in an assertion then resolved as Unknown (unresolved-reference is in the lint ignore baseline, so it only showed as the assertion mismatch). Import restored.
  3. TC006: cast() targets in the probe are now quoted per the current ruff rules.

The remaining red jobs are the distro builds (archlinux/darwin/debian/macos) — they die in external packaging (cypari2 build failure + PARI 2.19 initprimetable deprecation failing C compilation), which is affecting the whole fleet today, not this diff. The conda matrix should go back to green now; happy to retrigger anything else.

@mantepse

Copy link
Copy Markdown
Contributor

I don't understand: ParentWithGens was removed already quite some time ago

parent_gens.pyx was reduced upstream to the localvars context manager;
the ParentWithGens class is gone and gens/ngens surface through the
category framework now. The stub for the removed class, its meson
entry, and the two probe assertions are dropped.
@starnotes-xj

Copy link
Copy Markdown
Contributor Author

@mantepse You're right — thank you! The class was already gone on develop (parent_gens.pyx is down to the localvars context manager); my runtime introspection ran against an installed 10.9, where the class still exists, which is how the ghost slipped in. Dropped parent_gens.pyi, its meson entry, and the two probe assertions in the pushed commit. The gens/ngens coverage will have to come from the categories layer instead if it's wanted.

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
vbraun merged commit d464779 into sagemath:develop Oct 28, 2026
30 of 33 checks passed
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.

4 participants